From 7b69abf62c2309bc8888798bc275c22ea97ddda2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 16 Jan 2017 07:55:12 -0800 Subject: [PATCH] doc: upload budget/rewrite/read-related mockups [ci skip] --- doc/mockups/budget-reporting.txt | 51 +++++++++++++++++++++++ doc/mockups/entry-macros.txt | 69 ++++++++++++++++++++++++++++++++ doc/mockups/rewriting-read.txt | 48 ++++++++++++++++++++++ 3 files changed, 168 insertions(+) create mode 100644 doc/mockups/budget-reporting.txt create mode 100644 doc/mockups/entry-macros.txt create mode 100644 doc/mockups/rewriting-read.txt diff --git a/doc/mockups/budget-reporting.txt b/doc/mockups/budget-reporting.txt new file mode 100644 index 000000000..cc9f1a011 --- /dev/null +++ b/doc/mockups/budget-reporting.txt @@ -0,0 +1,51 @@ +budget report mockups + +$ hledger bal ^expenses -M --depth 1 --average # add average & total columns +Change of balance (flow): + + || 2014/01/01-2014/01/31 2014/02/01-2014/02/28 2014/03/01-2014/03/31 average total +==========++============================================================================================ + expenses || $3500.00 $3400.00 $4200.00 $3700.00 $11100.00 +----------++-------------------------------------------------------------------------------------------- + || $3500.00 $3400.00 $4200.00 $3700.00 $11100.00 + +$ hledger bal ^expenses -M --depth 1 --budget-simple # assume a fixed budget +Change of balance (flow, with simple budget): + + || | 2014/01/01-2014/01/31 2014/02/01-2014/02/28 2014/03/01-2014/03/31 | average total + || budget | actual over actual over actual over | over over +==========++======================================================================================================= + expenses || $4000 | $3500.00 $-500.00 $3400.00 $-600.00 $4200.00 $200.00 | $-300.00 $-900.00 +----------++------------------------------------------------------------------------------------------------------- + || $4000 | $3500.00 $-500.00 $3400.00 $-600.00 $4200.00 $200.00 | $-300.00 $-900.00 + +$ hledger bal ^expenses -M --depth 1 --budget # budget can change per period +Change of balance (flow, with budget): + + || 2014/01/01-2014/01/31 2014/02/01-2014/02/28 2014/03/01-2014/03/31 average total + || budget actual over budget actual over budget actual over over over +==========++========================================================================================================================= + expenses || $4000 $3500.00 $-500.00 $4000 $3400.00 $-600.00 $4000 $4200.00 $200.00 $-300.00 $-900.00 +----------++------------------------------------------------------------------------------------------------------------------------- + || $4000 $3500.00 $-500.00 $4000 $3400.00 $-600.00 $4000 $4200.00 $200.00 $-300.00 $-900.00 + +$ hledger bal ^expenses -M --depth 1 --budget --cumulative +Ending balance (cumulative, with budget): + + || 2014/01/01-2014/01/31 2014/02/01-2014/02/28 2014/03/01-2014/03/31 average final + || budget actual over budget actual over budget actual over over over +==========++========================================================================================================================== + expenses || $4000 $3500.00 $-500.00 $8000 $6900.00 $-1100.00 $12000 $11100.00 $-900.00 $-833.33 $-900.00 +----------++-------------------------------------------------------------------------------------------------------------------------- + || $4000 $3500.00 $-500.00 $8000 $6900.00 $-1100.00 $12000 $11100.00 $-900.00 $-833.33 $-900.00 + +$ hledger bal ^expenses -M --depth 1 --budget --historical # assume $10000 budget, $20000 expenses starting balances +Ending balance (historical, with budget): + + || 2014/01/01-2014/01/31 2014/02/01-2014/02/28 2014/03/01-2014/03/31 average final + || budget actual over budget actual over budget actual over over over +==========++========================================================================================================================== + expenses || $14000 $23500.00 $9500.00 $18000 $26900.00 $8900.00 $22000 $31100.00 $9100.00 $9166.66 $9100.00 +----------++-------------------------------------------------------------------------------------------------------------------------- + || $14000 $23500.00 $9500.00 $18000 $26900.00 $8900.00 $22000 $31100.00 $9100.00 $9166.66 $9100.00 + diff --git a/doc/mockups/entry-macros.txt b/doc/mockups/entry-macros.txt new file mode 100644 index 000000000..24322a0d2 --- /dev/null +++ b/doc/mockups/entry-macros.txt @@ -0,0 +1,69 @@ +Journal entry macro/template mockups -*- org -*- + + +* hledger-entry +$ hledger-entry --help +hledger-entry NAME [ARGS..] +Generates a journal entry using the named template, interpolating any ARGS. + +$ ls *.entry +laundry.entry date.entry + +$ hledger entry laundry 20 +2015-05-06 laundry ; household:$20 + expenses:personal:home:laundry $10 + liabilities:personal:accounts payable:household $10 + assets:personal:cash:wallet $-20 + +$ hledger entry date 5/3 23.24 +2015/05/03 date ; date:$23.24 + expenses:personal:food:dining $11.62 + expenses:personal:gifts:eleonore $11.62 + assets:personal:bank:wf:checking:food $-11.62 + assets:personal:bank:wf:checking:gifts $-11.62 + + +* hledger-expand +$ hledger-expand --help +hledger-expand ... < STDIN +Expands any entry macros in the journal data provided on stdin. + +$ cat t.j +2015/04/29 * trader joes personal 0 1 18 2.07 50 + +$ hledger expand < t.j +2015/04/29 * trader joes + expenses:personal:food:snacks $1.00 + expenses:personal:gifts:eleonore $18.00 + expenses:personal:spiritual:lodge $2.07 + assets:personal:cash:wallet $50.00 + assets:personal:bank:wf:checking:food $-1.00 + assets:personal:bank:wf:checking:gifts $-20.07 + assets:personal:bank:wf:checking:available $-50.00 + + +* entry macros defined in the journal + +$ cat t.j +entry trader joes personal GROCERIES SNACKS ELEONORE LODGE CASH +%DATE %STATUS (%CODE) %NAME + expenses:personal:food:groceries $%GROCERIES + expenses:personal:food:snacks $%SNACKS + expenses:personal:gifts:eleonore $%ELEONORE + expenses:personal:spiritual:lodge $%LODGE + assets:personal:cash:wallet $%CASH + assets:personal:bank:wf:checking:food $-%(GROCERIES+SNACKS) + assets:personal:bank:wf:checking:gifts $-%(ELEONORE+LODGE) + assets:personal:bank:wf:checking:available $-%CASH + +2015/04/29 * trader joes personal 0 1 18 2.07 50 + +$ hledger print -f t.j +2015/04/29 * trader joes personal + expenses:personal:gifts:eleonore $18.00 + expenses:personal:spiritual:lodge $2.07 + expenses:personal:food:snacks $1.00 + assets:personal:cash:wallet $50.00 + assets:personal:bank:wf:checking:gifts $-20.07 + assets:personal:bank:wf:checking:food $-1.00 + assets:personal:bank:wf:checking:available $-50.00 diff --git a/doc/mockups/rewriting-read.txt b/doc/mockups/rewriting-read.txt new file mode 100644 index 000000000..350359bc3 --- /dev/null +++ b/doc/mockups/rewriting-read.txt @@ -0,0 +1,48 @@ + +2014/5/11: new read system spec. +-------------------------------- + +Reading a journal from some data source conceptually consists of: + +1. Parse the data records into fields providing some or all of the standard + journal transaction fields - at least date, description and amount. + +2. Expand (if needed) these partial journal transactions into + complete ones. + +In practical terms, it happens in one of these ways: + +1. the data source is a file or stdin + +2. + If FILE.rules (or other file specified with --rules-file) + exists, it can define rules which help with parsing. Eg the skip, + fields, and date-format rules. + +2. Expansion: partial transactions are fleshed out into complete ones. + Eg partial transactions from CSV records need to have an account and + a balancing posting added. Expansion is done in several ways: + + 1a. Rules: if FILE.rules (or other file specified with --rules-file) + exists, it can define rules which help with expansion. Eg field + assignments and conditional blocks. + + Pro: easy, somewhat backward compatible, built in, cross platform. + Con: limited flexibility. + + 1b. Filter: or, if FILE-read (or other file specified with --read-filter) + exists, it is used as a filter to translate FILE into (partial) journal + format, which is then parsed with the (partial) journal reader. + Pro: powerful, flexible. + Con: requires programming & tools, data is parsed twice. + + 2a. History: if a transaction is still not complete, the best recent match + for it among existing transactions is used as a template to fill out + missing fields/postings (as with hledger add or ledger-autosync). + Pro: no rules or programming required, learns from past manual corrections. + Con: less precise, more likely to require manual correction, requires existing data. + + 2b. Guess: or, if there is no existing data or no acceptable match (or + history matching has been disabled with --no-history-match), we guess + default values for the missing fields. +