sleepyfran / pledger

💰 An experimental ledger-like plain text accounting CLI

¡Hola, soy Fran! 👋

• 🗺 Living in Prague, Czech Republic 🇨🇿
• 💻 Working at Microsoft, making Microsoft Teams
• 👾 Working on a little game called Duets
• 🎸 Also making music

pledger's Issues

Journal year

All journals can begin with the year all the transactions apply to. The year is specified by an upper or lower case Y followed by the year. This year is set automatically in all transactions unless overridden by the transaction itself.

Example:

Y2021

[...]

Transaction status & tags

• Statuses indicate whether the transaction was cleared or not via an optional character before the payee or description. When omitted the transaction is taken as cleared, but if a ! is specified then it's marked as pending. Example:

09/21 ! Rent
expenses:...

• Tags are extra labels attached to the transaction. A tag is a word that can be hyphen separated (but should not include spaces) that follows a semicolon and a space inside of the payee or description. Multiple tags can be assigned by separating them with a comma. Example

09/21 Hotel ; september-madrid-trip
expenses:travel...

or

09/21 Rent | Just a comment ; some-tag,other-tag
expenses:...

Balance command

The balance (or aliased as b) command invoked as pledger balance shows a table with the current balance for each account registered with the account directive. By default it shows the balance of the account converted into the default currency (#10).

Options

Dates & periods

• -W: shows the closing balance of all accounts weekly
• -M: shows the closing balance of all accounts monthly
• -Q: shows the closing balance of all accounts in each quarter
• -Y: shows the closing balance of all accounts in each year
• --date={}: shows the closing balance of all accounts in a specific date

Other options

• --no-conversion or -n: shows the closing balance of all accounts without converting the value to the default currency

With no options, the command shows the closing balance of all accounts as of the current date, which means taking all inflow and outflow transactions to show the balance.

Check command

The check (or aliased as c) commands attempts to parse the given journal file and reports back whether the file is valid or not.

Goals

• Investigate whether there's an easy way of get the line and column that errored and show a descriptive error message

If the above is not possible then just broadcasting the error from nom should be enough for the first iteration.

Declaring payees

A payee can be declared by using the payee directive. Payees are alphanumeric strings of any length that might contain spaces and symbols. Example:

payee Apple Music
payee GitHub
payee Last.fm

Transaction parsing

Transactions are the core of the journal and represent a movement between two accounts, initially only two although planning on supporting more later on. A transaction stores:

• Date
• Payee
• Description (optional, only if | specified after payee)
• Postings
  • Account name
  • Amount

Restrictions

• Dates have to be in either YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD format. The year can be omitted only if the year was specified on the top of the journal (#1)
• The postings section must specify exactly two accounts
• Account names cannot contain spaces
• If an account name contains : then it's assumed to follow a hierarchy where each new element separated by a colon is a child of the previous one. Example: expenses:subscriptions, where subscriptions is a child of expenses
• Amounts in the postings must follow the format 145.4 EUR, which basically means an amount whose decimals are divided by a comma and the currency or commodity code (no validations on the code aside from having at least 1 letter)
• Amounts in the posting might have a value on both accounts or only one

Example

2021-10-04 GitHub | GitHub's Pro Subscription
    expenses:subscriptions 4.05 USD
    assets:checking       -4.05 USD

Y2021

10-04 GitHub
    expenses:subscriptions 4.05 USD
    assets:checking

Currency check, value & conversion

• We should fetch the value of both currencies and stock values based on the symbol provided.
• The check command should validate that the symbol specified in the currency is valid.

Declaring accounts

Accounts can be declared via the directive account which uses the same parsing logic for accounts as described in #2. Example:

Y2021

account expenses:food
account expenses:gaming

This declares to account under the parent expenses: food and gaming.

Default currency

This directive, declared via the currency keyword, sets the default base currency that all the other currencies specified in the journal will be converted into. Example:

currency CZK

Comments

Comments are lines that are completely ignored when parsing. For now we'll only support line C-style comments. Example:

// This is a valid comment
09/10 Test
expenses:test...

This is not valid (for now):

09/10 Test
expenses:test 40 USD // This is not a valid comment
assets:...

Account listing command

The command accounts invoked as pledger accounts shows a list of accounts that are registered through the account directive.