Skip to content

Commit

Permalink
docs: Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
trevorld committed May 18, 2024
1 parent ee475bb commit 53e7982
Show file tree
Hide file tree
Showing 4 changed files with 192 additions and 186 deletions.
36 changes: 17 additions & 19 deletions README.Rrst
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,24 @@ ledger

.. {r setup, echo = FALSE}
knitr::opts_chunk$set(fig.path = "man/figures/README-")
options(width=80)
.. ..

.. image:: https://www.r-pkg.org/badges/version/ledger
.. |CRAN-status| image:: https://www.r-pkg.org/badges/version/ledger
:target: https://cran.r-project.org/package=ledger
:alt: CRAN Status Badge

.. image:: https://github.com/trevorld/r-ledger/workflows/R-CMD-check/badge.svg
.. |R-CMD-check| image:: https://github.com/trevorld/r-ledger/workflows/R-CMD-check/badge.svg
:target: https://github.com/trevorld/r-ledger/actions
:alt: R-CMD-check

.. image:: https://codecov.io/github/trevorld/r-ledger/branch/master/graph/badge.svg
.. |codecov| image:: https://codecov.io/github/trevorld/r-ledger/branch/master/graph/badge.svg
:target: https://app.codecov.io/github/trevorld/r-ledger?branch=master
:alt: Coverage Status

.. image:: https://cranlogs.r-pkg.org/badges/ledger
.. |downloads| image:: https://cranlogs.r-pkg.org/badges/ledger
:target: https://cran.r-project.org/package=ledger
:alt: RStudio CRAN mirror downloads

|CRAN-status| |R-CMD-check| |codecov| |downloads|

``ledger`` is an R package to import data from `plain text accounting <https://plaintextaccounting.org/>`_ software like `Ledger <https://www.ledger-cli.org/>`_, `HLedger <https://hledger.org/>`_, and `Beancount <https://github.com/beancount/beancount>`_ into an R data frame for convenient analysis, plotting, and export.

Right now it supports reading in the register from ``ledger``, ``hledger``, and ``beancount`` files.
Expand Down Expand Up @@ -78,14 +78,13 @@ API

The main function of this package is ``register`` which reads in the register of a plaintext accounting file. This package also registers S3 methods so one can use ``rio::import`` to read in a register, a ``net_worth`` convenience function, and a ``prune_coa`` convenience function.

register
~~~~~~~~
``register()``
~~~~~~~~~~~~~~

Here are some examples of very basic files stored within the package:

.. {r register}
library("ledger")
options(width=180)
ledger_file <- system.file("extdata", "example.ledger", package = "ledger")
register(ledger_file)
hledger_file <- system.file("extdata", "example.hledger", package = "ledger")
Expand All @@ -100,16 +99,15 @@ Here is an example reading in a beancount file generated by ``bean-example``:
bean_example_file <- tempfile(fileext = ".beancount")
system(paste("bean-example -o", bean_example_file), ignore.stderr=TRUE)
df <- register(bean_example_file)
options(width=240)
print(df)
suppressPackageStartupMessages(library("dplyr"))
dplyr::filter(df, grepl("Expenses", account), grepl("trip", tags)) %>%
group_by(trip = tags, account) %>%
summarise(trip_total = sum(amount))
summarize(trip_total = sum(amount), .groups = "drop")
.. ..

Using rio::import and rio::convert
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using ``rio::import()`` and ``rio::convert()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If one has loaded in the ``ledger`` package one can also use ``rio::import`` to read in the register:

Expand All @@ -125,8 +123,8 @@ The main advantage of this is that it allows one to use ``rio::convert`` to easi
bean-example -o example.beancount
Rscript --default-packages=ledger,rio -e 'convert("example.beancount", "example.csv")'

net_worth
~~~~~~~~~
``net_worth()``
~~~~~~~~~~~~~~~

Some examples of using the ``net_worth`` function using the example files from the ``register`` examples:

Expand All @@ -135,11 +133,12 @@ dates <- seq(as.Date("2016-01-01"), as.Date("2018-01-01"), by="years")
net_worth(ledger_file, dates)
net_worth(hledger_file, dates)
net_worth(beancount_file, dates)
dates <- seq(min(as.Date(df$date)), max(as.Date(df$date)), by="years")
net_worth(bean_example_file, dates)
.. ..

prune_coa
~~~~~~~~~
``prune_coa()``
~~~~~~~~~~~~~~~

Some examples using the ``prune_coa`` function to simplify the "Chart of Account" names to a given maximum depth:

Expand All @@ -164,7 +163,6 @@ beancount example generated by ``bean-example``.
First we load the (mainly tidyverse) libraries we'll be using and adjusting terminal output:

.. {r setup_things, message=FALSE}
options(width=240) # tibble output looks better in wide terminal output
library("ledger")
library("dplyr")
filter <- dplyr::filter
Expand Down
Loading

0 comments on commit 53e7982

Please sign in to comment.