rust_ledger

适用于 Linux 和 macOS 的命令行会计工具

摘要

• 基于 ledger 的精神移植
• 使用复式记账范式
• 支持所有 ISO 4217 货币格式
• 使用 yaml 文件作为数据存储
• 包括将 csv 文件转换为 yaml 格式的工具
• 基于典型个人财务管理用例的小功能集

贡献

• 请参阅 CODE_OF_CONDUCT.md 获取指南
• 欢迎并鼓励提出 PR、问题和功能请求

安装

从 Cargo

cargo安装 rust_ledger

Linux 和 macOS 的二进制文件

我们为上述平台提供二进制文件。请参阅 发布 以获取完整列表。

从源代码构建

或者，克隆此仓库并执行以下操作

• 如果您的机器上未安装 Rust，请按照以下说明进行安装： https://rust-lang.net.cn/tools/install
• 运行 cargo build --release 来编译二进制文件
• 将 /target/release/rust_ledger 二进制文件复制到 /usr/bin 或您的系统维护应用程序二进制文件的任何位置

测试

• cargo测试

用法

rust_ledger --help 将提供所有可用命令和可选参数的菜单。

rust_ledger <version>
Eric Crowder <[email protected]>

USAGE:
    rust_ledger [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    account     account module
    balance     balance module
    budget      budget module
    csv         csv module
    help        Prints this message or the help of the given subcommand(s)
    register    register module

rust_ledger yaml 文件格式

该项目使用定义的 yaml 架构，而不是纯文本的 ledger 文件格式。 yaml 具有相对简单的语法，并且能够轻松地表示有用的数据类型，例如列表。

一个示例的账本 yaml 文件可以在 examples/example.yaml 找到。

此外，由于有如 serde 这样的工具，解析 yaml 是非常简单的。这使得我能够跳过编写支持 ledger 纯文本文件格式的解析器，并专注于实现功能。此外，现代格式化工具，如 prettier，可以轻松地维护 yaml 文件，因为它们对底层文件的架构不敏感。

ledger 工具已经被用 许多 编程语言重写。几乎所有这些移植都利用了原始的 ledger 纯文本格式。最重要的是，我认为 rust_ledger 是在保持原始工具核心功能集的同时，使用不同账本文件格式的一种实验。

rust_ledger 使用以下格式的 yaml 文件

currency: USD

accounts:
  - account:
    amount:

transactions:
  - date:
    amount:
    description:
    account:
    offset_account:
  - date:
    description:
    transactions:
      - amount:
        account:
      - amount:
        account:

账本格式架构是有意设计的轻量级。唯一的要求如下

• currency 字段应为一个 ISO 4217 货币代码。
• account 字段应以以下格式表达：account_classification:account_name。
• amount 字段应为一个数字。它可以包含最多两个（2）小数点。
• date 字段应以下列格式：YYYY-MM-DD。

交易

交易可以以两种不同的方式表达。一种是仅影响两个账户的“简化”格式

- date: 2020-01-01
  amount: 200
  offset_account: liability:cc_amex
  description: grocery store
  account: expense:expense_general

与 offset_account 值相关的符号（借方/贷方）与 amount 字段中的值的符号相反。

在上面的示例交易中，由于 expense_general 被借记了200，因此 cc_amex 账户将被贷记相同金额。

涉及两个以上账户的交易以下述方式表达

- date: 2020-01-01
  description: grocery store
  transactions:
    - amount: 20
      account: expense:general
    - amount: 180
      account: expense:grocery
    - amount: -200
      account: liability:cc_amex

仅涉及两个账户的交易也可以以上述格式表达。

通过环境变量指定 rust_ledger 文件路径

可选地，可以通过环境变量 RUST_LEDGER_FILE 设置 ledger 文件路径，而不是在程序被调用时指定。如果提供了带有文件路径的 -f，将使用提供的文件，而不是任何 RUST_LEDGER_FILE 设置。

API

账户

列出账本文件中包含的所有账户。

rust_ledger-account
account module

USAGE:
    rust_ledger account [OPTIONS] --filename <filename>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -f, --filename <filename>    location of ledger file

示例输出

 Account 
----------------------------
 asset:cash_checking 
 asset:cash_savings 
 liability:cc_amex 
 equity:equity 
 expense:grocery 
 expense:general 
 expense:mortgage 
 income:general 

余额

列出到目前的账户余额。

rust_ledger-balance
balance module

USAGE:
    rust_ledger balance [OPTIONS] --filename <filename>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -f, --filename <filename>    location of ledger file

示例输出

 Account             | Balance 
---------------------+------------
 asset               |  
 asset:cash_checking | $-400.00 
  asset:cash_savings | $1,000.00 
 liability           |  
   liability:cc_amex | $-455.00 
 equity              |  
       equity:equity | $-3,500.00 
 expense             |  
     expense:grocery | $635.00 
     expense:general | $1,020.00 
    expense:mortgage | $2,000.00 
 income              |  
      income:general | $-300.00 
                     |  
 check               | 0 

登记

列出到目前的总账交易。输出可以通过可选参数按任何字段过滤。

rust_ledger-register
register module

USAGE:
    rust_ledger register [OPTIONS] --filename <filename>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -f, --filename <filename>    location of ledger file
    -g, --group <group>          group register output by value
    -o, --option <option>        filter output by optional value

• 登记报告可以可选地通过 group 参数（yearly、monthly 或 daily）进行汇总
• 如果指定了 group 参数，还必须指定一个 option 参数来指示分组值。例如，如果使用 yearly 分组参数，则此值可以是 2020；如果使用 monthly 分组参数，则此值可以是 12（十二月）。
• 注册报告也可以通过可选的option参数进行筛选。所有匹配的Description、Account或Amount值都将包含在输出中。

 Date       | Description        | Account             | Amount 
------------+--------------------+---------------------+------------
 2019-12-31 | weekly groceries   | expense:grocery     | $455.00 
 2019-12-31 | weekly groceries   | liability:cc_amex   | $-455.00 
 2020-01-01 | mortage            | expense:mortgage    | $2,000.00 
 2020-01-01 | mortage            | asset:cash_checking | $-2,000.00 
 2020-01-01 | stuff              | expense:general     | $1,000.00 
 2020-01-01 | stuff              | asset:cash_savings  | $-1,000.00 
 2020-01-01 | grocery store      | expense:general     | $20.00 
 2020-01-01 | grocery store      | expense:grocery     | $180.00 
 2020-01-01 | grocery store      | asset:cash_checking | $-200.00 
 2020-01-01 | donut sale to dale | asset:cash_checking | $300.00 
 2020-01-01 | donut sale to dale | income:general      | $-300.00 

 Date       | Description      | Account             | Amount 
------------+------------------+---------------------+----------
 2019-12-31 | weekly groceries | expense:grocery     | $455.00 
 2020-01-01 | grocery store    | expense:general     | $20.00 
 2020-01-01 | grocery store    | expense:grocery     | $180.00 
 2020-01-01 | grocery store    | asset:cash_checking | -$200.00

Date / Account      | Total
---------------------+------------
2020                |  
expense:grocery     | $180.00
expense:mortgage    | $2,000.00
asset:cash_checking | -$1,900.00
income:general      | -$300.00
asset:cash_savings  | -$1,000.00
expense:general     | $1,020.00

rust_ledger-budget 
budget module

USAGE:
    rust_ledger budget --filename <filename> --group <group> --option <option>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -f, --filename <filename>    location of ledger file
    -g, --group <group>          group budget output by value
    -o, --option <option>        filter output by optional value

 Date / Account   | Budget     | Actual    | Delta 
------------------+------------+-----------+------------
 2020             |            |           |  
 income:general   | $0.00      | -$300.00  | $300.00 
 expense:mortgage | $24,000.00 | $2,000.00 | $22,000.00 
 expense:grocery  | $6,000.00  | $180.00   | $5,820.00 
 expense:general  | $0.00      | $1,020.00 | -$1,020.00 

rust_ledger-csv
csv module

USAGE:
    rust_ledger csv [OPTIONS] --csv <csv> --filename <filename>

FLAGS:
    -h, --help       Prints help information
    -i, --invert     invert amount for each csv transaction
    -V, --version    Prints version information

OPTIONS:
    -c, --csv <csv>              path of csv file
    -f, --filename <filename>    location of ledger file
    -o, --offset <offset>        offset account for each csv transaction