Add --pivot option #323

Merged
merged 1 commit into from May 7, 2016

Projects

None yet

2 participants

@maralorn
Contributor

Hey,
I found the --pivot from the original ledger to be very useful, so I reimplemented it for hledger. I am fairly new at haskell, so feel free to criticize my code in any way you can imagine. If you would like to include the feature in hledger I am open to modify the pull request according to your wishes.

The option --pivot TAG will change

2016/02/16 Test Transaction
    Account1                                   2 EUR
    Account2                                  -2 EUR
      ; TAG: value

to

2016/02/16 Test Transaction
    Account1  2 EUR
    TAG:value  -2 EUR
      ; TAG: value

while this run of hledger. (Node: This differs slightly from the original ledger, where --pivot will instead create the posting TAG:value:Account2 -2 EUR. One could consider renaming or offering both features.)

Greetings,
Malte

@simonmichael
Owner

Nice! +1 for the example.

I haven't used this feature and could use some more hand-holding. Could you post a draft of the user documentation for it (here is fine). Also, could you say more about what you use it for ? Does it affect commands other than print ?

@maralorn
Contributor

Hey, glad to hear, that you like it. Regarding your questions:

The --pivot option runs a transformation on your journal before processing it with the main command you select. It therefore works with any report implemented. The output of the print command illustrates very well, what it does, but this is not a likely use case. I use it especially with the balance and the equity command. I will adapt two examples from the accounting for our hackspace for which I use ledger. (I am not sure about the english words for the accounting stuff):

member payment status.

2016/02/16 Member Fee Payment John Doe
    assets:bank account                                   2 EUR
    income:member fees                                  -2 EUR
      ; member: John Doe

hledger bal --pivot member
               2 EUR  assets:bank account
              -2 EUR  member:John Doe

This way I can track how much any member of the club has paid in member fees. This way I separate between the “real accounting” with bank accounts, assets and stuff and the “virtual accounting” with the member accounts, which are for example not of interest for the tax return but necessary for me to know whom to poke for more money.

donation budgets:

2016/02/16 Donation Freifunk
    assets:bank account                                   2 EUR
    income:donations                                  -2 EUR
      ; budget: Freifunk

hledger bal --pivot budget
           2 EUR  assets:bank account
          -2 EUR  budget:Freifunk

This way I can track how much money we spent on certain projects for which we got donations. (We are obliged by law to spend the money on that project.) (Freifunk is a german open WiFi initiative.)

I use this in conjunction with the equity command to carry the budgets and member account states to the next year.

Does that clear things up?

Cheers, Malte

@simonmichael
Owner

Yes, thank you.

How is the tag matched ? full-length string, infix, case-insensitive, regex.. ?

Do you know what happens if

  • there are no tags matching the --pivot argument
  • there are multiple matching tags in a single transaction
  • the matched tag is on the transaction, not a posting
  • multiple --pivot options are given, which might interfere with each other or be applied in series
  • the tag's value is a multi:level:account:name
@maralorn
Contributor

Let's see …

Am 17.02.2016 um 21:09 schrieb Simon Michael:

How is the tag matched ? full-length string, infix, case-insensitive, regex.. ?

In the moment the tag is matched only as full-length string. I could
imagine doing that differently.

Do you know what happens if

  • there are no tags matching the --pivot argument

Nothing happens. That works as intended.

  • there are multiple matching tags in a single transaction

Multiple tags in a single transaction should work fine. It would convert
every posting, which has a tag. Works as intended.

If one posting has multiple matching tags, only the first one will be
applied. (Assuming the list of tags is not shuffled by hledger
anywhere.) I think that's a corner case the user should avoid. I am not
sure, what the expected behaviour would be.

  • the matched tag is on the transaction, not a posting

It will be ignored. Works as intended.

  • multiple --pivot options are given, which might interfere with each other or be applied in series

Right now, only the last one is applied (due to the behavior of
maybestringopt, it seems to pick the last occurence). I could also
imagine doing that differently. But I think it's okay this way.

  • the tag's value is a multi:level:account:name

That will create an account tag:multi:level:account:name. This works
as intended. I use this feature regularly.

@simonmichael
Owner

Great! Can you add this to the user manual (in both hledger/hledger.1.md and site/manual.md, sorry) and confirm that unit and functional tests still pass (make test). Ideally, add a test for this as well, eg in tests/misc/pivot.test.

@maralorn
Contributor

Okay, I will do that once I can spare a minute for it.

@maralorn
Contributor
maralorn commented May 5, 2016

Okay, I added some doku and tests. travis says it’s working.
Please have a look at it, if it’s okay this way. I don’t trust me very much with this.
I am especially worried about the white spaces in the tests. I think this tests could break if you change the formatting somewhere else. Is that a problem?

@simonmichael simonmichael merged commit 913b8e4 into simonmichael:master May 7, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@simonmichael
Owner

If there are docs and make test passes, I'm very happy. Further cleanups are welcome as we find them.

Thank you for this feature! I wanted it recently to report US Schedule C business expense categories.

@simonmichael
Owner

Some cleanups to consider:

  • give pivot example its own section heading under hledger options
  • fix stray quote
  • add the flag to the hledger options list in hledger-ui and hledger-web manuals
@simonmichael
Owner
  • warning at hledger/Hledger/Cli/Utils.hs:78:1:
    Pattern match(es) are non-exhaustive
    In an equation for ‘pivotByOpts’: Patterns not matched: _
@maralorn
Contributor
maralorn commented May 8, 2016

I will have a look at all of it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment