Tackler

https://github.com/tackler-ng/tackler
Admin
Tackler is a fast and reliable bookkeeping engine for plain text accounting written in Rust,...
Tokens:23,974
Snippets:400
Trust Score:5.3
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Tackler Output Examples

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Example output showing Git storage metadata, checksums, and balance reports.

```text
Git Storage
      reference : set-1e5
      directory : txns
      extension : txn
         commit : 4648a2994b41ed341b544a148b3060fd2d267d79
         author : tackler <accounting@example.com>
           date : 2016-12-31 17:41:24 +0000
        subject : set-1e5: 2016-12-31

Txn Set Checksum
        SHA-256 : 2f4bc22df78502182aa27037d8d0f72462adb018be3e768399e0b803fa75baa7
       set size : 100000

**********************************************************************************
Account Selector Checksum
        SHA-256 : df4714ff3f5bd031a8256df95863a8085f740b436f1b47febb45c9eb9aaa9e9e
       selector : 'a:.*'


Balance Report
--------------
               -135601.00   a:ay2016:am01
               -118950.00   a:ay2016:am02
               -135631.00   a:ay2016:am03
               -127137.00   a:ay2016:am04
               -135616.00   a:ay2016:am05
               -127154.00   a:ay2016:am06
               -135600.00   a:ay2016:am07
               -135603.00   a:ay2016:am08
               -127140.00   a:ay2016:am09
               -135619.00   a:ay2016:am10
               -127126.00   a:ay2016:am11
               -133402.00   a:ay2016:am12
=========================
              -1574579.01
##################################################################################
```

```text
Git Storage
      reference : set-1e5
      directory : txns
      extension : txn
         commit : 4648a2994b41ed341b544a148b3060fd2d267d79
         author : tackler <accounting@example.com>
           date : 2016-12-31 17:41:24 +0000
        subject : set-1e5: 2016-12-31

Txn Set Checksum
        SHA-256 : 8ff80f72dc8b36fd6272319d08b99c54d8cf47baff47eda3df68b69e7b7b66bc
       set size : 8405

Filter
  Posting Account: "a:ay2016:am12"

**********************************************************************************
Account Selector Checksum
        SHA-256 : df4714ff3f5bd031a8256df95863a8085f740b436f1b47febb45c9eb9aaa9e9e
       selector : 'a:.*'


Balance Report
--------------
              -133402.00   a:ay2016:am12
========================
              -133402.00
##################################################################################
```

--------------------------------

### Tracking Unit Based Commodity (Time)

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1001/units.adoc

Example demonstrating how to track a commodity based on time units, specifying start and end times with their respective unit values and a final accumulator value.

```text
2017-05-01 tracking unit based commodity (time)
   Time:Start  1493629200 s ; 2017-05-01T12:00:00+03:00
   Time:End   -1493636400 s ; 2017-05-01T14:00:00+03:00
   Accumulator  ; 7200 s
```

--------------------------------

### Install and Run Tackler

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Commands to install the Tackler binary via Cargo, initialize a new project, and execute it with a configuration file.

```bash
cargo install --locked tackler
tackler new demo
tackler --config demo/conf/tackler.toml
```

--------------------------------

### Run Complex Git Storage Example

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Executes Tackler with a configuration for Git storage. This example demonstrates strict and audit modes.

```bash
target/release/tackler --config examples/audit.toml
```

--------------------------------

### Create a New Journal Setup

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Initializes a new Tackler journal and sets the configuration file for subsequent commands.

```bash
target/release/tackler new journal
target/release/tackler --config journal/conf/tackler.toml
```

--------------------------------

### Audit Mode Output Example

Source: https://context7.com/tackler-ng/tackler/llms.txt

Example output format when running Tackler in audit mode.

```text
Git Storage
      reference : set-1e5
      directory : txns
      extension : txn
         commit : 4648a2994b41ed341b544a148b3060fd2d267d79
         author : tackler <accounting@example.com>
           date : 2016-12-31 17:41:24 +0000
        subject : set-1e5: 2016-12-31

Txn Set Checksum
        SHA-256 : 2f4bc22df78502182aa27037d8d0f72462adb018be3e768399e0b803fa75baa7
       set size : 100000

**********************************************************************************
Account Selector Checksum
        SHA-256 : abbcd1800caab82df857441d734b728ca18850f08f9a1c96602ee740b970cae0
       selector : 'a:ay2016:am12'


Balance Report
--------------
              -133402.00   a:ay2016:am12
========================
              -133402.00
##################################################################################
```

--------------------------------

### Build Tackler with Just

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Builds the release version of Tackler using the 'just' command. Assumes 'just' is installed.

```bash
just release-build
```

--------------------------------

### Run Simple Filesystem Journal Example

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Executes Tackler using a simple configuration file for filesystem journaling. The binary is expected in the target/release directory.

```bash
target/release/tackler --config examples/simple.toml
```

--------------------------------

### Initialize and Run Tackler

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Commands to install the Tackler binary, initialize a new demo project, and execute the engine using a specific configuration file.

```bash
cargo install --locked tackler # (2)
tackler new demo
tackler --config demo/conf/tackler.toml
```

--------------------------------

### Install Latest Development Version

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Installs the latest development version of Tackler from its Git repository. Ensure you have Rust and Cargo installed.

