gnucash 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 52713dfe700ed99ecbde5b43d7c0614e86d3ec34
-  data.tar.gz: d59a7c2b7069bc1c355201e4c4e9f4ec832d1d55
+SHA256:
+  metadata.gz: 72eb52f6d34ca1767398d5a0bbb0379b311ef87ed8ca7ae9190d7c02b5692e0d
+  data.tar.gz: 8f414c48579e293d9539b06c90e79e7a13fba80ffd53f8f07d483e2ee8cfcc1a
 SHA512:
-  metadata.gz: ed54f96c4c23bb1960895f8c3df8918faed0b83362e73b5682251501fd8b664b3458797fe0a9abd45d5fb378b81f1dc508c825ff83c2e3b9a1a376c5c1a94e0c
-  data.tar.gz: a92fc8a0fcb6eff1a5e851f9e512fd8c7714aaec0d69053055a879a7548e1036a283ba7cde903c34f52d615dbd2e80076ceb3a532fc840541f293a9823bea4a2
+  metadata.gz: ad9bf95fcff49be8da8027e4c15a6246b261c4855e752073be128c883a1511d960791a51d80f4c084f49216d7242fcebf5c25505b4fa502807d1222458b2ad19
+  data.tar.gz: 77b49d4963895f3b08a7f8e55b11d5e3e427e3fa5425a80384fe09aad80fb09d17ab0f877b47fbb63ceb09c740d6e56b27719a057afb6e587829a072f74519e4

data/.gitignore

