rvgp 0.3.2

data/lib/rvgp/journal/currency.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RVGP
+  class Journal
+    # This abstraction offers a repository by which currencies can be defined,
+    # and by which their rules can be queried. An instance of this class, is an
+    # entry in the currency table, that we support. The default currencies that RVGP
+    # supports can be found in:
+    # {https://github.com/brighton36/rvgp/blob/main/resources/iso-4217-currencies.json iso-4217-currencies.json}
+    # , and this file is typically loaded during rvgp initialization.
+    #
+    # Here's what an entry in that file, looks like:
+    # ```
+    #  {
+    #    "Entity":"UNITED STATES",
+    #    "Currency":"US Dollar",
+    #    "Alphabetic Code":"USD",
+    #    "Numeric Code":"840",
+    #    "Minor unit":"2",
+    #    "Symbol":"$"
+    #  },
+    # ```
+    #
+    # PR's welcome, if you have additions to offer on this file.
+    #
+    # This class is used in several places throughout the codebase, and provides
+    # a standard set of interfaces for working with this global repository of
+    # currency properties.
+    # @attr_reader [String] entity The name of the institution to which this currency belongs. For some reason
+    #                              (I believe this is part of the ISO-4217 standard) this string is capitalized
+    #                              (ie, 'UNITED STATES')
+    # @attr_reader [String] currency A colloquial name for this currency (ie. "US Dollar")
+    # @attr_reader [String] alphabetic_code The shorthand, three digit letter code for this currency (ie 'USD')
+    # @attr_reader [Integer] numeric_code The ISO 4217 code for this currency 840
+    # @attr_reader [Integer] minor_unit The default precision for this currency, as would be typically implied.
+    #                                   For the case of USD, this would be 2. Indicating two decimal digits for a
+    #                                   default transcription of a USD amount.
+    # @attr_reader [String] symbol The shorthand, (typically) one character symbol code for this currency (ie '$')
+    class Currency
+      # Raised on a parse error
+      class Error < StandardError; end
+
+      attr_reader :entity, :currency, :alphabetic_code, :numeric_code, :minor_unit, :symbol
+
+      # Create a Currency commodity, from constituent parts
+      # @param [Hash] opts The parts of this complex commodity
+      # @option opts [String] entity see {Currency#entity}
+      # @option opts [String] currency see {Currency#currency}
+      # @option opts [String] alphabetic_code see {Currency#alphabetic_code}
+      # @option opts [Integer] numeric_code see {Currency#numeric_code}
+      # @option opts [Integer] minor_unit see {Currency#minor_unit}
+      # @option opts [String] symbol see {Currency#symbol}
+      def initialize(opts = {})
+        @entity = opts[:entity]
+        @currency = opts[:currency]
+        @alphabetic_code = opts[:alphabetic_code]
+        @numeric_code = opts[:numeric_code].to_i
+        @minor_unit = opts[:minor_unit].to_i
+        @symbol = opts[:symbol]
+        raise Error, format('Unabled to parse config entry: "%s"', inspect) unless valid?
+      end
+
+      # Indicates whether or not this instance contains all required fields
+      # @return [TrueClass,FalseClass] whether or not we're valid
+      def valid?
+        [entity, currency, alphabetic_code, numeric_code, minor_unit].all?
+      end
+
+      # Create a new commodity, from this currency, with the provided quantity
+      # @param [Integer] quantity The quantity component, of the newly created commodity
+      # @return [RVGP::Journal::Commodity]
+      def to_commodity(quantity)
+        RVGP::Journal::Commodity.new symbol || alphabetic_code, alphabetic_code, quantity, minor_unit
+      end
+
+      # Load and return a parsed RVGP::Journal::Currency, out of the provided
+      # {https://github.com/brighton36/rvgp/blob/main/resources/iso-4217-currencies.json iso-4217-currencies.json}
+      # file.
+      # @param [String] str Either a three digit :alphabetic_code, or a single digit :symbol
+      # @return [RVGP::Journal::Currency] the requested currency, with its default parameters
+      def self.from_code_or_symbol(str)
+        @currencies ||= begin
+          unless currencies_config && File.readable?(currencies_config)
+            raise StandardError, 'Missing currency config file'
+          end
+
+          JSON.parse(File.read(currencies_config)).map do |c|
+            new(c.transform_keys { |k| k.downcase.tr(' ', '_').to_sym })
+          end
+        end
+        @currencies.find { |c| (c.alphabetic_code && c.alphabetic_code == str) || (c.symbol && c.symbol == str) }
+      end
+
+      class << self
+        attr_accessor :currencies_config
+      end
+    end
+  end
+end

