ledgerjournal 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54a88d089772a52d3f2679f0ca80c2d3fed563d7cbadd44531ace686018045df
+  data.tar.gz: f78a221028fd29e7a2553b55431b10fe7ff2ea0cac4fbe4cfb7d62db73f5da3f
+SHA512:
+  metadata.gz: aea34667a60c6560425fa18032ae15b525db1459b741d50e67afed0d52fba9fcce3205163b39ecf01e4d258e59dff21674fdf945f86762df8d9af9296b4a92b5
+  data.tar.gz: 20a2e543860cd3cc7e72ccd9a805d7bdd20e5cbf485f519afd7be24e84d2949de7fdfbc049fdb6a1ef8995d8bcae0c0d0790e36c6843e2577d8d693b6733fe75

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea
+.DS_Store

data/.travis.yml

@@ -0,0 +1,9 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.6
+  - 2.7
+before_install:
+  - gem install bundler -v 2.1.4
+  - sudo apt-get -y install ledger

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ledgerjournal.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -0,0 +1,27 @@
+PATH
+  remote: .
+  specs:
+    ledgerjournal (0.5.0)
+      nokogiri (~> 1.10)
+      open4 (~> 1.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    mini_portile2 (2.4.0)
+    minitest (5.14.0)
+    nokogiri (1.10.9)
+      mini_portile2 (~> 2.4.0)
+    open4 (1.3.4)
+    rake (12.3.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ledgerjournal!
+  minitest (~> 5.0)
+  rake (~> 12.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Ralf Ebert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# ledgerjournal
+
+[![Build Status](https://travis-ci.org/ralfebert/ledgerjournal.svg?branch=master)](https://travis-ci.org/github/ralfebert/ledgerjournal)
+
+ledgerjournal is a Ruby gem to read and write [ledger](https://www.ledger-cli.org/) accounting files.
+For parsing, it uses the xml output from ledger. For outputting, it formats the ledger data to String in custom Ruby code.
+The ledger binary needs to be installed to parse and pretty-print.
+
+## Usage
+
+Parsing a leger file: 
+
+```ruby
+journal = Ledger::Journal.new(path: "example_journal_en.txt")
+journal.transactions.each do |tx|
+  puts tx.date, tx.payee
+end
+```
+
+Creating a ledger:
+
+```ruby
+journal = Ledger::Journal.new(path: "example_journal_en.txt")
+
+journal.transactions << Ledger::Transaction.new(
+  date: Date.new(2020, 1, 2),
+  state: :cleared,
+  payee: 'Example Payee',
+  metadata: { "Foo" => "Bar", "Description" => "Example Transaction" },
+  postings: [
+    Ledger::Posting.new(account: "Expenses:Unknown", currency: "EUR", amount: BigDecimal('1234.56'), metadata: { "Foo" => "Bar", "Description" => "Example Posting" }),
+    Ledger::Posting.new(account: "Assets:Checking", currency: "EUR", amount: BigDecimal('-1234.56'))
+  ]
+)
+
+puts(journal.to_s)
+```
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ledgerjournal'
+```
+
+Or install it yourself as:
+
+    $ gem install ledgerjournal
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ralfebert/ledgerjournal.
+
+## License
+
+libledger is released under the MIT License. See LICENSE.md.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ledgerjournal"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ledgerjournal.gemspec

@@ -0,0 +1,30 @@
+require_relative 'lib/ledgerjournal/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ledgerjournal"
+  spec.version       = Ledger::VERSION
+  spec.licenses      = ['MIT']
+  spec.authors       = ["Ralf Ebert"]
+  spec.email         = ["ralf.ebert@gmail.com"]
+
+  spec.summary       = %q{Library to read and write ledger accounting files.}
+  spec.description   = %q{ledgerjournal is a Ruby gem to read and write ledger accounting files.
+For parsing, it uses the xml output from ledger. For outputting, it formats the ledger data to String in custom Ruby code.
+The ledger binary needs to be installed to parse and pretty-print.}
+  spec.homepage      = "https://github.com/ralfebert/ledgerjournal"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ralfebert/ledgerjournal.git"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+  
+  spec.add_dependency 'nokogiri', '~> 1.10'
+  spec.add_dependency 'open4', '~> 1.3'
+  
+end

data/lib/ledgerjournal/journal.rb

@@ -0,0 +1,72 @@
+require 'shellwords'
+require 'nokogiri'
+require 'open4'
+
+module Ledger
+
+  # Represents a ledger journal
+  # @see https://www.ledger-cli.org/3.0/doc/ledger3.html#Journal-Format
+  class Journal
+
+    # @return [Array<Ledger::Transaction>] list of transactions in journal
+    attr_accessor :transactions
+    # @return [String] path path to ledger file
+    attr_reader :path
+
+    # Creates a new ledger journal or loads transactions from a ledger journal file.
+    # @param [String] path path to a ledger journal to load
+    # @param [String] ledger_args when loading from a path, you can pass in arguments to the ledger command (for example to filter transactions)
+    def initialize(path: nil, ledger_args: nil)
+      @transactions = []
+      if path
+        @path = path
+        raise Error.new("#{@path} not found") unless File.exist?(@path)
+        args = ["-f #{@path.shellescape}", ledger_args].compact.join(" ")
+        read_ledger(ledger_args: args)
+      end
+    end
+
+    # @param [Ledger::Journal] other
+    # @return [Boolean] true if the other journal contains equal transactions
+    def ==(other)
+      self.transactions == other.transactions
+    end
+
+    # @return [String] returns the transactions in the journal formatted as string
+    # @param [Boolean] pretty_print calls ledger to format the journal if true
+    def to_s(pretty_print: true)
+      str = self.transactions.map(&:to_s).join("\n\n")
+      if pretty_print
+        begin
+          str = Ledger.defaults.run("-f - print", stdin: str)
+          str = str.lines.map { |line| line.rstrip }.join("\n") + "\n"
+        rescue => error
+          # return an unformatted string if an error occurs
+          puts "Couldn't format transaction log: #{error}"
+        end
+      end
+      return str
+    end
+
+    # If the journal was opened from a file, save/overwrite the file with the transactions from this journal.
+    def save!
+      raise Error.new("Journal was not read from path, cannot save") unless @path
+      File.write(@path, self.to_s)
+    end
+
+    # returns all transactions that have a posting for the given account
+    # @param [String] account account name
+    def transactions_with_account(account)
+      @transactions.select {|tx| tx.postings.map(&:account).include?(account) }
+    end
+
+    private
+    def read_ledger(ledger_args: "")
+      xml_result = Ledger.defaults.run(ledger_args + " xml")
+      xml = Nokogiri::XML(xml_result)
+      @transactions = xml.css("transaction").map { |tx_xml| Transaction.parse_xml(tx_xml) }
+    end
+
+  end
+
+end

data/lib/ledgerjournal/options.rb

@@ -0,0 +1,79 @@
+module Ledger
+
+  # Options for interaction with ledger-cli
+  class Options
+    
+    # @param [String] date_format like '%Y/%m/%d' to pass to ledger-cli
+    # @param [Boolean] decimal_comma pass true to use ',' as decimal comma separator
+    def initialize(date_format:, decimal_comma:)
+      @date_format = date_format
+      @decimal_comma = decimal_comma
+    end
+
+    # Returns default options by locale. Currently supported are :en or :de.
+    # @param [Symbol] locale as symbol
+    # @return [Ledger::Options]
+    def self.for_locale(locale)
+      case locale.to_sym
+      when :en
+        Options.new(date_format: '%Y/%m/%d', decimal_comma: false)
+      when :de
+        Options.new(date_format: '%d.%m.%Y', decimal_comma: true)
+      else
+        raise Error.new("Unknown locale for ledger options: #{locale}, supported are :en, :de")
+      end
+    end
+
+    # @param [String] string decimal amount as String (like '12.34')
+    # @return [BigDecimal] the given string as BigDecimal, parsed according the decimal_comma setting
+    def parse_amount(string)
+      BigDecimal(if @decimal_comma then string.gsub(".", "").gsub(",", ".") else string end)
+    end
+
+    # Formats the given value as String
+    # @param [Date, BigDecimal] value to parse
+    # @return [String] string representation according to the options
+    def format(value)
+      if value.instance_of? Date
+        return value.strftime(@date_format)
+      elsif value.instance_of? BigDecimal
+        str = '%.2f' % value
+        str.gsub!('.', ',') if @decimal_comma
+        return str
+      else
+        raise Error.new("Unknown value type #{value.class}")
+      end
+    end
+
+    # Runs ledger-cli
+    # @param [String] args command line arguments to pass
+    # @param [String] stdin stdin text to pass
+    # @return [String] stdout result of calling ledger
+    def run(args, stdin: nil)
+      output = ""
+      error = ""
+      begin
+        Open4.spawn("ledger #{cmdline_options} #{args}", :stdin => stdin, :stdout => output, :stderr => error)
+      rescue => e
+        raise Error.new("#{e}: #{error}")
+      end
+      return output
+    end
+
+    private
+    def cmdline_options
+      args = ["--args-only", "--date-format #{@date_format}", "--input-date-format #{@date_format}"]
+      args << "--decimal-comma" if @decimal_comma
+      return args.join(" ")
+    end
+
+  end
+
+  @defaults = Options.for_locale(:en)
+
+  class <<self
+    # @attr [Ledger::Options] defaults options to use when interacting with ledger-cli, by default settings for locale :en are used
+    attr_accessor :defaults
+  end
+
+end

data/lib/ledgerjournal/posting.rb

@@ -0,0 +1,63 @@
+require 'date'
+require 'bigdecimal'
+
+module Ledger
+
+  # @attr [String] account
+  # @attr [String] currency
+  # @attr [BigDecimal] amount
+  # @attr [BigDecimal] balance_assignment if a balance_assignment is set, ledger-cli checks the balance of the account after this posting
+  # @attr [Hash<String, String>] metadata
+  class Posting
+    
+    attr_accessor :account, :currency, :amount, :balance_assignment, :metadata
+        
+    def initialize(account:, currency:, amount:, balance_assignment: nil, metadata: {})
+      @account = account
+      @currency = currency
+      @amount = amount
+      @balance_assignment = balance_assignment
+      @metadata = metadata
+    end
+    
+    def self.parse_xml(xml)
+      balance_assignment = nil
+      currency = xml.xpath('post-amount/amount/commodity/symbol').text
+      if xml_balance = xml.xpath('balance-assignment').first
+        balance_currency = xml_balance.xpath('commodity/symbol').text
+        raise Error.new("Posting currency #{currency} doesn't match assignment currency #{balance_currency}") if currency != balance_currency
+        balance_assignment = Ledger.defaults.parse_amount(xml_balance.xpath('quantity').text)
+      end
+      Posting.new(
+        account: xml.xpath('account/name').text,
+        currency: currency,
+        amount: Ledger.defaults.parse_amount(xml.xpath('post-amount/amount/quantity').text),
+        balance_assignment: balance_assignment,
+        metadata: Hash[xml.xpath("metadata/value").collect {|m| [m['key'], m.xpath("string").text]}]
+      )
+    end
+    
+    def ==(other)
+      self.class == other.class && self.all_fields == other.all_fields
+    end
+    
+    def to_s
+      posting_line = "#{self.account}      #{self.currency} #{Ledger.defaults.format(self.amount)}"
+      if self.balance_assignment
+        posting_line += " = #{self.currency} #{Ledger.defaults.format(self.balance_assignment)}"
+      end
+      lines = [posting_line]
+      unless self.metadata.empty?
+        lines += metadata.to_a.sort {|a,b| a[0].casecmp(b[0]) }.collect{|m| "; #{m[0]}: #{m[1]}" }
+      end
+      return lines.join("\n")
+    end
+    
+    protected
+    def all_fields
+      self.instance_variables.map { |variable| self.instance_variable_get variable }
+    end
+    
+  end
+
+end

data/lib/ledgerjournal/transaction.rb

@@ -0,0 +1,64 @@
+require 'date'
+
+module Ledger
+
+  # @attr [Date] date
+  # @attr [Symbol] state state of transaction, can be :cleared or :pending
+  # @attr [String] payee
+  # @attr [Hash<String, String>] metadata
+  # @attr [Array<Ledger::Posting>] postings
+  class Transaction
+
+    attr_accessor :date, :state, :payee, :metadata, :postings
+
+    def initialize(date:, state: :cleared, payee:, metadata: {}, postings:)
+      @date = date
+      @state = state
+      @payee = payee
+      @metadata = metadata
+      @postings = postings
+    end
+
+    def self.parse_xml(xml)
+      Transaction.new(
+          date: Date.strptime(xml.xpath('date').text, '%Y/%m/%d'),
+          payee: xml.xpath('payee').text,
+          state: xml['state'].to_sym,
+          metadata: Hash[xml.xpath("metadata/value").collect { |m| [m['key'], m.xpath("string").text] }],
+          postings: xml.xpath('postings/posting').map { |posting_xml| Posting.parse_xml(posting_xml) }
+      )
+    end
+
+    def ==(other)
+      self.class == other.class && self.all_fields == other.all_fields
+    end
+
+    def to_s
+      date_str = Ledger.defaults.format(self.date)
+      states = {:pending => "!", :cleared => "*"}
+      lines = ["#{date_str} #{states[self.state]} #{self.payee}"]
+
+      unless self.metadata.empty?
+        lines += metadata.to_a.sort { |a, b| a[0].casecmp(b[0]) }.collect { |m| "    ; #{m[0]}: #{m[1]}" }
+      end
+
+      lines += self.postings.map { |posting| posting.to_s.lines.map { |line| "    " + line }.join }
+
+      return lines.join("\n") + "\n"
+    end
+
+    # @param [String] account
+    # @return [Ledger::Posting]
+    def posting_for_account(account)
+      postings.select { |posting| posting.account == account }.first
+    end
+
+    protected
+
+    def all_fields
+      self.instance_variables.map { |variable| self.instance_variable_get(variable) }
+    end
+
+  end
+
+end

data/lib/ledgerjournal/version.rb

@@ -0,0 +1,4 @@
+module Ledger
+  # ledgerjournal version
+  VERSION = "0.5.0"
+end

data/lib/ledgerjournal.rb

@@ -0,0 +1,13 @@
+require "ledgerjournal/version"
+require "ledgerjournal/options"
+require "ledgerjournal/journal"
+require "ledgerjournal/transaction"
+require "ledgerjournal/posting"
+
+# Ledger provides classes to read and write ledger accounting files.
+module Ledger
+
+  # Error class for errors handling ledger files
+  class Error < StandardError; end
+
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: ledgerjournal
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Ralf Ebert
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-04-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: open4
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: |-
+  ledgerjournal is a Ruby gem to read and write ledger accounting files.
+  For parsing, it uses the xml output from ledger. For outputting, it formats the ledger data to String in custom Ruby code.
+  The ledger binary needs to be installed to parse and pretty-print.
+email:
+- ralf.ebert@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- ledgerjournal.gemspec
+- lib/ledgerjournal.rb
+- lib/ledgerjournal/journal.rb
+- lib/ledgerjournal/options.rb
+- lib/ledgerjournal/posting.rb
+- lib/ledgerjournal/transaction.rb
+- lib/ledgerjournal/version.rb
+homepage: https://github.com/ralfebert/ledgerjournal
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ralfebert/ledgerjournal
+  source_code_uri: https://github.com/ralfebert/ledgerjournal.git
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.4
+signing_key: 
+specification_version: 4
+summary: Library to read and write ledger accounting files.
+test_files: []