Merge commit 'fa641c581c3e2724d61fecd28fdb70f3dbb1beec'

.gitignore

@@ -91,6 +91,7 @@ CMakeCache.txt
 CPackConfig.cmake
 CPackSourceConfig.cmake
 CMakeFiles/
+CTestTestfile.cmake
 _CPack_Packages/
 cmake_install.cmake
 install_manifest.txt

README.md

@@ -7,6 +7,15 @@ UNIX command-line.  This may put off some users, since there is no flashy UI,
 but for those who want unparalleled reporting access to their data there are
 few alternatives.
 
+Ledger uses text files for input.  It reads the files and generates reports;
+there is no other database or stored state.  To use Ledger, you create a
+file of your account names and transactions, run from the command line with
+some options to specify input and requested reports, and get output.
+The output is generally plain text, though you could generate a graph or
+html instead.  Ledger is simple in concept, surprisingly rich in ability,
+and easy to use.
+
+
 ## For the Impatient
 
 I know, you just want to build and play.  If you have all the dependencies
@@ -54,7 +63,8 @@ much further with those.
 ## Dependencies
 
 If you wish to proceed in this venture, you'll need a few dependencies.  The
-easiest way to get them for your platform is to run:
+easiest way to get them for your platform is to run this handy Python
+script:
 
     ./acprep dependencies
 
