node-ledger's Introduction

ledger-cli

API for the Ledger command-line interface (ledger-cli.org).

Ledger is a powerful, double-entry accounting system that is accessed from the UNIX command-line.

MIT License

Dependencies

Ledger 3
Node.js and npm

Installing Ledger

The simplest way to install Ledger 3 is through Homebrew.

brew install ledger --HEAD

The --HEAD option is required to install version 3.x.

Usage

Install ledger-cli and its dependencies with npm.

npm install ledger-cli

Then require the library and use the exported Ledger class to execute commands.

var Ledger = require('ledger-cli').Ledger;

You must provide the path to the Ledger journal file via the file option

var ledger = new Ledger({ file: 'path/to/ledger/journal/file.dat' });

Available commands

There are five available Ledger commands.

accounts - Lists all accounts for postings.
balance - Reports the current balance of all accounts.
print - Prints out the full transactions, sorted by date, using the same format as they would appear in a Ledger data file.
register - Displays all the postings occurring in a single account.
stats - Retrieves statistics, like number of unique accounts.
version - Gets the currently installed Ledger version number.

Accounts

Lists all accounts for postings. It returns a readable object stream.

ledger.accounts()
  .on('data', function(account) {
    // account is the name of an account (e.g. 'Assets:Current Account')
  });

Balance

The balance command reports the current balance of all accounts. It returns a readable object stream.

ledger.balance()
  .on('data', function(entry) {
    // JSON object for each entry
    entry = {
      total: {
        currency: '£',
        amount: 1000,
        formatted: '£1,000.00'
      },
      account: {
        fullname: 'Assets:Checking',
        shortname: 'Assets:Checking',
        depth: 2,
      }
    };
  })
  .once('end', function(){
    // completed
  })
  .once('error', function(error) {
    // error
  });

Print

The print command formats the full list of transactions, ordered by date, using the same format as they would appear in a Ledger data file. It returns a readable stream.

var fs = require('fs'),
    out = fs.createWriteStream('output.dat');

ledger.print().pipe(out);

Register

The register command displays all the postings occurring in a single account. It returns a readable object stream.

ledger.register()
  .on('data', function(entry) {
    // JSON object for each entry
    entry = {
      date: new Date(2014, 1, 1),
      cleared: true,
      pending: true,
      payee: 'Salary',
      postings: [{
        commodity: {
          currency: '£',
          amount: 1000,
          formatted: '£1,000.00'
        },
        account: 'Assets:Checking'
      }]
    };
  })
  .once('end', function(){
    // completed
  })
  .once('error', function(error) {
    // error
  });

Stats

The stats command is used to retrieve statistics about the Ledger data file. It requires a Node style callback function that is called with either an error or the stats object.

ledger.stats(function(err, stats) {
  if (err) { return console.error(err); }

  // stats is a map (e.g. stats['Unique accounts'] = 13)
});

Version

The version command is used to get the Ledger binary version. It requires a Node style callback function that is called with either an error or the version number as a string.

ledger.version(function(err, version) {
  if (err) { return console.error(err); }

  // version is a string (e.g. '3.0.0-20130529')
});

node-ledger's People

Contributors

Stargazers

Watchers

node-ledger's Issues

Stats returns 'Failed to parse Ledger stats' for files with no postings

I am (ab)using stats to have ledger validate some files that don't contain any posting. They could be legitimate files. Imagine a file containing only prices or a file containing only a budget. Something like

P 2016/12/31 $ £0.81

or something like

~ Monthly
Expenses:House:Rent £1000
Assets

If I invoke ledger stats from the command line I get an empty output, which triggers the error.

Is that necessary?

Output of register is incomplete

I have a file with 501 entries, but register is only returning a fraction of them (roughly between 80 and 90). As a further proof that something is broken the callback for .once('end', onEnd) is never called for my full file, but it gets called for much shorter files.

.once('error', onError) is broken as well. A malformed ledger file, even a very short one, doesn't trigger it. I only see a call to .once('end', onEnd).

This seems related to 097bfdf by @bergie so I suspect all the other functions might be affected as well.

slashdotdash / node-ledger Goto Github PK