@@ -17,3 +17,4 @@ tmp
 test.rb
 spec/books/*.gnucash.*.*
 spec/books/*.LCK
+bin/

data/.travis.yml

@@ -0,0 +1,26 @@
+language: ruby
+
+bundler_args: --without debugger
+
+cache: bundler
+sudo: false
+
+before_install:
+  - gem --version
+
+script: bundle exec rspec
+
+rvm:
+  - 2.4.6
+  - 2.5.5
+  - 2.6.4
+  - ruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+
+notifications:
+  email:
+    recipients:
+      - niklaus.giger@member.fsf.org

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # ChangeLog
 
+## v1.6.0
+
+- add Customer class and Book#find_customer_by_full_name (#12, #13)
+
+## v1.5.0
+
+- add options Hash to Account#balance_on with :recursive option
+
 ## v1.4.0
 
 - add Account#parent_id and #parent

data/Gemfile

@@ -2,3 +2,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in gnucash.gemspec
 gemspec
+
+group :development do
+  # rdbg / Cursor: depuración (vscode-rdbg)
+  gem "debug", ">= 1.9", require: false
+end

data/Gemfile.lock

@@ -1,44 +1,96 @@
 PATH
   remote: .
   specs:
-    gnucash (1.4.0)
+    gnucash (1.6.0)
       nokogiri
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.3)
-    docile (1.1.5)
-    json (2.1.0)
-    mini_portile2 (2.3.0)
-    nokogiri (1.8.1)
-      mini_portile2 (~> 2.3.0)
-    rake (12.3.0)
-    rdoc (6.0.1)
-    rspec (3.7.0)
-      rspec-core (~> 3.7.0)
-      rspec-expectations (~> 3.7.0)
-      rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.1)
-      rspec-support (~> 3.7.0)
-    rspec-expectations (3.7.0)
+    date (3.5.1)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    erb (6.0.4)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    mini_portile2 (2.8.9)
+    nokogiri (1.19.3)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.19.3-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.3-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.3-x86_64-linux-musl)
+      racc (~> 1.4)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rake (13.4.2)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-mocks (3.7.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-support (3.7.0)
-    simplecov (0.15.1)
-      docile (~> 1.1.0)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    yard (0.9.12)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    yard (0.9.43)
 
 PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
   ruby
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
 
 DEPENDENCIES
+  debug (>= 1.9)
   gnucash!
   rake
   rdoc
@@ -47,4 +99,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   1.16.1
+   4.0.11

data/README.md

@@ -37,7 +37,7 @@ act.transactions.each do |txn|
                  txn.date,
                  txn.value,
                  balance,
-                 txn.description))
+                 txn.description)
 end
 
 year = Date.today.year
@@ -45,6 +45,14 @@ delta = act.balance_on("#{year}-12-31") - act.balance_on("#{year - 1}-12-31")
 puts "You've saved #{delta} this year so far!"
 ```
 
+To get the balance of an account, use ```act.balance_on("#{year}-12-31")```.
+To get the total balance of an account with all its children accounts,
+use ```act.balance_on("#{year}-12-31", recursive: true)```.
+
+## Full YARD Documentation
+
+See <https://rubydoc.info/github/holtrop/ruby-gnucash/master>.
+
 ## Contributing
 
 1. Fork it

data/gnucash.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |gem|
   gem.homepage      = "https://github.com/holtrop/ruby-gnucash"
   gem.license       = "MIT"
 
-  gem.files         = `git ls-files`.split($/)
+  gem.files         = `git ls-files`.split($/).reject { |f| f == "bin/rdbg" }
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]

data/lib/gnucash/account.rb

@@ -15,6 +15,11 @@ module Gnucash
     # @return [String] The GUID of the account.
     attr_reader :id
 
+    # @return [String, nil] Account code (+act:code+), if set in GnuCash.
+    #
+    # @since 1.6.0
+    attr_reader :code
+
     # @return [Array<AccountTransaction>]
     #   List of transactions associated with this account.
     attr_reader :transactions
@@ -22,6 +27,16 @@ module Gnucash
     # @return [Boolean] Whether the account is a placeholder or not.
     attr_reader :placeholder
 
+    # @return [String, nil] Commodity namespace (+cmdty:space+) from +act:commodity+, if present.
+    #
+    # @since 1.6.0
+    attr_reader :commodity_space
+
+    # @return [String, nil] Commodity id (+cmdty:id+) from +act:commodity+, if present.
+    #
+    # @since 1.6.0
+    attr_reader :commodity_id
+
     # @since 1.4.0
     #
     # @return [String, nil] The GUID of the parent account, if any.
@@ -38,6 +53,8 @@ module Gnucash
       @type = node.xpath('act:type').text
       @description = node.xpath('act:description').text
       @id = node.xpath('act:id').text
+      code_raw = node.at_xpath('act:code')&.text
+      @code = (code_raw.nil? || code_raw.empty?) ? nil : code_raw
       @parent_id = node.xpath('act:parent').text
       @parent_id = nil if @parent_id == ""
       @transactions = []
@@ -46,6 +63,29 @@ module Gnucash
         (slot.xpath("slot:key").first.text == "placeholder" and
          slot.xpath("slot:value").first.text == "true")
       end ? true : false
+
+      cmd = node.at_xpath("act:commodity")
+      if cmd
+        @commodity_space = cmd.at_xpath("cmdty:space")&.text&.strip
+        @commodity_id = cmd.at_xpath("cmdty:id")&.text&.strip
+        @commodity_space = nil if @commodity_space.nil? || @commodity_space.empty?
+        @commodity_id = nil if @commodity_id.nil? || @commodity_id.empty?
+      else
+        @commodity_space = nil
+        @commodity_id = nil
+      end
+    end
+
+    # Priced {Security} for this account's commodity, if the commodity appears in the
+    # book's price database (+gnc:pricedb+). Otherwise +nil+.
+    #
+    # @since 1.6.0
+    #
+    # @return [Security, nil]
+    def security
+      return nil unless @commodity_space && @commodity_id
+
+      @book.find_security(@commodity_space, @commodity_id)
     end
 
     # Return the fully qualified account name.
@@ -99,13 +139,28 @@ module Gnucash
     # Transactions that occur on the given date are included in the returned
     # balance.
     #
-    # @param date [String, Date] Date on which to query the balance.
+    # @param date [String, Date]
+    #   Date on which to query the balance.
+    # @param options [Hash]
+    #   Optional parameters.
+    # @option options [Boolean] :recursive
+    #   Whether to include children account balances.
     #
-    # @return [Value] Balance of the account as of the date given.
-    def balance_on(date)
+    # @return [Value]
+    #   Balance of the account as of the date given.
+    def balance_on(date, options = {})
       date = Date.parse(date) if date.is_a?(String)
-      return Value.new(0) unless @balances.size > 0
-      return Value.new(0) if @balances.first[:date] > date
+      return_value = Value.new(0)
+
+      if options[:recursive]
+        # Get all child accounts from this account and accumulate the balances of them.
+        @book.accounts.reject { |account| account.parent != self }.each do |child_account|
+          return_value += child_account.balance_on(date, recursive: true)
+        end
+      end
+
+      return return_value unless @balances.size > 0
+      return return_value if @balances.first[:date] > date
       return @balances.last[:value] if date >= @balances.last[:date]
       imin = 0
       imax = @balances.size - 2
@@ -126,7 +181,7 @@ module Gnucash
     # @return [Array<Symbol>] Attributes used to build the inspection string
     # @see Gnucash::Support::LightInspect
     def attributes
-      %i[id name description type placeholder parent_id]
+      %i[id name description type code placeholder parent_id commodity_space commodity_id]
     end
 
     private

data/lib/gnucash/book.rb

@@ -1,3 +1,4 @@
+require "date"
 require "zlib"
 require "nokogiri"
 
@@ -6,12 +7,27 @@ module Gnucash
   class Book
     include Support::LightInspect
 
+    # One row from +gnc:pricedb+.
+    #
+    # @since 1.6.0
+    PriceRow = Struct.new(:commodity_space, :commodity_id, :currency_space, :currency_id, :date, :value)
+
     # @return [Array<Account>] Accounts in the book.
     attr_reader :accounts
 
+    # @return [Array<Account>] Customers in the book.
+    # @since 1.6.0
+    attr_reader :customers
+
     # @return [Array<Transaction>] Transactions in the book.
     attr_reader :transactions
 
+    # @return [Array<PriceRow>]
+    #   Raw price-database rows (commodity/currency/value/date). Prefer
+    #   {Security#value_on} for valuations.
+    # @since 1.6.0
+    attr_reader :price_rows
+
     # @return [Date] Date of the first transaction in the book.
     attr_reader :start_date
 
@@ -36,8 +52,11 @@ module Gnucash
         raise "Error: Expected to find one gnc:book entry"
       end
       @book_node = book_nodes.first
+      build_customers
       build_accounts
       build_transactions
+      build_price_quotes
+      build_commodity_isin_index
       finalize
     end
 
@@ -61,6 +80,76 @@ module Gnucash
       @accounts.find { |a| a.full_name == full_name }
     end
 
+    # Return a handle to the Customer object that has the given fully-qualified
+    # name.
+    #
+    # @since 1.6.0
+    #
+    # @param full_name [String]
+    #   Fully-qualified customer name (ex: "Joe Doe").
+    #
+    # @return [Customer, nil] Customer object, or nil if not found.
+    def find_customer_by_full_name(full_name)
+      @customers.find { |a| a.full_name == full_name }
+    end
+
+    # Return every {Security} that appears in the price database (unique commodity).
+    #
+    # @since 1.6.0
+    #
+    # @return [Array<Security>]
+    def securities
+      @securities ||= @price_rows.map { |r| [r.commodity_space, r.commodity_id] }.uniq.map do |space, id|
+        Security.new(self, space, id)
+      end
+    end
+
+    # Look up a security by GnuCash commodity +space+ and +id+.
+    #
+    # @since 1.6.0
+    #
+    # @return [Security, nil]
+    def find_security(space, id)
+      return nil unless @price_rows.any? { |r| r.commodity_space == space && r.commodity_id == id }
+      Security.new(self, space, id)
+    end
+
+    # Look up a priced security whose commodity defines this ISIN (+cmdty:xcode+ or a slot
+    # whose key matches +isin+, e.g. +user:ISIN+). Comparison ignores spaces, hyphens and case.
+    #
+    # @since 1.6.0
+    #
+    # @param isin [String] ISIN as stored or typed (e.g. +"US0378331005"+).
+    #
+    # @return [Security, nil]
+    def find_security_by_isin(isin)
+      key = ISIN.normalize(isin)
+      return nil if key.empty?
+
+      pair = @isin_index[key]
+      return nil unless pair
+
+      find_security(pair[0], pair[1])
+    end
+
+    # ISIN for a commodity if present in the book (+nil+ otherwise).
+    #
+    # @since 1.6.0
+    #
+    # @return [String, nil] Normalized ISIN (12 uppercase alphanumeric characters).
+    def isin_for_commodity(space, id)
+      @isin_for_commodity[[space, id]]
+    end
+
+    # Price-database rows for one commodity (used by {Security#value_on}).
+    #
+    # @since 1.6.0
+    #
+    # @return [Array<PriceRow>]
+    def quotes_for_commodity(space, id)
+      @price_rows.select { |r| r.commodity_space == space && r.commodity_id == id }
+    end
+
     # Attributes available for inspection
     #
     # @return [Array<Symbol>] Attributes used to build the inspection string
@@ -78,6 +167,12 @@ module Gnucash
       end
     end
 
+    def build_customers
+      @customers = @book_node.xpath('gnc:GncCustomer').map do |customer_node|
+        Customer.new(self, customer_node)
+      end
+    end
+
     # @return [void]
     def build_transactions
       @start_date = nil
@@ -90,6 +185,82 @@ module Gnucash
       end
     end
 
+    # @return [void]
+    def build_price_quotes
+      pricedb = @book_node.at_xpath('gnc:pricedb')
+      @price_rows = []
+      return unless pricedb
+
+      pricedb.element_children.each do |node|
+        next unless node.element?
+        row = parse_price_node(node)
+        @price_rows << row if row
+      end
+    end
+
+    # @return [PriceRow, nil]
+    def parse_price_node(node)
+      return nil unless node.at_xpath('price:commodity')
+
+      cmd = node.at_xpath('price:commodity')
+      cur = node.at_xpath('price:currency')
+      return nil unless cmd && cur
+
+      commodity_space = cmd.at_xpath('cmdty:space')&.text
+      commodity_id = cmd.at_xpath('cmdty:id')&.text
+      currency_space = cur.at_xpath('cmdty:space')&.text
+      currency_id = cur.at_xpath('cmdty:id')&.text
+      return nil if [commodity_space, commodity_id, currency_space, currency_id].any? { |s| s.nil? || s.empty? }
+
+      ts = node.at_xpath('price:time/ts:date')&.text
+      return nil if ts.nil? || ts.empty?
+
+      date = Date.parse(ts.split(' ').first)
+      val_text = node.at_xpath('price:value')&.text
+      return nil if val_text.nil? || val_text.empty?
+
+      PriceRow.new(commodity_space, commodity_id, currency_space, currency_id, date, Value.new(val_text))
+    end
+
+    # @return [void]
+    def build_commodity_isin_index
+      @isin_for_commodity = {}
+      @isin_index = {}
+
+      @book_node.xpath("gnc:commodity").each do |node|
+        space = node.at_xpath("cmdty:space")&.text&.strip
+        id = node.at_xpath("cmdty:id")&.text&.strip
+        next if space.nil? || id.nil? || space.empty? || id.empty?
+
+        raw = extract_isin_from_commodity_node(node)
+        next unless raw
+
+        key = ISIN.normalize(raw)
+        next unless ISIN.valid_format?(key)
+
+        @isin_for_commodity[[space, id]] = key
+        @isin_index[key] ||= [space, id]
+      end
+    end
+
+    # @return [String, nil] raw ISIN string from XML before normalization
+    def extract_isin_from_commodity_node(node)
+      node.xpath(".//slot").each do |slot|
+        k = slot.at_xpath("slot:key")&.text
+        next unless k&.match?(/isin/i)
+
+        v = slot.at_xpath("slot:value")&.text&.strip
+        next if v.nil? || v.empty?
+
+        return v if ISIN.valid_format?(v)
+      end
+
+      xcode = node.at_xpath("cmdty:xcode")&.text&.strip
+      return xcode if xcode && ISIN.valid_format?(xcode)
+
+      nil
+    end
+
     # @return [void]
     def finalize
       @accounts.sort! do |a, b|

data/lib/gnucash/customer.rb

@@ -0,0 +1,54 @@
+module Gnucash
+  # Represent a GnuCash customer object.
+  # @since 1.6.0
+  class Customer
+    include Support::LightInspect
+    # gnc:GncCustomer
+    ## id, company, name, addr1, addr2, addr3, addr4, phone, fax, email, notes, shipname, shipaddr1, shipaddr2, shipaddr3, shipaddr4, shiphone, shipfax, shipmail
+
+    # @return [String] The name of the customer (unqualified).
+    attr_reader :name
+
+    # @return [String] The GUID of the customer.
+    attr_reader :guid
+
+    # @return [String] The ID of the customer.
+    attr_reader :id
+
+    # @return [String] The address of the customer.
+    attr_reader :address
+
+    # @return [String] The shipping address of the customer.
+    attr_reader :shipping_address
+
+    # Create an customer object.
+    #
+    # @param book [Book] The {Gnucash::Book} containing the customer.
+    # @param node [Nokogiri::XML::Node] Nokogiri XML node.
+    def initialize(book, node)
+      @book = book
+      @node = node
+      @name = node.xpath('cust:name').text
+      @id = node.xpath('cust:id').text
+      @guid = node.xpath('cust:guid').text
+      @address = node.xpath('cust:addr').text
+      @shipping_address = node.xpath('cust:shipaddr').text
+    end
+
+    # Return the fully qualified customer name.
+    #
+    # @return [String] Fully qualified customer name.
+    def full_name
+      name
+    end
+
+    # Attributes available for inspection
+    #
+    # @return [Array<Symbol>] Attributes used to build the inspection string
+    # @see Gnucash::Support::LightInspect
+    def attributes
+      %i[id name guid address shipping_address]
+    end
+
+  end
+end

data/lib/gnucash/isin.rb

@@ -0,0 +1,25 @@
+module Gnucash
+  # Helpers for ISIN (ISO 6166) strings as stored on GnuCash commodities.
+  #
+  # @since 1.6.0
+  module ISIN
+    module_function
+
+    # @param str [String, nil]
+    # @return [String] Uppercase ISIN with spaces and hyphens removed.
+    def normalize(str)
+      return "" if str.nil? || str.to_s.empty?
+      str.to_s.gsub(/[\s-]/, "").upcase
+    end
+
+    # Rough format check: 12 alphanumeric characters after normalization.
+    #
+    # @param str [String, nil]
+    # @return [Boolean]
+    def valid_format?(str)
+      s = normalize(str)
+      return false if s.length != 12
+      s.match?(/\A[A-Z0-9]{12}\z/)
+    end
+  end
+end

data/lib/gnucash/security.rb

@@ -0,0 +1,116 @@
+require "date"
+
+module Gnucash
+  # Price quote for a security (commodity) from the GnuCash price database: the
+  # value of one unit of the security expressed in +currency+ as of +date+.
+  #
+  # @since 1.6.0
+  class SecurityQuote
+    include Support::LightInspect
+
+    # @return [Value] Price of one unit of the security in the quote currency.
+    attr_reader :value
+
+    # @return [String] Commodity namespace (GnuCash "space") of the quote currency.
+    attr_reader :currency_space
+
+    # @return [String] Commodity id of the quote currency (e.g. +"USD"+).
+    attr_reader :currency_id
+
+    # @return [Date] Date of the price in the book (quote time, date-only).
+    attr_reader :date
+
+    def initialize(value:, currency_space:, currency_id:, date:)
+      @value = value
+      @currency_space = currency_space
+      @currency_id = currency_id
+      @date = date
+    end
+
+    def attributes
+      %i[value currency_space currency_id date]
+    end
+  end
+
+  # A security (stock, fund, etc.) identified by its GnuCash commodity
+  # +space+ and +id+, with prices loaded from the book's price database.
+  #
+  # @since 1.6.0
+  class Security
+    include Support::LightInspect
+
+    # @return [String] Commodity namespace (e.g. +"NASDAQ"+, +"ISO4217"+).
+    attr_reader :space
+
+    # @return [String] Commodity id (e.g. ticker or currency code).
+    attr_reader :id
+
+    # @param book [Book] Parent book.
+    # @param space [String] Commodity space.
+    # @param id [String] Commodity id.
+    def initialize(book, space, id)
+      @book = book
+      @space = space
+      @id = id
+    end
+
+    # @return [String, nil] ISIN from the commodity definition (+cmdty:xcode+ or ISIN slot), normalized.
+    def isin
+      @book.isin_for_commodity(@space, @id)
+    end
+
+    # Return the most recent price quote whose date is on or before the given
+    # valuation date.
+    #
+    # If the security has multiple quote currencies, +currency_space+ and
+    # +currency_id+ select one; if omitted, USD (+ISO4217+ / +USD+) is preferred
+    # when present, otherwise an arbitrary quote chain is used.
+    #
+    # @param date [String, Date] Valuation date.
+    # @param currency_space [String, nil] Restrict to this quote currency space.
+    # @param currency_id [String, nil] Restrict to this quote currency id.
+    #
+    # @return [SecurityQuote, nil] Quote used for valuation, or nil if none applies.
+    def value_on(date, currency_space: nil, currency_id: nil)
+      date = Date.parse(date) if date.is_a?(String)
+      if (currency_space.nil? ^ currency_id.nil?)
+        raise ArgumentError, "currency_space and currency_id must both be set or both omitted"
+      end
+
+      quotes = @book.quotes_for_commodity(@space, @id)
+      return nil if quotes.empty?
+
+      filtered =
+        if currency_space
+          quotes.select { |q| q.currency_space == currency_space && q.currency_id == currency_id }
+        else
+          quotes
+        end
+      return nil if filtered.empty?
+
+      pick_currency = lambda do |list|
+        usd = list.select { |q| q.currency_space == "ISO4217" && q.currency_id == "USD" }
+        (usd.empty? ? list : usd)
+      end
+
+      candidates = currency_space ? filtered : pick_currency.call(filtered)
+      return nil if candidates.empty?
+
+      candidates = candidates.select { |q| q.date <= date }
+      return nil if candidates.empty?
+
+      best = candidates.max_by(&:date)
+
+      SecurityQuote.new(
+        value: best.value,
+        currency_space: best.currency_space,
+        currency_id: best.currency_id,
+        date: best.date
+      )
+    end
+
+    def attributes
+      %i[space id isin]
+    end
+  end
+end

data/lib/gnucash/version.rb

@@ -1,4 +1,4 @@
 module Gnucash
   # gem version
-  VERSION = "1.4.0"
+  VERSION = "1.6.0"
 end

data/lib/gnucash.rb

@@ -1,6 +1,9 @@
 require_relative "gnucash/support"
 require_relative "gnucash/account"
+require_relative "gnucash/customer"
 require_relative "gnucash/account_transaction"
+require_relative "gnucash/isin"
+require_relative "gnucash/security"
 require_relative "gnucash/book"
 require_relative "gnucash/transaction"
 require_relative "gnucash/value"

data/spec/books/sample-text.gnucash

@@ -33,9 +33,10 @@
 <gnc:book version="2.0.0">
 <book:id type="guid">b8178c8d763ec49988c2696d9e41d7f6</book:id>
 <gnc:count-data cd:type="commodity">1</gnc:count-data>
-<gnc:count-data cd:type="account">64</gnc:count-data>
-<gnc:count-data cd:type="transaction">473</gnc:count-data>
+<gnc:count-data cd:type="account">65</gnc:count-data>
+<gnc:count-data cd:type="transaction">474</gnc:count-data>
 <gnc:count-data cd:type="schedxaction">6</gnc:count-data>
+<gnc:count-data cd:type="gnc:GncCustomer">1</gnc:count-data>
 <gnc:commodity version="2.0.0">
   <cmdty:space>ISO4217</cmdty:space>
   <cmdty:id>USD</cmdty:id>
@@ -30238,6 +30239,56 @@
     </gnc:recurrence>
   </sx:schedule>
 </gnc:schedxaction>
+<gnc:GncCustomer version="2.0.0">
+  <cust:guid type="guid">0938eaff7545d7ba45fe7b866d60a209</cust:guid>
+  <cust:name>Joe Doe</cust:name>
+  <cust:id>8765</cust:id>
+  <cust:addr version="2.0.0">
+    <addr:name>Joe Doe jr</addr:name>
+    <addr:addr1>Main Street 7</addr:addr1>
+    <addr:addr2>3rd floor</addr:addr2>
+    <addr:addr3>adress 3rd line</addr:addr3>
+    <addr:addr4>adress 4th line</addr:addr4>
+    <addr:phone>+41 55 612 20 54</addr:phone>
+    <addr:fax>+41 55 612 20 55</addr:fax>
+    <addr:email>joe.doe@gmail.com</addr:email>
+  </cust:addr>
+  <cust:shipaddr version="2.0.0">
+    <addr:name>Joe Doe sr</addr:name>
+    <addr:addr1>Main Street 1</addr:addr1>
+    <addr:addr2>line 2</addr:addr2>
+    <addr:addr3>line 3</addr:addr3>
+    <addr:addr4>line 4</addr:addr4>
+    <addr:phone>+41 612 20 55</addr:phone>
+    <addr:fax>+41 612 20 56</addr:fax>
+    <addr:email>joe.doe@gmail-copy.com</addr:email>
+  </cust:shipaddr>
+  <cust:notes>Some remark about the customer</cust:notes>
+  <cust:taxincluded>USEGLOBAL</cust:taxincluded>
+  <cust:active>1</cust:active>
+  <cust:discount>0/1</cust:discount>
+  <cust:credit>0/1</cust:credit>
+  <cust:currency>
+    <cmdty:space>ISO4217</cmdty:space>
+    <cmdty:id>USD</cmdty:id>
+  </cust:currency>
+  <cust:use-tt>0</cust:use-tt>
+  <cust:slots>
+    <slot>
+      <slot:key>last-posted-to-acct</slot:key>
+      <slot:value type="guid">849f778995e8ecf8d4b96940afbbdcd7</slot:value>
+    </slot>
+    <slot>
+      <slot:key>payment</slot:key>
+      <slot:value type="frame">
+        <slot>
+          <slot:key>last_acct</slot:key>
+          <slot:value type="guid">f58e9b550445468e25f277abdeadee91</slot:value>
+        </slot>
+      </slot:value>
+    </slot>
+  </cust:slots>
+</gnc:GncCustomer>
 </gnc:book>
 </gnc-v2>
 

data/spec/gnucash/account_spec.rb

@@ -54,6 +54,12 @@ module Gnucash
       it "includes transactions that occur on the given date" do
         expect(@checking.balance_on("2007-03-27")).to eq Value.new(780000)
       end
+
+      describe 'with child accounts' do
+        it "returns the balance with the balance of the child accounts" do
+          expect(@assets.balance_on("2007-03-27", recursive: true)).to eq Value.new(790000)
+        end
+      end
     end
 
     it "stores whether the account was a placeholder" do
@@ -64,7 +70,36 @@ module Gnucash
     end
 
     it "avoid inspection of heavier attributes" do
-      expect(@salary.inspect).to eq "#<Gnucash::Account id: efebb6cb617971b0a7f62e9d5a204789, name: Salary, description: Salary, type: INCOME, placeholder: false, parent_id: 35ab61d46f5404895bf5d4949f8a5593>"
+      expect(@salary.inspect).to eq "#<Gnucash::Account id: efebb6cb617971b0a7f62e9d5a204789, name: Salary, description: Salary, type: INCOME, code: , placeholder: false, parent_id: 35ab61d46f5404895bf5d4949f8a5593, commodity_space: ISO4217, commodity_id: USD>"
+    end
+
+    context "with pricedb-fixture (account linked to a priced security)" do
+      before(:all) do
+        @pricedb_book = Gnucash.open("spec/books/pricedb-fixture.gnucash")
+        @stocks_account = @pricedb_book.find_account_by_full_name("Stocks")
+      end
+
+      it "returns the Security for the account commodity when it appears in the price database" do
+        sec = @stocks_account.security
+        expect(sec).not_to be_nil
+        expect(sec.space).to eq("TEST")
+        expect(sec.id).to eq("STK")
+        expect(sec.isin).to eq("US0378331005")
+      end
+
+      it "returns nil when the account commodity has no priced security" do
+        brokerage = @pricedb_book.find_account_by_full_name("Brokerage")
+        expect(brokerage.security).to be_nil
+      end
+
+      it "exposes the GnuCash account code (act:code)" do
+        expect(@pricedb_book.find_account_by_full_name("Brokerage").code).to eq("98234989234")
+        expect(@stocks_account.code).to eq("9823498n ewori oio982394")
+      end
+
+      it "returns nil for code when act:code is absent" do
+        expect(@pricedb_book.find_account_by_full_name("Root Account").code).to be_nil
+      end
     end
   end
 end

data/spec/gnucash/customer_spec.rb

@@ -0,0 +1,42 @@
+module Gnucash
+  describe Customer do
+    @@addr_1 = "\n    Joe Doe jr\n    Main Street 7\n    3rd floor\n    adress 3rd line\n    adress 4th line\n    +41 55 612 20 54\n    +41 55 612 20 55\n    joe.doe@gmail.com\n  "
+    @@addr_2 = "\n    Joe Doe sr\n    Main Street 1\n    line 2\n    line 3\n    line 4\n    +41 612 20 55\n    +41 612 20 56\n    joe.doe@gmail-copy.com\n  "
+    
+    before(:all) do
+      # just read the file once
+      @book = Gnucash.open("spec/books/sample.gnucash")
+      @joe_doe =  @book.find_customer_by_full_name("Joe Doe")
+    end
+
+    it "gives access to the name" do
+      expect(@joe_doe.name).to eq "Joe Doe"
+    end
+
+    it "gives access to the full name" do
+      expect(@joe_doe.full_name).to eq "Joe Doe"
+    end
+
+    it "gives access to the guid" do
+      expect(@joe_doe.guid).to eq "0938eaff7545d7ba45fe7b866d60a209"
+    end
+
+    it "gives access to the ID" do
+      expect(@joe_doe.id).to eq "8765"
+    end
+
+    it "gives access to the address" do
+      expect(@joe_doe.address).to eq @@addr_1
+    end
+
+    it "gives access to the shipping address" do
+      expect(@joe_doe.shipping_address).to eq @@addr_2
+    end
+
+    it "avoid inspection of heavier attributes" do
+      expect(@joe_doe.inspect).to eq "#<Gnucash::Customer id: 8765, name: Joe Doe, guid: 0938eaff7545d7ba45fe7b866d60a209" +
+          ", address: " + @@addr_1 + 
+          ", shipping_address: " + @@addr_2 + ">"
+    end
+  end
+end

data/spec/gnucash/isin_spec.rb

@@ -0,0 +1,19 @@
+module Gnucash
+  describe ISIN do
+    describe ".normalize" do
+      it "strips spaces and hyphens and uppercases" do
+        expect(ISIN.normalize("us 03783-31005")).to eq("US0378331005")
+      end
+    end
+
+    describe ".valid_format?" do
+      it "accepts 12 alphanumeric characters" do
+        expect(ISIN.valid_format?("US0378331005")).to be true
+      end
+
+      it "rejects wrong length" do
+        expect(ISIN.valid_format?("US037833100")).to be false
+      end
+    end
+  end
+end

data/spec/gnucash/security_spec.rb

@@ -0,0 +1,85 @@
+module Gnucash
+  describe Security do
+    before(:all) do
+      @book = Gnucash.open("spec/books/pricedb-fixture.gnucash")
+      @security = @book.find_security("TEST", "STK")
+    end
+
+    it "loads price rows from the fixture" do
+      expect(@book.price_rows.size).to eq(4)
+    end
+
+    it "lists securities from the price database" do
+      expect(@book.securities.size).to eq(2)
+      ids = @book.securities.map(&:id).sort
+      expect(ids).to eq(%w[ESFUND STK])
+    end
+
+    it "returns nil when the commodity is not priced" do
+      expect(@book.find_security("NONE", "X")).to be_nil
+    end
+
+    describe "ISIN" do
+      it "exposes isin from cmdty:xcode" do
+        expect(@security.isin).to eq("US0378331005")
+      end
+
+      it "exposes isin from commodity slots" do
+        s = @book.find_security("TEST", "ESFUND")
+        expect(s.isin).to eq("ES0105046009")
+      end
+
+      it "finds security by ISIN ignoring case and spaces" do
+        found = @book.find_security_by_isin("us 03783-31005")
+        expect(found.id).to eq("STK")
+        expect(@book.find_security_by_isin("ES0105046009").id).to eq("ESFUND")
+      end
+
+      it "returns nil when ISIN is unknown or commodity not priced" do
+        expect(@book.find_security_by_isin("DE0000000000")).to be_nil
+      end
+    end
+
+    it "supports light inspect on security and quote" do
+      expect(@security.inspect).to include("TEST", "STK", "US0378331005")
+      q = @security.value_on(Date.new(2020, 6, 1))
+      expect(q.inspect).to include("currency_id", "USD")
+    end
+
+    describe "#value_on" do
+      it "returns nil when the date is before the first quote" do
+        expect(@security.value_on(Date.new(2019, 12, 31))).to be_nil
+      end
+
+      it "returns the most recent quote on or before the date" do
+        q = @security.value_on(Date.new(2020, 3, 15))
+        expect(q.value).to eq(Value.new("10000/100"))
+        expect(q.date).to eq(Date.new(2020, 1, 1))
+
+        q2 = @security.value_on(Date.new(2020, 6, 1))
+        expect(q2.value).to eq(Value.new("15000/100"))
+        expect(q2.date).to eq(Date.new(2020, 6, 1))
+
+        q3 = @security.value_on("2020-12-31")
+        expect(q3.date).to eq(Date.new(2020, 6, 1))
+        expect(q3.value).to eq(Value.new("15000/100"))
+      end
+
+      it "accepts an explicit quote currency" do
+        q = @security.value_on(
+          Date.new(2020, 12, 31),
+          currency_space: "CURRENCY",
+          currency_id: "USD"
+        )
+        expect(q.value.to_f).to eq(150.0)
+        expect(q.date).to eq(Date.new(2020, 6, 1))
+      end
+
+      it "raises when only one currency keyword is given" do
+        expect {
+          @security.value_on(Date.new(2020, 1, 1), currency_space: "CURRENCY")
+        }.to raise_error(ArgumentError)
+      end
+    end
+  end
+end

data/spec/gnucash/transaction_spec.rb

@@ -32,7 +32,7 @@ module Gnucash
       end
 
       it "avoid inspection of heavier attributes" do
-        expect(@book.transactions.first.inspect).to eq "#<Gnucash::Transaction id: 12efba30f14dc6cd4c3ffe2994de8284, date: 2007-01-01, description: Opening Balance, splits: [{:account=>#<Gnucash::Account id: 849f778995e8ecf8d4b96940afbbdcd7, name: Checking Account, description: Checking Account, type: BANK, placeholder: false, parent_id: c8e868259d70f6491f9e70ffdf6634ee>, :value=>#<Gnucash::Value val: 30000, div: 100>}, {:account=>#<Gnucash::Account id: 23bea6468ee7b4acb4db4b3f54598a71, name: Opening Balances, description: Opening Balances, type: EQUITY, placeholder: false, parent_id: ea7fe8b8abd560bef49826f68387ca78>, :value=>#<Gnucash::Value val: -30000, div: 100>}]>"
+        expect(@book.transactions.first.inspect).to match /#<Gnucash::Transaction.*12efba30f14dc6cd4c3ffe2994de8284.*2007-01-01.*Opening Balance/
       end
     end
   end

data/spec/spec_helper.rb

@@ -1,5 +1,9 @@
 require "simplecov"
 
-SimpleCov.start
+SimpleCov.start do
+  minimum_coverage 100
+  add_filter "/.bundle/"
+  add_filter "/spec/"
+end
 
 require "gnucash"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gnucash
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Josh Holtrop
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -103,6 +102,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".travis.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -114,16 +114,23 @@ files:
 - lib/gnucash/account.rb
 - lib/gnucash/account_transaction.rb
 - lib/gnucash/book.rb
+- lib/gnucash/customer.rb
+- lib/gnucash/isin.rb
+- lib/gnucash/security.rb
 - lib/gnucash/support.rb
 - lib/gnucash/support/light_inspect.rb
 - lib/gnucash/transaction.rb
 - lib/gnucash/value.rb
 - lib/gnucash/version.rb
+- spec/books/pricedb-fixture.gnucash
 - spec/books/sample-text.gnucash
 - spec/books/sample.gnucash
 - spec/gnucash/account_spec.rb
 - spec/gnucash/account_transaction_spec.rb
 - spec/gnucash/book_spec.rb
+- spec/gnucash/customer_spec.rb
+- spec/gnucash/isin_spec.rb
+- spec/gnucash/security_spec.rb
 - spec/gnucash/support/light_inspect_spec.rb
 - spec/gnucash/transaction_spec.rb
 - spec/gnucash/value_spec.rb
@@ -133,7 +140,6 @@ homepage: https://github.com/holtrop/ruby-gnucash
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -148,17 +154,19 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
-signing_key: 
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Extract data from XML GnuCash data files
 test_files:
+- spec/books/pricedb-fixture.gnucash
 - spec/books/sample-text.gnucash
 - spec/books/sample.gnucash
 - spec/gnucash/account_spec.rb
 - spec/gnucash/account_transaction_spec.rb
 - spec/gnucash/book_spec.rb
+- spec/gnucash/customer_spec.rb
+- spec/gnucash/isin_spec.rb
+- spec/gnucash/security_spec.rb
 - spec/gnucash/support/light_inspect_spec.rb
 - spec/gnucash/transaction_spec.rb
 - spec/gnucash/value_spec.rb