@@ -154,6 +164,7 @@ You can run `make check` to confirm the result, and `make install` to install.
 Now that you're up and running, here are a few resources to keep in mind:
 
  - [Home page](http://ledger-cli.org)
+ - [Documentation](http://www.ledger-cli.org/docs.html)
  - [IRC channel](irc://irc.freenode.net/ledger)
  - [Mailing List / Forum](http://groups.google.com/group/ledger-cli)
  - [GitHub project page](http://github.com/ledger/ledger)

doc/DEVELOP.md

@@ -0,0 +1,81 @@
+GLOSSARY
+----
+
+Developing the Ledger software uses a number different tools, not all of
+which will be familiar to all developers.
+
+[**Boost**](http://www.boost.org): a standard set of C++ libraries.  Most
+Boost libraries consist of inline functions and templates in header files.
+
+[**Cheetah**](http://www.cheetahtemplate.org): a Python templating engine,
+used by *./python/server.py*.
+
+[**CMake**](http://www.cmake.org): A cross platform system for building
+from source code.  It uses the *CMakeLists.txt* files.
+
+[**DOxygen**](http://doxygen.org): generates programming documentation from
+source code files.  Primarly used on C++ sources, but works on all.  Uses
+the *doc/Doxyfile.in* file.
+
+[**GCC**](http://gcc.gnu.org): Gnu Compiler Collection, which includes the
+*gcc* compiler and *gcov* coverage/profiler tool.
+
+[**GMP**](https://gmplib.org): Gnu Multiple Precision Arithmetic Library
+provides arbitrary precision math.
+
+[**Markdown**](https://daringfireball.net/projects/markdown/): A typesetter
+format that produces *html* files from *.md* files.  Note that GitHub
+automatically renders *.md* files.
+
+[**sha1**](http://en.wikipedia.org/wiki/SHA-1): a marginally secure
+cryptographic hash function, used only for signing the license file.
+
+[**Texinfo**](http://www.gnu.org/software/texinfo/): Gnu documentation
+typesetter that produces *html* and *pdf* files from the *doc/\*.texi*
+files.
+
+[**Travis CI**](https://travis-ci.org): a hosted continuous integration
+  service that builds and runs tests each commit posted to GitHub.  Each
+  build creates a [log](https://travis-ci.org/ledger/ledger), updates a
+  [small graphic](https://travis-ci.org/ledger/ledger.png?branch=master) at
+  the top left of the main project's
+  [README.md](https://github.com/ledger/ledger/blob/master/README.md), and
+  emails the author of the commit if any tests fail.
+
+[**utfcpp**](http://utfcpp.sourceforge.net): a library for handling utf-8
+in a variety of C++ versions.
+
+
+Orientation
+---
+
+The source tree can be confusing to a new developer.  Here is a selective
+orientation:
+
+**./acprep**: a custom thousand-line script to install dependencies, grab
+  updates, and build.  It also creates *\*.cmake*,
+  *./CmakeFiles/* and other CMake temporary files.  Use *./acprep --help*
+  for more information.
+
+**./README.md**: user readme file in markdown format, also used as the project
+  discription on GitHub.
+
+**./contrib/**: contributed scripts of random quality and completion.  They
+  usually require editing to run.
+
+**./doc/**: documentation, licenses, and
+  tools for generating documents such as the *pdf* manual.
+
+**./lib/**: a couple libraries used in development.
+
+**./lisp/**: the [Emacs](http://www.gnu.org/software/emacs/)
+  [ledger-mode](http://ledger-cli.org/3.0/doc/ledger-mode.html) lisp code,
+  under the [GPLv2](http://www.gnu.org/licenses/gpl-2.0.html) license.
+
+**./python/**:  samples using the Python ledger module.
+
+**./src/**:  the C++ header and source files in a flat directory.
+
+**./test/**:  a testing harness with subdirectories full of tests
+
+**./tools/**:  an accretion of tools, mostly small scripts, to aid development

doc/GLOSSARY.md

@@ -0,0 +1,154 @@
+ACCOUNTING GLOSSARY
+---
+
+   Accounting and bookkeeping represent an entire field of human effort and
+   has evolved its own specialized vocabulary.  Accounting hopes to
+   summarize and add understanding to where the money is going.
+
+**Account**: A category for grouping together amounts from similar
+  transactions.  Each account has a name, which is usually capitalized, and
+  an account type.  Accounts are often organized into a heirarchy when it
+  helps understanding.  For example, a coffee shop might have Coffee,
+  Merchandise, and Equipment as accounts but arranged under an Inventory
+  account because different decisions are made on the total inventory
+  rather than just coffee.  A heirarchy can be part of the account name in
+  Ledger, e.g., "Assets:Inventory:Coffee".  Note that the Ledger software
+  usually creates the list of accounts on the fly: accounts are created
+  when transactions use them.
+
+**Account Type**: Each account has a type of Asset, Liability, Equity,
+  Income, or Expense.  Assets represent something owned, e.g., Cash or
+  Inventory.  Liabilities represent sometime owed, e.g., a Loan or
+  Mortgage.  Equity, also called capital, is everything owned minus
+  everything owed (Assets - Liabilities).  It is the financial measure of
+  how much you are ahead.  Income is money earned somewhere, which puts you
+  more ahead.  Expenses is money spent somewhere, which puts you less
+  ahead.  The type of account determines if a debit represents an increase
+  or decrease in an account.  For example, Inventory is an asset so a
+  transcation debiting Inventory would increase its value.  Assets and
+  Expenses increase with debits and decrease with credits; Liabilities,
+  Equity, and Expenses increase with credits and decrease with debits.
+
+**Journal**: A record of all the financial transactions of a person or
+  firm.  This data of where money goes can be collated into reports.  This
+  used to be done with a physical book, called a ledger, where each account
+  was on one page.  Each debit or credit in the journal was transfered to
+  the appropriate account page and the pages were totalled to produce
+  reports.  This process is now done with the Ledger software which creates
+  reports from the journal.  A journal is sometimes called a register.
+
+**Posting**: A single debit or credit line of a transaction.  A posting
+comprises an account and the debit or credit amount.  It also inherits the
+shared description and date from the transaction.  In the Ledger software,
+a posting may also have metadata and an account state.
+
+
+**Report**: A summary made from a journal of transactions.  Each
+  transaction affects accounts and those effects are collated and totaled.
+  The two most common reports are the balance sheet, which shows what is
+  owned and owed on a specific date, and the cash flow statement, which
+  shows how money was earned and spent over a period.  The cash flow
+  statement is also called a profit and loss statement or an income
+  statement.
+
+**Transaction**: Our financial lives are recorded as a series of
+  transactions.  Each transaction has a specific date, an equal total of
+  debits and credits affecting accounts, and some sort of description.  For
+  example, "On January 1, pay $100 with check #243 from Checking to
+  Utilities for my Verizon phone bill" is a transaction.  A credit of $100
+  decreases my Checking asset, while a balancing debit of $100 increases my
+  Utility expense.  A transaction needs at least two *postings*, meaning
+  account debits or credits, but can be as complicated as humans can make
+  finances.
+
+LEDGER GLOSSARY
+---
+
+The Ledger software also has its own terms.
+
+**Automated Transaction**: a command directive that modifies subsequent
+  transactions that match an expression.  An automated transaction can add
+  additional postings to a transaction, add metadata, or change transaction
+  amounts.  Reports can be filter postings modified or generated by an automated
+  transaction.
+  [§ Automated Transactions](http://www.ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions);
+  [§ Concrete Example of Automated Transactions](http://www.ledger-cli.org/3.0/doc/ledger3.html#Concrete-Example-of-Automated-Transactions)
+
+**Command Directive**: a command in a journal file to change how subsequent
+lines and transactions in a journal file are processed.  Command directives
+control processing, set default values for subsequent accounts and
+transactions, or override parts of subsequent transactions.  A directive
+line begins with name of the directive and may have addidtional arguments
+or additional indented lines.  The single letters *AbCDhIiNOoY* are aliased
+to other command directives, providing compatiblity with the ancient past.
+The characters **'='** and **'-'** are command directives for a automatic
+transactions and periodic transactions, respectively.
+[§ Command Directives](http://www.ledger-cli.org/3.0/doc/ledger3.html#Command-Directives)
+
+**Commodity**: any currency, stock, time or resource to be tracked
+  numerically.  While many people only track money in Ledger, Ledger can
+  track different resources and manage rules to convert between them.  The
+  system is flexible enough for the needs of very different users.  Some
+  track billable time, converting minutes and hours into dollars.  Others
+  track multiple currencies.  Still others track the purchase and sale of
+  stocks.  Each commodity is seperate unless a conversion rule is given.
+  [§ Commodities and Currencies](http://www.ledger-cli.org/3.0/doc/ledger3.html#Commodities-and-Currencies);
+  [§ Currencies and Commodities](http://www.ledger-cli.org/3.0/doc/ledger3.html#Currency-and-Commodities);
+  [§ Accounts and Inventories](http://www.ledger-cli.org/3.0/doc/ledger3.html#Accounts-and-Inventories);
+  [§ Posting Cost](http://www.ledger-cli.org/3.0/doc/ledger3.html#Posting-cost)
+  *(and next ten sections)*;
+  [§ Commodity Reporting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Commodity-Reporting)
+
+**Effective Date**: an optional, second date information item in for a
+posting or transaction.  Some use the effective date for when work is
+billed or when a check has cleared.  The `--effective-date` option causes
+the effective date to override the transaction's initial date for that
+report.
+[§ Effective Dates](http://www.ledger-cli.org/3.0/doc/ledger3.html#Effective-Dates);
+
+**Journal File**: the text input file for ledger, sometimes called a
+register file.  A journal file is a series of transactions, command
+directives, and comments.  Command directives start with the single word
+name of the directive at the beginning of the line and include any
+following indented lines.  Transactions start with a date a the beginning
+of the line and include any indented lines following.  The journal file is
+expected to be encoded as ASCII or utf-8 text.
+
+**Periodic Transaction**: the estimate of a transaction that would occur
+  periodically, e.g., a monthly expense.  These estimates are only used in
+  budgeting and forecasting reports using the `--budget`,
+  `--forecast`, or `--unbudgeted` options.
+  [§ Budgeting and Forecasting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Budgeting-and-Forecasting)
+
+**Transaction Code**: an optional item in a transaction or posting often
+  used to record a check number or bank code.  Certain custom reports can
+  report this code.
+  [§ Codes](http://www.ledger-cli.org/3.0/doc/ledger3.html#Codes);
+  [§ Format Expressions](http://www.ledger-cli.org/3.0/doc/ledger3.html#Format-Expressions)
+
+**Transaction Metadata**: a term for comments and tags annotating a
+transaction.  Comments indented with a transaction will be stored with each
+posting of a transaction.  Tags are words in comments followed by colons.
+Tags can be used as filters in reports and certain tags, "Payee" or
+"Value", may affect fields of the transaction.
+[§ Metadata](http://www.ledger-cli.org/3.0/doc/ledger3.html#Metadata),
+[§ Applying Metadata to every matched posting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Applying-metadata-to-every-matched-posting),
+[§ Applying Metadata to the generated posting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Applying-metadata-to-the-generated-posting)
+
+**Transaction State**: a state of *cleared*, *pending*, or *uncleared* on
+each posting.  The state is usually set for an entire transaction at once
+with a mark after the date.  The marks are ***** (cleared), **!**
+(pending), or no mark (uncleared).  The interpretation of this state is up
+to the user, but is typically used in bank reconcilations or
+differentiating time worked versus billed.  Ledger supports reports and
+filters based on state.
+[§ Transaction State](http://www.ledger-cli.org/3.0/doc/ledger3.html#Transaction-state);
+[§ Cleared Report](
+http://www.ledger-cli.org/3.0/doc/ledger3.html#Cleared-Report)
+
+**Virtual Posting**: an annotation posting in a transaction, similar in form as a regular posting but not required to balance debits and
+credits.   It is often used to support
+[Fund Accounting](http://en.wikipedia.org/wiki/Fund_accounting) and various reports will collate and summarize virtual postings.  Virtual postings should not be
+confused with virtual posting costs.
+[§ Virtual Postings](http://www.ledger-cli.org/3.0/doc/ledger3.html#Virtual-postings)
+[§ Working with Multiple Funds and Accounts](http://www.ledger-cli.org/3.0/doc/ledger3.html#Working-with-multiple-funds-and-accounts)

doc/README

@@ -1,64 +0,0 @@
-
-                          Welcome to Ledger
-
-                 the command-line accounting program
-
-Introduction
-============
-
-Ledger is an accounting program which is invoked from the command-line using a
-textual ledger file.  To start using Ledger, you will need to create such a
-file containing your financial postings.  A sample has been provided in the
-file "sample.dat".  See the documentation (ledger.pdf, or ledger.info) for
-full documentation on creating a ledger file and using Ledger to generate
-reports.
-
-Once you have such a file -- you might call it "ledger.dat" -- you can start
-looking at balances and account registers using commands like the following:
-
-  ledger -f ledger.dat balance assets:checking
-  ledger -f ledger.dat register expenses:food
-
-This assumes, of course, that like the sample file you use account names such
-as "Assets:Checking" and "Expenses:Food".  If you use other account names, you
-will need to vary the reporting commands you use accordingly.
-
-
-Building
-========
-
-To build Ledger, you will need a fairly modern C++ compiler (gcc 2.95 will not
-work), and at least these two libraries installed:
-
-    gmp        GNU multi-precision library
-    pcre       Perl regular expression library
-
-(On some GNU/Linux systems, the packages you need to install are called
-"gmp-dev" and "pcre-dev").
-
-Once you have determined where the headers and libraries for the above
-packages are installed, run the script "configure", passing those paths.  If
-you installed everything under /usr/local, you can probably just type
-"./configure".  Otherwise, do this:
-
-    ./configure CPPFLAGS=-I<INCLUDE-PATH>  LDFLAGS=-L<LIBRARY-PATH>
-
-If you need to specify multiple include or library paths, then do this:
-
-    ./configure CPPFLAGS="-I<PATH1> -I<PATH2>"  LDFLAGS="-L<PATH1> -L<PATH2>"
-
-Once configure is done running, just type:
-
-    make install
-
-
-Mailing List and IRC
-====================
-
-If you need help on how to use Ledger, or run into problems, you can join the
-Ledger mailing list at the following Web address:
-
-    http://groups.google.com/group/ledger-cli
-
-You can also find help at the #ledger channel on the IRC server
-irc.freenode.net.

src/stream.cc

@@ -80,18 +80,10 @@ namespace {
       close(pfd[1]);
       close(pfd[0]);
 
-      // Find command name: its the substring starting right of the
+      execlp("/bin/sh", "/bin/sh", "-c", pager_path.string().c_str(), NULL);
-      // rightmost '/' character in the pager pathname.  See manpage for
-      // strrchr.
-#if BOOST_VERSION >= 103700
-      path basename(pager_path.filename());
-#else
-      path basename(pager_path.leaf());
-#endif
-      execlp(pager_path.string().c_str(), basename.string().c_str(), NULL);
 
       // We should never, ever reach here
-      perror((std::string("execlp: ") + pager_path.string()).c_str());
+      perror("execlp: /bin/sh");
       exit(1);
     }
     else {                      // parent

src/token.cc

@@ -522,7 +522,8 @@ void expr_t::token_t::expected(const char wanted, char c)
 void expr_t::token_t::expected(const kind_t wanted)
 {
   try {
-    if (wanted == '\0' || wanted == -1)
+    if (wanted == expr_t::token_t::ERROR ||
+        wanted == expr_t::token_t::UNKNOWN)
       throw_(parse_error, _f("Invalid token '%1%'") % *this);
     else
       throw_(parse_error,