data/lib/rvgp/journal/journal.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module RVGP
+  # This class parses a pta journal, and offers that journal in its constitutent
+  # parts. See the {Journal.parse} for the typical entry point, into this class.
+  # This class itself, really only offers the one method, .parse, to parse a pta
+  # journal's contents. Most of the functionality in this class, is provided
+  # by the classes contained within it.
+  # @attr_reader [Array<RVGP::Journal::Posting>] postings The postings that were encountered in this journal
+  class Journal
+    # @!visibility private
+    MSG_MISSING_POSTING_SEPARATOR = 'Missing a blank line before line %d: %s'
+    # @!visibility private
+    MSG_UNRECOGNIZED_HEADER = 'Unrecognized posting header at line %d: %s'
+    # @!visibility private
+    MSG_INVALID_DATE = 'Invalid posting date at line %d: %s'
+    # @!visibility private
+    MSG_UNEXPECTED_TRANSFER = 'Unexpected transfer at line %d: %s'
+    # @!visibility private
+    MSG_UNEXPECTED_TAG = 'Unexpected tag at line %d: %s'
+    # @!visibility private
+    MSG_UNEXPECTED_LINE = 'Unexpected at line %d: %s'
+    # @!visibility private
+    MSG_INVALID_TRANSFER_COMMODITY = 'Unparseable or unimplemented commodity-parse in transfer at line %d: %s'
+    # @!visibility private
+    MSG_INVALID_POSTING = 'Invalid Posting at separator line %d: %s'
+    # @!visibility private
+    MSG_TOO_MANY_SEMICOLONS = 'Too many semicolons at line %d. Are these comments? %s'
+    # @!visibility private
+    MSG_UNPARSEABLE_TRANSFER = 'Something is wrong with this transfer at line %d: %s'
+
+    attr :postings
+
+    # Declare and initialize this Journal.
+    # @param [Array[RVGP::Journal::Posting]] postings An array of postings that this instance represents
+    def initialize(postings)
+      @postings = postings
+    end
+
+    # Unparse this journal, and return the parsed objects in their serialized form.
+    # @return [String] A pta journal. Presumably, the same one we were initialized from
+    def to_s
+      @postings.map(&:to_ledger).join "\n\n"
+    end
+
+    # Given a pta journal, already read from the filesystem, return a parsed representation of its contents.
+    # @param [String] contents A pta journal, as a string
+    # @return [RVGP::Journal] The parsed representation of the provided string
+    def self.parse(contents)
+      postings = []
+
+      posting = nil
+      cite = nil
+      contents.lines.each_with_index do |line, i|
+        line_number = i + 1
+        cite = [line_number, line.inspect] # in case we run into an error
+        line_comment = nil
+
+        # Here, we separate the line into non-comment lvalue and comment rvalue:
+        # NOTE: We're not supporting escaped semicolons, at this time
+        case line
+        when /\A.*[^\\];.*[^\\];.*\Z/
+          raise StandardError, format(MSG_TOO_MANY_SEMICOLONS, cite)
+        when /\A( *.*?) *;[ \t]*(.*)\Z/
+          line = ::Regexp.last_match(1)
+          line_comment = ::Regexp.last_match(2)
+        end
+
+        # This case parses anything to the left of a comment:
+        case line
+        when /\A([^ \n].*)\Z/
+          # This is a post declaration line
+          raise StandardError, MSG_MISSING_POSTING_SEPARATOR % cite if posting
+          unless %r{\A(\d{4})[/-](\d{2})[/-](\d{2}) +(.+?) *\Z}.match ::Regexp.last_match(1)
+            raise StandardError, MSG_UNRECOGNIZED_HEADER % cite
+          end
+
+          begin
+            date = Date.new ::Regexp.last_match(1).to_i, ::Regexp.last_match(2).to_i, ::Regexp.last_match(3).to_i
+          rescue Date::Error
+            raise StandardError, MSG_INVALID_DATE % cite
+          end
+
+          posting = Posting.new date, ::Regexp.last_match(4), line_number: line_number
+        when /\A[ \t]+([^ ].+)\Z/
+          # This is a transfer line, to be appended to the current posting
+          raise StandardError, MSG_UNEXPECTED_TRANSFER % cite unless posting
+
+          # NOTE: We chose 2 or more spaces as the separator between
+          # the account and the commodity, mostly because this was the smallest
+          # we could find in the official ledger documentation
+          unless /\A(.+?)(?: {2,}([^ ].+)| *)\Z/.match ::Regexp.last_match(1)
+            raise StandardError, format(MSG_UNPARSEABLE_TRANSFER, cite)
+          end
+
+          begin
+            posting.append_transfer ::Regexp.last_match(1), ::Regexp.last_match(2)
+          rescue RVGP::Journal::Commodity::Error
+            raise StandardError, MSG_INVALID_TRANSFER_COMMODITY % cite
+          end
+        when /\A[ \t]*\Z/
+          if line_comment.nil? && posting
+            unless posting.valid?
+              posting.transfers.each do |transfer|
+                puts format('  - Not valid. account %<acct>s commodity: %<commodity>s complex_commodity: %<complex>s',
+                            acct: transfer.account.inspect,
+                            commodity: transfer.commodity.inspect,
+                            complex: transfer.complex_commodity.inspect)
+              end
+            end
+
+            raise StandardError, MSG_INVALID_POSTING % cite unless posting.valid?
+
+            # This is a blank line
+            postings << posting
+            posting = nil
+          end
+        else
+          raise StandardError, MSG_UNEXPECTED_LINE % cite unless posting
+        end
+
+        next unless line_comment && posting
+
+        tags = line_comment.scan(/(?:[^ ]+: *[^,]*|:[^ \t]+:)/).map do |declaration|
+          /\A:?(.+):\Z/.match(declaration) ? ::Regexp.last_match(1).split(':') : declaration
+        end.flatten
+
+        tags.each { |tag| posting.append_tag tag }
+      end
+
+      # The last line could be \n, which, makes this unnecessary
+      if posting
+        raise StandardError, MSG_INVALID_POSTING % cite unless posting.valid?
+
+        postings << posting
+      end
+
+      new postings
+    end
+  end
+end