```bash
cargo install --locked --git https://github.com/tackler-ng/tackler tackler
```

--------------------------------

### Opening Position Example

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1003.adoc

Illustrates how to record an opening position for a commodity, including its quantity, currency, and associated cash transaction.

```plaintext
2014-05-01 opening / buy
   inventory  1 USD {1.38 EUR}
   a:cash    -1.38 EUR
```

--------------------------------

### Git and Price Data Metadata

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Example of Git storage metadata and price data entries.

```text
Git Storage
         commit : 4aa4e9797501c1aefc92f32dff30ab462dae5545
      reference : txns-1E1
      directory : txns
         suffix : .txn
        message : txns-1E1: 2016/12

Txn Set Checksum
        SHA-256 : 9b29071e1bf228cfbd31ca2b8e7263212e4b86e51cfee1e8002c9b795ab03f76
       Set size : 10

Price Data
           time : 2025-01-08 12:13:14
      commodity : EUR
          value : 1.234 USD
                -
           time : 2024-12-31 08:00:00
      commodity : He·bar_50L·tank
          value : 3.45 EUR
```

--------------------------------

### Example Price Entry in Journal File

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Provides an example of a price entry in the journal file, specifying the currency, amount, and an optional comment indicating the source of the rate.

```plaintext
P 2025-01-07 EUR 1.0393 USD ; as reported by Central Bank of Europe
```

--------------------------------

### Commodity Position Example

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1003.adoc

Shows an example of a commodity position, specifying its quantity, currency, and conversion rate to another currency.

```plaintext
e   1 USD {1.00 NOK} @ 1.20 EUR
```

--------------------------------

### Install Tackler via Cargo

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Commands to install either the latest released version or the latest development version of Tackler from the Git repository.

```bash
# Latest released version
cargo install --locked tackler

# Latest development version
cargo install --locked --git https://github.com/tackler-ng/tackler tackler
```

--------------------------------

### Install Tackler via Cargo

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Command to install the latest released version of the Tackler binary using the Rust cargo toolchain.

```bash
# Latest released version
cargo install --locked tackler
```

--------------------------------

### Run Git Storage Example with Specific Ref and Account

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Executes Tackler with Git storage, specifying a Git reference ('set-1e5') and an account selector ('a:ay2016:am12'). This is optimized for large transaction sets.

```bash
target/release/tackler \
   --config examples/audit.toml \
   --input.git.ref set-1e5 \
   --accounts 'a:ay2016:am12'
```

--------------------------------

### PriceDB without direct EUR to USD rate

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Demonstrates a PriceDB setup where a direct conversion from EUR to USD is absent, and conversion chains are not supported. The example shows an indirect conversion path.

```plaintext
P 2025-01-07 EUR 11.50 SEK
P 2025-01-07 SEK  1.02 NOK
P 2025-01-07 NOK  0.09 USD ; EUR->SEK-NOK->USD = 1.055700; The real rate is 1.02
```

--------------------------------

### Closing Position Example with PnL Calculation

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1003.adoc

Demonstrates recording a closing position, calculating the Profit and Loss (PnL) based on the difference between opening and closing values, and updating cash and PnL accounts.

```plaintext
2017-01-01 close / sell at loss
 ; o - c = 1.04 - 1.38 EUR => PnL  -0.34 EUR
 inventory  -1 USD {1.38 EUR} @ 1.04 EUR ; loss 0.34
 a:cash      1.04 EUR
 PnL -0.34
```

--------------------------------

### Invalid ISO-8601 Timestamp Example

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1009.adoc

An example of a transaction header that is currently misinterpreted due to an extra space in the timestamp.

```text
2019-03-01T12:00:00 -04:00 Description
```

--------------------------------

### Initialize and Update Git Submodules

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Initializes and updates Git submodules, which is a prerequisite for running the audit example that relies on submodule data.

```bash
git submodule init
git submodule update
```

--------------------------------

### Tackler Report Output

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Example output format for balance and register reports generated by the Tackler engine.

```text
Balance Report
--------------
                 0.00    17.50  Expenses
                 0.00    12.00  Expenses:Food
                12.00    12.00  Expenses:Food:Fast-Food
                 0.00     5.50  Expenses:Sweets
                 2.50     2.50  Expenses:Sweets:Candy
                 3.00     3.00  Expenses:Sweets:Ice·Cream
=====================
                17.50

Register Report
---------------
...
```

--------------------------------

### Build Release Version of Tackler

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Builds a release version of the Tackler project using 'just' or 'cargo'. This is a prerequisite for running most examples.

```bash
just release-build
```

```bash
cargo build --release --bin tackler
```

--------------------------------

### Tackler Balance Report Output

Source: https://context7.com/tackler-ng/tackler/llms.txt

Example output of the balance report generated by Tackler. This shows the structure and formatting of financial summaries.

```text
Balance Report
--------------
                 0.00    17.50  Expenses
                 0.00    12.00  Expenses:Food
                12.00    12.00  Expenses:Food:Fast-Food
                 0.00     5.50  Expenses:Sweets
                 2.50     2.50  Expenses:Sweets:Candy
                 3.00     3.00  Expenses:Sweets:Ice·Cream
=====================
                17.50

```

--------------------------------

