![CI status](https://github.com/zacchiro/beangrep/actions/workflows/python-package.yml/badge.svg)
Beangrep - grep-like filter for Beancount
=========================================
[Beangrep][beangrep-home] is a [grep][grep-wikipedia]-like filter for the
[Beancount][beancount-home] plain text accounting system.
[beangrep-home]: https://github.com/zacchiro/beangrep
[grep-wikipedia]: https://en.wikipedia.org/wiki/Grep
[beancount-home]: http://beancount.github.io/
Installation
------------
### Prebuilt package
```console
$ python3 -m venv ./venv # optional but recommended
$ source venv/bin/activate
$ pip install beangrep
[...]
Successfully installed beancount-2.3.6 beangrep-...
$ bean-grep --help
Usage: bean-grep [OPTIONS] FILENAME
[...]
```
### From source
```console
$ git clone https://github.com/zacchiro/beangrep
$ cd beangrep
$ python3 -m venv ./venv # optional but recommended
$ source venv/bin/activate
$ pip install -e .
[...]
Successfully installed beancount-2.3.6 beangrep-...
$ bean-grep --help
Usage: bean-grep [OPTIONS] FILENAME
[...]
```
Usage
-----
The CLI says it all when invoked as `bean-grep --help`:
```
Usage: bean-grep [OPTIONS] [PATTERN] FILENAME...
Search for entries matching given criteria in Beancount journals. Pretty
print matching entries to standard output.
Search criteria can be specified with the options below and/or providing an
explicit "smart" PATTERN. If given, PATTERN is interpreted as described
below under "Patterns". If not given, search criteria are defined by
explicit options.
Multiple options, options given mutiple times, and PATTERN(s) are logically
joined (AND-ed) together.
The granularity of matching (and results) is that of individual entries,
e.g., full transactions, balances, notes, etc. By default only transactions
are returned; use the --type/-T option to override.
To read from standard input, pass "-" as FILENAME, but beware that it
implies on-disk buffering of stdin.
All options can be set via environment variables, which is most useful if
you want to override the defaults. Each environment variable
consists of the prefix BEANGREP_ followed by the option name in uppercase.
e.g., BEANGREP_VERBOSE, BEANGREP_CASE_SENSITIVE, BEANGREP_QUIET,
BEANGREP_NO_SKIP_INTERNALS, etc. Boolean options are enabled/disabled by
setting the corresponding variables to 1/0 respectively, e.g.,
BEANGREP_QUIET=1.
Options:
-a, --account REGEX Only return entries referencing accounts
with names matching given regex.
-A, --amount "[OP]AMOUNT [REGEX]"
Only return entries with amounts matching
the given amount predicate. An amount
predicate start with an optional comparison
operator (one of "<", "<=", "=", ">=", ">",
with "=" being the default), followed by a
decimal number (using "." as decimal
separator), followed by an optional currency
regex. Multiple amount predicates can be
given to express complex amount ranges.
-d, --date [OP]DATE Only return entries with dates matching the
given date predicate. A date predicate start
with an optional comparison operator (one of
"<", "<=", "=", ">=", ">", with "=" being
the default), and is followed by a date in
the form YYYY-[MM[-DD]]. Multiple date
predicates can be given to express complex
date ranges.
-f, --flag REGEX Only return transactions with at least one
flag matching the given regex (usually a
single character, properly escaped). Both
transaction and posting flags are used for
matching.
-l, --link REGEX Only return entries with at least one link
matching given regex.
-m, --meta, --metadata REGEX[:REGEX]
Only return entries with at least one
metadata key/value pair matching given
pattern. A pattern is a pair of regexs
separated by ":", the former matching on
metadata key, the latter on metadata value.
The second regex is optional and defaults to
".*".
-n, --narration REGEX Only return entries whose narrations match
given regex.
-p, --payee REGEX Only return entries whose payees match given
regex.
-s, --somewhere, --anywhere REGEX
Only return entries with a value in them,
anywhere, matching given regex.
-t, --tag REGEX Only return entries with at least one tag
matching given regex. The tag can be located
anywhere.
-T, --type TYPE(S) Only return entries of certain types. Types
are specified as a ","-separated list of
type names; type names are: open, close,
commodity, pad, balance, transaction, note,
event, query, price, document, custom. The
special value "all" means: all directive
types. [default: transaction]
--case-sensitive Search case sensitively. Overrides:
-i/--ignore-case and -S/--smart-case.
-i, --ignore-case Search case insensitively. Overrides
-S/--smart-case; overridden by --case-
sensitive.
-S, --smart-case Search case insensitively if all criteria
are lowercase, sensitively otherwise.
Overridden by: --case-sensitive and
-i/--ignore-case. [default: True]
--posting-tags-meta TEXT Metadata key used to attach tags to
transaction postings. [default: tags]
-q, --quiet / --no-quiet Quiet, do not write anything to standard
output. Exit successfully immediately if any
match is found. [default: no-quiet]
--skip-internals / --no-skip-internals
When matching, ignore internal information
not visible in the ledger. This includes the
automatic metadata: filename, lineno.
[default: skip-internals]
-v, --invert-match Invert the sense of matching: return entries
that do *not* match given criteria. This
clears the default "--type transaction"
criteria, to avoid only returning non-
transaction entries by default.
--verbose Increase logging verbosity. Default
verbosity is at WARNING level; passing this
option once will increase it to INFO, twice
or more to DEBUG.
-V, --version Show the version and exit.
--help Show this message and exit.
Patterns:
When given the "smart" PATTERN is interpreted according to the following
heuristics, tried in order, first match wins:
- if it is in the form "YYYY-MM-DD" -> then it is interpreted as --date
- "#tag" -> --tag
- "^link" -> --link
- "@payee" -> --payee
- if it starts with one of the five account types ("Assets", "Equity",
"Expenses", "Income", "Liabilities") -> --account
- "key:value" -> --metadata
- otherwise -> --somewhere
Exit status:
Exit status is 0 (success) if a match is found, 1 if no match is found, 2 if
an error occurred.
```
Author
------
* [Stefano Zacchiroli][zack-home] [`<zack@upsilon.cc>`][zack-email]
[zack-home]: https://upsilon.cc/~zack
[zack-email]: mailto:zack@upsilon.cc
License
-------
Beangrep is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is [distributed with Beangrep][gpl2-here]
as well as from the [official license page][gpl2-home].
[gpl2-here]: https://github.com/zacchiro/beangrep/blob/main/LICENSE-GPL-2.0-or-later
[gpl2-home]: https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
Raw data
{
"_id": null,
"home_page": null,
"name": "beangrep",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "accounting, beancount, grep, ledger, plaintext, plaintext-accounting",
"author": null,
"author_email": "Stefano Zacchiroli <zack@upsilon.cc>",
"download_url": "https://files.pythonhosted.org/packages/f5/52/dce5573f9fcd5ccbcc6c39451fc1cbf8d725323976a2f6bfbf807f04ae64/beangrep-0.6.0.tar.gz",
"platform": null,
"description": "![CI status](https://github.com/zacchiro/beangrep/actions/workflows/python-package.yml/badge.svg)\n\n\nBeangrep - grep-like filter for Beancount\n=========================================\n\n[Beangrep][beangrep-home] is a [grep][grep-wikipedia]-like filter for the\n[Beancount][beancount-home] plain text accounting system.\n\n[beangrep-home]: https://github.com/zacchiro/beangrep\n[grep-wikipedia]: https://en.wikipedia.org/wiki/Grep\n[beancount-home]: http://beancount.github.io/\n\n\nInstallation\n------------\n\n### Prebuilt package\n\n```console\n$ python3 -m venv ./venv # optional but recommended\n$ source venv/bin/activate\n\n$ pip install beangrep\n[...]\nSuccessfully installed beancount-2.3.6 beangrep-...\n\n$ bean-grep --help\nUsage: bean-grep [OPTIONS] FILENAME\n[...]\n```\n\n### From source\n\n```console\n$ git clone https://github.com/zacchiro/beangrep\n$ cd beangrep\n\n$ python3 -m venv ./venv # optional but recommended\n$ source venv/bin/activate\n\n$ pip install -e .\n[...]\nSuccessfully installed beancount-2.3.6 beangrep-...\n\n$ bean-grep --help\nUsage: bean-grep [OPTIONS] FILENAME\n[...]\n```\n\n\nUsage\n-----\n\nThe CLI says it all when invoked as `bean-grep --help`:\n\n```\nUsage: bean-grep [OPTIONS] [PATTERN] FILENAME...\n\n Search for entries matching given criteria in Beancount journals. Pretty\n print matching entries to standard output.\n\n Search criteria can be specified with the options below and/or providing an\n explicit \"smart\" PATTERN. If given, PATTERN is interpreted as described\n below under \"Patterns\". If not given, search criteria are defined by\n explicit options.\n\n Multiple options, options given mutiple times, and PATTERN(s) are logically\n joined (AND-ed) together.\n\n The granularity of matching (and results) is that of individual entries,\n e.g., full transactions, balances, notes, etc. By default only transactions\n are returned; use the --type/-T option to override.\n\n To read from standard input, pass \"-\" as FILENAME, but beware that it\n implies on-disk buffering of stdin.\n\n All options can be set via environment variables, which is most useful if\n you want to override the defaults. Each environment variable\n consists of the prefix BEANGREP_ followed by the option name in uppercase.\n e.g., BEANGREP_VERBOSE, BEANGREP_CASE_SENSITIVE, BEANGREP_QUIET,\n BEANGREP_NO_SKIP_INTERNALS, etc. Boolean options are enabled/disabled by\n setting the corresponding variables to 1/0 respectively, e.g.,\n BEANGREP_QUIET=1.\n\nOptions:\n -a, --account REGEX Only return entries referencing accounts\n with names matching given regex.\n -A, --amount \"[OP]AMOUNT [REGEX]\"\n Only return entries with amounts matching\n the given amount predicate. An amount\n predicate start with an optional comparison\n operator (one of \"<\", \"<=\", \"=\", \">=\", \">\",\n with \"=\" being the default), followed by a\n decimal number (using \".\" as decimal\n separator), followed by an optional currency\n regex. Multiple amount predicates can be\n given to express complex amount ranges.\n -d, --date [OP]DATE Only return entries with dates matching the\n given date predicate. A date predicate start\n with an optional comparison operator (one of\n \"<\", \"<=\", \"=\", \">=\", \">\", with \"=\" being\n the default), and is followed by a date in\n the form YYYY-[MM[-DD]]. Multiple date\n predicates can be given to express complex\n date ranges.\n -f, --flag REGEX Only return transactions with at least one\n flag matching the given regex (usually a\n single character, properly escaped). Both\n transaction and posting flags are used for\n matching.\n -l, --link REGEX Only return entries with at least one link\n matching given regex.\n -m, --meta, --metadata REGEX[:REGEX]\n Only return entries with at least one\n metadata key/value pair matching given\n pattern. A pattern is a pair of regexs\n separated by \":\", the former matching on\n metadata key, the latter on metadata value.\n The second regex is optional and defaults to\n \".*\".\n -n, --narration REGEX Only return entries whose narrations match\n given regex.\n -p, --payee REGEX Only return entries whose payees match given\n regex.\n -s, --somewhere, --anywhere REGEX\n Only return entries with a value in them,\n anywhere, matching given regex.\n -t, --tag REGEX Only return entries with at least one tag\n matching given regex. The tag can be located\n anywhere.\n -T, --type TYPE(S) Only return entries of certain types. Types\n are specified as a \",\"-separated list of\n type names; type names are: open, close,\n commodity, pad, balance, transaction, note,\n event, query, price, document, custom. The\n special value \"all\" means: all directive\n types. [default: transaction]\n --case-sensitive Search case sensitively. Overrides:\n -i/--ignore-case and -S/--smart-case.\n -i, --ignore-case Search case insensitively. Overrides\n -S/--smart-case; overridden by --case-\n sensitive.\n -S, --smart-case Search case insensitively if all criteria\n are lowercase, sensitively otherwise.\n Overridden by: --case-sensitive and\n -i/--ignore-case. [default: True]\n --posting-tags-meta TEXT Metadata key used to attach tags to\n transaction postings. [default: tags]\n -q, --quiet / --no-quiet Quiet, do not write anything to standard\n output. Exit successfully immediately if any\n match is found. [default: no-quiet]\n --skip-internals / --no-skip-internals\n When matching, ignore internal information\n not visible in the ledger. This includes the\n automatic metadata: filename, lineno.\n [default: skip-internals]\n -v, --invert-match Invert the sense of matching: return entries\n that do *not* match given criteria. This\n clears the default \"--type transaction\"\n criteria, to avoid only returning non-\n transaction entries by default.\n --verbose Increase logging verbosity. Default\n verbosity is at WARNING level; passing this\n option once will increase it to INFO, twice\n or more to DEBUG.\n -V, --version Show the version and exit.\n --help Show this message and exit.\n\n Patterns:\n\n When given the \"smart\" PATTERN is interpreted according to the following\n heuristics, tried in order, first match wins:\n\n - if it is in the form \"YYYY-MM-DD\" -> then it is interpreted as --date\n\n - \"#tag\" -> --tag\n\n - \"^link\" -> --link\n\n - \"@payee\" -> --payee\n\n - if it starts with one of the five account types (\"Assets\", \"Equity\",\n \"Expenses\", \"Income\", \"Liabilities\") -> --account\n\n - \"key:value\" -> --metadata\n\n - otherwise -> --somewhere\n\n Exit status:\n\n Exit status is 0 (success) if a match is found, 1 if no match is found, 2 if\n an error occurred.\n```\n\n\nAuthor\n------\n\n* [Stefano Zacchiroli][zack-home] [`<zack@upsilon.cc>`][zack-email]\n\n[zack-home]: https://upsilon.cc/~zack\n[zack-email]: mailto:zack@upsilon.cc\n\n\nLicense\n-------\n\nBeangrep is free software; you can redistribute it and/or modify it under the\nterms of the GNU General Public License as published by the Free Software\nFoundation; either version 2 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nA copy of the GNU General Public License is [distributed with Beangrep][gpl2-here]\nas well as from the [official license page][gpl2-home].\n\n[gpl2-here]: https://github.com/zacchiro/beangrep/blob/main/LICENSE-GPL-2.0-or-later\n[gpl2-home]: https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html\n",
"bugtrack_url": null,
"license": "GPL-2.0-or-later",
"summary": "Grep-like filter for the Beancount plain text accounting system",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/zacchiro/beangrep",
"Issues": "https://github.com/zacchiro/beangrep/issues"
},
"split_keywords": [
"accounting",
" beancount",
" grep",
" ledger",
" plaintext",
" plaintext-accounting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8493e81f6305ba77964074edeb7cf8ae1ce2d3c76fab1e1fc553c52bb4a41b1c",
"md5": "3b78d2176083f3084bbad89921cbe043",
"sha256": "b6f8320fcb4c06172f5abe99628641ece5f696f8330f1f21120074913088fdbe"
},
"downloads": -1,
"filename": "beangrep-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b78d2176083f3084bbad89921cbe043",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 25658,
"upload_time": "2024-08-04T14:24:33",
"upload_time_iso_8601": "2024-08-04T14:24:33.351419Z",
"url": "https://files.pythonhosted.org/packages/84/93/e81f6305ba77964074edeb7cf8ae1ce2d3c76fab1e1fc553c52bb4a41b1c/beangrep-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f552dce5573f9fcd5ccbcc6c39451fc1cbf8d725323976a2f6bfbf807f04ae64",
"md5": "2a4edffc49a85e990e6df0ad0e626ae0",
"sha256": "5c062a9a2c30723cf097a5fc725fcfbd9e6f1e68eb2f326e7685b196e50708c8"
},
"downloads": -1,
"filename": "beangrep-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "2a4edffc49a85e990e6df0ad0e626ae0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 56672,
"upload_time": "2024-08-04T14:24:34",
"upload_time_iso_8601": "2024-08-04T14:24:34.907963Z",
"url": "https://files.pythonhosted.org/packages/f5/52/dce5573f9fcd5ccbcc6c39451fc1cbf8d725323976a2f6bfbf807f04ae64/beangrep-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-04 14:24:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zacchiro",
"github_project": "beangrep",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "beangrep"
}