simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-12-26 20:02:27 +03:00
Code Issues Projects Releases Wiki Activity

doc: style devguide, howtos

Browse Source
This commit is contained in:
Simon Michael 2015-05-25 17:56:00 -07:00
parent 5e7fd191f2
commit 6d0343817c
4 changed files with 96 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/developer-guide.md
View File

@ -211,17 +211,21 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
On some platforms the command will be eg `gmake` instead of `make`.
4. Get the hledger repo:
git clone https://github.com/simonmichael/hledger.git
```shell
$ git clone https://github.com/simonmichael/hledger.git
```
5. You might want to install or upgrade some of these haskell developer tools.
If you're not sure, skip this step and return to it as needed.
Be sure the cabal bin directory where these are installed (eg ~/.cabal/bin) is in your PATH.
cabal update
cabal install alex happy # if you get alex/happy-related errors when building hledger
cabal install haddock # needed to build hledger API docs
cabal install shelltestrunner # needed to run hledger functional tests (may need latest git version)
cabal install hoogle hlint # maybe useful for searching API docs and checking code
```{.shell .bold}
$ cabal update
$ cabal install alex happy # if you get alex/happy-related errors when building hledger
$ cabal install haddock # needed to build hledger API docs
$ cabal install shelltestrunner # needed to run hledger functional tests (may need latest git version)
$ cabal install hoogle hlint # maybe useful for searching API docs and checking code
```
You'll also want a comfortable code editor, preferably with Haskell support.
(I use emacs + [haskell-mode](https://github.com/haskell/haskell-mode),
@ -229,10 +233,12 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
6. Install haskell libs required by hledger:
cabal update
cd hledger
cabal sandbox init # optional
make installdeps # or cabal install --only-dep ./hledger-lib ./hledger [./hledger-web]
```{.shell .bold}
$ cabal update
$ cd hledger
$ cabal sandbox init # optional
$ make installdeps # or cabal install --only-dep ./hledger-lib ./hledger [./hledger-web]
```
This will install the required dependencies from Hackage.
If you're new to cabal, you can expect problems at this stage.
@ -242,13 +248,17 @@ and the default view given by [bugs.hledger.org](http://bugs.hledger.org) exclud
7. Build with cabal:
make cabalbuild
```shell
$ make cabalbuild
```
(Tip: `make cabalCMD` runs `cabal CMD` in each of the hledger packages).
8. Build with GHC:
make bin/hledgerdev
```shell
$ make bin/hledgerdev
```
This builds hledger (and hledger-lib) with GHC directly, without using cabal,
and as quickly as possible, without optimizations (the "dev" suffix is a reminder of this).

7
doc/site/css/style.css
View File

@ -29,7 +29,12 @@ pre {
border:thin solid #eec;
/* border:none; */
}
.csv, .rules {
.csv {
background-color:#cce;
border:thin solid #aad;
/* border:none; */
}
.rules {
background-color:#eef;
border:thin solid #cce;
/* border:none; */

74
doc/site/how-to-read-csv-files.md
View File

@ -3,51 +3,55 @@
Here's a quick example of [converting a CSV file](manual.html#csv).
Say we have downloaded `checking.csv` from a bank for the first time:
"Date","Note","Amount"
"2012/3/22","DEPOSIT","50.00"
"2012/3/23","TRANSFER TO SAVINGS","-10.00"
```csv
"Date","Note","Amount"
"2012/3/22","DEPOSIT","50.00"
"2012/3/23","TRANSFER TO SAVINGS","-10.00"
```
We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [CSV rules syntax](manual.html#csv). Eg:
```rules
# skip the first CSV line (headings)
skip 1
# skip the first CSV line (headings)
skip 1
# use the first three fields in each CSV record as transaction date, description and amount respectively
fields date, description, amount
# use the first three fields in each CSV record as transaction date, description and amount respectively
fields date, description, amount
# prepend $ to CSV amounts
currency $
# prepend $ to CSV amounts
currency $
# always set the first account to assets:bank:checking
account1 assets:bank:checking
# always set the first account to assets:bank:checking
account1 assets:bank:checking
# if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings
# (if not set, it will be expenses:unknown or income:unknown)
if ~ SAVINGS
account2 assets:bank:savings
# if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings
# (if not set, it will be expenses:unknown or income:unknown)
if ~ SAVINGS
account2 assets:bank:savings
```
Now hledger can read this CSV file as journal data:
$ hledger -f checking.csv print
using conversion rules file checking.csv.rules
2012/03/22 DEPOSIT
income:unknown $-50.00
assets:bank:checking $50.00
```shell
$ hledger -f checking.csv print
using conversion rules file checking.csv.rules
2012/03/22 DEPOSIT
income:unknown $-50.00
assets:bank:checking $50.00
2012/03/23 TRANSFER TO SAVINGS
assets:bank:savings $10.00
assets:bank:checking $-10.00
2012/03/23 TRANSFER TO SAVINGS
assets:bank:savings $10.00
assets:bank:checking $-10.00
```
We might save this output as `checking.journal`, and/or merge it (manually) into the main journal file.
We could also run other commands:
$ hledger -f checking.csv balance
using conversion rules file checking.csv.rules
$50.00 assets:bank
$40.00 checking
$10.00 savings
$-50.00 income:unknown
--------------------
0
```shell
$ hledger -f checking.csv balance
using conversion rules file checking.csv.rules
$50.00 assets:bank
$40.00 checking
$10.00 savings
$-50.00 income:unknown
--------------------
0
```

54
doc/site/how-to-use-account-aliases.md
View File

@ -3,43 +3,47 @@
Here's an example of using [account aliases](manual.html#account-aliases).
Say a sole proprietor has a `personal.journal`:
2014/1/2
expenses:food $1
assets:cash
```journal
2014/1/2
expenses:food $1
assets:cash
```
and a `business.journal`:
2014/1/1
expenses:office supplies $1
assets:business checking
```journal
2014/1/1
expenses:office supplies $1
assets:business checking
```
So each entity (the business owner, and the business) has their own file with its own simple chart of accounts.
However, at tax reporting time we need to view these as a single entity (at least in the US).
In `unified.journal`, we include both files, and rewrite the personal
account names to fit into the business chart of accounts,
```journal
alias expenses = equity:draw:personal
alias assets:cash = assets:personal cash
include personal.journal
end aliases
alias ^expenses = equity:draw:personal
alias ^assets:cash = assets:personal cash
include personal.journal
end aliases
include business.journal
include business.journal
```
Now we can see the data from both files at once, and the personal account names have changed:
```shell
$ hledger -f unified.journal print
2014/01/01 # from business.journal - no aliases applied
expenses:office supplies $1
assets:business checking $-1
$ hledger -f unified.journal print
2014/01/01 # from business.journal - no aliases applied
expenses:office supplies $1
assets:business checking $-1
2014/01/02 # from personal.journal
equity:draw:personal:food $1 # <- was expenses:food
assets:personal cash $-1 # <- was assets:cash
2014/01/02 # from personal.journal
equity:draw:personal:food $1 # <- was expenses:food
assets:personal cash $-1 # <- was assets:cash
```
You can also specify aliases on the command line. This could be useful to
quickly rewrite account names when sharing a report with someone else, such as
your accountant:
$ hledger --alias 'my earning=income:business' ...
```shell
$ hledger --alias 'my earning=income:business' ...
```