### Register Report Ambiguity Example

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1009.adoc

Demonstrates how current register report output fails to distinguish between a transaction code and a description containing similar characters.

```text
2019-03-01 (#123)
 a 1
 b

2019-03-01 '(#123)
 a 1
 b
```

--------------------------------

### Filter Transactions by Timestamp Range

Source: https://context7.com/tackler-ng/tackler/llms.txt

Define transaction filters based on start or end timestamps using JSON.

```json
{
  "txnFilter": {
    "TxnFilterTxnTSBegin": {
      "begin": "2023-02-25T10:11:22.345+02:00"
    }
  }
}
```

```json
{
  "txnFilter": {
    "TxnFilterTxnTSEnd": {
      "end": "2024-12-31T23:59:59.999Z"
    }
  }
}
```

--------------------------------

### Transaction Filtering with Base64 Armor

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Applies transaction filters using a base64 encoded definition for the same filtering logic as the JSON example. This is an alternative way to pass complex filter definitions.

```bash
target/release/tackler \
    --config examples/audit.toml \
    --input.git.ref set-1e2 \
    --reports register \
    --accounts 'a:.*' \
    --audit.mode true \
    --api-filter-def \
      base64:eyAidHhuRmlsdGVyIjogeyAiVHhuRmlsdGVyVHhuRGVzY3JpcHRpb24iOiB7ICJyZWdleCI6ICJeMUUyIHR4bi0oMXwxN3wxMDApJCIgfX19Cg==
```

--------------------------------

### Initialize Audit Repositories

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/audit-repo.adoc

Commands to initialize Git repositories for the generated audit data.

```bash
$perf/bin/git-data-init.sh audit-repo 1e1
$perf/bin/git-data-init.sh audit-repo 1e2
$perf/bin/git-data-init.sh audit-repo 1e3
$perf/bin/git-data-init.sh audit-repo 1e4
$perf/bin/git-data-init.sh audit-repo 1e5
$perf/bin/git-error-init.sh audit-repo
```

--------------------------------

### Run Tackler test suite

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Build the binary and execute the test runner script.

```bash
cargo build --bin tackler && tests/sh/test-runner-ng.sh --debug
```

--------------------------------

### Initialize and Run Tackler

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1016.adoc

Commands to create a new project and run a report using a specific configuration file.

```bash
tackler new demo
tackler --config demo/conf/tackler.toml
```

--------------------------------

### Configure Commodity Price Database

Source: https://context7.com/tackler-ng/tackler/llms.txt

Sets up commodity price conversion using a local price database in maple.toml.

```toml
[kernel]
strict = false
audit = { mode = false, hash = "SHA-256" }
timestamp = { default-time = 00:00:00, timezone = { name = "UTC" } }

input = { storage = "fs", fs = { path = "maple", dir = "txns", ext = "txn" } }

[price]
db-path = "maple/txns/price.db"
lookup-type = "last-price"

[transaction]
accounts    = { path = "none" }
commodities = { path = "none" }
tags        = { path = "none" }

[report]
report-timezone = "UTC"
scale = { min = 2, max = 12 }
formats = [ "txt", "json" ]
targets = [ "balance", "register" ]
commodity = "CAD"
accounts = [ ]

balance       = { title = "Balance Report", type = "tree" }
register      = { title = "Register Report", accounts = [ "Assets:.*", "Expenses:.*", "Income:.*" ]}

[export]
targets = [ ]
equity = { accounts = [ ], equity-account = "Equity:Balance" }
```

--------------------------------

### Display Tackler CLI Help

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/README.adoc

Displays the help menu for the Tackler CLI application.

```bash
cargo run -- \
    --help
```

--------------------------------

### Run unit tests

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Execute unit tests at the root of the project workspace.

```bash
cargo test
```

--------------------------------

### Basic Tackler Configuration (simple.toml)

Source: https://context7.com/tackler-ng/tackler/llms.txt

A minimal TOML configuration file for Tackler, setting up filesystem-based journal storage and disabling strict validation. It also defines report settings.

```toml
[kernel]
strict = false
audit = { mode = false, hash = "SHA-256" }
timestamp = { default-time = 00:00:00, timezone = { name = "UTC" } }

input = { storage = "fs", fs = { path = "simple", dir = "txns", ext = "txn" } }

[transaction]
accounts    = { path = "none" }
commodities = { path = "none" }
tags        = { path = "none" }

[report]
report-timezone = "UTC"
scale = { min = 2, max = 2 }
accounts = [ "Expenses(:.*)?" ]
targets = [ "balance", "balance-group", "register" ]

balance       = { title = "Balance Report", type = "tree" }
balance-group = { title = "Balance Group Report", type = "tree", group-by = "month" }
register      = { title = "Register Report", accounts = [ "Assets:.*", "Expenses:.*", "Income:.*" ]}

[export]
targets = [ ]
equity = { accounts = [ "Assets:.*", ], equity-account = "Equity:Balance" }

```

--------------------------------

### Configure Commodity Price Lookups via CLI

Source: https://context7.com/tackler-ng/tackler/llms.txt

Use these commands to set price lookup strategies for commodity value conversion in reports.

