From f898fbf911e3505f5fcd29980113da9e234b182c Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Wed, 18 Nov 2020 13:16:56 -0800
Subject: [PATCH] examples: clean up & add more budgeting examples

---
 .../budgeting/auto-envelope-budget-1.journal  |  80 +++++++
 examples/budgeting/forecast-budget-1.journal  |  55 +++++
 .../forecast-budget-2.journal}                |   5 +
 examples/budgeting/forecast-budget-3.journal  |  42 ++++
 .../forecast-budget-4.budget.journal          |  86 +++++++
 examples/budgeting/forecast-budget-4.journal  | 127 +++++++++++
 .../manual-envelope-budget-1.journal          | 210 ++++++++++++++++++
 7 files changed, 605 insertions(+)
 create mode 100644 examples/budgeting/auto-envelope-budget-1.journal
 create mode 100644 examples/budgeting/forecast-budget-1.journal
 rename examples/{budget.journal => budgeting/forecast-budget-2.journal} (68%)
 create mode 100644 examples/budgeting/forecast-budget-3.journal
 create mode 100644 examples/budgeting/forecast-budget-4.budget.journal
 create mode 100644 examples/budgeting/forecast-budget-4.journal
 create mode 100644 examples/budgeting/manual-envelope-budget-1.journal

diff --git a/examples/budgeting/auto-envelope-budget-1.journal b/examples/budgeting/auto-envelope-budget-1.journal
new file mode 100644
index 000000000..cdb00fc60
--- /dev/null
+++ b/examples/budgeting/auto-envelope-budget-1.journal
@@ -0,0 +1,80 @@
+; An "envelope budget" assisted by auto postings.
+; From the "Planning/allocating budget" example at https://gist.github.com/ony/bbec599c0893e676b772559909b81de6.
+
+; Envelope balances, representing the currently available funds in each budget category, 
+; are tracked as pseudo-accounts under "budget". 
+; Here we allocate some funds to the envelopes. These are imaginary, so unbalanced postings are fine:
+
+2008/4/1 Budget for 2008q2
+    (budget:food)                 $1000
+    (budget:clothes)               $200
+    (budget:misc)                 $1000
+
+; When you spend, a corresponding amount should be removed from the appropriate budget envelope.
+; You can record this manually, eg:
+;
+; 2008-04-15
+;   expenses:food     $10
+;   assets:checking  -$10
+;   (budget:food)    -$10
+
+; Or you can do it automatically with auto postings, activated with --auto.
+; This is often recommended, as a labour saver.
+; Auto posting rules:
+
+; for each posting to a clothes expense account,
+; add an auto posting removing the same amount from the clothes budget envelope.
+= expenses.*clothes
+    (budget:clothes)               *-1
+
+; for each posting to a food or supplies expense account, 
+; remove the same amount from the food budget envelope.
+= expenses.*(food|supplies)
+    (budget:food)                  *-1
+
+; for each posting to any other expense account,
+; remove the same amount from the misc budget envelope.
+= expenses: not:expenses.*(clothes|food|supplies)
+    (budget:misc)                  *-1
+
+; Some transactions:
+
+2008-04-15
+  expenses:food     $400
+  expenses:clothes  $300
+  assets:checking
+
+2008-06-15
+  expenses:food     $600
+  assets:checking
+
+
+; Some reports:
+comment
+
+Monthly changes in budget envelopes during the quarter:
+
+$ hledger -f examples/budgeting/budget2.journal bal budget date:2008q2 --auto -M
+Balance changes in 2008Q2:
+
+                ||   Apr  May    Jun 
+================++===================
+ budget:clothes || $-100    0      0 
+ budget:food    ||  $600    0  $-600 
+ budget:misc    || $1000    0      0 
+----------------++-------------------
+                || $1500    0  $-600 
+
+Month-end balances of budget envelopes:
+
+$ hledger -f examples/budgeting/budget2.journal bal budget date:2008q2 --auto -M -H
+Ending balances (historical) in 2008Q2:
+
+                || 2008-04-30  2008-05-31  2008-06-30 
+================++====================================
+ budget:clothes ||      $-100       $-100       $-100 
+ budget:food    ||       $600        $600           0 
+ budget:misc    ||      $1000       $1000       $1000 
+----------------++------------------------------------
+                ||      $1500       $1500        $900 
+
diff --git a/examples/budgeting/forecast-budget-1.journal b/examples/budgeting/forecast-budget-1.journal
new file mode 100644
index 000000000..38832be48
--- /dev/null
+++ b/examples/budgeting/forecast-budget-1.journal
@@ -0,0 +1,55 @@
+; A minimal "forecast budget", defined with a periodic transaction rule.
+
+; We forecast/plan to spend $500 on food each month in 2020:
+~ monthly in 2020
+  (expenses:food)  $500
+
+; Some transactions:
+
+2020-01-15
+  expenses:food    $400
+  assets:checking
+
+2020-03-15
+  expenses:food    $600
+  assets:checking
+
+; Some examples of the balance --budget report,
+; which compares the actual (so far) and forecasted amounts.
+; There are some open bugs; here is output from several hledger versions:
+comment
+
+; the totals row has always been wrong (a bug)
+$ hledger-1.15 -f examples/budgeting/budget1.journal bal --budget -M
+Budget performance in 2020q1:
+
+               ||                   Jan                    Feb                    Mar 
+===============++=====================================================================
+ <unbudgeted>  || $-400                      0                  $-600                 
+ expenses      ||  $400 [  80% of $500]      0 [   0% of $500]   $600 [ 120% of $500] 
+ expenses:food ||  $400 [  80% of $500]      0 [   0% of $500]   $600 [ 120% of $500] 
+---------------++---------------------------------------------------------------------
+               ||     0 [   0% of $500]      0 [   0% of $500]      0 [   0% of $500] 
+
+; since 1.16, Jan is showing no info (a bug)
+; since 1.19, the boring parent "expenses" is elided by default
+$ hledger-1.19.1 -f examples/budgeting/budget1.journal bal --budget -M
+Budget performance in 2020Q1:
+
+               ||                   Jan                    Feb                    Mar 
+===============++=====================================================================
+ <unbudgeted>  || $-400                      0                  $-600                 
+ expenses:food ||  $400                      0 [   0% of $500]   $600 [ 120% of $500] 
+---------------++---------------------------------------------------------------------
+               ||     0                      0 [   0% of $500]      0 [   0% of $500] 
+
+; since 1.19.99, columns shrink to fit and can vary in width
+$ hledger -f examples/budgeting/budget1.journal bal --budget -M
+Budget performance in 2020Q1:
+
+               ||   Jan             Feb                   Mar 
+===============++=============================================
+ <unbudgeted>  || $-400  0               $-600                
+ expenses:food ||  $400  0 [0% of $500]   $600 [120% of $500] 
+---------------++---------------------------------------------
+               ||     0  0 [0% of $500]      0 [  0% of $500] 
diff --git a/examples/budget.journal b/examples/budgeting/forecast-budget-2.journal
similarity index 68%
rename from examples/budget.journal
rename to examples/budgeting/forecast-budget-2.journal
index f8d33d672..931ddf1ea 100644
--- a/examples/budget.journal
+++ b/examples/budgeting/forecast-budget-2.journal
@@ -1,3 +1,8 @@
+; A budget defined by periodic transaction rules :
+; one recurring monthly, one yearly, and one non-recurring.
+; This would show up in a report like:
+; $ hledger balance --budget Income Expenses -M
+
 ~ monthly from 2013/01
   Expenses:Food    500 USD
   Expenses:Health  200 USD
