diff --git a/Justfile b/Justfile index 02abd3d83..822efc51c 100644 --- a/Justfile +++ b/Justfile @@ -1,5 +1,5 @@ #!/usr/bin/env just -# * Project scripts, using https://github.com/casey/just (last tested with 1.16.0) +# * Project scripts, using https://github.com/casey/just (last tested with 1.24.0) # Usage: alias j=just, run j to list available scripts. # # After many years with make and plain shell and haskell for @@ -22,7 +22,7 @@ # (highlight-lines-matching-regexp "^@?\\w.*\\w:$" 'hi-pink) ; recipe headings (misses recipes with dependencies) # )) # -# This file is formatted by `just _fmt`, which currently eats blank lines a bit (and commits). +# This file is formatted by `just format`, which currently eats blank lines a bit (and commits). # # 'set export' makes constants and arguments available as $VAR as well as {{ VAR }}. # $ makes just code more like shell code. @@ -59,9 +59,9 @@ alias h := help @check: just --fmt --unstable --check -# if this justfile is error free but in non-standard format, reformat and commit it +# if this justfile is error free but in non-standard format, reformat it, and if it has changes, commit it @format: - just -q chk || just --fmt --unstable && git commit -m ';just: format' -- {{ justfile() }} + just -q chk || just -q --fmt --unstable && git diff --quiet || git commit -m ';just: format' -- {{ justfile() }} # rerun RECIPE when any watched-by-default file changes watch RECIPE *JOPTS: @@ -87,13 +87,14 @@ _watchgitdbg *WOPTS: BROWSE := 'open' # XXX These often don't work well interpolated as $CMD or {{ CMD }}, not sure why - # find GNU tools, eg on mac -GDATE := `type -P gdate || echo date` -GTAR := `type -P gtar || echo tar` -#GNUTAR := `which gtar >/dev/null && echo gtar || echo tar` +GDATE := `type -P gdate || echo date` +GTAR := `type -P gtar || echo tar` + +#GNUTAR := `which gtar >/dev/null && echo gtar || echo tar` # make ghc usable for scripting with -e + GHC := 'ghc -ignore-dot-ghci -package-env -' GHCI := 'ghci' @@ -204,8 +205,8 @@ DOCSOURCEFILES := ' CONTRIBUTING.md ' + MANUALSOURCEFILES + COMMANDHELPFILES TESTFILES := `fd '\.test$' --exclude ledger-compat` -# XXX it's fd-find on gnu/linux ? +# XXX it's fd-find on gnu/linux ? # # file(s) which require recompilation for a build to have an up-to-date version string # VERSIONSOURCEFILE := 'hledger/Hledger/Cli/Version.hs' # Two or three-part version string, set as program version in builds made by this makefile. @@ -246,55 +247,30 @@ BUILDFLAGS := '-rtsopts ' + WARNINGS + GHCLOWMEMFLAGS + CABALMACROSFLAGS + ' -DD TIME := "{{ shell date +'%Y%m%d%H%M' }}" MONTHYEAR := "{{ shell date +'%B %Y' }}" -# ** ghci ------------------------------------------------------------ -GHCI: +# ** Building ------------------------------------------------------------ +BUILDING: -# run ghci on hledger-lib + hledger -@ghci: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger/Hledger/Cli.hs +# build the hledger package showing ghc codegen times/allocations +@buildtimes: + time ($STACK build hledger --force-dirty --ghc-options='-fforce-recomp -ddump-timings' 2>&1 | grep -E '\bCodeGen \[.*time=') -# run ghci on hledger-lib + hledger with profiling/call stack information -@ghci-prof: - stack build --profile hledger --only-dependencies - $STACKGHCI exec -- $GHCI $BUILDFLAGS -fexternal-interpreter -prof -fprof-auto hledger/Hledger/Cli.hs - -# # run ghci on hledger-lib + hledger + dev.hs script -# @ghci-dev: -# $STACKGHCI exec -- $GHCI $BUILDFLAGS -fno-warn-unused-imports -fno-warn-unused-binds dev.hs - -# run ghci on hledger-lib + hledger + hledger-ui -@ghci-ui: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-ui/Hledger/UI/Main.hs - -# run ghci on hledger-lib + hledger + hledger-web -@ghci-web: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/app/main.hs - -# run ghci on hledger-lib + hledger + hledger-web + hledger-web test suite -@ghci-web-test: - $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/test/test.hs - -# # better than stack exec ? -# # XXX does not see changes to files -# # run ghci on hledger-lib + test runner -# ghci-lib-test: -# $STACKGHCI ghci --ghc-options="\'-rtsopts {{ WARNINGS }} -ihledger-lib -DDEVELOPMENT -DVERSION=\"1.26.99\"\'" hledger-lib/test/unittest.hs -# run ghci on all the hledger -# ghci-all: -# $STACK exec -- $GHCI $BUILDFLAGS \ -# hledger-ui/Hledger/UI/Main.hs \ -# hledger-web/app/main.hs \ - -# run ghci on hledger-lib doctests -@ghci-doctest: - cd hledger-lib; $STACKGHCI ghci hledger-lib:test:doctest - -# run ghci on Shake.hs -@ghci-shake: - $STACK exec {{ SHAKEDEPS }} -- ghci Shake.hs - -# ** ghcid ------------------------------------------------------------ -GHCID: +# # build an unoptimised hledger at bin/hledger.EXT.unopt (default: git describe) +# build-unopt *EXT: +# #!/usr/bin/env bash +# ext={{ if EXT == '' { `git describe --tags` } else { EXT } }} +# exe="bin/hledger.$ext.unopt" +# $STACK --verbosity=error install --ghc-options=-O0 hledger --local-bin-path=bin +# mv bin/hledger "$exe" +# echo "$exe" +# # build hledger with profiling enabled at bin/hledgerprof +# hledgerprof: +# # $STACK --verbosity=error install --local-bin-path=bin hledger +# $STACK build --profile hledger +# # hledger-lib --ghc-options=-fprof-auto +# # @echo "to profile, use $STACK exec --profile -- hledger ..." +# # build "bin/hledgercov" for coverage reports (with ghc) +# hledgercov: +# $STACK ghc {{ MAIN }} -fhpc -o bin/hledgercov -outputdir .hledgercovobjs $BUILDFLAGS # run ghcid on hledger-lib + hledger @ghcid: @@ -349,7 +325,53 @@ SHAKEDEPS := '\ ghcid-shake: stack exec {{ SHAKEDEPS }} -- ghcid Shake.hs -# ** dev.hs script ------------------------------------------------------------ +# ** Testing ------------------------------------------------------------ +TESTING: + +# run ghci on hledger-lib + hledger +@ghci: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger/Hledger/Cli.hs + +# run ghci on hledger-lib + hledger with profiling/call stack information +@ghci-prof: + stack build --profile hledger --only-dependencies + $STACKGHCI exec -- $GHCI $BUILDFLAGS -fexternal-interpreter -prof -fprof-auto hledger/Hledger/Cli.hs + +# # run ghci on hledger-lib + hledger + dev.hs script +# @ghci-dev: +# $STACKGHCI exec -- $GHCI $BUILDFLAGS -fno-warn-unused-imports -fno-warn-unused-binds dev.hs + +# run ghci on hledger-lib + hledger + hledger-ui +@ghci-ui: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-ui/Hledger/UI/Main.hs + +# run ghci on hledger-lib + hledger + hledger-web +@ghci-web: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/app/main.hs + +# run ghci on hledger-lib + hledger + hledger-web + hledger-web test suite +@ghci-web-test: + $STACKGHCI exec -- $GHCI $BUILDFLAGS hledger-web/test/test.hs + +# # better than stack exec ? +# # XXX does not see changes to files +# # run ghci on hledger-lib + test runner +# ghci-lib-test: +# $STACKGHCI ghci --ghc-options="\'-rtsopts {{ WARNINGS }} -ihledger-lib -DDEVELOPMENT -DVERSION=\"1.26.99\"\'" hledger-lib/test/unittest.hs +# run ghci on all the hledger +# ghci-all: +# $STACK exec -- $GHCI $BUILDFLAGS \ +# hledger-ui/Hledger/UI/Main.hs \ +# hledger-web/app/main.hs \ + +# run ghci on hledger-lib doctests +@ghci-doctest: + cd hledger-lib; $STACKGHCI ghci hledger-lib:test:doctest + +# run ghci on Shake.hs +@ghci-shake: + $STACK exec {{ SHAKEDEPS }} -- ghci Shake.hs + # # hledger-lib/Hledger/Read/TimeclockReaderPP.hs # # build the dev.hs script for quick experiments (with ghc) # dev: @@ -372,34 +394,6 @@ ghcid-shake: # curl -F "file=@devprof-hc.hp" -F "title='hledger parser'" http://heap.ezyang.com/upload # curl -F "file=@devprof-hr.hp" -F "title='hledger parser'" http://heap.ezyang.com/upload -# ** Building ------------------------------------------------------------ -BUILDING: - -# build the hledger package showing ghc codegen times/allocations -@buildtimes: - time ($STACK build hledger --force-dirty --ghc-options='-fforce-recomp -ddump-timings' 2>&1 | grep -E '\bCodeGen \[.*time=') - -# # build an unoptimised hledger at bin/hledger.EXT.unopt (default: git describe) -# build-unopt *EXT: -# #!/usr/bin/env bash -# ext={{ if EXT == '' { `git describe --tags` } else { EXT } }} -# exe="bin/hledger.$ext.unopt" -# $STACK --verbosity=error install --ghc-options=-O0 hledger --local-bin-path=bin -# mv bin/hledger "$exe" -# echo "$exe" -# # build hledger with profiling enabled at bin/hledgerprof -# hledgerprof: -# # $STACK --verbosity=error install --local-bin-path=bin hledger -# $STACK build --profile hledger -# # hledger-lib --ghc-options=-fprof-auto -# # @echo "to profile, use $STACK exec --profile -- hledger ..." -# # build "bin/hledgercov" for coverage reports (with ghc) -# hledgercov: -# $STACK ghc {{ MAIN }} -fhpc -o bin/hledgercov -outputdir .hledgercovobjs $BUILDFLAGS - -# ** Testing ------------------------------------------------------------ -TESTING: - # run tests that are reasonably quick (files, unit, functional) and benchmarks test: filestest functest @@ -492,6 +486,18 @@ ADDONEXTS := 'pl py rb sh hs lhs rkt exe com bat' mkdir hledger/test/addons/hledger-addondir chmod +x hledger/test/addons/hledger-* +# compare hledger's and ledger's balance report +compare-balance: + #!/usr/bin/env bash + for f in examples/1txns-1accts.journal \ + examples/10txns-10accts.journal \ + ; do \ + (export f=$f; \ + printf "\n-------------------------------------------------------------------------------\n"; \ + echo "comparing hledger -f $f balance and ledger -f $f balance --flat"; \ + difft --color=always --display side-by-side-show-both <(hledger -f $f balance) <(ledger -f $f balance --flat) ) | tail +2; \ + done + # generate a hlint report # hlinttest hlint: # hlint --hint=hlint --report=hlint.html {{ SOURCEFILES }} @@ -513,6 +519,53 @@ ADDONEXTS := 'pl py rb sh hs lhs rkt exe com bat' installtest: cd; {{ justfile_directory() }}/hledger-install/hledger-install.sh +# ** Installing ------------------------------------------------------------ +INSTALLING: + +# # copy the current ~/.local/bin/hledger to bin/old/hledger-VER +# @copy-as VER: +# cp ~/.local/bin/hledger bin/old/hledger-{{ VER }}; echo "bin/hledger-{{ VER }}" + +# stack install, then copy the hledger executables to bin/old/hledger*-VER +@installas VER: + $STACK install --local-bin-path bin/old + for e in hledger hledger-ui hledger-web ; do cp bin/old/$e bin/old/$e-{{ VER }}; echo "bin/$e-{{ VER }}"; done + +# # make must be GNU Make 4.3+ +# .PHONY: shellcompletions +# # update shell completions in hledger package +# shellcompletions: +# make -C hledger/shell-completion/ clean-all all + +# download a recent set of hledger versions from github releases to bin/hledger-VER +get-binaries: + for V in 1.32.2 1.31 1.30 1.29.2 1.28 1.27.1; do just get-binary $OS x64 $V; done + just symlink-binaries + +# download hledger version VER for OS (linux, mac windows) and ARCH (x64) from github releases to bin/hledger-VER + +# On gnu/linux: can't interpolate GTAR here for some reason, and need the shebang line. +get-binary OS ARCH VER: + #!/usr/bin/env bash + cd bin && curl -Ls https://github.com/simonmichael/hledger/releases/download/{{ VER }}/hledger-{{ OS }}-{{ ARCH }}.zip | funzip | `type -P gtar || echo tar` xf - hledger --transform 's/$/-{{ VER }}/' + +# add easier symlinks for all the minor hledger releases downloaded by get-binaries. +symlink-binaries: + just symlink-binary 1.32.2 + just symlink-binary 1.29.2 + just symlink-binary 1.27.1 + +# add an easier symlink for this minor hledger release (hledger-1.29 -> hledger-1.29.2, etc.) +@symlink-binary MINORVER: + cd bin && ln -sf hledger-$MINORVER hledger-`echo $MINORVER | sed -E 's/\.[0-9]+$//'` + +# sym-link some directories required by hledger-web dev builds +symlink-web-dirs: + echo "#ln -sf hledger-web/config # disabled, causes makeinfo warnings" + ln -sf hledger-web/messages + ln -sf hledger-web/static + ln -sf hledger-web/templates + # ** Benchmarking ------------------------------------------------------------ BENCHMARKING: @@ -571,29 +624,9 @@ samplejournals: # The current OS name, in the form used for hledger release binaries: linux, mac, windows or other. # can't use $GHC or {{GHC}} here for some reason + OS := `ghc -ignore-dot-ghci -package-env - -e 'import System.Info' -e 'putStrLn $ case os of "darwin"->"mac"; "mingw32"->"windows"; "linux"->"linux"; _->"other"'` -# download a recent set of hledger versions from github releases to bin/hledger-VER -get-binaries: - for V in 1.32.2 1.31 1.30 1.29.2 1.28 1.27.1; do just get-binary $OS x64 $V; done - just symlink-binaries - -# download hledger version VER for OS (linux, mac windows) and ARCH (x64) from github releases to bin/hledger-VER -# On gnu/linux: can't interpolate GTAR here for some reason, and need the shebang line. -get-binary OS ARCH VER: - #!/usr/bin/env bash - cd bin && curl -Ls https://github.com/simonmichael/hledger/releases/download/{{ VER }}/hledger-{{ OS }}-{{ ARCH }}.zip | funzip | `type -P gtar || echo tar` xf - hledger --transform 's/$/-{{ VER }}/' - -# add easier symlinks for all the minor hledger releases downloaded by get-binaries. -symlink-binaries: - just symlink-binary 1.32.2 - just symlink-binary 1.29.2 - just symlink-binary 1.27.1 - -# add an easier symlink for this minor hledger release (hledger-1.29 -> hledger-1.29.2, etc.) -@symlink-binary MINORVER: - cd bin && ln -sf hledger-$MINORVER hledger-`echo $MINORVER | sed -E 's/\.[0-9]+$//'` - # tools/generatejournal.hs 3 5 5 --chinese > examples/chinese.journal # don't regenerate, keep the simple version # $ just --set BENCHEXES ledger,hledger bench @@ -602,20 +635,14 @@ symlink-binaries: printf "Running quick benchmarks (times are approximate, can be skewed):\n" which quickbench >/dev/null && quickbench {{ ARGS }} || echo "quickbench not installed (see bench.sh), skipping" -@bench-quick8: - quickbench -w hledger-1.23,hledger-1.24,hledger-1.25,hledger-1.26,hledger-1.28,hledger-1.29,hledger-21ad,ledger - -@bench-quick3: - quickbench -w hledger-1.26,hledger-21ad,ledger '_ -f examples/10ktxns-1kaccts.journal print' '_ -f examples/10ktxns-1kaccts.journal register' '_ -f examples/10ktxns-1kaccts.journal balance' - -@bench-gtime: - for args in '-f examples/10ktxns-1kaccts.journal print' '-f examples/100ktxns-1kaccts.journal register' '-f examples/100ktxns-1kaccts.journal balance'; do \ - echo; \ - for app in hledger-1.26 hledger-21ad ledger; do \ - echo; echo $app $args:; \ - gtime $app $args >/dev/null; \ - done; \ - done +# @bench-gtime: +# for args in '-f examples/10ktxns-1kaccts.journal print' '-f examples/100ktxns-1kaccts.journal register' '-f examples/100ktxns-1kaccts.journal balance'; do \ +# echo; \ +# for app in hledger-1.26 hledger-21ad ledger; do \ +# echo; echo $app $args:; \ +# gtime $app $args >/dev/null; \ +# done; \ +# done # show throughput at various data sizes with the given hledger executable (requires samplejournals) @bench-throughput EXE: @@ -633,28 +660,15 @@ symlink-binaries: stack build hledger stack exec -- just throughput hledger +# show throughput of recent hledger versions (requires samplejournals) @bench-throughput-recent: - for v in 1.25 1.28 1.29 1.32 21ad; do printf "\nhledger-$v:\n"; for i in `seq 1 3`; do hledger-$v -f examples/10ktxns-10kaccts.journal stats | grep throughput; done; done - -@bench-balance-many-accts: - quickbench -w hledger-1.26,hledger-21ad,ledger -f bench-many-accts.sh -N2 - #quickbench -w hledger-1.25,hledger-1.28,hledger-1.29,hledger-1.30,hledger-1.31,hledger-1.32,hledger-21ad,ledger -f bench-many-accts.sh -N2 - -@bench-balance-many-txns: - quickbench -w hledger-21ad,ledger -f bench-many-txns.sh -N2 - -# examples/100txns-100accts.journal \ -compare-balance: - #!/usr/bin/env bash - for f in examples/1txns-1accts.journal \ - examples/10txns-10accts.journal \ - ; do \ - (export f=$f; \ - printf "\n-------------------------------------------------------------------------------\n"; \ - echo "comparing hledger -f $f balance and ledger -f $f balance --flat"; \ - difft --color=always --display side-by-side-show-both <(hledger -f $f balance) <(ledger -f $f balance --flat) ) | tail +2; \ - done + for v in 1.25 1.28 1.29 1.32 1.32.3; do printf "\nhledger-$v:\n"; for i in `seq 1 3`; do hledger-$v -f examples/10ktxns-10kaccts.journal stats | grep throughput; done; done +# @bench-balance-many-accts: +# quickbench -w hledger-1.26,hledger-21ad,ledger -f bench-many-accts.sh -N2 +# #quickbench -w hledger-1.25,hledger-1.28,hledger-1.29,hledger-1.30,hledger-1.31,hledger-1.32,hledger-21ad,ledger -f bench-many-accts.sh -N2 +# @bench-balance-many-txns: +# quickbench -w hledger-21ad,ledger -f bench-many-txns.sh -N2 # samplejournals bench.sh # bench: samplejournals tests/bench.tests tools/simplebench \ # $(call def-help,bench,\ @@ -674,7 +688,6 @@ compare-balance: # run progression benchmark tests and save graphical results\ # ) # tools/progressionbench -- -t png -k png - # # prof: samplejournals \ # # $(call def-help,prof,\ # # generate and archive an execution profile\ @@ -745,12 +758,6 @@ DOCUMENTING: # see also Shake.hs # http://www.haskell.org/haddock/doc/html/invoking.html -# optimise and commit RELEASING value map diagram -@releasediag: - pngquant doc/HledgerReleaseValueMap.png -f -o doc/HledgerReleaseValueMap.png - git add doc/HledgerReleaseValueMap.png - git commit -m ';doc: RELEASING: update value map' -- doc/HledgerReleaseValueMap.png - STACKHADDOCK := 'time ' + STACK + ' --verbosity=error haddock --fast --no-keep-going \ --only-locals --no-haddock-deps --no-haddock-hyperlink-source \ --haddock-arguments="--no-warnings" \ @@ -832,95 +839,20 @@ haddock-open: # @(printf "\nbrowser will open in $(BROWSEDELAY)s (adjust BROWSE in Makefile if needed)...\n\n"; sleep $(BROWSEDELAY); $(BROWSE) $(LOCALSITEURL)) & # @$(WATCHEXEC) --print-events -e md,m4 -i hledger.md -i hledger-ui.md -i hledger-web.md -r './Shake webmanuals && ./Shake orgfiles && make -sC site serve' -# ** Installing ------------------------------------------------------------ -INSTALLING: - -# # copy the current ~/.local/bin/hledger to bin/old/hledger-VER -# @copy-as VER: -# cp ~/.local/bin/hledger bin/old/hledger-{{ VER }}; echo "bin/hledger-{{ VER }}" - -# stack install, then copy the hledger executables to bin/old/hledger*-VER -@installas VER: - $STACK install --local-bin-path bin/old - for e in hledger hledger-ui hledger-web ; do cp bin/old/$e bin/old/$e-{{ VER }}; echo "bin/$e-{{ VER }}"; done - -# # make must be GNU Make 4.3+ -# .PHONY: shellcompletions -# # update shell completions in hledger package -# shellcompletions: -# make -C hledger/shell-completion/ clean-all all - -# ** Releasing ------------------------------------------------------------ -RELEASING: - -# Symlink/copy important files temporarily in .relfiles/. -relfiles: - #!/usr/bin/env bash - echo "linking/copying important release files in .relfiles/ for convenient access..." - mkdir -p .relfiles - cd .relfiles - for f in \ - ../stack.yaml \ - ../Shake.hs \ - ../hledger-install/hledger-install.sh \ - ../CHANGES.md \ - ../hledger/CHANGES.md \ - ../hledger-ui/CHANGES.md \ - ../hledger-web/CHANGES.md \ - ../hledger-lib/CHANGES.md \ - ../doc/github-release.md \ - ../doc/ANNOUNCE \ - ../doc/ANNOUNCE.masto \ - ../site/src/release-notes.md \ - ../site/src/install.md \ - ; do ln -sf $f .; done - cp ../doc/RELEASING.md ./RELEASING2.md # temp copy which can be edited without disruption - -# Prepare to release today, creating/switching to release branch, updating versions, dates, manuals, changelogs etc. -relprep VER: - #!/usr/bin/env bash - set -euo pipefail - [[ -z {{ VER }} ]] && usage - BRANCH=$(just _versionReleaseBranch {{ VER }}) - COMMIT="-c" - echo "Switching to $BRANCH, auto-creating it if needed..." - just _gitSwitchAutoCreate "$BRANCH" - echo "Bumping all version strings to {{ VER }} ..." - ./Shake setversion {{ VER }} $COMMIT - echo "Updating all command help texts for embedding..." - ./Shake cmdhelp $COMMIT - echo "Updating all dates in man pages..." - ./Shake mandates - echo "Generating all the manuals in all formats...." - ./Shake manuals $COMMIT - echo "Updating CHANGES.md files with latest commits..." - ./Shake changelogs $COMMIT - -# Push the current branch to github to generate release binaries. -@relbin: - # assumes the github remote is named "github" - git push -f github HEAD:binaries - -# Show last release date (of hledger package). -@reldate: - awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{print $3;exit}' hledger/CHANGES.md - -# Show last release date and version (of hledger package). -@rel: - just rels | head -1 - -# Show all release dates and versions (of hledger package). -@rels: - awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{printf "%s %s\n",$3,$2}' hledger/CHANGES.md +# optimise and commit RELEASING value map diagram +@releasediag: + pngquant doc/HledgerReleaseValueMap.png -f -o doc/HledgerReleaseValueMap.png + git add doc/HledgerReleaseValueMap.png + git commit -m ';doc: RELEASING: update value map' -- doc/HledgerReleaseValueMap.png # Convert DATEARG to an ISO date. It can be an ISO date, number of recent days, or nothing (meaning last release date). -@datearg *DATEARG: +@_datearg *DATEARG: echo {{ if DATEARG == '' { `just reldate` } else { if DATEARG =~ '^\d+$' { `dateadd $(date +%Y-%m-%d) -$DATEARG` } else { DATEARG } } }} # Show activity since (mostly) this date or days ago or last release. Eg: just log > log.org log *DATEARG: #!/usr/bin/env osh - DATE=`just datearg $DATEARG` + DATE=`just _datearg $DATEARG` printf "* Activity since $DATE:\n\n" printf "Last release: `just rel`\n\n" just chlog @@ -954,7 +886,7 @@ GITLG := "git log --format='%ad %h %s' --date=short" # Show commits in the three repos since this date or days ago or last release, briefly. commitlog *DATEARG: #!/usr/bin/env osh - DATE=`just datearg $DATEARG` + DATE=`just _datearg $DATEARG` printf "** hledger commits\n\n" {{ GITLG }} --since $DATE echo @@ -1037,16 +969,79 @@ bloglog: echo "** pta.o: https://plaintextaccounting.org/#`date +%Y`" echo -# Some evil works against this.. -# echo "open https://www.reddit.com/r/plaintextaccounting/new, copy links since $DAYS days ago ($DATE), paste into obsidian, select, cut, and paste here for cleaning (in emacs shell use C-c C-d, C-c C-r)" -# just redditclean > $$.tmp -# printf "\n\n\n\n\n" -# cat $$.tmp -# rm -f $$.tmp -# -# Clean links copied from old.reddit.com. -@redditclean: - rg '^(\[.*?]\([^\)]+\)).*self.plaintextaccounting' -or '- $1\n' - +# # Some evil works against this.. +# # echo "open https://www.reddit.com/r/plaintextaccounting/new, copy links since $DAYS days ago ($DATE), paste into obsidian, select, cut, and paste here for cleaning (in emacs shell use C-c C-d, C-c C-r)" +# # just redditclean > $$.tmp +# # printf "\n\n\n\n\n" +# # cat $$.tmp +# # rm -f $$.tmp +# # +# # Clean links copied from old.reddit.com. +# @redditclean: +# rg '^(\[.*?]\([^\)]+\)).*self.plaintextaccounting' -or '- $1\n' - + +# ** Releasing ------------------------------------------------------------ +RELEASING: + +# Symlink/copy important files temporarily in .relfiles/. +relfiles: + #!/usr/bin/env bash + echo "linking/copying important release files in .relfiles/ for convenient access..." + mkdir -p .relfiles + cd .relfiles + for f in \ + ../stack.yaml \ + ../Shake.hs \ + ../hledger-install/hledger-install.sh \ + ../CHANGES.md \ + ../hledger/CHANGES.md \ + ../hledger-ui/CHANGES.md \ + ../hledger-web/CHANGES.md \ + ../hledger-lib/CHANGES.md \ + ../doc/github-release.md \ + ../doc/ANNOUNCE \ + ../doc/ANNOUNCE.masto \ + ../site/src/release-notes.md \ + ../site/src/install.md \ + ; do ln -sf $f .; done + cp ../doc/RELEASING.md ./RELEASING2.md # temp copy which can be edited without disruption + +# Prepare to release today, creating/switching to release branch, updating versions, dates, manuals, changelogs etc. +relprep VER: + #!/usr/bin/env bash + set -euo pipefail + [[ -z {{ VER }} ]] && usage + BRANCH=$(just _versionReleaseBranch {{ VER }}) + COMMIT="-c" + echo "Switching to $BRANCH, auto-creating it if needed..." + just _gitSwitchAutoCreate "$BRANCH" + echo "Bumping all version strings to {{ VER }} ..." + ./Shake setversion {{ VER }} $COMMIT + echo "Updating all command help texts for embedding..." + ./Shake cmdhelp $COMMIT + echo "Updating all dates in man pages..." + ./Shake mandates + echo "Generating all the manuals in all formats...." + ./Shake manuals $COMMIT + echo "Updating CHANGES.md files with latest commits..." + ./Shake changelogs $COMMIT + +# Push the current branch to github to generate release binaries. +@relbin: + # assumes the github remote is named "github" + git push -f github HEAD:binaries + +# Show last release date (of hledger package). +@reldate: + awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{print $3;exit}' hledger/CHANGES.md + +# Show last release date and version (of hledger package). +@rel: + just rels | head -1 + +# Show all release dates and versions (of hledger package). +@rels: + awk '/^#+ +[0-9]+\.[0-9].*([0-9]{4}-[0-9]{2}-[0-9]{2})/{printf "%s %s\n",$3,$2}' hledger/CHANGES.md # *** hledger version number helpers # (as hidden recipes, since just doesn't support global custom functions) @@ -1288,9 +1283,9 @@ sccv: # ** Misc ------------------------------------------------------------ MISC: -# push to github CI, wait for tests to pass, then push to master -@push: - tools/push +# push to github CI, wait for tests to pass, refreshing every INTERVAL (default:10s), then push to master. +@push *INTERVAL: + tools/push {{ INTERVAL }} # run some tests to validate the development environment # check-setup: @@ -1300,13 +1295,6 @@ MISC: # @({{ SHELLTEST }} checks \ # && echo $@ PASSED) || echo $@ FAILED -# sym-link some directories required by hledger-web dev builds -mkwebdirs: - echo "#ln -sf hledger-web/config # disabled, causes makeinfo warnings" - ln -sf hledger-web/messages - ln -sf hledger-web/static - ln -sf hledger-web/templates - # Show activity over the last N days (eg 7), for This Week In Hledger. @_lastweek DAYS: echo "hledger time last $DAYS days including today (this should be run on a Friday):" diff --git a/Shake.hs b/Shake.hs index 28db69032..1c4d99a6c 100755 --- a/Shake.hs +++ b/Shake.hs @@ -1,5 +1,5 @@ #!/usr/bin/env stack -{- stack script --resolver nightly-2023-10-13 --compile +{- stack script --resolver nightly-2024-02-28 --compile --extra-include-dirs /Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/usr/include/ffi --package base-prelude --package directory diff --git a/hledger-lib/Hledger/Data/Amount.hs b/hledger-lib/Hledger/Data/Amount.hs index 2aec34e9d..844ad4431 100644 --- a/hledger-lib/Hledger/Data/Amount.hs +++ b/hledger-lib/Hledger/Data/Amount.hs @@ -97,7 +97,7 @@ module Hledger.Data.Amount ( amountSetPrecisionMax, withPrecision, amountSetFullPrecision, - amountSetFullPrecisionOr, + amountSetFullPrecisionUpTo, amountInternalPrecision, amountDisplayPrecision, defaultMaxPrecision, @@ -159,6 +159,7 @@ module Hledger.Data.Amount ( wbUnpack, mixedAmountSetPrecision, mixedAmountSetFullPrecision, + mixedAmountSetFullPrecisionUpTo, mixedAmountSetPrecisionMin, mixedAmountSetPrecisionMax, @@ -453,24 +454,26 @@ amountSetFullPrecision a = amountSetPrecision p a -- | We often want to display "infinite decimal" amounts rounded to some readable --- number of digits, while still displaying amounts with a large "non infinite" number --- of decimal digits (eg, 100 or 200 digits) in full. +-- number of digits, while still displaying amounts with a large but "non infinite" +-- number of decimal digits (eg 10 or 100 or 200 digits) in full. -- This helper is like amountSetFullPrecision, but with some refinements: --- 1. If the internal precision is the maximum (255), indicating an infinite decimal, --- the display precision is set to a smaller hard-coded default (8). --- 2. A maximum display precision can be specified, setting a hard upper limit. +-- +-- 1. A maximum display precision can be specified, setting a hard upper limit. +-- +-- 2. If no limit is specified, and the internal precision is the maximum (255), +-- indicating an infinite decimal, display precision is set to a smaller default (8). +-- -- This function always sets an explicit display precision (ie, Precision n). -amountSetFullPrecisionOr :: Maybe Word8 -> Amount -> Amount -amountSetFullPrecisionOr mmaxp a = amountSetPrecision (Precision p2) a +-- +amountSetFullPrecisionUpTo :: Maybe Word8 -> Amount -> Amount +amountSetFullPrecisionUpTo mmaxp a = amountSetPrecision (Precision p) a where - p1 = if -- dbg0 "maxdigits" $ - amountHasMaxDigits a then defaultMaxPrecision else max disp intp - -- & dbg0 "p1" + p = case mmaxp of + Just maxp -> min maxp $ max disp intp + Nothing -> if amountHasMaxDigits a then defaultMaxPrecision else max disp intp where - intp = amountInternalPrecision a disp = amountDisplayPrecision a - p2 = maybe p1 (min p1) mmaxp - -- & dbg0 "p2" + intp = amountInternalPrecision a -- | The fallback display precision used when showing amounts -- representing an infinite decimal. @@ -1228,6 +1231,14 @@ mixedAmountSetPrecision p = mapMixedAmountUnsafe (amountSetPrecision p) mixedAmountSetFullPrecision :: MixedAmount -> MixedAmount mixedAmountSetFullPrecision = mapMixedAmountUnsafe amountSetFullPrecision +-- | In each component amount, increase the display precision sufficiently +-- to render it exactly if possible, but not more than the given max precision, +-- and if no max precision is given and the amount has infinite decimals, +-- limit display precision to a hard-coded smaller number (8). +-- See amountSetFullPrecisionUpTo. +mixedAmountSetFullPrecisionUpTo :: Maybe Word8 -> MixedAmount -> MixedAmount +mixedAmountSetFullPrecisionUpTo mmaxp = mapMixedAmountUnsafe (amountSetFullPrecisionUpTo mmaxp) + -- | In each component amount, ensure the display precision is at least the given value. -- Makes all amounts have an explicit Precision. mixedAmountSetPrecisionMin :: Word8 -> MixedAmount -> MixedAmount diff --git a/hledger-lib/Hledger/Data/Balancing.hs b/hledger-lib/Hledger/Data/Balancing.hs index 031a6e888..5f3c9767c 100644 --- a/hledger-lib/Hledger/Data/Balancing.hs +++ b/hledger-lib/Hledger/Data/Balancing.hs @@ -131,11 +131,17 @@ transactionCheckBalanced BalancingOpts{commodity_styles_} t = errs rmsg | rsumok = "" | not rsignsok = "The real postings all have the same sign. Consider negating some of them." - | otherwise = "The real postings' sum should be 0 but is: " ++ showMixedAmountOneLineWithoutCost False rsumcost + | otherwise = "The real postings' sum should be 0 but is: " ++ + (showMixedAmountWith oneLineNoCostFmt{displayCost=True, displayZeroCommodity=True} $ + mixedAmountSetFullPrecisionUpTo Nothing $ mixedAmountSetFullPrecision + rsumcost) bvmsg | bvsumok = "" | not bvsignsok = "The balanced virtual postings all have the same sign. Consider negating some of them." - | otherwise = "The balanced virtual postings' sum should be 0 but is: " ++ showMixedAmountOneLineWithoutCost False bvsumcost + | otherwise = "The balanced virtual postings' sum should be 0 but is: " ++ + (showMixedAmountWith oneLineNoCostFmt{displayCost=True, displayZeroCommodity=True} $ + mixedAmountSetFullPrecisionUpTo Nothing $ mixedAmountSetFullPrecision + bvsumcost) -- | Legacy form of transactionCheckBalanced. isTransactionBalanced :: BalancingOpts -> Transaction -> Bool diff --git a/hledger-lib/Hledger/Data/Dates.hs b/hledger-lib/Hledger/Data/Dates.hs index a7e90bc6f..d131bc6e3 100644 --- a/hledger-lib/Hledger/Data/Dates.hs +++ b/hledger-lib/Hledger/Data/Dates.hs @@ -63,6 +63,7 @@ module Hledger.Data.Dates ( spanIntersect, spansIntersect, spanDefaultsFrom, + spanExtend, spanUnion, spansUnion, daysSpan, @@ -314,8 +315,8 @@ groupByDateSpan showempty date colspans = where groupByCols [] _ = [] groupByCols (c:cs) [] = if showempty then (c, []) : groupByCols cs [] else [] - groupByCols (c:cs) ps = (c, map snd matches) : groupByCols cs later - where (matches, later) = span ((spanEnd c >) . Just . fst) ps + groupByCols (c:cs) ps = (c, map snd colps) : groupByCols cs laterps + where (colps, laterps) = span ((spanEnd c >) . Just . fst) ps beforeStart = maybe (const False) (>) $ spanStart =<< headMay colspans @@ -324,40 +325,82 @@ spansIntersect [] = nulldatespan spansIntersect [d] = d spansIntersect (d:ds) = d `spanIntersect` (spansIntersect ds) --- | Calculate the intersection of two datespans. --- --- For non-intersecting spans, gives an empty span beginning on the second's start date: --- >>> DateSpan (Just $ Flex $ fromGregorian 2018 01 01) (Just $ Flex $ fromGregorian 2018 01 03) `spanIntersect` DateSpan (Just $ Flex $ fromGregorian 2018 01 03) (Just $ Flex $ fromGregorian 2018 01 05) --- DateSpan 2018-01-03..2018-01-02 -spanIntersect (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan b e - where - b = latest b1 b2 - e = earliest e1 e2 - --- | Fill any unspecified dates in the first span with the dates from --- the second one. Sort of a one-way spanIntersect. -spanDefaultsFrom (DateSpan a1 b1) (DateSpan a2 b2) = DateSpan a b - where a = if isJust a1 then a1 else a2 - b = if isJust b1 then b1 else b2 - -- | Calculate the union of a number of datespans. spansUnion [] = nulldatespan spansUnion [d] = d spansUnion (d:ds) = d `spanUnion` (spansUnion ds) +-- | Calculate the intersection of two datespans. +-- +-- For non-intersecting spans, gives an empty span beginning on the second's start date: +-- >>> DateSpan (Just $ Flex $ fromGregorian 2018 01 01) (Just $ Flex $ fromGregorian 2018 01 03) `spanIntersect` DateSpan (Just $ Flex $ fromGregorian 2018 01 03) (Just $ Flex $ fromGregorian 2018 01 05) +-- DateSpan 2018-01-03..2018-01-02 +spanIntersect (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan (laterDefinite b1 b2) (earlierDefinite e1 e2) + +-- | Fill any unspecified dates in the first span with the dates from +-- the second one (if specified there). Sort of a one-way spanIntersect. +spanDefaultsFrom (DateSpan a1 b1) (DateSpan a2 b2) = DateSpan a b + where a = if isJust a1 then a1 else a2 + b = if isJust b1 then b1 else b2 + -- | Calculate the union of two datespans. -spanUnion (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan b e - where - b = earliest b1 b2 - e = latest e1 e2 +-- If either span is open-ended, the union will be too. +-- +-- >>> ys2024 = fromGregorian 2024 01 01 +-- >>> ys2025 = fromGregorian 2025 01 01 +-- >>> to2024 = DateSpan Nothing (Just $ Exact ys2024) +-- >>> in2024 = DateSpan (Just $ Exact ys2024) (Just $ Exact ys2025) +-- >>> spanUnion to2024 in2024 +-- DateSpan ..2024-12-31 +-- >>> spanUnion in2024 to2024 +-- DateSpan ..2024-12-31 +spanUnion (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan (earlier b1 b2) (later e1 e2) -latest d Nothing = d -latest Nothing d = d -latest (Just d1) (Just d2) = Just $ max d1 d2 +-- | Extend the first span to include any definite end dates of the second. +-- Unlike spanUnion, open ends in the second are ignored. +-- If the first span was open-ended, it still will be after being extended. +-- +-- >>> ys2024 = fromGregorian 2024 01 01 +-- >>> ys2025 = fromGregorian 2025 01 01 +-- >>> to2024 = DateSpan Nothing (Just $ Exact ys2024) +-- >>> all2024 = DateSpan (Just $ Exact ys2024) (Just $ Exact ys2025) +-- >>> partof2024 = DateSpan (Just $ Exact $ fromGregorian 2024 03 01) (Just $ Exact $ fromGregorian 2024 09 01) +-- >>> spanExtend to2024 all2024 +-- DateSpan 2024 +-- >>> spanExtend all2024 to2024 +-- DateSpan 2024 +-- >>> spanExtend partof2024 all2024 +-- DateSpan 2024 +-- >>> spanExtend all2024 partof2024 +-- DateSpan 2024 +-- +spanExtend (DateSpan b1 e1) (DateSpan b2 e2) = DateSpan (earlierDefinite b1 b2) (laterDefinite e1 e2) -earliest d Nothing = d -earliest Nothing d = d -earliest (Just d1) (Just d2) = Just $ min d1 d2 +-- | Pick the earlier of two DateSpan starts, treating Nothing as infinitely early. +-- An Exact and Flex with the same date are considered equal; the first argument wins. +earlier :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +earlier = min + +-- | Pick the later of two DateSpan starts, treating Nothing as infinitely late. +-- An Exact and Flex with the same date are considered equal; the second argument wins. +later :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +later _ Nothing = Nothing +later Nothing _ = Nothing +later d1 d2 = max d1 d2 + +-- | Pick the earlier of two DateSpan ends that is a definite date (if any). +-- An Exact and Flex with the same date are considered equal; the first argument wins. +earlierDefinite :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +earlierDefinite d1 Nothing = d1 +earlierDefinite Nothing d2 = d2 +earlierDefinite d1 d2 = min d1 d2 + +-- | Pick the later of two DateSpan ends that is a definite date (if any). +-- An Exact and Flex with the same date are considered equal; the second argument wins. +laterDefinite :: Maybe EFDay -> Maybe EFDay -> Maybe EFDay +laterDefinite d1 Nothing = d1 +laterDefinite Nothing d2 = d2 +laterDefinite d1 d2 = max d1 d2 -- | Calculate the minimal DateSpan containing all of the given Days (in the -- usual exclusive-end-date sense: beginning on the earliest, and ending on diff --git a/hledger-lib/Hledger/Data/Valuation.hs b/hledger-lib/Hledger/Data/Valuation.hs index 7e174e347..614f59a4d 100644 --- a/hledger-lib/Hledger/Data/Valuation.hs +++ b/hledger-lib/Hledger/Data/Valuation.hs @@ -115,7 +115,7 @@ amountPriceDirectiveFromCost :: Day -> Amount -> Maybe PriceDirective amountPriceDirectiveFromCost d amt@Amount{acommodity=fromcomm, aquantity=n} = case acost amt of Just (UnitCost u) -> Just $ pd{pdamount=u} Just (TotalCost t) | n /= 0 -> Just $ pd{pdamount=u} - where u = amountSetFullPrecisionOr Nothing $ divideAmount n t + where u = amountSetFullPrecisionUpTo Nothing $ divideAmount n t _ -> Nothing where pd = PriceDirective{pddate = d, pdcommodity = fromcomm, pdamount = nullamt} @@ -209,7 +209,7 @@ amountValueAtDate priceoracle styles mto d a = -- set the display precision to match the internal precision (showing all digits), -- unnormalised (don't strip trailing zeros); -- but if it looks like an infinite decimal, limit the precision to 8. - & amountSetFullPrecisionOr Nothing + & amountSetFullPrecisionUpTo Nothing & dbg9With (lbl "calculated value".showAmount) -- | Calculate the gain of each component amount, that is the difference diff --git a/hledger-lib/Hledger/Reports/ReportOptions.hs b/hledger-lib/Hledger/Reports/ReportOptions.hs index 8e1a46164..665829c0d 100644 --- a/hledger-lib/Hledger/Reports/ReportOptions.hs +++ b/hledger-lib/Hledger/Reports/ReportOptions.hs @@ -696,7 +696,7 @@ reportSpanHelper bothdates j ReportSpec{_rsQuery=query, _rsReportOpts=ropts} = _ -> Nothing -- If the requested span is open-ended, close it using the journal's start and end dates. -- This can still be the null (open) span if the journal is empty. - requestedspan' = dbg3 "requestedspan'" $ requestedspan `spanDefaultsFrom` (journalspan `spanUnion` pricespan) + requestedspan' = dbg3 "requestedspan'" $ requestedspan `spanDefaultsFrom` (journalspan `spanExtend` pricespan) -- The list of interval spans enclosing the requested span. -- This list can be empty if the journal was empty, -- or if hledger-ui has added its special date:-tomorrow to the query diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index 587b7e665..574fdb3ce 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -341,9 +341,11 @@ This is very useful when reconciling. A good workflow is to have your bank's online register open in a browser window, for reference; the journal file open in an editor window; and hledger-ui in watch mode in a terminal window, eg: + ```cli $ hledger-ui --watch --register checking -C ``` + As you mark things cleared in the editor, you can see the effect immediately without having to context switch. This leaves more mental bandwidth for your accounting. diff --git a/hledger-web/Hledger/Web/Widget/Common.hs b/hledger-web/Hledger/Web/Widget/Common.hs index 01ca30758..a71ffb664 100644 --- a/hledger-web/Hledger/Web/Widget/Common.hs +++ b/hledger-web/Hledger/Web/Widget/Common.hs @@ -95,7 +95,7 @@ accountOnlyQuery = ("inacctonly:" <>) . quoteIfSpaced mixedAmountAsHtml :: MixedAmount -> HtmlUrl a mixedAmountAsHtml b _ = - for_ (lines (showMixedAmountWithoutCost False b)) $ \t -> do + for_ (lines (showMixedAmountWith noCostFmt{displayZeroCommodity=True} b)) $ \t -> do H.span ! A.class_ c $ toHtml t H.br where diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index a063c4321..aafea02d3 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -129,6 +129,12 @@ Query options and arguments may be used to set an initial filter, which although not shown in the UI, will restrict the data shown, in addition to any search query entered in the UI. +Note that hledger-web shows accounts with zero balances by default, like `hledger-ui` (and unlike `hledger`). +Using the `-E/--empty` flag at startup will hide them. + +If you see accounts which appear to have a zero balance, but cannot be hidden with `-E`: +these have a mixed-cost balance which looks like zero when costs are hidden. +Currently hledger-web does not show costs at all. ## General help options diff --git a/hledger-web/templates/balance-report.hamlet b/hledger-web/templates/balance-report.hamlet index bd0b1879a..e430a8910 100644 --- a/hledger-web/templates/balance-report.hamlet +++ b/hledger-web/templates/balance-report.hamlet @@ -17,9 +17,9 @@ $forall (acct, adisplay, aindent, abal) <- items $if hasSubAccounts acct only - + ^{mixedAmountAsHtml abal} - + ^{mixedAmountAsHtml total} diff --git a/hledger/Hledger/Cli/Commands/Add.md b/hledger/Hledger/Cli/Commands/Add.md index 1405e98bc..c30c150cd 100644 --- a/hledger/Hledger/Cli/Commands/Add.md +++ b/hledger/Hledger/Cli/Commands/Add.md @@ -33,9 +33,9 @@ Features: - If you make a mistake, enter `<` at any prompt to go one step backward. - Input prompts are displayed in a different colour when the terminal supports it. -Example (see https://hledger.org/add.html for a detailed tutorial): +Example (see for a detailed tutorial): -``` shell +```cli $ hledger add Adding transactions to journal file /src/hledger/examples/sample.journal Any command line arguments will be used as defaults. diff --git a/hledger/Hledger/Cli/Commands/Balance.md b/hledger/Hledger/Cli/Commands/Balance.md index cd3b5f106..5901f6d47 100644 --- a/hledger/Hledger/Cli/Commands/Balance.md +++ b/hledger/Hledger/Cli/Commands/Balance.md @@ -39,6 +39,7 @@ Many of these work with the higher-level commands as well. - or value of balance changes ([`-V`](#valuation-type)) - or change of balance values ([`--valuechange`](#balance-report-types)) - or unrealised capital gain/loss ([`--gain`](#balance-report-types)) +- or balance changes from sibling postings (`--related`/`-r`) - or postings count ([`--count`](#balance-report-types)) ..in.. @@ -77,9 +78,6 @@ This command supports the with output formats `txt`, `csv`, `tsv` (*Added in 1.32*), `json`, and (multi-period reports only:) `html`. In `txt` output in a colour-supporting terminal, negative amounts are shown in red. -The `--related`/`-r` flag shows the balance of the *other* postings in the -transactions of the postings which would normally be shown. - ### Simple balance report With no arguments, `balance` shows a list of all accounts and their @@ -189,6 +187,7 @@ Some example formats: [valuation]: #valuation [valuation date(s)]: #valuation-date [valuation commodity]: #valuation-commodity + ### Filtered balance report You can show fewer accounts, a different time period, totals from @@ -371,7 +370,9 @@ Multi-period reports with many periods can be too wide for easy viewing in the t Here are some ways to handle that: - Hide the totals row with `-N/--no-total` -- Convert to a single currency with `-V` +- Filter to a single currency with `cur:` +- Convert to a single currency with `-V [--infer-market-price]` +- Use a more compact layout like `--layout=bare` - Maximize the terminal window - Reduce the terminal's font size - View with a pager like less, eg: `hledger bal -D --color=yes | less -RS` @@ -440,13 +441,13 @@ It is one of: #### Accumulation type -How amounts should accumulate across report periods. +How amounts should accumulate across a report's subperiods/columns. Another way to say it: which time period's postings should contribute to each cell's calculation. It is one of: - `--change` : calculate with postings from column start to column end, ie "just this column". Typically used to see revenues/expenses. - (**default for balance, incomestatement**) + (**default for balance, cashflow, incomestatement**) - `--cumulative` : calculate with postings from report start to column end, ie "previous columns plus this column". Typically used to show changes accumulated since the report's start date. @@ -455,7 +456,7 @@ It is one of: - `--historical/-H` : calculate with postings from journal start to column end, ie "all postings from before report start date until this column's end". Typically used to see historical end balances of assets/liabilities/equity. - (**default for balancesheet, balancesheetequity, cashflow**) + (**default for balancesheet, balancesheetequity**) #### Valuation type @@ -658,30 +659,16 @@ and then select from multiple budgets defined in your journal. #### Budgeting vs forecasting -`--budget` and `--forecast` both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. +`--forecast` and `--budget` both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features - though you can use both at the same time if you want. Here are some differences between them: -1. `--budget` is a command-specific option; it selects the **budget report**. - - `--forecast` is a general option; **forecasting works with all reports**. - -2. `--budget` uses **all periodic rules**; `--budget=DESCPAT` uses **just the rules matched** by DESCPAT. - - `--forecast` uses **all periodic rules**. - -3. `--budget`'s budget goal transactions are invisible, except that they produce **goal amounts**. - - `--forecast`'s forecast transactions are visible, and **appear in reports**. - -4. `--budget` generates budget goal transactions **throughout the report period**, - optionally restricted by periods specified in the periodic transaction rules. - - `--forecast` generates forecast transactions - from **after the last regular transaction**, to the end of the report period; - while `--forecast=PERIODEXPR` generates them **throughout the specified period**; - both optionally restricted by periods specified in the periodic transaction rules. - +| --forecast | --budget | +|------------|----------| +| is a general option; it enables forecasting with all reports | is a balance command option; it selects the balance report's budget mode | +| generates visible transactions which appear in reports | generates invisible transactions which produce goal amounts | +| generates forecast transactions from after the last regular transaction, to the end of the report period; or with an argument `--forecast=PERIODEXPR` generates them throughout the specified period, both optionally restricted by periods specified in the periodic transaction rules | generates budget goal transactions throughout the report period, optionally restricted by periods specified in the periodic transaction rules | +| uses all periodic rules | uses all periodic rules; or with an argument `--budget=DESCPAT` uses just the rules matched by DESCPAT | ### Balance report layout @@ -695,8 +682,8 @@ It has four possible values: - `--layout=bare`: commodity symbols are in their own column, amounts are bare numbers - `--layout=tidy`: data is normalised to easily-consumed "tidy" form, with one row per data value -Here are the `--layout` modes supported by each [output format](#output-format); -note only CSV output supports all of them: +Here are the `--layout` modes supported by each [output format](#output-format) +Only CSV output supports all of them: | - | txt | csv | html | json | sql | |------|-----|-----|------|------|-----| @@ -707,119 +694,122 @@ note only CSV output supports all of them: Examples: -- Wide layout. With many commodities, reports can be very wide: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ``` +#### Wide layout +With many commodities, reports can be very wide: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide +Balance changes in 2012-01-01..2014-12-31: -- Limited wide layout. A width limit reduces the width, but some commodities will be hidden: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ``` + || 2012 2013 2014 Total +==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +``` -- Tall layout. Each commodity gets a new line (may be different in each column), and account names are repeated: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - ``` +A width limit reduces the width, but some commodities will be hidden: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 +Balance changes in 2012-01-01..2014-12-31: -- Bare layout. Commodity symbols are kept in one column, each commodity gets its own report row, account names are repeated: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - ``` + || 2012 2013 2014 Total +==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +``` -- Bare layout also affects [CSV output](#output-format), - which is useful for producing data that is easier to consume, eg for making charts: - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - ``` +#### Tall layout +Each commodity gets a new line (may be different in each column), and account names are repeated: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall +Balance changes in 2012-01-01..2014-12-31: -- Note: bare layout will sometimes display an extra row for the no-symbol commodity, - because of zero amounts (hledger treats zeroes as commodity-less, usually). - This can break `hledger-bar` confusingly (workaround: add a `cur:` query to exclude - the no-symbol row). + || 2012 2013 2014 Total +==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT +------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT +``` -- Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. - See for more. - This is the easiest kind of data for other software to consume. - Here's how it looks: - - ```cli - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - ``` +#### Bare layout +Commodity symbols are kept in one column, each commodity has its own row, +amounts are bare numbers, account names are repeated: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare +Balance changes in 2012-01-01..2014-12-31: -### Useful balance reports + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 +``` + +Bare layout also affects [CSV output](#output-format), +which is useful for producing data that is easier to consume, eg for making charts: +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"total","GLD","70.00" +"total","ITOT","17.00" +"total","USD","5120.50" +"total","VEA","36.00" +"total","VHT","294.00" +``` + +Bare layout will sometimes display an extra row for the no-symbol commodity, +because of zero amounts (hledger treats zeroes as commodity-less, usually). +This can break `hledger-bar` confusingly (workaround: add a `cur:` query to exclude +the no-symbol row). + +#### Tidy layout +This produces normalised "tidy data" (see ) +where every variable has its own column and each row represents a single data point. +This is the easiest kind of data for other software to consume: + +```cli +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy +"account","period","start_date","end_date","commodity","value" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" +``` + +### Some useful balance reports Some frequently used `balance` options/reports are: diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 1e01a6f12..2a16f9593 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -35,6 +35,7 @@ balance can show.. - or value of balance changes (-V) - or change of balance values (--valuechange) - or unrealised capital gain/loss (--gain) +- or balance changes from sibling postings (--related/-r) - or postings count (--count) ..in.. @@ -70,9 +71,6 @@ with output formats txt, csv, tsv (Added in 1.32), json, and (multi-period reports only:) html. In txt output in a colour-supporting terminal, negative amounts are shown in red. -The --related/-r flag shows the balance of the other postings in the -transactions of the postings which would normally be shown. - Simple balance report With no arguments, balance shows a list of all accounts and their change @@ -343,7 +341,9 @@ Multi-period reports with many periods can be too wide for easy viewing in the terminal. Here are some ways to handle that: - Hide the totals row with -N/--no-total -- Convert to a single currency with -V +- Filter to a single currency with cur: +- Convert to a single currency with -V [--infer-market-price] +- Use a more compact layout like --layout=bare - Maximize the terminal window - Reduce the terminal's font size - View with a pager like less, eg: @@ -415,13 +415,13 @@ The basic calculation to perform for each table cell. It is one of: Accumulation type -How amounts should accumulate across report periods. Another way to say -it: which time period's postings should contribute to each cell's -calculation. It is one of: +How amounts should accumulate across a report's subperiods/columns. +Another way to say it: which time period's postings should contribute to +each cell's calculation. It is one of: - --change : calculate with postings from column start to column end, ie "just this column". Typically used to see revenues/expenses. - (default for balance, incomestatement) + (default for balance, cashflow, incomestatement) - --cumulative : calculate with postings from report start to column end, ie "previous columns plus this column". Typically used to show @@ -431,7 +431,7 @@ calculation. It is one of: column end, ie "all postings from before report start date until this column's end". Typically used to see historical end balances of assets/liabilities/equity. (default for balancesheet, - balancesheetequity, cashflow) + balancesheetequity) Valuation type @@ -659,35 +659,35 @@ defined in your journal. Budgeting vs forecasting ---budget and --forecast both use the periodic transaction rules in the +--forecast and --budget both use the periodic transaction rules in the journal to generate temporary transactions for reporting purposes. However they are separate features - though you can use both at the same time if you want. Here are some differences between them: -1. --budget is a command-specific option; it selects the budget report. + ----------------------------------------------------------------------- + --forecast --budget + -------------------------------------- -------------------------------- + is a general option; it enables is a balance command option; it + forecasting with all reports selects the balance report's + budget mode - --forecast is a general option; forecasting works with all reports. + generates visible transactions which generates invisible transactions + appear in reports which produce goal amounts -2. --budget uses all periodic rules; --budget=DESCPAT uses just the - rules matched by DESCPAT. + generates forecast transactions from generates budget goal + after the last regular transaction, to transactions throughout the + the end of the report period; or with report period, optionally + an argument --forecast=PERIODEXPR restricted by periods specified + generates them throughout the in the periodic transaction + specified period, both optionally rules + restricted by periods specified in the + periodic transaction rules - --forecast uses all periodic rules. - -3. --budget's budget goal transactions are invisible, except that they - produce goal amounts. - - --forecast's forecast transactions are visible, and appear in - reports. - -4. --budget generates budget goal transactions throughout the report - period, optionally restricted by periods specified in the periodic - transaction rules. - - --forecast generates forecast transactions from after the last - regular transaction, to the end of the report period; while - --forecast=PERIODEXPR generates them throughout the specified - period; both optionally restricted by periods specified in the - periodic transaction rules. + uses all periodic rules uses all periodic rules; or with + an argument --budget=DESCPAT + uses just the rules matched by + DESCPAT + ----------------------------------------------------------------------- Balance report layout @@ -704,8 +704,8 @@ four possible values: - --layout=tidy: data is normalised to easily-consumed "tidy" form, with one row per data value -Here are the --layout modes supported by each output format; note only -CSV output supports all of them: +Here are the --layout modes supported by each output format Only CSV +output supports all of them: - txt csv html json sql ------ ----- ----- ------ ------ ----- @@ -716,115 +716,122 @@ CSV output supports all of them: Examples: -- Wide layout. With many commodities, reports can be very wide: +Wide layout - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: +With many commodities, reports can be very wide: - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide +Balance changes in 2012-01-01..2014-12-31: -- Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: + || 2012 2013 2014 Total +==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: +A width limit reduces the width, but some commodities will be hidden: - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 +Balance changes in 2012-01-01..2014-12-31: -- Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: + || 2012 2013 2014 Total +==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: +Tall layout - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT +Each commodity gets a new line (may be different in each column), and +account names are repeated: -- Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall +Balance changes in 2012-01-01..2014-12-31: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: + || 2012 2013 2014 Total +==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT +------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 +Bare layout -- Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg for making charts: +Commodity symbols are kept in one column, each commodity has its own +row, amounts are bare numbers, account names are repeated: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare +Balance changes in 2012-01-01..2014-12-31: -- Note: bare layout will sometimes display an extra row for the - no-symbol commodity, because of zero amounts (hledger treats zeroes - as commodity-less, usually). This can break hledger-bar confusingly - (workaround: add a cur: query to exclude the no-symbol row). + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 -- Tidy layout produces normalised "tidy data", where every variable - has its own column and each row represents a single data point. See - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html - for more. This is the easiest kind of data for other software to - consume. Here's how it looks: +Bare layout also affects CSV output, which is useful for producing data +that is easier to consume, eg for making charts: - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"total","GLD","70.00" +"total","ITOT","17.00" +"total","USD","5120.50" +"total","VEA","36.00" +"total","VHT","294.00" -Useful balance reports +Bare layout will sometimes display an extra row for the no-symbol +commodity, because of zero amounts (hledger treats zeroes as +commodity-less, usually). This can break hledger-bar confusingly +(workaround: add a cur: query to exclude the no-symbol row). + +Tidy layout + +This produces normalised "tidy data" (see +https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) +where every variable has its own column and each row represents a single +data point. This is the easiest kind of data for other software to +consume: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy +"account","period","start_date","end_date","commodity","value" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + +Some useful balance reports Some frequently used balance options/reports are: diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 36378939c..adf0e7612 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -132,6 +132,10 @@ balances in an opening transaction. These provide useful error checking, but you can ignore them temporarily with -I, or remove them if you prefer. +Single-commodity, subaccount-exclusive balance assertions (=) are +generated by default. This can be changed with --assertion-type='==*' +(eg). + When running close you should probably avoid using -C, -R, status: (filtering by status or realness) or --auto (generating postings), since the generated balance assertions would then require these. diff --git a/hledger/Hledger/Cli/Commands/Prices.hs b/hledger/Hledger/Cli/Commands/Prices.hs index 0d46899d9..65ac476f1 100644 --- a/hledger/Hledger/Cli/Commands/Prices.hs +++ b/hledger/Hledger/Cli/Commands/Prices.hs @@ -107,7 +107,7 @@ reversePriceDirective pd@PriceDirective{pdcommodity=c, pdamount=a} where lbl = lbl_ "reversePriceDirective" a' = - amountSetFullPrecisionOr (Just defaultMaxPrecision) $ + amountSetFullPrecisionUpTo (Just defaultMaxPrecision) $ invertAmount a{acommodity=c} & dbg9With (lbl "calculated reverse price".showAmount) -- & dbg9With (lbl "precision of reverse price".show.amountDisplayPrecision) diff --git a/hledger/Hledger/Cli/Commands/Roi.hs b/hledger/Hledger/Cli/Commands/Roi.hs index 0ec91c5a4..28c1bb9a3 100644 --- a/hledger/Hledger/Cli/Commands/Roi.hs +++ b/hledger/Hledger/Cli/Commands/Roi.hs @@ -147,7 +147,7 @@ roi CliOpts{rawopts_=rawopts, reportspec_=rspec@ReportSpec{_rsReportOpts=ReportO , T.pack $ showMixedAmount $ styleAmounts styles $ cashFlowAmt -- , T.pack $ showMixedAmount $ -- -- dbg0With (lbl "cashflow after styling".showMixedAmountOneLine) $ - -- mapMixedAmount (amountSetFullPrecisionOr (Just defaultMaxPrecision)) $ + -- mapMixedAmount (amountSetFullPrecisionUpTo (Just defaultMaxPrecision)) $ -- styleAmounts (styles -- -- & dbg0With (lbl "styles".show)) -- cashFlowAmt diff --git a/hledger/Hledger/Cli/Commands/Roi.md b/hledger/Hledger/Cli/Commands/Roi.md index 915cc682c..73357991d 100644 --- a/hledger/Hledger/Cli/Commands/Roi.md +++ b/hledger/Hledger/Cli/Commands/Roi.md @@ -72,7 +72,7 @@ contributions and which is due to the return on investment. assets, or otherwise converting between your investment commodity and any other commodity. Example: - ``` + ```journal 2019-01-01 Investing in Snake Oil assets:cash -$100 investment:snake oil @@ -84,7 +84,7 @@ any other commodity. Example: - "Profit and loss" is change in the value of your investment: - ``` + ```journal 2019-06-01 Snake Oil falls in value investment:snake oil = $57 equity:unrealized profit or loss @@ -98,7 +98,7 @@ investment return. Example: if you use `--inv snake --pnl equity:unrealized`, then postings in the example below would be classifed as: -``` +```journal 2019-01-01 Snake Oil #1 assets:cash -$100 ; cash flow posting investment:snake oil ; investment posting diff --git a/hledger/Hledger/Cli/Commands/Stats.hs b/hledger/Hledger/Cli/Commands/Stats.hs index 1b84c3a90..ff0a32022 100644 --- a/hledger/Hledger/Cli/Commands/Stats.hs +++ b/hledger/Hledger/Cli/Commands/Stats.hs @@ -16,6 +16,7 @@ module Hledger.Cli.Commands.Stats ( where import Data.Default (def) +import System.FilePath (takeFileName) import Data.List (intercalate, nub, sortOn) import Data.List.Extra (nubSort) import qualified Data.Map as Map @@ -39,7 +40,8 @@ import Hledger.Cli.Utils (writeOutputLazyText) statsmode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Stats.txt") - [flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE." + [ flagNone ["verbose","v"] (setboolopt "verbose") "show more detailed output" + ,flagReq ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE." ] [generalflagsgroup1] hiddenflags @@ -48,16 +50,17 @@ statsmode = hledgerCommandMode -- like Register.summarisePostings -- | Print various statistics for the journal. stats :: CliOpts -> Journal -> IO () -stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do +stats opts@CliOpts{rawopts_=rawopts, reportspec_=rspec, progstarttime_} j = do let today = _rsDay rspec + verbose = boolopt "verbose" rawopts q = _rsQuery rspec l = ledgerFromJournal q j intervalspans = snd $ reportSpanBothDates j rspec - showstats = showLedgerStats l today - (ls, txncounts) = unzip $ map showstats intervalspans + ismultiperiod = length intervalspans > 1 + (ls, txncounts) = unzip $ map (showLedgerStats verbose l today) intervalspans numtxns = sum txncounts - b = unlinesB ls - writeOutputLazyText opts $ TL.init $ TB.toLazyText b + txt = (if ismultiperiod then id else TL.init) $ TB.toLazyText $ unlinesB ls + writeOutputLazyText opts txt t <- getPOSIXTime let dt = t - progstarttime_ rtsStatsEnabled <- getRTSStatsEnabled @@ -68,11 +71,11 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do RTSStats{..} <- getRTSStats printf (intercalate ", " - ["Runtime stats : %.2f s elapsed" - ,"%.0f txns/s" + ["Runtime stats : %.2f s elapsed" -- keep synced + ,"%.0f txns/s" -- -- ,"%0.0f MB avg live" - ,"%0.0f MB max live" - ,"%0.0f MB peak allocation" + ,"%0.0f MB live" + ,"%0.0f MB alloc" -- ,"(%0.0f MiB" -- ,"%0.0f MiB)" ] ++ "\n") @@ -84,7 +87,7 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do else printf (intercalate ", " - ["Runtime stats : %.2f s elapsed" + ["Runtime stats : %.2f s elapsed" -- keep ,"%.0f txns/s" ] ++ "\n(add +RTS -T -RTS for more)\n") (realToFrac dt :: Float) @@ -93,36 +96,37 @@ stats opts@CliOpts{reportspec_=rspec, progstarttime_} j = do toMegabytes n = realToFrac n / 1000000 ::Float -- SI preferred definition, 10^6 -- toMebibytes n = realToFrac n / 1048576 ::Float -- traditional computing definition, 2^20 -showLedgerStats :: Ledger -> Day -> DateSpan -> (TB.Builder, Int) -showLedgerStats l today spn = +showLedgerStats :: Bool -> Ledger -> Day -> DateSpan -> (TB.Builder, Int) +showLedgerStats verbose l today spn = (unlinesB $ map (renderRowB def{tableBorders=False, borderSpaces=False} . showRow) stts ,tnum) where showRow (label, val) = Group NoLine $ map (Header . textCell TopLeft) [fitText (Just w) (Just w) False True label `T.append` ": ", T.pack val] - w = 25 -- keep synced with labels above + w = 20 -- keep synced with labels above -- w = maximum $ map (T.length . fst) stts (stts, tnum) = ([ - ("Main file", path) -- ++ " (from " ++ source ++ ")") - ,("Included files", unlines $ drop 1 $ journalFilePaths j) - ,("Transactions span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) - ,("Last transaction", maybe "none" show lastdate ++ showelapsed lastelapsed) - ,("Transactions", printf "%d (%0.1f per day)" tnum txnrate) - ,("Transactions last 30 days", printf "%d (%0.1f per day)" tnum30 txnrate30) - ,("Transactions last 7 days", printf "%d (%0.1f per day)" tnum7 txnrate7) + ("Main file", path') -- ++ " (from " ++ source ++ ")") + ,("Included files", if verbose then unlines includedpaths else show (length includedpaths)) + ,("Txns span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) + ,("Last txn", maybe "none" show lastdate ++ showelapsed lastelapsed) + ,("Txns", printf "%d (%0.1f per day)" tnum txnrate) + ,("Txns last 30 days", printf "%d (%0.1f per day)" tnum30 txnrate30) + ,("Txns last 7 days", printf "%d (%0.1f per day)" tnum7 txnrate7) ,("Payees/descriptions", show $ size $ fromList $ map (tdescription) ts) ,("Accounts", printf "%d (depth %d)" acctnum acctdepth) - ,("Commodities", printf "%s (%s)" (show $ length cs) (T.intercalate ", " cs)) - ,("Market prices", printf "%s (%s)" (show $ length mktprices) (T.intercalate ", " mktpricecommodities)) - -- Transactions this month : %(monthtxns)s (last month in the same period: %(lastmonthtxns)s) - -- Unmarked transactions : %(unmarked)s + ,("Commodities", printf "%s%s" (show $ length cs) (if verbose then " (" <> T.intercalate ", " cs <> ")" else "")) + ,("Market prices", printf "%s%s" (show $ length mktprices) (if verbose then " (" <> T.intercalate ", " mktpricecommodities <> ")" else "")) + -- Txns this month : %(monthtxns)s (last month in the same period: %(lastmonthtxns)s) + -- Unmarked txns : %(unmarked)s -- Days since reconciliation : %(reconcileelapsed)s - -- Days since last transaction : %(recentelapsed)s + -- Days since last txn : %(recentelapsed)s ] ,tnum1) where j = ljournal l - path = journalFilePath j + path' = if verbose then path else ".../" <> takeFileName path where path = journalFilePath j + includedpaths = drop 1 $ journalFilePaths j ts = sortOn tdate $ filter (spanContainsDate spn . tdate) $ jtxns j as = nub $ map paccount $ concatMap tpostings ts cs = either error' Map.keys $ commodityStylesFromAmounts $ concatMap (amountsRaw . pamount) $ concatMap tpostings ts -- PARTIAL: diff --git a/hledger/Hledger/Cli/Commands/Stats.md b/hledger/Hledger/Cli/Commands/Stats.md index 4bcc0731d..85a0227cc 100644 --- a/hledger/Hledger/Cli/Commands/Stats.md +++ b/hledger/Hledger/Cli/Commands/Stats.md @@ -4,36 +4,43 @@ Show journal and performance statistics. _FLAGS -The stats command displays summary information for the whole journal, or +The stats command shows summary information for the whole journal, or a matched part of it. With a [reporting interval](#reporting-interval), it shows a report for each report period. -At the end, it shows (in the terminal) the overall run time and number of -transactions processed per second. Note these are approximate and will vary -based on machine, current load, data size, hledger version, haskell lib -versions, GHC version.. but they may be of interest. The `stats` command's -run time is similar to that of a single-column balance report. +The default output is fairly impersonal, though it reveals the main file name. +With `-v/--verbose`, more details are shown, like file paths, included files, +and commodity names. + +It also shows some run time statistics: + +- elapsed time +- throughput: the number of transactions processed per second +- live: the peak memory in use by the program to do its work +- alloc: the peak memory allocation from the OS as seen by GHC. + Measuring this externally, eg with GNU time, is more accurate; + usually that will be a larger number; sometimes (with swapping?) smaller. + +The `stats` command's run time is similar to that of a balance report. Example: ```cli -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s +$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file : .../1ktxns-1kaccts.journal +Included files : 0 +Txns span : 2000-01-01 to 2002-09-27 (1000 days) +Last txn : 2002-09-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc ``` This command supports the [-o/--output-file](hledger.html#output-destination) option -(but not [-O/--output-format](hledger.html#output-format) selection). +(but not [-O/--output-format](hledger.html#output-format)). diff --git a/hledger/Hledger/Cli/Commands/Stats.txt b/hledger/Hledger/Cli/Commands/Stats.txt index 5dc1293e6..8708f4953 100644 --- a/hledger/Hledger/Cli/Commands/Stats.txt +++ b/hledger/Hledger/Cli/Commands/Stats.txt @@ -4,34 +4,41 @@ Show journal and performance statistics. _FLAGS -The stats command displays summary information for the whole journal, or -a matched part of it. With a reporting interval, it shows a report for +The stats command shows summary information for the whole journal, or a +matched part of it. With a reporting interval, it shows a report for each report period. -At the end, it shows (in the terminal) the overall run time and number -of transactions processed per second. Note these are approximate and -will vary based on machine, current load, data size, hledger version, -haskell lib versions, GHC version.. but they may be of interest. The -stats command's run time is similar to that of a single-column balance -report. +The default output is fairly impersonal, though it reveals the main file +name. With -v/--verbose, more details are shown, like file paths, +included files, and commodity names. + +It also shows some run time statistics: + +- elapsed time +- throughput: the number of transactions processed per second +- live: the peak memory in use by the program to do its work +- alloc: the peak memory allocation from the OS as seen by GHC. + Measuring this externally, eg with GNU time, is more accurate; + usually that will be a larger number; sometimes (with swapping?) + smaller. + +The stats command's run time is similar to that of a balance report. Example: -$ hledger stats -f examples/1000x1000x10.journal -Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal -Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days) -Last transaction : 2002-09-26 (6995 days ago) -Transactions : 1000 (1.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z) -Market prices : 1000 (A) - -Run time : 0.12 s -Throughput : 8342 txns/s +$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file : .../1ktxns-1kaccts.journal +Included files : 0 +Txns span : 2000-01-01 to 2002-09-27 (1000 days) +Last txn : 2002-09-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc This command supports the -o/--output-file option (but not --O/--output-format selection). +-O/--output-format). diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 5637603c4..022ee615d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -67,12 +67,14 @@ are some good choices (see ). To get started, run `hledger add` and follow the prompts, or save some entries like the above in `$HOME/.hledger.journal`, -then try commands like:\ -`hledger print -x`\ -`hledger aregister assets`\ -`hledger balance`\ -`hledger balancesheet`\ -`hledger incomestatement`.\ +then try commands like: +```cli +$ hledger print -x +$ hledger aregister assets +$ hledger balance +$ hledger balancesheet +$ hledger incomestatement +``` Run `hledger` to list the commands. See also the "Starting a journal file" and "Setting opening balances" sections in [PART 5: COMMON TASKS](#part-5-common-tasks). @@ -589,7 +591,7 @@ Some notes about the various output formats: ### CSV output -- In CSV output, [digit group marks](#decimal-marks-digit-group-marks) (such as thousands separators) +- In CSV output, [digit group marks](#digit-group-marks) (such as thousands separators) are disabled automatically. ### HTML output @@ -664,9 +666,8 @@ This option can repeated to set the display style for multiple commodities/currencies. Its argument is as described in the [commodity directive](#commodity-directive). -hledger will occasionally make some additional adjustments to number formatting, -eg adding a trailing decimal mark to disambiguate numbers with digit group marks; -for details, see [Amount formatting, parseability](#amount-formatting-parseability). +In some cases hledger will adjust number formatting to improve their parseability +(such as adding [trailing decimal marks](#trailing-decimal-marks) when needed). ## Colour @@ -740,9 +741,73 @@ unless overridden by an explicit `--color/--colour` option. # Journal -hledger's default file format, representing a General Journal. -Here's a cheatsheet/mini-tutorial, -or you can skip ahead to [About journal format](#about-journal-format). +hledger's usual data source is a plain text file containing journal entries in hledger `journal` format. +If you're looking for a quick reference, jump ahead to the +[journal cheatsheet](#journal-cheatsheet) (or use the table of contents at ). + +This file represents an accounting [General Journal](http://en.wikipedia.org/wiki/General_journal). +The `.journal` file extension is most often used, though not strictly required. +The journal file contains a number of transaction entries, +each describing a transfer of money (or any commodity) between two or more named accounts, +in a simple format readable by both hledger and humans. + +hledger's journal format is compatible with most of +[Ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), but not all of it. +The differences and interoperation tips are described at [hledger and Ledger](ledger.html). +With some care, and by avoiding incompatible features, you can keep your hledger journal +readable by Ledger and vice versa. This can useful eg for comparing the behaviour of one app +against the other. + +You can use hledger without learning any more about this file; just +use the [add](#add) or [web](#web) or [import](#import) commands to +create and update it. + +Many users, though, edit the journal file with a text editor, +and track changes with a version control system such as git. +Editor addons such as +ledger-mode or hledger-mode for Emacs, +vim-ledger for Vim, +and hledger-vscode for Visual Studio Code, +make this easier, adding colour, formatting, tab completion, and useful commands. +See [Editor configuration](/editors.html) at hledger.org for the full list. + + + +A hledger journal file can contain three kinds of thing: +comment lines, transactions, and/or directives (including periodic transaction rules and auto posting rules). +Understanding the journal file format will also give you a good understanding of hledger's data model. +Here's a quick cheatsheet/overview, followed by detailed descriptions of each part. ## Journal cheatsheet @@ -837,74 +902,6 @@ P 2022-01-01 AAAA $1.40 12/31 also allowed (but consistent YYYY-MM-DD is recommended). ``` -## About journal format - -hledger's usual data source is a plain text file containing journal entries in hledger journal format. -This file represents a standard accounting [general journal](http://en.wikipedia.org/wiki/General_journal). -I use file names ending in `.journal`, but that's not required. -The journal file contains a number of transaction entries, -each describing a transfer of money (or any commodity) between two or more named accounts, -in a simple format readable by both hledger and humans. - -hledger's journal format is compatible with most of -[Ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), but not all of it. -The differences and interoperation tips are described at [hledger and Ledger](ledger.html). -With some care, and by avoiding incompatible features, you can keep your hledger journal -readable by Ledger and vice versa. This can useful eg for comparing the behaviour of one app -against the other. - -You can use hledger without learning any more about this file; just -use the [add](#add) or [web](#web) or [import](#import) commands to -create and update it. - -Many users, though, edit the journal file with a text editor, -and track changes with a version control system such as git. -Editor addons such as -ledger-mode or hledger-mode for Emacs, -vim-ledger for Vim, -and hledger-vscode for Visual Studio Code, -make this easier, adding colour, formatting, tab completion, and useful commands. -See [Editor configuration](/editors.html) at hledger.org for the full list. - - - -Here's a description of each part of the file format (and hledger's data model). - -A hledger journal file can contain three kinds of thing: -file comments, transactions, and/or directives -(counting periodic transaction rules and auto posting rules as directives). - ## Comments Lines in the journal will be ignored if they begin with a hash (`#`) or a semicolon (`;`). (See also [Other syntax](#other-syntax).) @@ -932,8 +929,7 @@ See Transaction comments, Posting comments, and Account comments below. ## Transactions Transactions are the main unit of information in a journal file. -They represent events, typically a movement of some quantity of -commodities between two or more named accounts. +They represent events, typically a movement of some quantity of commodities between two or more named accounts. Each transaction is recorded as a journal entry, beginning with a [simple date](#simple-dates) in column 0. This can be followed by any @@ -1001,9 +997,9 @@ eg a `date:` tag with no value is not allowed. ## Status -Transactions, or individual postings within a transaction, +Transactions (or individual postings within a transaction) can have a status mark, which is a single character before -the transaction description or posting account name, +the transaction description (or posting account name), separated from it by a space, indicating one of three statuses: | mark   | status | @@ -1013,14 +1009,13 @@ separated from it by a space, indicating one of three statuses: | `*` | cleared | When reporting, you can filter by status with -the `-U/--unmarked`, `-P/--pending`, and `-C/--cleared` flags; -or the `status:`, `status:!`, and `status:*` [queries](#queries); +the `-U/--unmarked`, `-P/--pending`, and `-C/--cleared` flags +(and you can combine these, eg `-UP` to match all except cleared things). +Or you can use the `status:`, `status:!`, and `status:*` [queries](#queries), or the U, P, C keys in hledger-ui. -Note, in Ledger and in older versions of hledger, the "unmarked" state is called -"uncleared". As of hledger 1.3 we have renamed it to unmarked for clarity. - -To replicate Ledger and old hledger's behaviour of also matching pending, combine -U and -P. +(Note: in Ledger the "unmarked" state is called "uncleared"; +in hledger we renamed it to "unmarked" for semantic clarity.) Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and shortcuts for working with status. @@ -1101,16 +1096,31 @@ Each posting line begins with at least one space or tab (2 or 4 spaces is common - (optional) a [status](#status) character (empty, `!`, or `*`), followed by a space - (required) an [account name](#account-names) (any text, optionally containing **single spaces**, until end of line or a double space) -- (optional) **two or more spaces** or tabs followed by an [amount](#amounts). +- (optional) **two or more spaces** (or tabs) followed by an [amount](#amounts). -Positive amounts are being added to the account, negative amounts are being removed. +If the amount is positive, it is being added to the account; +if negative, it is being removed from the account. -The amounts within a transaction must always sum up to zero. -As a convenience, one amount may be left blank; it will be inferred so as to balance the transaction. +The posting amounts in a transaction must sum up to zero, indicating that the inflows and outflows are equal. We call this a balanced transaction. +(You can read more about the nitty-gritty details of "sum up to zero" in [Transaction balancing](#transaction-balancing) below.) -Be sure to note the unusual two-space delimiter between account name and amount. -This makes it easy to write account names containing spaces. -But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name. +As a convenience, you can optionally leave one amount blank; hledger will infer what it should be so as to balance the transaction. + +### Debits and credits + +The traditional accounting concepts of debit and credit of course exist in hledger, but we represent them with numeric sign, as described above. +Positive and negative posting amounts represent debits and credits respectively. + +You don't need to remember that, but if you would like to - eg for helping newcomers or for talking with your accountant - here's a handy mnemonic: + +*`debit / plus / left / short words`*\ +*`credit / minus / right / longer words`* + +### The two space delimiter + +Be sure to notice the unusual separator between the account name and the following amount. +Because hledger allows account names with spaces in them, you must separate the account name and amount (if any) by **two or more spaces** (or tabs). +It's easy to forget at first. If you ever see the amount being treated as part of the account name, you'll know you probably need to add another space between them. ## Account names @@ -1159,7 +1169,7 @@ Account names can be altered temporarily or permanently by [account aliases](#al ## Amounts After the account name, there is usually an amount. -(Important: between account name and amount, there must be **two or more spaces**.) +(Remember: between account name and amount, there must be two or more spaces.) hledger's amount format is flexible, supporting several international formats. Here are some examples. @@ -1192,17 +1202,42 @@ Scientific E notation is allowed: 1E-6 EUR 1E3 -### Decimal marks, digit group marks + + +### Decimal marks A *decimal mark* can be written as a period or a comma: 1.23 1,23 -In the integer part of the quantity (left of the decimal mark), groups -of digits can optionally be separated by a *digit group mark* - +Both of these are common in [international number formats][international number formats], +so hledger is not biased towards one or the other. +Because hledger also supports digit group marks (eg thousands separators), +this means that a number like `1,000` or `1.000` containing just one period or comma is ambiguous. +In such cases, hledger by default assumes it is a decimal mark, and will parse both of those as 1. + +[international number formats]: https://en.wikipedia.org/wiki/Decimal_separator#Conventions_worldwide + +To help hledger parse such ambiguous numbers more accurately, +if you use digit group marks, we recommend declaring the decimal mark explicitly. +The best way is to add a [`decimal-mark`](#decimal-mark-directive) directive at the top of each data file, like this: +```journal +decimal-mark . +``` +Or you can declare it per commodity with [`commodity`](#commodity-directive) directives, described below. + +hledger also accepts numbers like `10.` with no digits after the decimal mark +(and will sometimes display numbers that way to disambiguate them - see +[Trailing decimal marks](#trailing-decimal-marks)). + +### Digit group marks + +In the integer part of the amount quantity (left of the decimal mark), +groups of digits can optionally be separated by a *digit group mark* - a comma or period (whichever is not used as decimal mark), -or a space (any of these Unicode space characters: +or a space (several Unicode space variants, like no-break space, are also accepted). + +So these are all valid amounts in a journal file: $1,000,000.00 EUR 2.000.000,00 INR 9,99,99,999.00 - 1 000 000.00 <- ordinary space - 1 000 000.00 <- no-break space - -hledger is not biased towards [period or comma decimal marks][international number formats], -so a number containing just one period or comma, like `1,000` or `1.000`, is ambiguous. -In such cases hledger assumes it is a decimal mark, parsing both of these as 1. - -[international number formats]: https://en.wikipedia.org/wiki/Decimal_separator#Conventions_worldwide - -To disambiguate these and ensure accurate number parsing, especially -if you use digit group marks, we recommend declaring the decimal mark. -You can declare it for each file with [`decimal-mark`](#decimal-mark-directive) directives, -or for each commodity with [`commodity`](#commodity-directive) directives -(described below). + 1 000 000.00 ; <- ordinary space + 1 000 000.00 ; <- no-break space ### Commodity @@ -1249,79 +1274,14 @@ the time. A multi-commodity amount could be, eg: `1 USD, 2 EUR, 3.456 TSLA`. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. + -(If you are writing scripts or working with hledger's internals, these -are the `Amount` and `MixedAmount` types.) - -### Directives influencing number parsing and display - -You can add `decimal-mark` and `commodity` directives to the journal, -to declare and control these things more explicitly and precisely. -These are described below, but here's a quick example: - -```journal -# the decimal mark character used by all amounts in this file (all commodities) -decimal-mark . - -# display styles for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 -``` - - - -### Commodity display style - -For the amounts in each commodity, hledger chooses a consistent display style -(symbol placement, decimal mark and digit group marks, number of decimal digits) -to use in most reports. This is inferred as follows: - -First, if there's a [`D` directive](#d-directive) declaring a default commodity, -that commodity symbol and amount format is applied to all no-symbol amounts in the journal. - -Then each commodity's display style is determined from its -[`commodity` directive](#commodity-directive). We recommend always -declaring commodities with `commodity` directives, since they help -ensure consistent display styles and precisions, and bring other -benefits such as error checking for commodity symbols. - -But if a `commodity` directive is not present, hledger infers a -commodity's display styles from its amounts as they are written in the -journal (excluding cost amounts and amounts in periodic transaction -rules or auto posting rules). It uses - -- the symbol placement and decimal mark of the first amount seen -- the digit group marks of the first amount with digit group marks -- and the maximum number of decimal digits seen across all amounts. - -And as fallback if no applicable amounts are found, it would use a -default style, like `$1000.00` (symbol on the left with no space, -period as decimal mark, and two decimal digits). - -Finally, commodity styles can be [overridden](#commodity-styles) by -the `-c/--commodity-style` command line option. - -### Rounding - -Amounts are stored internally as decimal numbers with up to 255 decimal places. -They are displayed -with their original journal precisions by print and print-like reports, -and rounded to their display precision (the number of decimal digits specified by the commodity display style) -by other reports. -When rounding, hledger uses [banker's rounding](https://en.wikipedia.org/wiki/Bankers_rounding) -(it rounds to the nearest even digit). So eg 0.5 displayed with zero decimal digits appears as "0". - -### Number format - -hledger will occasionally make some additional adjustments to number formatting, -eg adding a trailing decimal mark to disambiguate numbers with digit group marks; -for details, see [Amount formatting, parseability](#amount-formatting-parseability). +By default, the format of amounts in the journal influences how hledger displays them in output. +This is explained in [Commodity display style](#commodity-display-style) below. -## Costs +### Costs After a posting amount, you can note its cost (when buying) or selling price (when selling) in another commodity, by writing either `@ UNITPRICE` or `@@ TOTALPRICE` after it. @@ -1374,67 +1334,6 @@ Note that the cost normally should be a positive amount, though it's not require This can be a little confusing, see discussion at [--infer-market-prices: market prices from transactions](#--infer-market-prices-market-prices-from-transactions). -### Other cost/lot notations - -A slight digression for Ledger and Beancount users. Ledger has a number of cost/lot-related notations: - -- `@ UNITCOST` and `@@ TOTALCOST` - - expresses a conversion rate, as in hledger - - when buying, also creates a lot than can be selected at selling time - -- `(@) UNITCOST` and `(@@) TOTALCOST` ([virtual cost][ledger: virtual posting costs]) - - like the above, but also means "this cost was exceptional, don't use it when inferring market prices". - -Currently, hledger treats the above like `@` and `@@`; the parentheses are ignored. - -- `{=FIXEDUNITCOST}` and `{{{{=FIXEDTOTALCOST}}}}` ([fixed price][ledger: fixing lot prices]) - - when buying, means "this cost is also the fixed price, don't let it fluctuate in value reports" - -- `{UNITCOST}` and `{{{{TOTALCOST}}}}` ([lot price][ledger: buying and selling stock]) - - can be used identically to `@ UNITCOST` and `@@ TOTALCOST`, also creates a lot - - when selling, combined with `@ ...`, specifies an investment lot by its cost basis; does not check if that lot is present - -- and related: `[YYYY/MM/DD]` ([lot date][ledger: lot dates]) - - when buying, attaches this acquisition date to the lot - - when selling, selects a lot by its acquisition date - -- `(SOME TEXT)` ([lot note][ledger: lot notes]) - - when buying, attaches this note to the lot - - when selling, selects a lot by its note - -Currently, hledger accepts any or all of the above in any order after the posting amount, but ignores them. -(This can break transaction balancing.) - -[ledger: virtual posting costs]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Virtual-posting-costs -[ledger: buying and selling stock]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Buying-and-Selling-Stock -[ledger: fixing lot prices]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices -[ledger: lot dates]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-dates -[ledger: lot notes]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-notes - -For Beancount users, the [notation][beancount: costs and prices] and [behaviour][beancount: how inventories work] is different: - -- `@ UNITCOST` and `@@ TOTALCOST` - - expresses a cost without creating a lot, as in hledger - - when buying (augmenting) or selling (reducing) a lot, combined with `{...}`: documents the cost/selling price (not used for transaction balancing) - -- `{UNITCOST}` and `{{{{TOTALCOST}}}}` - - when buying (augmenting), expresses the cost for transaction balancing, and also creates a lot with this cost basis attached - - when selling (reducing), - - selects a lot by its cost basis - - raises an error if that lot is not present or can not be selected unambiguously (depending on booking method configured) - - expresses the selling price for transaction balancing - -Currently, hledger accepts the `{UNITCOST}`/`{{{{TOTALCOST}}}}` notation but ignores it. - -- variations: `{}`, `{YYYY-MM-DD}`, `{"LABEL"}`, `{UNITCOST, "LABEL"}`, `{UNITCOST, YYYY-MM-DD, "LABEL"}` etc. - -Currently, hledger rejects these. - - -[beancount: costs and prices]: https://beancount.github.io/docs/beancount_language_syntax.html#costs-and-prices -[beancount: how inventories work]: https://beancount.github.io/docs/how_inventories_work.html - - ## Balance assertions hledger supports @@ -1618,6 +1517,37 @@ except they may contain [tags](#tags), which are not ignored. ; a second comment line for posting 2 ``` +## Transaction balancing + +How exactly does hledger decide when a transaction is balanced ? +The general goal is that if you look at the journal entry and calculate the amounts' +sum perfectly with pencil and paper, hledger should agree with you. + +Real world transactions, especially for investments or cryptocurrencies, +often involve imprecise costs, complex decimals, and/or infinitely-recurring decimals, +which are difficult or inconvenient to handle on a computer. +So to be a practical accounting system, hledger allows some imprecision when checking transaction balancedness. +The question is, how much imprecision should be allowed ? + +hledger currently decides it based on the [commodity display styles](#commodity-display-style): +if the postings' sum would appear to be zero when displayed with the standard display precisions, the transaction is considered balanced. + +Or equivalently: if the journal entry is displayed with amounts rounded to the +standard display precisions (with `hledger print --round=hard`), and a human with +pencil and paper would agree that those displayed amounts add up to zero, +the transaction is considered balanced. + +This has some advantages: it is fairly intuitive, general not hard-coded, yet configurable when needed. +On the downside it means that transaction balancedness is related to commodity display precisions, +so eg when using `-c/--commodity-style` to display things with more than usual precision, +you might need to fix some of your journal entries (ie, add decimal digits to make them balance more precisely). + +Other PTA tools (Ledger, Beancount..) have their own ways of doing it. +Possible improvements are discussed at [#1964](https://github.com/simonmichael/hledger/issues/1964). + +Note: if you have multiple journal files, and are relying on commodity directives to make imprecise journal entries balance, +the directives' placement might be important - see [`commodity` directive](#commodity-directive). + ## Tags @@ -1758,11 +1688,11 @@ Here are all hledger's directives, with their effects and scope summarised - nin | **[`account`]** | Declares an account, for [checking](#check) all entries in all files;
and its [display order](#account-display-order) and [type](#declaring-account-types).
Subdirectives: any text, ignored. | N | | **[`alias`]** | Rewrites account names, in following entries until end of current file or [`end aliases`].
Command line equivalent: [`--alias`] | Y | | **[`comment`]** | Ignores part of the journal file, until end of current file or `end comment`. | Y | -| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the decimal mark for parsing amounts of this commodity, in the following entries until end of current file (if there is no `decimal-mark` directive)
3. and the display style for amounts of this commodity
4. which is also the precision to use for balanced-transaction checking in this commodity.
Takes precedence over `D`.
Subdirectives: `format` (Ledger-compatible syntax).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
Y,
N,
N | +| **[`commodity`]** | Declares up to four things:
1. a commodity symbol, for checking all amounts in all files
2. the display style for all amounts of this commodity
3. the decimal mark for parsing amounts of this commodity, in the rest of this file and its children, if there is no `decimal-mark` directive
4. the precision to use for balanced-transaction checking in this commodity, in this file and its children.
Takes precedence over `D`.
Subdirectives: `format` (ignored).
Command line equivalent: [`-c/--commodity-style`](#commodity-styles) | N,
N,
Y,
Y | | **[`decimal-mark`]** | Declares the decimal mark, for parsing amounts of all commodities in following entries until next `decimal-mark` or end of current file. Included files can override. Takes precedence over `commodity` and `D`. | Y | | **[`include`]** | Includes entries and directives from another file, as if they were written inline.
Command line alternative: multiple [`-f/--file`](#multiple-files) | N | | **[`payee`]** | Declares a payee name, for checking all entries in all files. | N | -| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#value-reporting). | N | +| **[`P`]** | Declares the market price of a commodity on some date, for [value reports](#value-reporting). | N | | **[`~`]** (tilde) | Declares a periodic transaction rule that generates future transactions with `--forecast` and budget goals with `balance --budget`. | N | | Other syntax: | | | | **[`apply account`]** | Prepends a common parent account to all account names, in following entries until end of current file or `end apply account`. | Y | @@ -1956,7 +1886,7 @@ Here are some tips for working with account types. 5. Otherwise, it will have no type. - For troubleshooting, you can list accounts and their types with: - ``` + ```cli $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES] ``` @@ -2168,23 +2098,28 @@ The `commodity` directive performs several functions: 1. It declares which commodity symbols may be used in the journal, enabling useful error checking with [strict mode] or the check command. - (See [Commodity error checking](#commodity-error-checking) below.) + See [Commodity error checking](#commodity-error-checking) below. -2. It declares the precision with which this commodity's amounts - should be compared when checking for balanced transactions. +2. It declares how all amounts in this commodity should be displayed, eg how many decimals to show. + See [Commodity display style](#commodity-display-style) above. -3. It declares how this commodity's amounts should be displayed, - eg their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. - (See [Commodity display style](#commodity-display-style) above.) +3. (If no `decimal-mark` directive is in effect:) + It sets the decimal mark to expect (period or comma) when parsing amounts in this commodity, + in this file and files it includes, from the directive until end of current file. + See [Decimal marks](#decimal-marks) above. -4. It sets which decimal mark (period or comma) to expect when parsing subsequent amounts in this commodity - (if there is no `decimal-mark` directive in effect. - See [Decimal marks, digit group marks](hledger.md#decimal-marks-digit-group-marks) above. - For related dev discussion, see [#793](https://github.com/simonmichael/hledger/issues/793).) +4. It declares the precision with which this commodity's amounts should be compared when checking for balanced transactions, + anywhere in this file and files it includes, until end of current file. Declaring commodities solves several common parsing/display problems, so we recommend it. -Generally you should put `commodity` directives at the top of your journal file (because function 4 is position-sensitive). + +Note that effects 3 and 4 above end at the end of the directive's file, +and will not affect sibling or parent files. +So if you are relying on them (especially 4) and using multiple files, +placing your commodity directives in a top-level parent file might be important. +Or, keep your decimal marks unambiguous and your entries well balanced and precise. + +(Related: [#793](https://github.com/simonmichael/hledger/issues/793)) ### Commodity directive syntax @@ -2258,7 +2193,7 @@ or decimal-mark , ``` -This prevents any [ambiguity](#decimal-marks-digit-group-marks) when +This prevents any [ambiguity](#decimal-mark) when parsing numbers in the file, so we recommend it, especially if the file contains digit group marks (eg thousands separators). @@ -2847,6 +2782,67 @@ value EXPR See also for a detailed hledger/Ledger syntax comparison. +### Other cost/lot notations + +A slight digression for Ledger and Beancount users. Ledger has a number of cost/lot-related notations: + +- `@ UNITCOST` and `@@ TOTALCOST` + - expresses a conversion rate, as in hledger + - when buying, also creates a lot than can be selected at selling time + +- `(@) UNITCOST` and `(@@) TOTALCOST` ([virtual cost][ledger: virtual posting costs]) + - like the above, but also means "this cost was exceptional, don't use it when inferring market prices". + +Currently, hledger treats the above like `@` and `@@`; the parentheses are ignored. + +- `{=FIXEDUNITCOST}` and `{{{{=FIXEDTOTALCOST}}}}` ([fixed price][ledger: fixing lot prices]) + - when buying, means "this cost is also the fixed price, don't let it fluctuate in value reports" + +- `{UNITCOST}` and `{{{{TOTALCOST}}}}` ([lot price][ledger: buying and selling stock]) + - can be used identically to `@ UNITCOST` and `@@ TOTALCOST`, also creates a lot + - when selling, combined with `@ ...`, specifies an investment lot by its cost basis; does not check if that lot is present + +- and related: `[YYYY/MM/DD]` ([lot date][ledger: lot dates]) + - when buying, attaches this acquisition date to the lot + - when selling, selects a lot by its acquisition date + +- `(SOME TEXT)` ([lot note][ledger: lot notes]) + - when buying, attaches this note to the lot + - when selling, selects a lot by its note + +Currently, hledger accepts any or all of the above in any order after the posting amount, but ignores them. +(This can break transaction balancing.) + +[ledger: virtual posting costs]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Virtual-posting-costs +[ledger: buying and selling stock]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Buying-and-Selling-Stock +[ledger: fixing lot prices]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices +[ledger: lot dates]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-dates +[ledger: lot notes]: https://www.ledger-cli.org/3.0/doc/ledger3.html#Lot-notes + +For Beancount users, the [notation][beancount: costs and prices] and [behaviour][beancount: how inventories work] is different: + +- `@ UNITCOST` and `@@ TOTALCOST` + - expresses a cost without creating a lot, as in hledger + - when buying (augmenting) or selling (reducing) a lot, combined with `{...}`: documents the cost/selling price (not used for transaction balancing) + +- `{UNITCOST}` and `{{{{TOTALCOST}}}}` + - when buying (augmenting), expresses the cost for transaction balancing, and also creates a lot with this cost basis attached + - when selling (reducing), + - selects a lot by its cost basis + - raises an error if that lot is not present or can not be selected unambiguously (depending on booking method configured) + - expresses the selling price for transaction balancing + +Currently, hledger accepts the `{UNITCOST}`/`{{{{TOTALCOST}}}}` notation but ignores it. + +- variations: `{}`, `{YYYY-MM-DD}`, `{"LABEL"}`, `{UNITCOST, "LABEL"}`, `{UNITCOST, YYYY-MM-DD, "LABEL"}` etc. + +Currently, hledger rejects these. + + +[beancount: costs and prices]: https://beancount.github.io/docs/beancount_language_syntax.html#costs-and-prices +[beancount: how inventories work]: https://beancount.github.io/docs/how_inventories_work.html + + # CSV @@ -3183,14 +3179,14 @@ Note the two kinds of field names mentioned here, and used only in hledger CSV r you can optionally name the CSV columns for easy reference (since hledger doesn't yet automatically recognise column headings in a CSV file), by writing arbitrary names in a `fields` list, eg: - ```csv + ```rules fields When, What, Some_Id, Net, Total, Foo, Bar ``` 2. Special **hledger field names** (`HLEDGERFIELD` in these docs): you must set at least some of these to generate the hledger transaction from a CSV record, by writing them as the left hand side of a [field assignment](#field-assignment), eg: - ```csv + ```rules date %When code %Some_Id description %What @@ -3198,7 +3194,7 @@ Note the two kinds of field names mentioned here, and used only in hledger CSV r amount1 $ %Total ``` or directly in a [`fields` list](#fields-list): - ```csv + ```rules fields date, description, code, , amount1, Foo, Bar currency $ comment %Foo %Bar @@ -4213,7 +4209,7 @@ some number of hours to an account. Or if the session spans more than one day, it is split into several transactions, one for each day. For the above time log, `hledger print` generates these journal entries: -``` shell +```cli $ hledger -f t.timeclock print 2015-03-30 * optional description after 2 spaces ; optional comment, tags: (some account) 0.33h @@ -4243,7 +4239,7 @@ To generate time logs, ie to clock in and clock out, you could: and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el) - at the command line, use these bash aliases: - ```shell + ```cli alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" ``` @@ -4393,7 +4389,7 @@ Letters: 2023-11-01 work:adm ccecces ``` -```journal +```cli $ hledger -f a.timedot print 2023-11-01 (work:adm) 1 ; t:c @@ -4484,14 +4480,68 @@ per:admin .... # PART 3: REPORTING CONCEPTS +# Amount formatting -# Amount formatting, parseability + + +## Commodity display style + +For the amounts in each commodity, hledger chooses a consistent display style +(symbol placement, decimal mark and digit group marks, number of decimal digits) +to use in most reports. This is inferred as follows: + +First, if there's a [`D` directive](#d-directive) declaring a default commodity, +that commodity symbol and amount format is applied to all no-symbol amounts in the journal. + +Then each commodity's display style is determined from its +[`commodity` directive](#commodity-directive). We recommend always +declaring commodities with `commodity` directives, since they help +ensure consistent display styles and precisions, and bring other +benefits such as error checking for commodity symbols. +Here's an example: + +```journal +# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) +# for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 +``` + +But for convenience, if a `commodity` directive is not present, +hledger infers a commodity's display styles from its amounts as they are written in the journal +(excluding cost amounts and amounts in periodic transaction rules or auto posting rules). +It uses + +- the symbol placement and decimal mark of the first amount seen +- the digit group marks of the first amount with digit group marks +- and the maximum number of decimal digits seen across all amounts. + +And as fallback if no applicable amounts are found, it would use a +default style, like `$1000.00` (symbol on the left with no space, +period as decimal mark, and two decimal digits). + +Finally, commodity styles can be [overridden](#commodity-styles) by +the `-c/--commodity-style` command line option. + +## Rounding + +Amounts are stored internally as decimal numbers with up to 255 decimal places. +They are displayed +with their original journal precisions by print and print-like reports, +and rounded to their display precision (the number of decimal digits specified by the commodity display style) +by other reports. +When rounding, hledger uses [banker's rounding](https://en.wikipedia.org/wiki/Bankers_rounding) +(it rounds to the nearest even digit). So eg 0.5 displayed with zero decimal digits appears as "0". + +## Trailing decimal marks If you're wondering why your [`print`](#print) report sometimes shows trailing decimal marks, with no decimal digits; it does this when showing amounts that have digit group marks but no decimal digits, to disambiguate them and allow them to be re-parsed reliably -(see also [Decimal marks, digit group marks](#decimal-marks-digit-group-marks). +(see [Decimal marks](#decimal-marks)). Eg: ```journal @@ -4528,7 +4578,9 @@ $ hledger print -c '$1,000.00' --round=soft ``` -More generally: hledger output falls into three rough categories, which +## Amount parseability + +More generally, hledger output falls into three rough categories, which format amounts a little bit differently to suit different consumers: **1. "hledger-readable output" - should be readable by hledger (and by humans)** @@ -5008,25 +5060,16 @@ Some queries can also be expressed as command-line options: When you mix command options and query arguments, generally the resulting query is their intersection. +## Queries and account aliases + +When account names are [rewritten](#alias-directive) with `--alias` or `alias`, +`acct:` will match either the old or the new account name. + ## Queries and valuation When amounts are converted to other commodities in [cost](#cost-reporting) or [value](#value-reporting) reports, -`cur:` and `amt:` match the old commodity symbol and the old amount quantity, -not the new ones -(except in hledger 1.22.0 where it's reversed, see [#1625](https://github.com/simonmichael/hledger/issues/1625)). - -## Querying with account aliases - -When account names are [rewritten](#alias-directive) with `--alias` or `alias`, -note that `acct:` will match either the old or the new account name. - -## Querying with cost or value - -When amounts are converted to other commodities in [cost](#cost-reporting) or [value](#value-reporting) reports, -note that `cur:` matches the new commodity symbol, and not the old one, -and `amt:` matches the new quantity, and not the old one. -Note: this changed in hledger 1.22, previously it was the reverse, -see the discussion at [#1625](https://github.com/simonmichael/hledger/issues/1625). +`cur:` and `amt:` match the old commodity symbol and the old amount quantity, not the new ones. +(Except in hledger 1.22, [#1625](https://github.com/simonmichael/hledger/issues/1625).) # Pivoting @@ -5140,7 +5183,7 @@ You can override it - eg to forecast farther into the future, or to force foreca assets:bank:checking expenses:rent $1000 ``` -```terminal +```cli $ hledger print --forecast --today=2023/4/21 2023-05-20 rent ; generated-transaction: ~ monthly from 2022-12-20 @@ -5175,7 +5218,7 @@ Here there are no ordinary transactions, so the forecasted transactions begin on Forecast transactions affect all reports, as you would expect. Eg: -```terminal +```cli $ hledger areg rent --forecast --today=2023/4/21 Transactions in expenses:rent and subaccounts: 2023-05-20 rent as:ba:checking $1000 $1000 @@ -5185,7 +5228,7 @@ Transactions in expenses:rent and subaccounts: 2023-09-20 rent as:ba:checking $1000 $5000 ``` -```terminal +```cli $ hledger bal -M expenses --forecast --today=2023/4/21 Balance changes in 2023-05-01..2023-09-30: @@ -5653,38 +5696,6 @@ This means: Amounts for which no valuation commodity can be found are not converted. -## Simple valuation examples - -Here are some quick examples of `-V`: - -```journal -; one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -; purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -; the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 -``` -How many euros do I have ? -```cli -$ hledger -f t.j bal -N euros - €100 assets:euros -``` -What are they worth at end of nov 3 ? -```cli -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros -``` -What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) -```cli -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros -``` - ## --value: Flexible valuation `-V` and `-X` are special cases of the more general `--value` option: @@ -5721,7 +5732,38 @@ a comma, then the target commodity's symbol. Eg: **`--value=now,EUR`**. hledger will do its best to convert amounts to this commodity, deducing [market prices](#p-directive) as described above. -## More valuation examples +## Valuation examples + +Here are some quick examples of `-V`: + +```journal +; one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +; purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +; the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 +``` +How many euros do I have ? +```cli +$ hledger -f t.j bal -N euros + €100 assets:euros +``` +What are they worth at end of nov 3 ? +```cli +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros +``` +What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) +```cli +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros +``` + Here are some examples showing the effect of `--value`, as seen with `print`: @@ -5810,8 +5852,7 @@ $ hledger -f- print --value=2000-01-15 ## Interaction of valuation and queries -When matching postings based on queries in the presence of valuation, the -following happens. +When matching postings based on queries in the presence of valuation, the following happens: 1. The query is separated into two parts: 1. the currency (`cur:`) or amount (`amt:`). @@ -5820,20 +5861,44 @@ following happens. 3. Valuation is applied to the postings. 4. The postings are matched to the other parts of the query based on post-valued amounts. -See: -[1625](https://github.com/simonmichael/hledger/issues/1625) +Related: +[#1625](https://github.com/simonmichael/hledger/issues/1625) ## Effect of valuation on reports -Here is a reference for how valuation is supposed to affect each part of hledger's reports (and a glossary). -(It's wide, you'll have to scroll sideways.) +Here is a reference for how valuation is supposed to affect each part of hledger's reports. +(It's wide, you may need to scroll sideways.) It may be useful when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Related: [#329](https://github.com/simonmichael/hledger/issues/329), [#1083](https://github.com/simonmichael/hledger/issues/1083). +First, a quick glossary: + +*cost* +: calculated using price(s) recorded in the transaction(s). + +*value* +: market value using available market price declarations, or the unchanged amount if no conversion rate can be found. + +*report start* +: the first day of the report period specified with -b or -p or date:, otherwise today. + +*report or journal start* +: the first day of the report period specified with -b or -p or date:, otherwise the earliest transaction date in the journal, otherwise today. + +*report end* +: the last day of the report period specified with -e or -p or date:, otherwise today. + +*report or journal end* +: the last day of the report period specified with -e or -p or date:, otherwise the latest transaction date in the journal, otherwise today. + +*report interval* +: a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperiods). + + | Report type | `-B`, `--cost` | `-V`, `-X` | `--value=then` | `--value=end` | `--value=DATE`, `--value=now` | |-----------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------| | **print** | | | | | | @@ -5864,30 +5929,6 @@ Related: `--cumulative` is omitted to save space, it works like `-H` but with a zero starting balance. -**Glossary:** - -*cost* -: calculated using price(s) recorded in the transaction(s). - -*value* -: market value using available market price declarations, or the unchanged amount if no conversion rate can be found. - -*report start* -: the first day of the report period specified with -b or -p or date:, otherwise today. - -*report or journal start* -: the first day of the report period specified with -b or -p or date:, otherwise the earliest transaction date in the journal, otherwise today. - -*report end* -: the last day of the report period specified with -e or -p or date:, otherwise today. - -*report or journal end* -: the last day of the report period specified with -e or -p or date:, otherwise the latest transaction date in the journal, otherwise today. - -*report interval* -: a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperiods). - - # PART 4: COMMANDS ## Commands overview diff --git a/hledger/test/journal/balance-assertions.test b/hledger/test/journal/balance-assertions.test index 68782e486..c746e75da 100755 --- a/hledger/test/journal/balance-assertions.test +++ b/hledger/test/journal/balance-assertions.test @@ -15,9 +15,7 @@ b $-1 = $-3 (b) $1 = $-2 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 2. same entries as 1 but different parse order, assertion should still pass based on date < @@ -34,9 +32,7 @@ $ hledger -f - stats a $1 =$2 b $-1 =$-2 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 3. like 1 but switch order of postings in last entry, # assertion should fail and exit code should be non zero @@ -54,7 +50,7 @@ $ hledger -f - stats (b) $1 = $-2 b $-1 = $-3 -$ hledger -f - stats +$ hledger -f - check >2 /Error: -:11:12/ >=1 @@ -63,9 +59,7 @@ $ hledger -f - stats 2013/1/1 (a) 1 =1 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 5. should work for fractional amount with trailing zeros < @@ -81,9 +75,7 @@ $ hledger -f - stats a $0.7 =$2 b =-$2 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 6. assertions currently check only a single commodity's balance, like Ledger < @@ -93,9 +85,7 @@ $ hledger -f - stats (a) 0 = A1 (a) C0 = D0 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 7. balances should accumulate (#195) < @@ -106,9 +96,7 @@ $ hledger -f - stats 1/2 (a) 3F = 4F -$ hledger -f - stats -> !/assertion failed/ ->=0 +$ hledger -f - check # ** 8. what should happen here ? Currently, # in a, 3.4 EUR @@ $5.6 and -3.4 EUR cancel out (wrong ?) @@ -128,9 +116,7 @@ $ hledger -f - stats # a $0.1 =$1.30 # b =-$1.30 -# $ hledger -f - stats -# > /Transactions/ -# >=0 +# $ hledger -f - check # ** 8. Using balance assignment to set balances. < @@ -146,9 +132,7 @@ $ hledger -f - stats a $10 =$11.3 b =$-11.3 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 9. Multiple assertions for an account in the same transaction. @@ -166,9 +150,7 @@ $ hledger -f - stats b $-1 = $-3 b $-1 = $-4 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 10. Multiple assertions and assignments for an account in the same transaction. < @@ -196,9 +178,7 @@ $ hledger -f - stats c = 50 B c = 50 A -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 11. Assignments and virtual postings < @@ -214,16 +194,15 @@ $ hledger -f - stats [a] = $5 b = $9 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check + # ** 12. Having both assignments and posting dates is not supported. < 2013/1/1 a $1 =$1 b =$-1 ; date:2012/1/1 -$ hledger -f - stats +$ hledger -f - check >2 /Balance assignments and custom posting dates may not be combined/ >=1 @@ -247,9 +226,7 @@ $ hledger -f - stats [d] 10 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 14. Mix different commodities < @@ -261,9 +238,7 @@ $ hledger -f - stats a $-1 = $0 b -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 15. Mix different commodities and assignments < @@ -282,9 +257,7 @@ $ hledger -f - stats a b = 0 zorkmids -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 16. Total assertions (==) parse correctly < @@ -295,9 +268,7 @@ $ hledger -f - stats 2016/1/2 a == $1 -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 17. Total assertions consider entire multicommodity amount < @@ -312,7 +283,7 @@ $ hledger -f - stats 2016/1/3 a 0 == $1 -$ hledger -f - stats +$ hledger -f - check >2 /Error: -:10:15:/ >=1 @@ -331,9 +302,7 @@ $ hledger -f - stats b 0 = $-1 b 0 = 0 zorkmids -$ hledger -f - stats -> /Transactions/ ->=0 +$ hledger -f - check # ** 19. Cost is ignored when checking balance assertions. < diff --git a/hledger/test/journal/include.test b/hledger/test/journal/include.test index cc8cb6244..ad4443707 100644 --- a/hledger/test/journal/include.test +++ b/hledger/test/journal/include.test @@ -74,12 +74,12 @@ $ printf '2018/01/01\n (A) 1\n' >included.journal; HOME="$PWD" hledger -f - pr # They use different file names so a single concurrent shelltest invocation will be fine. # ** 7. test that order of include files is maintained -$ printf 'include _b\n' >_a; touch _b; hledger -f _a stats | grep _ | sed -e 's%.*/%%'; rm -rf _a _b +$ printf 'include _b\n' >_a; touch _b; hledger -f _a stats -v | grep _ | sed -e 's%.*/%%'; rm -rf _a _b _a _b # ** 8. and with --auto code path -$ printf 'include _d\n=\n' >_c; touch _d; hledger -f _c stats --auto | grep _ | sed -e 's%.*/%%'; rm -rf _c _d +$ printf 'include _d\n=\n' >_c; touch _d; hledger -f _c stats -v --auto | grep _ | sed -e 's%.*/%%'; rm -rf _c _d _c _d diff --git a/hledger/test/query-bool.test b/hledger/test/query-expr.test similarity index 92% rename from hledger/test/query-bool.test rename to hledger/test/query-expr.test index cf476351d..8b452a99c 100644 --- a/hledger/test/query-bool.test +++ b/hledger/test/query-expr.test @@ -146,3 +146,15 @@ $ hledger -f - print expr:"not (tag:transactiontag=B)" expenses:food >= + +# ** 11. Posting-based reports handle OR'd open-ended date periods properly. (#2177) +< +2023-12-26 2023 + (2023) 2023 + +2024-01-26 2024 + (2024) 2024 + +$ hledger -f- reg -w80 expr:'date:2023 or date:2024' +2023-12-26 2023 (2023) 2023 2023 +2024-01-26 2024 (2024) 2024 4047 diff --git a/hledger/test/stats.test b/hledger/test/stats.test index cdb7945b0..dede1acad 100644 --- a/hledger/test/stats.test +++ b/hledger/test/stats.test @@ -7,6 +7,6 @@ $ hledger -f- stats < include a.j include b.j -$ touch a.j b.j; hledger -f- stats; rm -f a.j b.j +$ touch a.j b.j; hledger -f- stats -v; rm -f a.j b.j > /Included files.*\/a\.j .*\/b\.j/ diff --git a/tools/buglist/index.html b/tools/buglist/index.html index 9588fbfd8..ae3f3e14b 100644 --- a/tools/buglist/index.html +++ b/tools/buglist/index.html @@ -10,32 +10,32 @@ th { white-space: nowrap; } tr { border-top:thin solid #eee; vertical-align:top; } td { padding:0 1em; } - .tag { color:white; text-shadow: 2px 2px 2px black; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } + /* .tag { color:white; text-shadow: 2px 2px 2px black; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } + .paletag { color:black; font-weight:bold; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } */ + .tag { color:white; font-weight:bold; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } .paletag { color:black; font-weight:bold; font-size:small; padding:2px 8px 4px 6px; border-radius:1em; } -

hledger open bugs

-

- Currently our user pain score is - Impact (number of people affected, 1-5) * Severity (for those affected, 1-5) / 25. -
+

hledger open bugs by user pain (user joy when fixed)

+

+ Our user pain score is + impact (number of people affected, 1-5) * severity (for those affected, 1-5) / 25 * 10.
The possible scores are: -0.04 -0.08 -0.12 -0.16 -0.20 -0.24 -0.32 -0.36 -0.40 -0.48 -0.60 -0.64 -0.80 -1.00 -. + 0.4 + 0.8 + 1.2 + 1.6 + 2.0 + 2.4 + 3.2 + 3.6 + 4.0 + 4.8 + 6.0 + 6.4 + 8.0 +10.0

diff --git a/tools/changelog.hs b/tools/changelog.hs index 2c8164703..c8ed70427 100755 --- a/tools/changelog.hs +++ b/tools/changelog.hs @@ -1,5 +1,5 @@ #!/usr/bin/env stack -{- stack script --resolver lts-18.18 +{- stack script --resolver lts-22.12 --package data-default --package extra --package process