```bash
# Enable price lookup with last known price
tackler --config examples/maple.toml \
    --price.lookup-type last-price \
    --report.commodity CAD

# Variable market value based on transaction time
tackler --config examples/solar.toml \
    --price.lookup-type txn-time

# Price lookup at specific time
tackler --config examples/maple.toml \
    --price.lookup-type given-time \
    --price.before "2024-06-01T00:00:00Z"
```

--------------------------------

### Compile Typst Report

Source: https://github.com/tackler-ng/tackler/blob/main/reports/readme.adoc

Use the Typst CLI tool to compile a balance report template into a PDF.

```bash
typst compile report-bal.typ
```

--------------------------------

### Import full haystack regex matchers

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-rs/CRATES.md

Use these constructors to create regex matchers that match against the full haystack by default.

```rust
tackler_rs::regex::{
    new_full_haystack_regex,
    new_full_haystack_regex_set,
    peeled_pattern,
    peeled_patterns
}
```

--------------------------------

### Run performance test

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Execute a simple performance test for the tackler-core crate.

```bash
cargo run --release -p tackler-core
```

--------------------------------

### Configure Report Formats

Source: https://github.com/tackler-ng/tackler/blob/main/reports/readme.adoc

Enable JSON and text output formats in the Tackler configuration file.

```toml
[report]
formats = [ "txt", "json" ]
```

--------------------------------

### Build Tackler Binary

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Compiles the project using either the just task runner or standard cargo commands.

```bash
cd tackler
just release-build
```

```bash
cd tackler
cargo build --release --locked --bin tackler
```

--------------------------------

### Build Tackler with Cargo

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Builds the release version of the Tackler binary using Cargo. Navigate to the tackler-ng directory first.

```bash
cd tackler-ng

# The main branch should build and pass all tests
cargo build --release --locked --bin tackler
```

--------------------------------

### Run QA checks

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Execute clippy and formatting checks across the workspace.

```bash
cargo clippy --workspace --all-targets --no-deps -- -D warnings
cargo fmt --all --check
```

--------------------------------

### Run parser benchmark

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Execute parser benchmark tests.

```bash
cargo bench
```

--------------------------------

### Transactions with Commodities and Prices

Source: https://context7.com/tackler-ng/tackler/llms.txt

Illustrates how to handle multi-currency transactions and exchange rates using the '@' notation in Tackler's journal format.

```text
2024-03-01 'Ice cream and maple syrup
  Expenses:Sweets  2.8 CAD
  Assets:Cash

2024-03-01 'The Royal Canadian Mint's Gold Maple Leaf (GML)
  Assets:Coins 1 GML @ 2780 CAD ; Gold Maple Leaf
  Expenses:Fees 20 CAD
  Assets:Cash -2800 CAD

```

--------------------------------

### Run Reports with Filesystem Storage

Source: https://context7.com/tackler-ng/tackler/llms.txt

Commands for generating reports from filesystem-based transaction storage.

```bash
# Basic report generation
tackler --config examples/simple.toml

# Specify reports to generate
tackler --config examples/simple.toml --reports balance register

# Filter by account selector
tackler --config examples/simple.toml --accounts "Expenses:.*"

# Output to files with specific formats
tackler --config examples/simple.toml \
    --output.dir ./reports \
    --output.prefix monthly \
    --formats txt json
```

--------------------------------

### Run Tackler with Filesystem Input

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/README.adoc

Executes Tackler using a local directory as the transaction source to generate a register report.

```bash
cargo run  -- \
    --input.fs.dir ../suite/core/ok/txns-id2id/ \
    --input.fs.ext txn \
    --reports register
```

--------------------------------

### Define Commodity

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Sets the default commodity for the project.

```text
commodity = "TCKLR"
```

--------------------------------

### Run Tackler with File Input

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/README.adoc

Executes Tackler using a specific transaction file to generate balance and register reports.

```bash
cargo run  -- \
    --input.file ../suite/reporting/ok/reporting.txn \
    --reports balance register
```

--------------------------------

### Calculate Value of Energy Used On-Site

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Calculates the value of energy when it is used at the site, using a specific Tackler configuration file.

```bash
target/release/tackler \
   --config examples/solar.toml \
   --reports balance
```

--------------------------------

### Run Tackler with Git Repository Input

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/README.adoc

Executes Tackler using a git repository as the transaction source to generate a balance report.

```bash
cargo run  -- \
    --input.git.repo ../suite/audit/audit-repo.git \
    --input.git.dir txns \
    --input.git.ref set-1e1 \
    --reports balance
```

```bash
cargo run  -- \
    --input.git.repo ../suite/audit/audit-repo.git \
    --input.git.dir txns \
    --input.git.ref set-1e1 \
    --reports balance \
    --audit.mode true
```

--------------------------------

### Run Reports with Git Storage

Source: https://context7.com/tackler-ng/tackler/llms.txt

Commands for generating reports from Git-based storage, including reference and commit overrides.

```bash
# Use default git reference from config
tackler --config examples/audit.toml

# Override git reference
tackler --config examples/audit.toml --input.git.ref set-1e5

# Use specific commit
tackler --config examples/audit.toml --input.git.commit 4648a2994b41ed341b544a148b3060fd2d267d79

# Filter accounts with git storage
tackler --config examples/audit.toml \
    --input.git.ref set-1e5 \
    --accounts 'a:ay2016:am12'
```

