README.md (4536B) - raw
1 # Ledger.py
2
3 A simple implementation of [ledger-cli](https://github.com/ledger/ledger). This
4 implementation only covers a few commands of the original ledger-cli. This
5 project is only for educational purposes. It does not provide any advantages
6 over the original project.
7
8 # Usage
9
10 You can use this program as if it was the original **ledger-cli**, but with a
11 selected group of flags and commands:
12 ```
13 ./ledger.py [-h] [-v] [-S value-expression] [--price-db FILE] [-f FILE] Action [Action ...]
14 ```
15
16 - `-h`: Displays the usage and description of the program.
17 - `-v`: Displays the current version of the program.
18 - `-S` or `--sort`: Sorts the entries. See the [`--sort` section](#sort) for
19 more details.
20 - `--price-db`: Currently it has no purpose. See the [`--price-db`
21 section](#price-db) for more details.
22 - `-f` or `--file`: Use the specified file as an input.
23 - `Action`: The first word will be our *verb*. The *verb* describes what our
24 program will output. It currently can be `register`, `balance` or `print`.
25
26 The following words will be our *filters* for which accounts we'll work with.
27 See the [filters section](#filters) for more details.
28
29 Let's see this commands in more detail.
30
31
32 # Filters
33
34 Filters can be applied to just see a subset of all of our accounts. To use
35 filters, we'll start by describing our keywords:
36
37 ### And
38
39 ```
40 {x} and {y}
41 ```
42
43 This way, we can filter accounts if they have the text `{x}` and `{y}` in them.
44
45 > Examples:
46 >
47 > ```
48 > Expenses and Amazon
49 > ```
50 > ```
51 > Income and Job and Encora
52 > ```
53
54 ### Or
55
56 ```
57 {x} or {y}
58 ```
59 ```
60 {x} {y}
61 ```
62
63 Both ways work. We can filter accounts if they have either `{x}` or `{y}`.
64
65 > Examples:
66 > ```
67 > Assets Liabilities
68 > ```
69 > ```
70 > Assets and (Bank or Wallet)
71 > ```
72
73 ### Not
74
75 ```
76 not {x}
77 ```
78
79 Filter accounts that DO NOT have `{x}` in them.
80
81 > Examples:
82 > ```
83 > (Liabilities and not Rent) or Expenses
84 > ```
85 > ```
86 > Expenses and not (Drinks or Food)
87 > ```
88
89 ### Regex
90
91 As you've just read. Every word is treated as a regex. For this project, we are
92 using [Python's regex](https://docs.python.org/3/library/re.html). Feel free to
93 experiment with this function. The only restriction is to not use spaces, as
94 they are our limiters for keywords and such.
95
96 > Examples:
97 > ```
98 > Income and [^:]+:[^:]+:[^:]+
99 > ```
100 > ```
101 > ^Expenses and not .*tion$
102 > ```
103
104 ~~Sorry for my poor examples. I don't know about finances. ;-;~~
105
106
107 # `--file`
108
109 This flag can be used multiple times. It indicates the ledger file(s) we will be
110 working on. ~~If no file is specified, the program will read from standard input
111 (`stdin`).~~ ***NOT YET IMPLEMENTED.***
112
113
114 # `--sort`
115
116 **The `--sort` flag will always sort in ascending order.** We can sort our
117 entries in two different ways:
118
119 - `date` or `d`: Sort every entry given the date of the transaction.
120 - `amount` or `a`: Sort given the amount of the transaction. **This breaks
121 entries into individual transactions.**
122
123 ## It doesn't work on `balance`
124
125 The `--sort` flag will only make changes on the outputs of `register` and
126 `print`. The verb `balance` will **always** print in alphabetical order.
127
128
129 # `--price-db`
130
131 It points to the file that contains our prices history.
132
133 ## It doesn't work well alone
134
135 The original flag for `--price-db` is commonly used alongside other flags such
136 as `-V` or `--market`, that uses the prices history to convert all amounts into
137 our default currency. That's why currently this command doesn't have any
138 function to it. It's yet to know how we will work with this flag.
139
140
141 # Examples
142
143 ```
144 $ ./ledger.py -f index.ledger -S d register Bank
145 11-Nov-21 Payment for hard.. Bank:Paypal $350.00 $350.00
146 12-Jul-01 Partial payment .. Bank:Paypal $100.00 $450.00
147 12-Nov-16 Sold some bitcoins Bank:Paypal $42.21 $492.21
148 12-Nov-29 Purchased bitcoins Bank:Paypal $-300.00 $192.21
149 ```
150
151 ```
152 $ ./ledger.py -f index.ledger --sort a print .\*coin # In ZSH, the `*` must be escaped.
153 2013/02/20 Purchased reddit gold for the year
154 Asset:Bitcoin Wallet -10.00 BTC
155
156 2012/11/16 Sold some bitcoins
157 Asset:Bitcoin Wallet -3.50 BTC
158
159 2012/11/29 Purchased bitcoins
160 Asset:Bitcoin Wallet 15.00 BTC
161 ```
162
163 ```
164 $ ./ledger.py --file index.ledger bal Bank: Expense:
165 $192.21 Bank:Paypal
166 10.00 BTC
167 $10.00 Expense
168 $10.00 Favor
169 10.00 BTC Web Services:Reddit
170 --------------------
171 10.00 BTC
172 $202.21
173 ```