Commit 266f825f authored by phil's avatar phil

add more examples and instructions on how to use them

parent 6cfd61ee
......@@ -73,37 +73,111 @@ Hence you will need to install the npm dependencies via =npm install=.
ClojureScript dependencies tracked in =deps.edn= are installed via
=clj= (aka. Clojure CLI). Please install =clj= as described [[https://clojure.org/guides/deps_and_cli][here]].
Additionally [[https://github.com/kislyuk/yq][yq]] is like [[https://stedolan.github.io/jq/][jq]] for YAML, it is actually a wrapper around
jq. It comes in really handy if working with multiple YAML files.
** Usage
#+BEGIN_SRC sh
sudo apt install python-pip
pip install yq
#+END_SRC
Easy provides two command line utilities: =easy= itself and =collect=.
Here are some examples on how to use these.
** Usage
You have to have some files in place in order to use easy. Please find
the example directory of this repo and to run these examples.
*** Examples
Render ledger entries from events and run the through ledger to create
a balance:
=easy ledger example.yml | ledger bal -f -=
=easy ledger -i example.yml | ledger bal -f -=
Render invoice 18.2.1 to latex:
=easy invoice example.yml 18.2.1=
=easy invoice -i example.yml -n 18.2.1=
Sidenote: Easy invoice identifiers (invoice-no) are divided into three
segments ~<customer-id>.<invoice-number>.<version>~. In events thei
can be given as =invoice-no= in aggregated form or separately as
=customer=, =number=, and =version=.
Just run a transform to see the transformed events, which is handy for
Run a transform to see the transformed events, which is handy for
writing templates:
=easy transform example.yml=
=easy transform -i example.yml=
Or, just validate the input and exit:
=easy validate -i example.yml=
Easy alternatively takes events via STDIN:
=cat example.yml | easy transform=
This comes in particularly handy, when working with multiple event
sources (i.e. YAML files)
=cat invoices.yml settlements.yml | easy ledger | ledger -f - bal=
(Please be ware that concatinating YAML files for easy only works if
the files lack the YAML's document prefix =---=. The reason for this
is explained in "On Frontmatter Templates". And it doens't really
matter as you won't be using =cat= anyways, just keep reading.)
Finally easy comes with its own utility to collect multiple event
sources into a single event stream. Given a root directory for events
it will find all files matching =*.yml=, load these, annotate each
event with its origin (for locating issues quickly), and outputs a
sorted stream of events.
=collect ./events/ | easy ledger -y 2018=
Yes, you guessed it, you can use `-y <year>` to filter events by year.
** On Frontmatter Templates
A typical event source for easy might look like this:
#+BEGIN_SRC yaml
- type: expense
account: Aufwand:6940-Bankspesen
payer: Joint
amount: 5
date: 2018-05-31
description: Bankgebühren
- type: expense
account: Aufwand:6940-Bankspesen
payer: Joint
amount: 5
date: 2018-06-30
description: Bankgebühren
#+END_SRC
Imaging the file going on like this. These are monthly occurring
events with very high redundancy. In these cases you might want to use
=collect='s (and =easy='s) capability to work with frontmatter
templates. This allows you to define common attributes of the list of
events as a template using multiple YAML documents in one YAML file.
That way you store the same information by writing:
#+BEGIN_SRC yaml
---
type: expense
account: Aufwand:6940-Bankspesen
payer: Joint
description: Bankgebühren
---
- date: 2018-05-31
amount: 5
- date: 2018-06-30
amount: 5
#+END_SRC
Neat, isn't it?
** On Resolve & Context
** Resolve & Context
This does only concern you if you are developing easy.
Easy uses a multimethod =transform= to transform events into a
/usable/ form. /Usable/ meaning it has all the details calculated and
associated data added to be used in a template.
/augmented/ form. /Augmented/ meaning it has all the details
calculated and associated data added to be used in a template.
The transformation of a single event might happen within a =context=.
The =context= is the set of all events within a processing run.
......@@ -111,12 +185,13 @@ The =context= is the set of all events within a processing run.
are lists of events and the keys are their corresponding =type=. This
is for convenience because in almost all cases you only want to have
events of a single =type= when using the context to resolve associated
events.)
events. E.g. for a given invoice you want to resolve its settlement,
or the other way round.)
Associated data is added via resolve-fns. The resolve-fns use the
context to lookup other events. As the context contains only "mildy"
and not fully transformed events the resolve-fn will very likely have
to transform the resolved event in order to make it usable. If this
to transform the resolved event in order to make it augmented. If this
would mean that another resolve-fn is triggerd this will likely
trigger an endless recursion of resolves.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment