beanquery
beanquery copied to clipboard
Improve function help by grouping by function type
As someone new to beancount, I found the function documentation really hard to navigate. The old help functions dumped everything on screen at once, which was overwhelming. While developing a BQL query, I found myself looking for functions to transform certain argument types, however I just had an alphabetical function list. (Re-open of #262)
What I changed:
Progressive disclosure:
help functionsnow shows just a category overview (takes ~10 lines instead of 100+) and explains custom object typeshelp functions amountshows only amount-related functions, same fordate,position,atomic,...
Better function docs:
- Added argument explanations to some functions (the old docs assumed you knew what arguments meant)
- Example:
grep(pattern, string)now explains "pattern" is a regex and "string" is input text - Examples on some types, e.g.
Positionis something like10 HOOL {100.30 USD}
Technical implementation:
- Query functions are grouped according to their first argument's type by
_describe_function(). - In addition, the decorators
@function,@registerand@aggregatortake agroup=argument to refine (e.g. for account names, which are strings)
The main benefit is you can find functions now much easier without scrolling through pages of text. When I started with beancount, I had no idea what functions were available or how to use them - I hope this makes it easier.