diff --git a/examples/budgeting/forecast-budget-3.journal b/examples/budgeting/forecast-budget-3.journal
new file mode 100644
index 000000000..7e8abbd7c
--- /dev/null
+++ b/examples/budgeting/forecast-budget-3.journal
@@ -0,0 +1,42 @@
+; https://www.reddit.com/r/plaintextaccounting/comments/e5sl1m/advice_on_projectionsforecasts/
+;
+; I've been reading up in preparation for switching to pta in 2020
+; from my current ad hoc spreadsheet. The forecasting docs/tutorial
+; for hledger answer many of my questions but I'm wondering about how
+; to duplicate a forecasting page of my spreadsheet.
+; On this page, I list all my future expenses with estimates for each.
+; However I don't assign any dates to most of the expenses since they
+; don't really have an associated date. As the year progresses and I
+; book expenses against these accounts I update the page with an
+; actual vs. estimated amount. This is just a big picture view of a
+; year's expenses vs. expected revenue so I have a better idea of what
+; big purchases I can plan for or maybe have to delay until the
+; following year.
+; This doesn't seem to fit within the typical forecasting/budget
+; reports I've seen, does anyone have tips or examples that might help
+; me generate a similar report with a ledger-like (I haven't chosen
+; the software I'll use yet but probably ledger or hledger). Thanks!
+
+~ 2020
+  (expenses:rent)  $12000
+  (expenses:food)   $6000
+
+2020/1/1
+  expenses:rent     $1000
+  assets:checking
+
+2020/1/5
+  expenses:food      $100
+  assets:checking
+
+comment
+$ hledger bal expenses --budget -YS --tree
+Budget performance in 2020:
+
+          ||                    2020 
+==========++=========================
+ expenses || $1100 [   6% of $18000] 
+   rent   || $1000 [   8% of $12000] 
+   food   ||  $100 [   2% of  $6000] 
+----------++-------------------------
+          || $1100 [   6% of $18000] 
diff --git a/examples/budgeting/forecast-budget-4.budget.journal b/examples/budgeting/forecast-budget-4.budget.journal
new file mode 100644
index 000000000..e1f026b32
--- /dev/null
+++ b/examples/budgeting/forecast-budget-4.budget.journal
@@ -0,0 +1,86 @@
+; A detailed forecast budget, defined with periodic transaction rules.
+
+; all amount are imaginary and will be either 1000 or 100 or 10
+
+; monthly wages and monthy expenses (which get deducted as a single transaction per month)
+~ every 1st day of month from 2017-01-01
+    income:work                 £-1000
+    liabilities:mortgage        £100
+    expenses:bills              £100
+    assets:current
+
+; regular expenses that either occur once per week (groceries, car
+; fuel), or could be expressed as a weekly total easier than a daily
+; spending - like commute on weekdays (but not on weekends!)
+~ weekly from 2017-01-02
+    expenses:travel:commute     £10
+    expenses:food:groceries     £10
+    expenses:car:fuel           £10
+    expenses:misc               £10
+    assets:current
+
+; tax that is deducted quarterly in four installments
+~ every 90 days from 2017-01-15
+    expenses:council tax        £100
+    assets:current
+
+; investment that pays out almost quartery, roughly on last day on quarter
+~ every 90 days from 2017/03/30
+    income:investments         £-1000
+    assets:current
+
+; School-related expenses are collected every 2 month, but not when the school is out
+~ every 60 days from 2017/01/01 to 2017/05/30
+  expenses:school              £100 
+  assets:current
+
+~ every 60 days from 2017/08/01 to 2017/12/31
+  expenses:school              £100 
+  assets:current
+  
+
+; Big once-per-year expenses
+~ every 15th Aug
+    expenses:fun                  £100 ;  birthday 1
+    assets:current
+
+~ every 15th Sep
+    expenses:fun                  £100 ;  birthday 2
+    assets:current
+
+~ every 25th Dec
+    expenses:fun                  £100 ;  Christmas and New Year
+    assets:current
+
+~ every 15th Feb
+    expenses:fun                  £100 ;  birthday 3
+    assets:current
+
+~ every 1st Apr
+    expenses:fun                  £100 ;  birthday 4
+    assets:current
+
+~ every 1st Jun
+   expenses:car:insurance    £100
+   assets:current
+
+;; Events that happen once
+~ 2017-01-29
+   income:work   £-1234  ; bonus
+   assets:current
+
+~ 2017-01-20
+   expenses:tax office    £100 ; capital gains tax
+   assets:current
+
+~ 2017-03-15
+  expenses:home:renovations   £100 ; renovations 1
+  assets:current 
+
+~ 2017-05-15
+  expenses:home:renovations   £100 ; renovations 2
+  assets:current 
+
+2017-01-01
+  expenses:misc   £1
+  assets:current
diff --git a/examples/budgeting/forecast-budget-4.journal b/examples/budgeting/forecast-budget-4.journal
new file mode 100644
index 000000000..a8f27641f
--- /dev/null
+++ b/examples/budgeting/forecast-budget-4.journal
@@ -0,0 +1,127 @@
+;; A main journal file, including budget goals from a separate file:
+include forecast-budget-4.budget.journal
+
+;; and containing some actual transactions:
+
+;; Regular income
+2017-01-25 Salary
+  income:work   £-999
+  assets:current
+
+2017-02-25 Salary
+  income:work   £-1000
+  assets:current
+
+2017-03-25 Salary
+  income:work   £-1000
+  assets:current
+
+2017-04-25 Salary
+  income:work   £-1000
+  assets:current
+
+2017-05-25 Salary
+  income:work   £-1000
+  assets:current
+
+2017-06-25 Salary
+  income:work   £-1000
+  assets:current
+
+;; Irregular income
+2017-01-25 Bonus
+   income:work   £-1345  
+   assets:current
+
+2017-03-28
+    income:investments         £-1010
+    assets:current
+
+2017-06-29
+    income:investments         £-970
+    assets:current
+
+2017-01-14
+    expenses:council tax        £101
+    assets:current
+
+2017-04-24
+    expenses:council tax        £99
+    assets:current
+
+2017-01-26 Capital gains tax
+   expenses:tax office    £101 ; capital gains tax
+   assets:current
+
+; other
+2017-05-28
+   expenses:car:insurance    £100
+   assets:current
+
+2017-03-01
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-02
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-03
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-04
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-05
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-06
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-06
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-07
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-03-07
+  expenses:home:renovations   £10 ; renovations 1
+  assets:current 
+
+2017-01-03
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-04
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-06
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-09
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-10
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-11
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-12
+  expenses:travel:commute   £2
+  assets:current
+
+2017-01-13
+  expenses:travel:commute   £2
+  assets:current 
diff --git a/examples/budgeting/manual-envelope-budget-1.journal b/examples/budgeting/manual-envelope-budget-1.journal
new file mode 100644
index 000000000..de8e1b5ec
--- /dev/null
+++ b/examples/budgeting/manual-envelope-budget-1.journal
@@ -0,0 +1,210 @@
+; An example of YNAB-ish envelope budgetting with hledger/ledger
+; cf https://github.com/simonmichael/hledger/issues/315
+
+; Using accounts like the following:
+;
+; assets                <- parent accounts, organising the chart of accounts
+;   business            
+;     bank              
+;       wf              
+;         bchecking     <- a real-world checking account
+;           available   <- imaginary subaccounts of checking. This one represents unallocated/buffer funds.
+;           month       <- a parent which groups the short-term, spending-control "envelopes"
+;             autosave  <- an envelope account. Holds funds to cover automated monthly transfer to a savings account.
+;             banking   <- envelope for banking-related expenses
+;             books     <- envelope for books/periodicals expenses. Etc.
+;             dues
+;             equipment
+;             online
+;             research
+;             software
+;             supplies
+;           year        <- parent for longer-term, spending/savings-goal envelopes
+;             conferences
+;             education
+;             legal/accounting
+; XXX missing savings
+;   personal
+;     bank
+;       wf
+;         checking      <- a second real-world checking account
+;           available
+;           month
+;             autosave
+;             clothing
+;             food
+;             gifts
+;             health
+;             home
+;             personal care
+;             phone
+;             recreation
+;             spiritual
+;             transport
+;           year
+;             vacation
+;         savings
+;           reserve
+; expenses
+;   business
+;     books/periodicals <- expense accounts, representing spending categories
+;     online            <-
+;       hosting         <-
+;   personal
+;     food              <-
+;       dining          <-
+;       snacks          <-
+;     gifts             <-
+
+2016/1/1 * set up some balances for this example
+    (assets:business:bank:wf:bchecking:month:books)       $-9.42
+    (assets:business:bank:wf:bchecking:available)           $500
+    (assets:personal:bank:wf:checking:month:food)        $-24.28
+    (assets:personal:bank:wf:checking:month:gifts)       $-16.30
+    (assets:personal:bank:wf:checking:available)           $2100
+
+; at the start of each month, zero out any overspending from last month:
+
+2016/1/1 * refill negative budget envelopes (business)
+    [assets:business:bank:wf:bchecking:month:books]        $9.42 = $0
+    [assets:business:bank:wf:bchecking:available]         $-9.42
+
+2016/1/1 * refill negative budget envelopes (personal)
+    [assets:personal:bank:wf:checking:month:food]         $24.28 = $0
+    [assets:personal:bank:wf:checking:month:gifts]        $16.30 = $0
+    [assets:personal:bank:wf:checking:available]         $-40.58
+
+; and transfer funds to various envelopes (books, etc.) for this month's
+; spending, and longer-term saving goals:
+
+2016/1/1 * budget for this month's business expenses
+    [assets:business:bank:wf:bchecking:month:autosave]      $100
+    [assets:business:bank:wf:bchecking:month:banking]          0
+    [assets:business:bank:wf:bchecking:month:books]          $10
+    [assets:business:bank:wf:bchecking:month:dues]           $10
+    [assets:business:bank:wf:bchecking:month:equipment]      $40
+    [assets:business:bank:wf:bchecking:month:online]         $70
+    [assets:business:bank:wf:bchecking:month:research]       $20
+    [assets:business:bank:wf:bchecking:month:software]       $20
+    [assets:business:bank:wf:bchecking:month:supplies]       $10
+    [assets:business:bank:wf:bchecking:year:conferences]     $20
+    [assets:business:bank:wf:bchecking:year:education]       $10
+    [assets:business:bank:wf:bchecking:year:legal/accounting]  $40
+    [assets:business:bank:wf:bchecking:available]          $-350
+
+2016/1/1 * budget for this month's personal expenses
+    [assets:personal:bank:wf:checking:month:autosave]       $100
+    [assets:personal:bank:wf:checking:month:clothing]        $30
+    [assets:personal:bank:wf:checking:month:food]           $300
+    [assets:personal:bank:wf:checking:month:gifts]           $30
+    [assets:personal:bank:wf:checking:month:health]         $300
+    [assets:personal:bank:wf:checking:month:home]          $1000
+    [assets:personal:bank:wf:checking:month:personal care]   $20
+    [assets:personal:bank:wf:checking:month:phone]           $80
+    [assets:personal:bank:wf:checking:month:recreation]      $20
+    [assets:personal:bank:wf:checking:month:spiritual]       $20
+    [assets:personal:bank:wf:checking:month:transport]       $50
+    [assets:personal:bank:wf:checking:year:vacation]         $50
+    [assets:personal:bank:wf:checking:available]          $-2000
+
+; Update appropriate envelopes as transactions are made:
+
+2016/1/1 * automatic savings transfer
+    assets:business:bank:wf:bchecking:month:autosave
+    assets:business:bank:wf:savings:reserve                 $100
+
+2016/1/1 * automatic savings transfer
+    assets:personal:bank:wf:checking:month:autosave
+    assets:personal:bank:wf:savings:reserve                 $100
+
+2016/1/2 * linode
+    expenses:business:online:hosting                         $50
+    assets:business:bank:wf:bchecking:month:online
+
+2016/1/3 * market
+    expenses:personal:food:dining                            $10
+    expenses:personal:food:snacks                             $2
+    assets:personal:bank:wf:checking:month:food             $-12
+    expenses:personal:gifts                                   $3
+    assets:personal:bank:wf:checking:month:gifts             $-3
+
+2016/1/4 * amazon  open source everything
+    ; a business purchase from personal account - use available
+    expenses:business:books/periodicals                   $12.33
+    assets:personal:bank:wf:checking:available           -$12.33
+    ; and adjust the appropriate business envelope
+    [assets:business:bank:wf:bchecking:available]         $12.33
+    [assets:business:bank:wf:bchecking:month:books]      -$12.33
+
+; Check your envelope balances periodically:
+;
+; $ hledger bal checking:
+;             $2272.67  assets
+;              $340.58    business:bank:wf:bchecking
+;              $152.91      available
+;              $117.67      month
+;               $-2.33        books      <- overspent already
+;               $10.00        dues
+;               $40.00        equipment
+;               $20.00        online
+;               $20.00        research
+;               $20.00        software
+;               $10.00        supplies
+;               $70.00      year
+;               $20.00        conferences
+;               $10.00        education
+;               $40.00        legal/accounting
+;             $1932.09    personal:bank:wf:checking
+;               $47.09      available
+;             $1835.00      month
+;               $30.00        clothing
+;              $288.00        food
+;               $27.00        gifts
+;              $300.00        health
+;             $1000.00        home
+;               $20.00        personal care
+;               $80.00        phone
+;               $20.00        recreation
+;               $20.00        spiritual
+;               $50.00        transport
+;               $50.00      year:vacation
+; --------------------
+;             $2272.67
+;
+; $ hledger bal checking: --weekly --historical --drop 4
+; Ending balances (historical) in 2015/12/28-2016/01/10:
+;
+;                                  ||  2016/01/03  2016/01/10 
+; =================================++=========================
+;  bchecking:available             ||     $140.58     $152.91 
+;  bchecking:month:books           ||      $10.00      $-2.33 
+;  bchecking:month:dues            ||      $10.00      $10.00 
+;  bchecking:month:equipment       ||      $40.00      $40.00 
+;  bchecking:month:online          ||      $20.00      $20.00 
+;  bchecking:month:research        ||      $20.00      $20.00 
+;  bchecking:month:software        ||      $20.00      $20.00 
+;  bchecking:month:supplies        ||      $10.00      $10.00 
+;  bchecking:year:conferences      ||      $20.00      $20.00 
+;  bchecking:year:education        ||      $10.00      $10.00 
+;  bchecking:year:legal/accounting ||      $40.00      $40.00 
+;  checking:available              ||      $59.42      $47.09 
+;  checking:month:clothing         ||      $30.00      $30.00 
+;  checking:month:food             ||     $288.00     $288.00 
+;  checking:month:gifts            ||      $27.00      $27.00 
+;  checking:month:health           ||     $300.00     $300.00 
+;  checking:month:home             ||    $1000.00    $1000.00 
+;  checking:month:personal care    ||      $20.00      $20.00 
+;  checking:month:phone            ||      $80.00      $80.00 
+;  checking:month:recreation       ||      $20.00      $20.00 
+;  checking:month:spiritual        ||      $20.00      $20.00 
+;  checking:month:transport        ||      $50.00      $50.00 
+;  checking:year:vacation          ||      $50.00      $50.00 
+; ---------------------------------++-------------------------
+;                                  ||    $2285.00    $2272.67 
+;
+; or (good for reviewing transactions):
+;
+; $ hledger-ui checking:
+
+; Try to keep spending envelopes above zero, and to
+; avoid unplanned withdrawals from savings envelopes.