@c      --budget           generate budget transactions based on FILE

There is more information about budgeting and forecasting in
@ref{Budgeting and forecasting}.  Basically, if you have any period
transactions in your ledger file, you can use these options.  A period
transaction looks like:

@example
~ Monthly
  Assets:Bank:Checking         $500.00
  Income:Salary
@end example

The difference from a regular transaction is that the first line begins with
a tilde (~), and instead of a payee there's a period expression
(@ref{Period expressions}).  Otherwise, a period transaction is in every
other way the same as a regular transaction.

With such a transaction in your ledger file, the @option{--budget} option
will report only postings that match a budgeted account.  Using
@file{sample.dat} from above:

@example
ledger --budget reg ^income
@end example

Reports:

@smallexample
2004/05/01 Budget transaction         Income:Salary               $500.00      $500.00
2004/05/14 Pay day              Income:Salary              $-500.00            0
@end smallexample

The final total is zero, indicating that the budget matched epostly
for the reported period.  Budgeting is most often helpful with period
reporting; for example, to show monthly budget results use
@option{--budget -p monthly}.

@c      --add-budget       show all postings plus the budget
@c      --unbudgeted       show only unbudgeted postings

The @option{--add-budget} option reports all matching postings in
addition to budget postings; while @option{--unbudgeted} shows
only those that don't match a budgeted account.  To summarize:

@table @option
@item --budget
Show postings matching budgeted accounts.
@item --unbudgeted
Show postings matching unbudgeted accounts.
@item --add-budget
Show both budgeted and unbudgeted postings together (i.e., add the
generated budget postings to the regular report).
@end table

@c      --forecast EXPR    generate forecast transactions while EXPR is true

A report with the @option{--forecast} option will add budgeted
postings while the specified value expression is true.  For
example:

@example
ledger --forecast 'd<[2005] reg ^income
@end example

Reports:

@smallexample
2004/05/14 Pay day              Income:Salary              $-500.00     $-500.00
2004/12/01 Forecast transaction       Income:Salary              $-500.00   $-1,000.00
2005/01/01 Forecast transaction       Income:Salary              $-500.00   $-1,500.00
@end smallexample

The date this report was made was November 5, 2004; the reason the
first forecast transaction is in december is that forecast transactions are only
added for the future, and they only stop after the value expression
has matched at least once, which is why the January transaction appears.  A
forecast report can be very useful for determining when money will run
out in an account, or for projecting future cash flow:

@example
ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp
@end example

This reports balances projected income against projected expenses,
showing the resulting total in yearly intervals until 2008.  For the
case of @file{sample.dat}, which has no budgeted expenses, the result
of the above command (in November 2004) is:

@smallexample
2004/01/01 - 2004/12/31         Income:Salary            $-1,000.00   $-1,000.00
                                Expenses:Books               $20.00     $-980.00
2005/01/01 - 2005/12/31         Income:Salary            $-6,000.00   $-6,980.00
2006/01/01 - 2006/12/31         Income:Salary            $-6,000.00  $-12,980.00
2007/01/01 - 2007/12/31         Income:Salary            $-6,000.00  $-18,980.00
2008/01/01 - 2008/01/01         Income:Salary              $-500.00  $-19,480.00
@end smallexample