From ca0d9e2a0ef88769c4e3bae3f1b1b1e7a3f20d50 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 5 Dec 2021 16:33:07 -1000 Subject: [PATCH] ;doc: update CLI usage texts --- hledger/Hledger/Cli/Commands/Balance.txt | 72 +++++++++++++++++++----- 1 file changed, 58 insertions(+), 14 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 78dd19ac6b3..bfde0e0109f 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -256,16 +256,29 @@ The idea of this is to be able to see a useful "complete" balance report, even when you don't have transactions in all of your declared accounts yet. -Commodity layout +Data layout -With --layout, you can control how amounts with more than one commodity -are displayed: +With --layout, you can influence how amounts with more than one +commodity are displayed (and a bit more), which in turn affects the +layout of the report data: -- --layout=wide[,WIDTH]: on a single line, possibly elided to the - specified width -- --layout=tall: each commodity is displayed on a separate line -- --layout=bare: amounts are displayed as bare numbers, with commodity +- --layout=wide[,WIDTH]: commodities are shown on a single line, + possibly elided to the specified width +- --layout=tall: each commodity is shown on a separate line +- --layout=bare: amounts are shown as bare numbers, with commodity symbols in a separate column +- --layout=tidy: data is normalised to tidy form, with one row per + data value (supported with CSV output only) + +These --layout values affect some but not all of the output formats, as +shown: + + - txt csv html json sql + ------ ----- ----- ------ ------ ----- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y Examples: @@ -348,13 +361,44 @@ Examples: "total","VEA","36.00" "total","VHT","294.00" -Here is how --layout currently affects the various output formats: - - - txt csv html json sql - ------ ----- ----- ------ ------ ----- - wide Y Y Y - tall Y Y Y - bare Y Y Y +- Tidy layout produces normalised "tidy data", where every variable is + a column and each row represents a single data point (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). + This is the form of data most easily processed by other software. + Currently we support it with the CSV output format only: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=tidy -Y + "account","date","commodity","value" + "Assets:US:ETrade","2012","GLD","0" + "Assets:US:ETrade","2012","ITOT","10.00" + "Assets:US:ETrade","2012","USD","337.18" + "Assets:US:ETrade","2012","VEA","12.00" + "Assets:US:ETrade","2012","VHT","106.00" + "Assets:US:ETrade","2013","GLD","70.00" + "Assets:US:ETrade","2013","ITOT","18.00" + "Assets:US:ETrade","2013","USD","-98.12" + "Assets:US:ETrade","2013","VEA","10.00" + "Assets:US:ETrade","2013","VHT","18.00" + "Assets:US:ETrade","2014","GLD","0" + "Assets:US:ETrade","2014","ITOT","-11.00" + "Assets:US:ETrade","2014","USD","4881.44" + "Assets:US:ETrade","2014","VEA","14.00" + "Assets:US:ETrade","2014","VHT","170.00" + "total","2012","GLD","0" + "total","2012","ITOT","10.00" + "total","2012","USD","337.18" + "total","2012","VEA","12.00" + "total","2012","VHT","106.00" + "total","2013","GLD","70.00" + "total","2013","ITOT","18.00" + "total","2013","USD","-98.12" + "total","2013","VEA","10.00" + "total","2013","VHT","18.00" + "total","2014","GLD","0" + "total","2014","ITOT","-11.00" + "total","2014","USD","4881.44" + "total","2014","VEA","14.00" + "total","2014","VHT","170.00" Sorting by amount