data/lib/rvgp/journal/posting.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module RVGP
+  class Journal
+    # This class represents a single posting, in a PTA journal. A posting is
+    # typically of the following form:
+    # ```
+    # 2020-02-10 Frozen Chicken from the Local Supermarket
+    #   Personal:Expenses:Food:Groceries    $ 50.00
+    #   Cash
+    # ```
+    # This is a simple example. There are a good number of permutations under which
+    # posting components s appear. Nonetheless, a posting is typically comprised of
+    # a date, a description, and a number of RVGP::Journal::Posting::Transfer lines,
+    # indented below these fields. This object represents the parsed format,
+    # of a post, traveling around the RVGP codebase.
+    # @attr_reader [Integer] line_number The line number, in a journal, that this posting was declared at.
+    # @attr_reader [Date] date The date this posting occurred
+    # @attr_reader [String] description The first line of this posting
+    # @attr_reader [Array<RVGP::Journal::Posting::Transfer>] transfers An array of transfers, that apply to this
+    #                                                                  posting.
+    # @attr_reader [Array<RVGP::Journal::Posting::Tag>] tags An array of tags, that apply to this posting.
+    class Posting
+      # This class represents an indented 'transfer' line, within a posting.
+      # Typically, such lines takes the form of :
+      # ```
+      #   Personal:Expenses:Food:Groceries    $ 50.00
+      # ```
+      # This class offers few functions, and mostly just offers its attributes. Note
+      # that there should be no reason a posting ever has both is commodity and complex_commodity
+      # set. Either one or the other should exist, for any given Transfer.
+      # @attr_reader [String] account The account this posting is crediting or debiting
+      # @attr_reader [String] commodity The amount (expressed in commodity terms) being credit/debited
+      # @attr_reader [String] complex_commodity The amount (expressed in complex commodity terms) being credit/debited
+      # @attr_reader [Array<RVGP::Journal::Posting::Tag>] tags An array of tags, that apply to this posting.
+      class Transfer
+        attr :account, :commodity, :complex_commodity, :tags
+
+        # Create a complex commodity, from constituent parts
+        # @param [String] account see {Transfer#account}
+        # @param [Hash] opts Additional parts of this Transfer
+        # @option opts [String] commodity see {Transfer#commodity}
+        # @option opts [String] complex_commodity see {Transfer#complex_commodity}
+        # @option opts [Array<RVGP::Journal::Posting::Tag>] tags ([]) see {Transfer#tags}
+        def initialize(account, opts = {})
+          @account = account
+          @commodity = opts[:commodity]
+          @complex_commodity = opts[:complex_commodity]
+          @tags = opts[:tags] || []
+        end
+      end
+
+      # This class represents a key, or key/value tag, within a journal.
+      # These tags can be affixed to transfers and postings. And, are pretty
+      # simple, comprising of a key and optionally, a value.
+      # @attr_reader [String] key The label of this tag
+      # @attr_reader [String] value The value of this tag
+      class Tag
+        attr :key, :value
+
+        # Create a tag from it's constituent parts
+        # @param [String] key see {Tag#key}
+        # @param [String] value (nil) see {Tag#value}
+        def initialize(key, value = nil)
+          @key = key
+          @value = value
+        end
+
+        # Serialize this tag, to a string
+        # @return [String] the tag, as would be found in a pta journal
+        def to_s
+          value ? [key, value].join(': ') : key
+        end
+
+        # Parse the provided string, into a Tag object
+        # @param [String] str The tag, possibly a key/value pair, as would be found in a pta journal
+        # @return [Tag] A parsed representation of this tag
+        def self.from_s(str)
+          /\A(.+) *: *(.+)\Z/.match(str) ? Tag.new(::Regexp.last_match(1), ::Regexp.last_match(2)) : Tag.new(str)
+        end
+      end
+
+      attr :line_number, :date, :description, :transfers, :tags
+
+      # Create a posting, from constituent parts
+      # @param [Date] date see {Posting#date}
+      # @param [String] description see {Posting#description}
+      # @param [Hash] opts Additional parts of this Posting
+      # @option opts [Array<RVGP::Journal::Posting::Transfer>] transfers see {Posting#transfers}
+      # @option opts [Array<RVGP::Journal::Posting::Tag>] tags see {Posting#transfers}
+      def initialize(date, description, opts = {})
+        @line_number = opts[:line_number]
+        @date = date
+        @description = description
+        @transfers = opts.key?(:transfers) ? opts[:transfers] : []
+        @tags = opts.key?(:tags) ? opts[:tags] : []
+      end
+
+      # Indicates whether or not this instance contains all required fields
+      # @return [TrueClass,FalseClass] whether or not we're valid
+      def valid?
+        # Required fields:
+        [date, description, transfers, transfers.any? { |t| t.account && (t.commodity || t.complex_commodity) }].all?
+      end
+
+      # Serializes this posting into a string, in the form that would be found in a PTA journal
+      # @return [String] The PTA journal representation of this posting
+      def to_ledger
+        max_to_length = transfers.map do |transfer|
+          transfer.commodity || transfer.complex_commodity ? transfer.account.length : 0
+        end.max
+
+        lines = [[date, description].join(' ')]
+        lines.insert(lines.length > 1 ? -2 : 1, format('  ; %s', tags.join(', '))) if tags && !tags.empty?
+        lines += transfers.map do |transfer|
+          [
+            if transfer.commodity || transfer.complex_commodity
+              format("  %<account>-#{max_to_length}s    %<commodity>s",
+                     account: transfer.account,
+                     commodity: (transfer.commodity || transfer.complex_commodity).to_s)
+            else
+              format('  %s', transfer.account)
+            end,
+            transfer.tags && !transfer.tags.empty? ? transfer.tags.map { |tag| format('  ; %s', tag) } : nil
+          ].compact.flatten.join("\n")
+        end
+        lines.join("\n")
+      end
+
+      # The append_*() is really only intended to be called by the parser:
+      # @!visibility private
+      def append_transfer(account_part, commodity_part)
+        opts = {}
+        if commodity_part
+          # Let's see if it'll parse as a commodity:
+          begin
+            opts[:commodity] = RVGP::Journal::Commodity.from_s commodity_part
+          rescue RVGP::Journal::Commodity::UnimplementedError
+            # Then let's see if it parses as a commodity pair
+            opts[:complex_commodity] = RVGP::Journal::ComplexCommodity.from_s commodity_part
+          end
+        end
+
+        @transfers << Transfer.new(account_part, opts)
+      end
+
+      # This is really only intended to simpify the parser, we push this onto the
+      # bottom of whatever exists here
+      # @!visibility private
+      def append_tag(as_string)
+        tag = Tag.from_s as_string
+        (transfers.empty? ? tags : transfers.last.tags) << tag
+      end
+    end
+  end
+end