--------------------------------

### Finalize Repository Configuration

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/audit-repo.adoc

Commands to clean up hooks and optimize the Git repository.

```bash
cd audit-repo.git/
rm -f hooks/*.sample
git gc --prune=now
```

--------------------------------

### Import Serde support for full haystack matchers

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-rs/CRATES.md

Provides serializer and deserializer implementations for full haystack matchers.

```rust
tackler_rs::regex::serde::full_haystack_matcher
```

--------------------------------

### Generate Equity Export

Source: https://context7.com/tackler-ng/tackler/llms.txt

Command to generate equity transactions for closing books or transferring balances using the Tackler CLI.

```bash
tackler --config examples/simple.toml \
    --output.dir ./exports \
    --output.prefix year-end \
    --exports equity
```

--------------------------------

### Calculate Value of Energy Sold to Grid

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Calculates the value of energy if it were sold to the grid, using a specific Tackler configuration and a dedicated price database.

```bash
target/release/tackler \
   --config examples/solar.toml \
   --reports balance \
   --pricedb examples/solar/txns/se-sold.db
```

--------------------------------

### Transactions with Full Timestamps

Source: https://context7.com/tackler-ng/tackler/llms.txt

Demonstrates the use of full timestamp format, including time and timezone information, for precise temporal tracking of events in Tackler.

```text
2024-03-20T08:00:00
   SolarPanels:Array:1  0.4638 kWh
   Sun

2024-03-20T09:00:00
   SolarPanels:Array:1  1.671 kWh
   Sun

2024-06-20T14:00:00
   SolarPanels:Array:1  0.8817 kWh
   Sun

```

--------------------------------

### Generate flamegraph

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Run flamegraph on the tackler-cli crate with specific configuration and input.

```bash
cd tackler-cli

CARGO_PROFILE_RELEASE_DEBUG=true \
    cargo flamegraph -- \
        --config ../examples/audit.toml \
        --input.git.ref set-1e5
```

--------------------------------

### Run Audit Report with Git Storage

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Generates a report with cryptographic checksums using a git repository as storage.

```bash
target/release/tackler \
    --config examples/audit.toml \
```

--------------------------------

### Apply Transaction Filters via CLI

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Use the --api-filter-def flag to pass a JSON-encoded filter definition. Alternatively, provide the filter as a Base64 encoded string.

```bash
target/release/tackler \
    --config examples/audit.toml \
    --input.git.ref set-1e5 \
    --api-filter-def '{"txnFilter":{"TxnFilterPostingAccount":{"regex":"a:ay2016:am12"}}}'
```

```bash
--api-filter-def \
base64:eyJ0eG5GaWx0ZXIiOnsiVHhuRmlsdGVyUG9zdGluZ0FjY291bnQiOnsicmVnZXgiOiJhOmF5MjAxNjphbTEyIn19fQ==
```

--------------------------------

### Verify Transaction Set Checksum with External Tools

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1007.adoc

A shell pipeline to extract UUIDs from transaction files and calculate a SHA-256 checksum.

```bash
(
    find "$1"  -type f -name '*.txn' | \
    xargs -n100 grep -h ';:uuid:'
) | \
    sed -E 's/[[:space:]]+;:uuid:[[:space:]]+([a-fA-F0-9-]+)[[:space:]]*/\1/' | \
    tr 'A-F' 'a-f' | \
    sort | \
    sha256sum
```

--------------------------------

### Search for unwrap or panic usage

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/readme.adoc

Command to identify unwrap or panic calls in the codebase, excluding test and approved files.

```bash
rg '(unwrap\()|(panic\!\()' | egrep -v '(:ok:)|(:test:)'
```

--------------------------------

### Define Tags

Source: https://context7.com/tackler-ng/tackler/llms.txt

Lists allowed transaction tags for categorization.

```toml
tags = [
    "travel:ice·cream·spree",
    "vehichle:XYZ-123"
]
```

--------------------------------

### Filter Transactions by Posting Account

Source: https://context7.com/tackler-ng/tackler/llms.txt

Apply regex-based account filtering using CLI arguments or JSON definitions.

```bash
# Filter by account regex via CLI
tackler --config examples/audit.toml \
    --input.git.ref set-1e5 \
    --api-filter-def '{"txnFilter":{"TxnFilterPostingAccount":{"regex":"a:ay2016:am12"}}}'
```

```json
{
  "txnFilter": {
    "TxnFilterPostingAccount": {
      "regex": "a:ay2016:am12"
    }
  }
}
```

--------------------------------

### List Available Transaction Filters

Source: https://context7.com/tackler-ng/tackler/llms.txt

Reference the available variants of the TxnFilter enum for programmatic filter construction.

