slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add: integrate CLI help & manual

Browse Source
This commit is contained in:
Simon Michael 2019-01-26 17:13:44 -08:00
parent 53620d0df2
commit 64d78f1644
6 changed files with 179 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
hledger/Hledger/Cli/Commands/Add.hs
View File

@ -4,6 +4,7 @@ A history-aware add command to help with data entry.
{-# OPTIONS_GHC -fno-warn-missing-signatures -fno-warn-unused-do-bind #-}
{-# LANGUAGE ScopedTypeVariables, DeriveDataTypeable, RecordWildCards, TypeOperators, FlexibleContexts, OverloadedStrings, PackageImports #-}
{-# LANGUAGE TemplateHaskell #-}
module Hledger.Cli.Commands.Add (
addmode
@ -46,17 +47,12 @@ import Hledger.Cli.CliOptions
import Hledger.Cli.Commands.Register (postingsReportAsText)
addmode = (defCommandMode ["add"]) {
modeHelp = "prompt for transactions and add them to the journal"
,modeHelpSuffix = ["Defaults come from previous similar transactions; use query patterns to restrict these."]
,modeGroupFlags = Group {
groupUnnamed = [
flagNone ["no-new-accounts"] (\opts -> setboolopt "no-new-accounts" opts) "don't allow creating new accounts"
]
,groupHidden = []
,groupNamed = [generalflagsgroup2]
}
}
addmode = hledgerCommandMode
$(hereFileRelative "Hledger/Cli/Commands/Add.md")
[flagNone ["no-new-accounts"] (\opts -> setboolopt "no-new-accounts" opts) "don't allow creating new accounts"]
[generalflagsgroup2]
[]
([], Just $ argsFlag "[QUERY]")
-- | State used while entering transactions.
data EntryState = EntryState {

61
hledger/Hledger/Cli/Commands/Add.md Normal file
View File

@ -0,0 +1,61 @@
add\
Prompt for transactions and add them to the journal.
_FLAGS_
Many hledger users edit their journals directly with a text editor, or generate them from CSV.
For more interactive data entry, there is the `add` command,
which prompts interactively on the console for new transactions, and appends
them to the journal file (if there are multiple `-f FILE` options, the first file is used.)
Existing transactions are not changed.
This is the only hledger command that writes to the journal file.
To use it, just run `hledger add` and follow the prompts.
You can add as many transactions as you like; when you are finished,
enter `.` or press control-d or control-c to exit.
Features:
- add tries to provide useful defaults, using the most similar (by description)
recent transaction (filtered by the query, if any) as a template.
- You can also set the initial defaults with command line arguments.
- [Readline-style edit keys](http://tiswww.case.edu/php/chet/readline/rluserman.html#SEC3)
can be used during data entry.
- The tab key will auto-complete whenever possible - accounts,
descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
area is empty, it will insert the default value.
- If the journal defines a [default commodity](#default-commodity),
it will be added to any bare numbers entered.
- A parenthesised transaction [code](#entries) may be entered following a date.
- [Comments](#comments) and tags may be entered following a description or amount.
- If you make a mistake, enter `<` at any prompt to restart the transaction.
- Input prompts are displayed in a different colour when the terminal supports it.
Example (see the [tutorial](step-by-step.html#record-a-transaction-with-hledger-add) for a detailed explanation):
``` shell
$ hledger add
Adding transactions to journal file /src/hledger/examples/sample.journal
Any command line arguments will be used as defaults.
Use tab key to complete, readline keys to edit, enter to accept defaults.
An optional (CODE) may follow transaction dates.
An optional ; COMMENT may follow descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
Date [2015/05/22]:
Description: supermarket
Account 1: expenses:food
Amount 1: $10
Account 2: assets:checking
Amount 2 [$-10.0]:
Account 3 (or . or enter to finish this transaction): .
2015/05/22 supermarket
expenses:food $10
assets:checking $-10.0
Save this transaction to the journal ? [y]:
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $
```

15
hledger/hledger.1
View File

@ -1409,13 +1409,11 @@ $\ hledger\ activity\ \-\-quarterly
.fi
.SS add
.PP
add
.PD 0
.P
.PD
Prompt for transactions and add them to the journal.
.TP
.B \f[C]\-\-no\-new\-accounts\f[]
don\[aq]t allow creating new accounts; helps prevent typos when entering
account names
.RS
.RE
.PP
Many hledger users edit their journals directly with a text editor, or
generate them from CSV.
@ -1432,8 +1430,9 @@ enter \f[C]\&.\f[] or press control\-d or control\-c to exit.
.PP
Features:
.IP \[bu] 2
add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
add tries to provide useful defaults, using the most similar (by
description) recent transaction (filtered by the query, if any) as a
template.
.IP \[bu] 2
You can also set the initial defaults with command line arguments.
.IP \[bu] 2

189
hledger/hledger.info
View File

@ -1071,13 +1071,9 @@ File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS
4.3 add
=======
add
Prompt for transactions and add them to the journal.
'--no-new-accounts'
don't allow creating new accounts; helps prevent typos when
entering account names
Many hledger users edit their journals directly with a text editor,
or generate them from CSV. For more interactive data entry, there is the
'add' command, which prompts interactively on the console for new
@ -1092,8 +1088,9 @@ or press control-d or control-c to exit.
Features:
* add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
* add tries to provide useful defaults, using the most similar (by
description) recent transaction (filtered by the query, if any) as
a template.
* You can also set the initial defaults with command line arguments.
* Readline-style edit keys can be used during data entry.
* The tab key will auto-complete whenever possible - accounts,
@ -2768,94 +2765,94 @@ Node: activity34448
Ref: #activity34558
Node: add34941
Ref: #add35040
Node: balance37701
Ref: #balance37812
Node: Classic balance report40932
Ref: #classic-balance-report41105
Node: Customising the classic balance report42474
Ref: #customising-the-classic-balance-report42702
Node: Colour support44776
Ref: #colour-support44943
Node: Flat mode45116
Ref: #flat-mode45264
Node: Depth limited balance reports45677
Ref: #depth-limited-balance-reports45877
Node: Multicolumn balance report46333
Ref: #multicolumn-balance-report46531
Node: Budget report51771
Ref: #budget-report51914
Node: Nested budgets56598
Ref: #nested-budgets56710
Ref: #output-format-160190
Node: balancesheet60268
Ref: #balancesheet60404
Node: balancesheetequity62715
Ref: #balancesheetequity62864
Node: cashflow63401
Ref: #cashflow63529
Node: check-dates65652
Ref: #check-dates65779
Node: check-dupes65896
Ref: #check-dupes66020
Node: close66157
Ref: #close66265
Node: files69678
Ref: #files69779
Node: help69920
Ref: #help70020
Node: import71094
Ref: #import71208
Node: incomestatement71938
Ref: #incomestatement72072
Node: prices74476
Ref: #prices74591
Node: print74863
Ref: #print74973
Node: print-unique79867
Ref: #print-unique79993
Node: register80061
Ref: #register80188
Node: Custom register output84689
Ref: #custom-register-output84818
Node: register-match86048
Ref: #register-match86182
Node: rewrite86365
Ref: #rewrite86480
Node: roi86549
Ref: #roi86647
Node: stats86763
Ref: #stats86862
Node: tags87732
Ref: #tags87830
Node: test88066
Ref: #test88150
Node: ADD-ON COMMANDS88858
Ref: #add-on-commands88968
Node: Official add-ons90255
Ref: #official-add-ons90395
Node: api90482
Ref: #api90571
Node: ui90623
Ref: #ui90722
Node: web90780
Ref: #web90869
Node: Third party add-ons90915
Ref: #third-party-add-ons91090
Node: diff91225
Ref: #diff91322
Node: iadd91421
Ref: #iadd91535
Node: interest91618
Ref: #interest91739
Node: irr91834
Ref: #irr91932
Node: Experimental add-ons92063
Ref: #experimental-add-ons92215
Node: autosync92495
Ref: #autosync92606
Node: chart92845
Ref: #chart92964
Node: check93035
Ref: #check93137
Node: balance37627
Ref: #balance37738
Node: Classic balance report40858
Ref: #classic-balance-report41031
Node: Customising the classic balance report42400
Ref: #customising-the-classic-balance-report42628
Node: Colour support44702
Ref: #colour-support44869
Node: Flat mode45042
Ref: #flat-mode45190
Node: Depth limited balance reports45603
Ref: #depth-limited-balance-reports45803
Node: Multicolumn balance report46259
Ref: #multicolumn-balance-report46457
Node: Budget report51697
Ref: #budget-report51840
Node: Nested budgets56524
Ref: #nested-budgets56636
Ref: #output-format-160116
Node: balancesheet60194
Ref: #balancesheet60330
Node: balancesheetequity62641
Ref: #balancesheetequity62790
Node: cashflow63327
Ref: #cashflow63455
Node: check-dates65578
Ref: #check-dates65705
Node: check-dupes65822
Ref: #check-dupes65946
Node: close66083
Ref: #close66191
Node: files69604
Ref: #files69705
Node: help69846
Ref: #help69946
Node: import71020
Ref: #import71134
Node: incomestatement71864
Ref: #incomestatement71998
Node: prices74402
Ref: #prices74517
Node: print74789
Ref: #print74899
Node: print-unique79793
Ref: #print-unique79919
Node: register79987
Ref: #register80114
Node: Custom register output84615
Ref: #custom-register-output84744
Node: register-match85974
Ref: #register-match86108
Node: rewrite86291
Ref: #rewrite86406
Node: roi86475
Ref: #roi86573
Node: stats86689
Ref: #stats86788
Node: tags87658
Ref: #tags87756
Node: test87992
Ref: #test88076
Node: ADD-ON COMMANDS88784
Ref: #add-on-commands88894
Node: Official add-ons90181
Ref: #official-add-ons90321
Node: api90408
Ref: #api90497
Node: ui90549
Ref: #ui90648
Node: web90706
Ref: #web90795
Node: Third party add-ons90841
Ref: #third-party-add-ons91016
Node: diff91151
Ref: #diff91248
Node: iadd91347
Ref: #iadd91461
Node: interest91544
Ref: #interest91665
Node: irr91760
Ref: #irr91858
Node: Experimental add-ons91989
Ref: #experimental-add-ons92141
Node: autosync92421
Ref: #autosync92532
Node: chart92771
Ref: #chart92890
Node: check92961
Ref: #check93063

End Tag Table

22
hledger/hledger.txt
View File

@ -944,28 +944,26 @@ COMMANDS
2008-10-01 **
add
add
Prompt for transactions and add them to the journal.
--no-new-accounts
don't allow creating new accounts; helps prevent typos when
entering account names
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (if there are multiple
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (if there are multiple
-f FILE options, the first file is used.) Existing transactions are not
changed. This is the only hledger command that writes to the journal
changed. This is the only hledger command that writes to the journal
file.
To use it, just run hledger add and follow the prompts. You can add as
many transactions as you like; when you are finished, enter . or press
many transactions as you like; when you are finished, enter . or press
control-d or control-c to exit.
Features:
o add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
o add tries to provide useful defaults, using the most similar (by
description) recent transaction (filtered by the query, if any) as a
template.
o You can also set the initial defaults with command line arguments.

61
hledger/hledger_commands.m4.md
View File

@ -32,67 +32,8 @@ _include_(Hledger/Cli/Commands/Accounts.md)
_include_(Hledger/Cli/Commands/Activity.md)
## add
Prompt for transactions and add them to the journal.
`--no-new-accounts`
: don't allow creating new accounts; helps prevent typos when entering account names
Many hledger users edit their journals directly with a text editor, or generate them from CSV.
For more interactive data entry, there is the `add` command,
which prompts interactively on the console for new transactions, and appends
them to the journal file (if there are multiple `-f FILE` options, the first file is used.)
Existing transactions are not changed.
This is the only hledger command that writes to the journal file.
To use it, just run `hledger add` and follow the prompts.
You can add as many transactions as you like; when you are finished,
enter `.` or press control-d or control-c to exit.
Features:
- add tries to provide useful defaults, using the most similar recent
transaction (by description) as a template.
- You can also set the initial defaults with command line arguments.
- [Readline-style edit keys](http://tiswww.case.edu/php/chet/readline/rluserman.html#SEC3)
can be used during data entry.
- The tab key will auto-complete whenever possible - accounts,
descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
area is empty, it will insert the default value.
- If the journal defines a [default commodity](#default-commodity),
it will be added to any bare numbers entered.
- A parenthesised transaction [code](#entries) may be entered following a date.
- [Comments](#comments) and tags may be entered following a description or amount.
- If you make a mistake, enter `<` at any prompt to restart the transaction.
- Input prompts are displayed in a different colour when the terminal supports it.
Example (see the [tutorial](step-by-step.html#record-a-transaction-with-hledger-add) for a detailed explanation):
_shell_({{
$ hledger add
Adding transactions to journal file /src/hledger/examples/sample.journal
Any command line arguments will be used as defaults.
Use tab key to complete, readline keys to edit, enter to accept defaults.
An optional (CODE) may follow transaction dates.
An optional ; COMMENT may follow descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
Date [2015/05/22]:
Description: supermarket
Account 1: expenses:food
Amount 1: $10
Account 2: assets:checking
Amount 2 [$-10.0]:
Account 3 (or . or enter to finish this transaction): .
2015/05/22 supermarket
expenses:food $10
assets:checking $-10.0
Save this transaction to the journal ? [y]:
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/22]: <CTRL-D> $
}})
_include_(Hledger/Cli/Commands/Add.md)
_include_({{hledger_balance.m4.md}})