data/lib/rvgp/journal/pricer.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module RVGP
+  class Journal
+    # This class takes a value, denominated in one commodity, and returns the equivalent value, in another commodity.
+    # This process is also known as price (or currency) exchange. The basis for exchanges are rates, affixed to a
+    # date. These exchange rates are expected to be provided in the same format that ledger and hledger use. Here's an
+    # example:
+    # ```
+    #   P 2020-01-01 USD 0.893179 EUR
+    #   P 2020-02-01 EUR 1.109275 USD
+    #   P 2020-03-01 USD 0.907082 EUR
+    # ```
+    # It's typical for these exchange rates to exist in a project's journals/prices.db, but, the constructor to this
+    # class expects the contents of such a file, as a string. The conversion process is fairly smart, in that a
+    # specified rate, works 'both ways'. Meaning that, a price query will resolve based on any stipulation of
+    # equivalence between commodities. And, the matter of which code is to the left, or right, of a ratio, is
+    # undifferentiated from the inverse arrangement. This behavior, and most all others in this class, mimics the way
+    # ledger works, wrt price conversion.
+    # @attr_reader [Array<Pricer::Price>] prices_db A parsed representation of the prices file, based on what was passed
+    #                                               in the constructor.
+    class Pricer
+      # This class represents a line, parsed from a prices journal. And, an instance of this class
+      # represents an exchange rate.
+      # This class contains a datetime, an amount, and two codes.
+      # @attr_reader [Time] at The time at which this exchange rate was declared in effect
+      # @attr_reader [String] lcode The character alphabetic code, or symbol for the left side of the exchange pair
+      # @attr_reader [String] rcode The character alphabetic code, or symbol for the right side of the exchange pair.
+      #                             This code should (always?) match the amount.code
+      # @attr_reader [RVGP::Journal::Commodity] amount The ratio of lcode, to rcode. Aka: The exchange rate.
+      class Price < RVGP::Base::Reader
+        readers :at, :lcode, :rcode, :amount
+
+        # A shortcut, to {RVGP::Journal::Pricer::Price.to_key}, if a caller is looking to use this price in a Hash
+        # @return [String] A code, intended for use in Hash table lookups
+        def to_key
+          self.class.to_key lcode, rcode
+        end
+
+        # Create a string, for this pair, that is unique to the codes, regardless of the order in which they're
+        # provided. This enables us to assert bidirectionality in the lookup of prices.
+        # @param [String] code1 A three character alphabetic currency code
+        # @param [String] code2 A three character alphabetic currency code
+        # @return [String] A code, intended for use in Hash table lookups
+        def self.to_key(code1, code2)
+          [code1, code2].sort.join(' ')
+        end
+      end
+
+      # This Error is raised when we're unable to perform a price conversion
+      class NoPriceError < StandardError; end
+
+      # @!visibility private
+      MSG_UNEXPECTED_LINE = 'Unexpected at line %d: %s'
+      # @!visibility private
+      MSG_INVALID_PRICE = 'Missing one or more required elements at line %d: %s'
+      # @!visibility private
+      MSG_INVALID_DATETIME = 'Invalid datetime at line %d: %s'
+
+      attr_reader :prices_db
+
+      # Create a Price exchanger, given a prices database
+      # @param [String] prices_content The contents of a prices.db file, defining the exchange rates.
+      # @param [Hash] opts Optional features
+      # @option opts [Proc<Time,String,String>] before_price_add
+      #   This option calls the provided Proc with the parameters offered to {#add}.
+      #   Mostly, this exists to solve a very specific bug that occurs under certain
+      #   conditions, in projects where currencies are automatically converted by
+      #   ledger. If you see the I18n.t(error.missing_entry_in_prices_db) message
+      #   in your build log, scrolling by - you should almost certainly add that entry
+      #   to your project's prices.db. And this option is how that notice was fired.
+      #
+      #   This option 'addresses' a pernicious bug that will likely affect you. And
+      #   I don't have an easy solution, as, I sort of blame ledger for this.
+      #   The problem will manifest itself in the form of grids that output
+      #   differently, depending on what grids were built in the process.
+      #
+      #   So, If, say, we're only building 2022 grids. But, a clean build
+      #   would have built 2021 grids, before instigating the 2022 grid
+      #   build - then, we would see different outputs in the 2022-only build.
+      #
+      #   The reason for this, is that there doesn't appear to be any way of
+      #   accounting for all historical currency conversions in ledger's output.
+      #   The data coming out of ledger only includes currency conversions in
+      #   the output date range. This will sometimes cause weird discrepencies
+      #   in the totals between a 2021-2022 run, vs a 2022-only run.
+      #
+      #   The only solution I could think of, at this time, was to burp on
+      #   any occurence, where, a conversion, wasn't already in the prices.db
+      #   That way, an operator (you) can simply add the outputted burp, into
+      #   the prices.db file. This will ensure consistency in all grids,
+      #   regardless of the ranges you run them.
+      #
+      #   NOTE: This feature is currently unimplemnted in hledger. And, I have no
+      #   solution planned there at this time. Probably, that means you should
+      #   only use ledger in your project, if you're working with multiple currencies,
+      #   and don't want to rebuild your project from clean, every time you make
+      #   non-trivial changes.
+      #
+      #   If you have a better idea, or some other way to ensure consistency
+      #   (A SystemValidation?)... PR's welcome!
+      def initialize(prices_content = nil, opts = {})
+        @prices_db = prices_content ? parse(prices_content) : {}
+        @before_price_add = opts[:before_price_add] if opts[:before_price_add]
+      end
+
+      # Retrieve an exchange rate, for a given commodity, to another commodity, at a given time.
+      # @param [Time] at The time at which you want to query for an exchange rate. The most-recently-availble and
+      #                  eligible entry, before this parameter, will be selected.
+      # @param [String] from The three character alphabetic currency code, of the source currency
+      # @param [String] to The three character alphabetic currency code, of the destination currency
+      # @return [RVGP::Journal::Commodity] An exchange rate, denominated in units of the :to currency
+      def price(at, from, to)
+        no_price! at, from, to if prices_db.nil? || prices_db.empty?
+
+        lcurrency = RVGP::Journal::Currency.from_code_or_symbol from
+        from_alpha = lcurrency ? lcurrency.alphabetic_code : from
+
+        rcurrency = RVGP::Journal::Currency.from_code_or_symbol to
+        to_alpha = rcurrency ? rcurrency.alphabetic_code : to
+
+        prices = prices_db[Price.to_key(from_alpha, to_alpha)]
+
+        no_price! at, from, to unless prices && !prices.empty? && at >= prices.first.at
+
+        price = nil
+
+        1.upto(prices.length - 1) do |i|
+          if prices[i].at > at
+            price = prices[i - 1]
+            break
+          end
+        end
+
+        price = prices.last if price.nil? && prices.last.at <= at
+
+        no_price! at, from, to unless price
+
+        # OK, so we have the price record that applies. But, it may need to be
+        # inverted.
+        if price.lcode == from_alpha && price.amount.alphabetic_code == to_alpha
+          price.amount
+        else
+          RVGP::Journal::Commodity.from_symbol_and_amount to,
+                                                          (1 / price.amount.quantity_as_bigdecimal).round(17).to_s('F')
+        end
+      end
+
+      # Convert the provided commodity, to another commodity, based on the rate at a given time.
+      # @param [Time] at The time at which you want to query for an exchange rate. The most-recently-availble and
+      #                  eligible entry, before this parameter, will be selected.
+      # @param [RVGP::Journal::Commodity] from_commodity The commodity you wish to convert
+      # @param [String] to_code_or_symbol The three character alphabetic currency code, or symbol, of the destination
+      #                                   currency you wish to convert to.
+      # @return [RVGP::Journal::Commodity] The resulting commodity, in units of :to_code_or_symbol
+      def convert(at, from_commodity, to_code_or_symbol)
+        rate = price at, from_commodity.code, to_code_or_symbol
+
+        RVGP::Journal::Commodity.from_symbol_and_amount(
+          to_code_or_symbol,
+          (from_commodity.quantity_as_bigdecimal * rate.quantity_as_bigdecimal).to_s('F')
+        )
+      end
+
+      # Add a conversion rate to the database
+      # @param [Time] time The time at which this rate was discovered
+      # @param [String] from_alpha The three character alphabetic currency code, of the source currency
+      # @param [RVGP::Journal::Currency] to A commodity, expressing the quantity and commodity, that one
+      #                                    unit of :from_alpha converts to
+      # @return [void]
+      def add(time, from_alpha, to)
+        lcurrency = RVGP::Journal::Currency.from_code_or_symbol from_alpha
+
+        price = Price.new time.to_time,
+                          lcurrency ? lcurrency.alphabetic_code : from_alpha,
+                          to.alphabetic_code || to.code,
+                          to
+
+        key = price.to_key
+        if @prices_db.key? key
+          i = @prices_db[key].find_index { |p| p.at > price.at.to_time }
+
+          # There's no need to add the price, if there's no difference between
+          # what we're adding, and what would have been found, otherwise
+          price_before_add = i ? @prices_db[key][i - 1] : @prices_db[key].last
+
+          if price_before_add.amount != price.amount
+            @before_price_add&.call time, from_alpha, to
+
+            if i
+              @prices_db[key].insert i, price
+            else
+              @prices_db[key] << price
+            end
+          end
+
+        else
+          @before_price_add&.call time, from_alpha, to
+          @prices_db[key] = [price]
+        end
+
+        price
+      end
+
+      private
+
+      def parse(contents)
+        posting = nil
+        parsed_lines = contents.lines.map.with_index do |line, i|
+          cite = [i + 1, line.inspect] # in case we run into an error
+
+          # Remove any comments from the line:
+          line = ::Regexp.last_match(1) if /(.*) *;.*/.match line
+
+          case line
+          when %r{\AP[ ]+
+            # Date:
+            (\d{4}[\-/]\d{1,2}[\-/]\d{1,2})
+            # Time:
+            (?:[ ]+(\d{1,2}:\d{1,2}:\d{1,2})|)
+            # Symbol:
+            [ ]+([^ ]+)
+            # Commodity:
+            [ ]+(.+?)
+            [ ]*\Z}x
+
+            # NOTE: This defaults to the local time zone. Not sure if we care.
+            begin
+              time = Time.new(
+                *[::Regexp.last_match(1).tr('/', '-').split('-').map(&:to_i),
+                  ::Regexp.last_match(2) ? ::Regexp.last_match(2).split(':').map(&:to_i) : nil].flatten.compact
+              )
+            rescue ArgumentError
+              raise StandardError, MSG_INVALID_DATETIME % cite
+            end
+
+            lcurrency = RVGP::Journal::Currency.from_code_or_symbol ::Regexp.last_match(3)
+            amount = ::Regexp.last_match(4).to_commodity
+
+            Price.new time,
+                      lcurrency ? lcurrency.alphabetic_code : ::Regexp.last_match(3),
+                      amount.alphabetic_code || amount.code, amount
+
+          when /\A *\Z/
+            # Blank Line
+            nil
+          else
+            raise StandardError, MSG_UNEXPECTED_LINE % cite unless posting
+          end
+        end.compact.sort_by(&:at)
+
+        parsed_lines.each_with_object({}) do |price, sum|
+          key = price.to_key
+          sum[key] = [] unless sum.key? key
+          sum[key] << price
+          sum
+        end
+      end
+
+      def no_price!(at, from, to)
+        raise NoPriceError, format('Unable to convert %<from>s to %<to>s at %<at>s', from: from, to: to, at: at.to_s)
+      end
+    end
+  end
+end