```rust
use tackler_api::filters::TxnFilter;

// Logic filters
TxnFilter::TxnFilterAND       // Combine filters with AND logic
TxnFilter::TxnFilterOR        // Combine filters with OR logic
TxnFilter::TxnFilterNOT       // Negate a filter

// Transaction header filters
TxnFilter::TxnFilterTxnTSBegin     // Filter by start timestamp
TxnFilter::TxnFilterTxnTSEnd       // Filter by end timestamp
TxnFilter::TxnFilterTxnCode        // Filter by transaction code
TxnFilter::TxnFilterTxnDescription // Filter by description regex
TxnFilter::TxnFilterTxnUUID        // Filter by transaction UUID
TxnFilter::TxnFilterTxnTags        // Filter by transaction tags
TxnFilter::TxnFilterTxnComments    // Filter by transaction comments
TxnFilter::TxnFilterBBoxLatLon     // Filter by geo bounding box (2D)
TxnFilter::TxnFilterBBoxLatLonAlt  // Filter by geo bounding box (3D)

// Posting filters
TxnFilter::TxnFilterPostingAccount       // Filter by posting account regex
TxnFilter::TxnFilterPostingComment       // Filter by posting comment
TxnFilter::TxnFilterPostingCommodity     // Filter by posting commodity
TxnFilter::TxnFilterPostingAmountEqual   // Filter by exact amount
TxnFilter::TxnFilterPostingAmountLess    // Filter by amount less than
TxnFilter::TxnFilterPostingAmountGreater // Filter by amount greater than

// Special filters
TxnFilter::NullaryTRUE   // Always matches (select all)
TxnFilter::NullaryFALSE  // Never matches (select none)
```

--------------------------------

### Transaction Filtering with JSON Definition

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Applies transaction filters using a plain JSON definition to filter transactions by description regex. Requires audit configuration and specific Git ref.

```bash
target/release/tackler \
    --config examples/audit.toml \
    --input.git.ref set-1e2 \
    --reports register \
    --accounts 'a:.*' \
    --audit.mode true \
    --api-filter-def \
      '{ "txnFilter": { "TxnFilterTxnDescription": { "regex": "1E2 txn-(1|17|100)" }}}'
```

--------------------------------

### Run Tackler with API Filter Definition

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/README.adoc

Executes Tackler with an audit mode and a specific API filter definition provided as JSON or base64 encoded string.

```bash
cargo run  -- \
	--input.git.repo ../suite/audit/audit-repo.git \
	--input.git.dir txns \
	--input.git.ref set-1e1 \
	--reports balance \
	--audit.mode true \
	--api-filter-def '{"txnFilter":{"TxnFilterPostingAccount":{"regex":"^e:ey2016:em1.*"}}}'
or 
	--api-filter-def base64:eyJ0eG5GaWx0ZXIiOnsiVHhuRmlsdGVyUG9zdGluZ0FjY291bnQiOnsicmVnZXgiOiJeZTpleTIwMTY6ZW0xLioifX19
```

--------------------------------

### PriceDB with inverted rate

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Shows a PriceDB configuration that includes an explicit entry for the inverted rate (USD to EUR), which is necessary for such conversions.

```plaintext
P 2025-01-07 EUR 1.3 USD
P 2025-01-07 USD 0.77 EUR ; 1/1.3 ~ 0.7692; Normally there is official inverted rate
```

--------------------------------

### Basic Transaction Syntax

Source: https://context7.com/tackler-ng/tackler/llms.txt

Defines the fundamental structure of a transaction in Tackler's plain text journal format. Transactions must balance to zero.

```text
2024-03-20 'Lucky Day!
   Assets:Bank:Acme_Inc  100
   Income:Lottery

2024-06-20 'Sweet'n Sour Candies
   Expenses:Sweets:Candy  2.50
   Assets:Cash

2024-09-22 'Hot dogs
   Expenses:Food:FastFood  12
   Assets:Visa:4012_8888_8888_1881

2024-12-21 'Strawberry ice cream
   Expenses:Sweets:Ice·Cream  3
   Assets:Cash

```

--------------------------------

### Generate Audit Test Data Sets

Source: https://github.com/tackler-ng/tackler/blob/main/docs/devel/audit-repo.adoc

Commands to create audit test data sets with different sizes using the pta-generator tool.

```bash
pta-generator audit --path sets --shard-type txn \
    --start 2016-01-01T00:00:00+0000[UTC] \
    --stop  2017-01-01T00:00:00+0000[UTC] \
    --set-size 1e1
```

```bash
pta-generator audit --path sets --shard-type txn \
    --start 2016-01-01T00:00:00+0000[UTC] \
    --stop  2017-01-01T00:00:00+0000[UTC] \
    --set-size 1e2
```

```bash
pta-generator audit --path sets --shard-type txn \
    --start 2016-01-01T00:00:00+0000[UTC] \
    --stop  2017-01-01T00:00:00+0000[UTC] \
    --set-size 1e3
```

```bash
pta-generator audit --path sets --shard-type txn \
    --start 2016-01-01T00:00:00+0000[UTC] \
    --stop  2017-01-01T00:00:00+0000[UTC] \
    --set-size 1e4
```

```bash
pta-generator audit --path sets --shard-type txn \
    --start 2016-01-01T00:00:00+0000[UTC] \
    --stop  2017-01-01T00:00:00+0000[UTC] \
    --set-size 1e5
```

--------------------------------

### Configure Git Storage with Audit Mode

Source: https://context7.com/tackler-ng/tackler/llms.txt

Defines Git-based transaction storage with cryptographic auditing enabled in audit.toml.

```toml
[kernel]
strict = true
audit = { mode = true, hash = "SHA-256" }
timestamp = { default-time = 00:00:00, timezone = { name = "UTC" } }

input = {
    storage = "git",
    git = {
        repo = "../suite/audit/audit-repo.git",
        dir = "txns",
        ext = "txn",
        ref = "set-1e1"
    }
}

[transaction]
accounts    = { path = "audit/accounts.toml" }
commodities = { path = "audit/commodities.toml" }
tags        = { path = "none" }

[report]
report-timezone = "UTC"
scale = { min = 2, max = 2 }
formats = [ "txt", "json" ]
accounts = [ "a:.*" ]
targets = [ "balance" ]

balance       = { title = "Balance Report", type = "flat" }
balance-group = { title = "Balance Group Report", type = "flat", group-by = "month" }
register      = { title = "Register Report", accounts = [ "e:.*", "a:.*" ]}

[export]
targets = [ ]
equity = { accounts = [ "a:.*", ], equity-account = "Equity:Balance" }
```

--------------------------------

### Use Base64 Armored Filter Definitions

Source: https://context7.com/tackler-ng/tackler/llms.txt

Encode complex JSON filter definitions as base64 strings for cleaner command-line execution.

```bash
# Base64 armored filter definition
tackler --config examples/audit.toml \
    --input.git.ref set-1e5 \
    --api-filter-def 'base64:eyJ0eG5GaWx0ZXIiOnsiVHhuRmlsdGVyUG9zdGluZ0FjY291bnQiOnsicmVnZXgiOiJhOmF5MjAxNjphbTEyIn19fQ=='
```

--------------------------------

### Journal File Format for Price Entries

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Defines the format for price data entries in the journal file, similar to the Ledger CLI's P-directive. It includes timestamp, commodity, amount, and an optional comment.

```plaintext
'P' TIMESTAMP COMMODITY AMOUNT COMMODITY OPT_COMMENT
```

--------------------------------

### Feature Coverage Metadata

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1016.adoc

YAML structure used for tracking feature and test coverage for the Flat Balance implementation.

```yaml
features:
  - feature:
      id: cb7f968e-61f4-43d2-b2d8-d08f179d5fd7
      subject: "Flat Balance"

  - feature:
      id: 55cbf642-7d2b-4a68-9eed-4cd97066b2be
      parent: cb7f968e-61f4-43d2-b2d8-d08f179d5fd7
      subject: "Flat Balance Report"

  - feature:
      id: eac0e587-2232-42ed-9569-d1026d762e60
      parent: cb7f968e-61f4-43d2-b2d8-d08f179d5fd7
      subject: "Flat Balance Group Report"
```

--------------------------------

### Run Audit Report for Specific Git Reference

Source: https://github.com/tackler-ng/tackler/blob/main/tackler-cli/CRATES.md

Generates a report for a specific git reference within the audit repository.

```bash
target/release/tackler \
    --config examples/audit.toml \
    --input.git.ref set-1e5
```

--------------------------------

### Generate Identity Export

Source: https://context7.com/tackler-ng/tackler/llms.txt

Command to export transactions in their original format for verification or transfer using the Tackler CLI.

```bash
tackler --config examples/audit.toml \
    --output.dir ./exports \
    --output.prefix backup \
    --exports identity
```

--------------------------------

### Calculate Current Market Value of Assets

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Calculates the current market value of specified assets using the 'last-price' lookup type and reporting in CAD.

```bash
target/release/tackler \
    --config examples/maple.toml \
    --reports balance \
    --accounts "Assets:Coins" \
    --price.lookup-type last-price \
    --report.commodity CAD
```

--------------------------------

### Balance Report JSON Format

Source: https://context7.com/tackler-ng/tackler/llms.txt

JSON output format for balance reports, including metadata about the input references and checksums.

```json
{
  "metadata": {
    "items": [
      {
        "GitInputReference": {
          "commit": "ed6e4b10de2daea8d143569c473d14a9b09c3270",
          "ref": "set-1e1",
          "dir": "txns",
          "extension": "txn",
          "author": "tackler <accounting@example.com>",
          "date": "2016-11-25 09:36:00 +0000",
          "subject": "set-1e1: 2016-11-25"
        }
      },
      {
        "TxnSetChecksum": {
          "size": 10,
          "hash": {
            "algorithm": "SHA-256",
            "value": "4a0eb2f8836447a025030a87136c047b4a737031162f593cb00f390c6ba113a3"
          }
        }
      },
      {
        "AccountSelectorChecksum": {
          "hash": {
            "algorithm": "SHA-256",
            "value": "cb5b67e3283b6dd95317dac2bd8bca339b3d1c20cb614e2de692e038d4b0e58a"
          }
        }
      }
    ]
  },
  "title": "BALANCE",
  "balances": [
    {
      "accountSum": "-6.0000001",
      "accountTreeSum": "-6.0000001",
      "account": "a:ay2016:am02"
    },
    {
      "accountSum": "6.0000001",
      "accountTreeSum": "6.0000001",
      "account": "e:ey2016:em02:ed06"
    }
  ],
  "deltas": [
    {
      "delta": "0.0000000"
    }
  ]
}
```

--------------------------------

### Parse and Manage Filters in Rust

Source: https://context7.com/tackler-ng/tackler/llms.txt

Use the tackler-api crate to parse, match, and serialize transaction filters programmatically.

```rust
use tackler_api::filters::FilterDefinition;
use tackler_api::filters::TxnFilter;

// Parse filter from JSON string
let filter_json_str = r#"{"txnFilter":{"TxnFilterPostingAccount":{"regex":"Expenses:.*"}}}"#;
let filter_def = FilterDefinition::from_json_str(filter_json_str)?;

match filter_def.txn_filter {
    TxnFilter::TxnFilterPostingAccount(f) => {
        println!("Filtering by account: {:?}", f.regex);
    },
    _ => {}
}

// Parse filter from base64 armor
let filter_armor = "base64:eyJ0eG5GaWx0ZXIiOnsiTnVsbGFyeVRSVUUiOnt9fX0K";
let filter_def = FilterDefinition::from_armor(filter_armor)?;

// Serialize filter back to JSON
let json_output = serde_json::to_string(&filter_def)?;
```

--------------------------------

### Register Report with Fixed Time Price

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Displays a register report where price data is calculated based on a fixed timestamp.

```text
Price Data
           time : 2024-01-31 00:00:00
      commodity : aaa
          value : 31.001 TCKLR

REGISTER
--------
2024-01-01
            e:conv                        1.00 aaa                        31.001 TCKLR
--------------------------------------------------------------------------------------
2024-01-12
            e:conv                        1.00 aaa                        62.002 TCKLR
--------------------------------------------------------------------------------------
2024-01-24
            e:conv                        1.00 aaa                        93.003 TCKLR
--------------------------------------------------------------------------------------
```

--------------------------------

### Clone Tackler Source Code with Submodules

Source: https://github.com/tackler-ng/tackler/blob/main/README.adoc

Clones the Tackler source code, including necessary Git submodules for test vectors. This is required for building from local source.

```bash
git clone --recurse-submodules https://github.com/tackler-ng/tackler
```

--------------------------------

### PriceDB with no USD to EUR rate

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Illustrates a PriceDB entry where a direct conversion from USD to EUR is missing. Inverted prices are not supported by default.

```plaintext
P 2025-01-07 EUR 1.3 USD
```

--------------------------------

### Rust FilterDefinition API

Source: https://context7.com/tackler-ng/tackler/llms.txt

Programmatic interface for parsing and creating transaction filters using the tackler-api crate.

```APIDOC
## Rust tackler-api

### Description
Use the `tackler_api` crate to parse filter definitions from JSON strings or base64-encoded armor.

### Usage
```rust
use tackler_api::filters::FilterDefinition;

// Parse filter from JSON string
let filter_def = FilterDefinition::from_json_str(json_str)?;

// Parse filter from base64 armor
let filter_def = FilterDefinition::from_armor(filter_armor)?;
```
```

--------------------------------

### Calculate Historic Market Value of Assets

Source: https://github.com/tackler-ng/tackler/blob/main/examples/readme.adoc

Calculates the market value of specified assets at a historic point in time (before 2024-03-01) using the 'given-time' lookup type and reporting in CAD.

```bash
target/release/tackler \
    --config examples/maple.toml \
    --reports balance \
    --accounts "Assets:Coins" \
    --price.lookup-type given-time \
    --price.before 2024-03-01 \
    --report.commodity CAD
```

--------------------------------

### UUID Parsing with java.util.UUID.fromString

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1007.adoc

Demonstrates the behavior of `java.util.UUID.fromString` with both valid and invalid UUID strings. Note that `fromString` may not strictly validate the UUID format as expected, potentially accepting malformed strings.

```scala
scala> java.util.UUID.fromString("69439222-4d8b-4d0e-8204-50e2a0c8b664")
res1: java.util.UUID = 69439222-4d8b-4d0e-8204-50e2a0c8b664
```

```scala
scala> java.util.UUID.fromString("694aaaaa39222-4d8b-4d0e-8204-50e2a0c8b664")
res2: java.util.UUID = aaa39222-4d8b-4d0e-8204-50e2a0c8b664
```

--------------------------------

### Register Report with Variable Price Data

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1015.adoc

Displays a register report where price data is calculated based on the transaction time.

```text
Price Data
           time : transaction time
      commodity : aaa
          value : - TCKLR

REGISTER
--------
2024-01-01
            e:conv                        1.00 aaa @ 1.001 TCKLR           1.001 TCKLR
--------------------------------------------------------------------------------------
2024-01-12
            e:conv                        1.00 aaa @ 12.001 TCKLR         13.002 TCKLR
--------------------------------------------------------------------------------------
2024-01-24
            e:conv                        1.00 aaa @ 24.001 TCKLR         37.003 TCKLR
--------------------------------------------------------------------------------------
```

--------------------------------

### Define Commodities

Source: https://context7.com/tackler-ng/tackler/llms.txt

Lists allowed commodities and currencies for strict mode validation.

```toml
permit-empty-commodity = true

commodities = [
    "€",
    "$",
    "¥",
    "EUR",
    "CAD",
    "USD",
    "He·litre",
    "O2·litre"
]
```

--------------------------------

### Define Transaction Tag Filter

Source: https://github.com/tackler-ng/tackler/blob/main/docs/tep/tep-1011.adoc

JSON structure used to define a transaction tag filter based on a regular expression.

```json
{
  "TxnFilterTxnTags" : {
    "regex" : "<regex>"
  }
}
```
Tokens:
Raw