Some review/clarification needed. An example: we added the new --forecast and --auto flags, generic to all commands. Here are the steps:
New record fields were added to ReportOpts in ReportOptions.hs in the hledger-lib package. ReportOpts is how generic reporting flags are passed around through hledger core.
In this file we also had to tell rawOptsToReportOpts how to parse these flags from RawOpts. RawOpts is how command-line options are shared between hledger packages which may not share each other's command line flag definitions, allowing modularity.
The corresponding command line flags (cmdargs Flag), and their help, were added to reportflags in CliOptions.hs in the hledger package. This causes most hledger commands and addons to show the new flags in --help -> "General flags", and to accept them on the command line.
Flags added to CliOptions.hs and similar places should also be documented in lib.m4, which we forgot. Also ./Shake all should be run, to update all generated docs. This causes the flag and help to appear in all the hledger tools' manuals (all formats).
Issues:
the above is complex and error-prone
it's not explained in the dev guide
why is flag order different in lib.m4 ?
why are flags like --color missing from lib.m4 ?
RawOptions.hs/ReportOptions.hs vs CliOptions.hs/UIOptions.hs/WebOptions.hs/etc. - similarly named but define different kinds of thing
ReportOptions has some fields valid only for particular commands
how can we ensure code (ReportOptions + eg CliOptions) and docs (lib.m4) remain in sync
how can we ensure code (RawOptions) and code (ReportOptions) remain in sync (RawOpts provides modularity at the expense of compile-time correctness checking)
simonmichael
commented
6 years ago
Some review/clarification needed. An example: we added the new --forecast and --auto flags, generic to all commands. Here are the steps:
New record fields were added to ReportOpts in ReportOptions.hs in the hledger-lib package. ReportOpts is how generic reporting flags are passed around through hledger core.
In this file we also had to tell rawOptsToReportOpts how to parse these flags from RawOpts. RawOpts is how command-line options are shared between hledger packages which may not share each other's command line flag definitions, allowing modularity.
The corresponding command line flags (cmdargs Flag), and their help, were added to reportflags in CliOptions.hs in the hledger package. This causes most hledger commands and addons to show the new flags in --help -> "General flags", and to accept them on the command line.
Flags added to CliOptions.hs and similar places should also be documented in lib.m4, which we forgot. Also ./Shake all should be run, to update all generated docs. This causes the flag and help to appear in all the hledger tools' manuals (all formats).
Issues: