rvgp 0.3.2

data/lib/rvgp/pta/ledger.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'open3'
+require 'nokogiri'
+
+require_relative '../pta'
+require_relative '../journal/pricer'
+
+module RVGP
+  class Pta
+    # A plain text accounting adapter implementation, for the 'ledger' pta command.
+    # This class conforms the ledger query, and output, interfaces in a ruby-like
+    # syntax, and with structured ruby objects as outputs.
+    #
+    # For a more detailed example of these queries in action, take a look at the
+    # {https://github.com/brighton36/rra/blob/main/test/test_pta_adapter.rb test/test_pta_adapter.rb}
+    class Ledger < RVGP::Pta
+      # @!visibility private
+      BIN_PATH = '/usr/bin/ledger'
+
+      # This module contains intermediary parsing objects, used to represent the output of ledger in
+      # a structured and hierarchial format.
+      module Output
+        # This is a base class from which RVGP::Pta::Ledger's outputs inherit. It mostly just provides
+        # helpers for dealing with the xml output that ledger produces.
+        # @attr_reader [Nokogiri::XML] doc The document that was produced by ledger, to construct this object
+        # @attr_reader [Array<RVGP::Pta::Ledger::Output::XmlBase::Commodity>] commodities The exchange rates that
+        #              were reportedly encountered, in the output of ledger.
+        # @attr_reader [RVGP::Journal::Pricer] pricer A price exchanger, to use for any currency exchange lookups
+        class XmlBase
+          # A commodity, as defined by ledger's xml meta-output. This is largely for the purpose of
+          # tracking exchange rates that were automatically deduced by ledger during the parsing
+          # of a journal. And, which, are stored in the {RVGP::Pta:::Ledger::Output::XmlBase#commodities}
+          # collection. hledger does not have this feature.
+          #
+          # @attr_reader [String] symbol A three letter currency code
+          # @attr_reader [Time] date The datetime when this commodity was declared or deduced
+          # @attr_reader [RVGP::Journal::Commodity] price The exchange price
+          class Commodity < RVGP::Base::Reader
+            readers :symbol, :date, :price
+          end
+
+          attr_reader :doc, :commodities, :pricer
+
+          # Declare the class, and initialize with the relevant options
+          # @param [String] xml The xml document this object is composed from
+          # @param [Hash] options Additional options
+          # @option options [RVGP::Journal::Pricer] :pricer see {RVGP::Pta::Ledger::Output::XmlBase#pricer}
+          def initialize(xml, options)
+            @doc = Nokogiri::XML xml, &:noblanks
+            @pricer = options[:pricer] || RVGP::Journal::Pricer.new
+
+            @commodities = doc.search('//commodities//commodity[annotation]').collect do |xcommodity|
+              next unless ['symbol', 'date', 'price', 'price/commodity/symbol',
+                           'price/quantity'].all? { |path| xcommodity.at(path) }
+
+              symbol = xcommodity.at('symbol').content
+              date = Date.strptime(xcommodity.at('date').content, '%Y/%m/%d')
+              commodity = RVGP::Journal::Commodity.from_symbol_and_amount(
+                xcommodity.at('price/commodity/symbol').content,
+                xcommodity.at('price/quantity').content
+              )
+
+              @pricer.add date.to_time, symbol, commodity
+              Commodity.new symbol, date, commodity
+            end
+          end
+        end
+
+        # An xml parser, to structure the output of balance queries to ledger. This object exists, as
+        # a return value, from the {RVGP::Pta::Ledger#balance} method
+        # @attr_reader [RVGP::Pta::BalanceAccount] accounts The accounts, and their components, that were
+        #                                                  returned by ledger.
+        class Balance < XmlBase
+          attr_reader :accounts
+
+          # Declare the registry, and initialize with the relevant options
+          # @param [String] xml see {RVGP::Pta::Ledger::Output::XmlBase#initialize}
+          # @param [Hash] options see {RVGP::Pta::Ledger::Output::XmlBase#initialize}
+          def initialize(xml, options = {})
+            super xml, options
+
+            # NOTE: Our output matches the --flat output, of ledger. We mostly do this
+            # because hledger defaults to the same output. It might cause some
+            # expectations to fail though, if you're comparing our balance return,
+            # to the cli output of balance
+            #
+            # Bear in mind that this query is slightly odd, in that account is nested
+            # So, I stipulate that we are at the end of a nest "not account" and
+            # have children "*"
+            xaccounts = doc.xpath('//accounts//account[not(account[*]) and *]')
+
+            if xaccounts
+              @accounts = xaccounts.collect do |xaccount|
+                fullname = xaccount.at('fullname')&.content
+
+                next unless fullname
+
+                RVGP::Pta::BalanceAccount.new(
+                  fullname,
+                  xaccount.xpath('account-amount/amount|account-amount/*/amount').collect do |amount|
+                    commodity = RVGP::Journal::Commodity.from_symbol_and_amount(
+                      amount.at('symbol').content, amount.at('quantity').content
+                    )
+                    commodity if commodity.quantity != 0
+                  end.compact
+                )
+              end.compact
+            end
+          end
+        end
+
+        # An xml parser, to structure the output of register queries to ledger. This object exists, as
+        # a return value, from the {RVGP::Pta::Ledger#register} method
+        # @attr_reader [RVGP::Pta::RegisterTransaction] transactions The transactions, and their components, that were
+        #                                                           returned by ledger.
+        class Register < XmlBase
+          attr_reader :transactions
+
+          # Declare the registry, and initialize with the relevant options
+          # @param [String] xml see {RVGP::Pta::Ledger::Output::XmlBase#initialize}
+          # @param [Hash] options see {RVGP::Pta::Ledger::Output::XmlBase#initialize}
+          def initialize(xml, options = {})
+            super xml, options
+
+            @transactions = doc.xpath('//transactions/transaction').collect do |xt|
+              date = Date.strptime(xt.at('date').content, '%Y/%m/%d')
+
+              RVGP::Pta::RegisterTransaction.new(
+                date,
+                xt.at('payee').content,
+                xt.xpath('postings/posting').collect do |xp|
+                  amounts, totals = *%w[post-amount total].collect do |attr|
+                    xp.at(attr).search('amount').collect do |xa|
+                      RVGP::Journal::Commodity.from_symbol_and_amount(
+                        xa.at('commodity/symbol')&.content,
+                        xa.at('quantity').content
+                      )
+                    end
+                  end
+
+                  if options[:empty] == false
+                    amounts.reject! { |amnt| amnt.quantity.zero? }
+                    totals.reject! { |amnt| amnt.quantity.zero? }
+
+                    next if [amounts, totals].all?(&:empty?)
+                  end
+
+                  account = xp.at('account/name').content
+
+                  # This phenomenon of '<None>' and '<total>', seems to only happen
+                  # when the :empty parameter is passed.
+                  if options[:translate_meta_accounts]
+                    case account
+                    when '<None>' then account = nil
+                    when '<Total>' then account = :total
+                    end
+                  end
+
+                  RVGP::Pta::RegisterPosting.new(
+                    account,
+                    amounts,
+                    totals,
+                    xp.search('metadata/value').to_h { |xvalue| [xvalue['key'], xvalue.content] },
+                    pricer: pricer,
+                    # This sets our date to the end -of the month, if this is a
+                    # monthly query
+                    price_date: options[:monthly] ? Date.new(date.year, date.month, -1) : date
+                  )
+                end.compact
+              )
+            end
+          end
+        end
+      end
+
+      # Return the tags that were found, given the specified journal path, and filters.
+      #
+      # The behavior between hledger and ledger are rather different here. Ledger has a slightly different
+      # featureset than HLedger, regarding tags. As such, while the return format is the same between implementations.
+      # The results for a given query won't be identical between pta implementations. Mostly, these results differ
+      # when a \\{values: true} option is supplied. In that case, ledger will return tags in a series of keys and
+      # values, separated by a colon, one per line. hledger, in that case, will only return the tag values themselves,
+      # without denotating their key.
+      #
+      # This method will simply parse the output of ledger, and return that.
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details
+      # @return [Array<String>] An array of the lines returned by ledger, split into strings. In most cases, this
+      #                         could also be described as simply 'an array of the filtered tags'.
+      def tags(*args)
+        args, opts = args_and_opts(*args)
+
+        # The first arg, is the tag whose values we want. This is how hledger does it, and
+        # we just copy that
+        for_tag = args.shift unless args.empty?
+
+        tags = command('tags', *args, opts).split("\n")
+
+        for_tag ? tags.map { |tag| ::Regexp.last_match(1) if /\A#{for_tag}: *(.*)/.match tag }.compact : tags
+      end
+
+      # Return the files that were encountered, when parsing the provided arguments.
+      # The output of this method should be identical, regardless of the Pta Adapter that resolves the request.
+      #
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details
+      # @return [Array<String>] An array of paths that were referenced when fetching data in provided arguments.
+      def files(*args)
+        args, opts = args_and_opts(*args)
+
+        # TODO: This should get its own error class...
+        raise StandardError, "Unexpected argument(s) : #{args.inspect}" unless args.empty?
+
+        stats(*args, opts)['Files these postings came from'].tap do |ret|
+          ret.unshift opts[:file] if opts.key?(:file) && !ret.include?(opts[:file])
+        end
+      end
+
+      # Returns the newest transaction, retured in set of transactions filtered with the provided arguments.
+      # This method is mostly a wrapper around \\{#register} with the \\{tail: 1} option passed to that method. This
+      # method may produce counterintutive results, if you override the sort: option.
+      #
+      # NOTE: For almost any case you think you want to use this method, {#newest_transaction_date} is probably
+      # more efficient. Particularly since this method has accelerated implementation in its {RVGP::Pta::Hledger}
+      # counterpart
+      #
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details.
+      # @return [RVGP::Pta::RegisterTransaction] The newest transaction in the set
+      def newest_transaction(*args)
+        args, opts = args_and_opts(*args)
+        first_transaction(*args, opts.merge(sort: 'date', tail: 1))
+      end
+
+      # Returns the oldest transaction, retured in set of transactions filtered with the provided arguments.
+      # This method is mostly a wrapper around {RVGP::Pta::Ledger#register} with the \\{head: 1} option passed to that
+      # method. This method may produce counterintutive results, if you override the sort: option.
+      #
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details.
+      # @return [RVGP::Pta::RegisterTransaction] The oldest transaction in the set
+      def oldest_transaction(*args)
+        args, opts = args_and_opts(*args)
+        first_transaction(*args, opts.merge(sort: 'date', head: 1))
+      end
+
+      # Returns the value of the 'Time Period' key, of the #{RVGP::Pta#stats} method. This method is a fast query to
+      # resolve.
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details.
+      # @return [Date] The date of the newest transaction found in your files.
+      def newest_transaction_date(*args)
+        Date.strptime ::Regexp.last_match(1), '%y-%b-%d' if /to ([^ ]+)/.match stats(*args)['Time period']
+      end
+
+      # Run the 'ledger balance' command, and return it's output.
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details.
+      # @return [RVGP::Pta::Ledger::Output::Balance] A parsed, hierarchial, representation of the output
+      def balance(*args)
+        args, opts = args_and_opts(*args)
+
+        RVGP::Pta::Ledger::Output::Balance.new command('xml', *args, opts)
+      end
+
+      # Run the 'ledger register' command, and return it's output.
+      #
+      # This method also supports the following options, for additional handling:
+      # - **:pricer** (RVGP::Journal::Pricer) - If provided, this option will use the specified pricer object when
+      #   calculating exchange rates.
+      # - **:empty** (TrueClass, FalseClass) - If false, we'll remove any accounts and totals, that have
+      #   quantities of zero.
+      # - **:translate_meta_accounts** (TrueClass, FalseClass) - If true, we'll convert accounts of name '<None>' to
+      #   nil, and '<Total>' to :total. This is mostly to useful when trying to preserve uniform behaviors between pta
+      #   adapters. (hledger seems to offer us nil, in cases where ledger offers us '<None>')
+      #
+      # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+      #                             details.
+      # @return [RVGP::Pta::Ledger::Output::Register] A parsed, hierarchial, representation of the output
+      def register(*args)
+        args, opts = args_and_opts(*args)
+
+        pricer = opts.delete :pricer
+        translate_meta_accounts = opts[:empty]
+
+        # We stipulate, by default, a date sort. Mostly because it makes sense. But, also so
+        # that this matches HLedger's default sort order
+        RVGP::Pta::Ledger::Output::Register.new command('xml', *args, { sort: 'date' }.merge(opts)),
+                                                monthly: (opts[:monthly] == true),
+                                                empty: opts[:empty],
+                                                pricer: pricer,
+                                                translate_meta_accounts: translate_meta_accounts
+      end
+
+      private
+
+      def first_transaction(*args)
+        reg = register(*args)
+
+        raise RVGP::Pta::AssertionError, 'Expected a single transaction' unless reg.transactions.length == 1
+
+        reg.transactions.first
+      end
+    end
+  end
+end

data/lib/rvgp/pta.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require_relative 'base/reader'
+
+module RVGP
+  # A base class, which offers functionality to plain text accounting adapters. At the moment,
+  # that means either 'ledger', or 'hledger'. This class contains abstractions and code shared
+  # by the {RVGP::Pta::HLedger} and {RVGP::Pta::Ledger} classes.
+  #
+  # In addition, this class contains the {RVGP::Pta::AvailabilityHelper}, which can be included
+  # by any class, in order to offer shorthand access to this entire suite of functions.
+  class Pta
+    # This module is intended for use in classes that wish to provide #ledger, #hledger,
+    # and #pta methods, to its instances.
+    module AvailabilityHelper
+      # (see RVGP::Pta.ledger)
+      def ledger
+        RVGP::Pta.ledger
+      end
+
+      # (see RVGP::Pta.hledger)
+      def hledger
+        RVGP::Pta.hledger
+      end
+
+      # (see RVGP::Pta.pta)
+      def pta
+        RVGP::Pta.pta
+      end
+    end
+
+    # This error is raised when a Sanity check fails. This should never happen.
+    class AssertionError < StandardError
+    end
+
+    # This class stores the Account details, as produced by the balance method of a pta adapter
+    # @attr_reader fullname [String] The name of this account
+    # @attr_reader amounts [Array<RVGP::Journal::Commodity>] The commodities in this account, as reported by balance
+    class BalanceAccount < RVGP::Base::Reader
+      readers :fullname, :amounts
+      # TODO: Implement and test the :pricer here
+    end
+
+    # This class stores the Transaction details, as produced by the register method of a pta adapter
+    # @attr_reader date [Date] The date this transaction occurred
+    # @attr_reader payee [String] The payee (aka description) line of this transaction
+    # @attr_reader postings [Array<RVGP::Pta::RegisterTransaction>] The postings in this transaction
+    class RegisterTransaction < RVGP::Base::Reader
+      readers :date, :payee, :postings
+    end
+
+    # A posting, as output by the 'register' command. Typically these are available as items in a
+    # transaction, via the {RVGP::Pta::RegisterTransaction#postings} method.
+    # @attr_reader account [String] The account this posting was assigned to
+    # @attr_reader amounts [Array<RVGP::Journal::Commodity>] The commodities that were encountered in the amount column
+    # @attr_reader totals [Array<RVGP::Journal::Commodity>] The commodities that were encountered in the total column
+    # @attr_reader tags [Hash<String,<String,TrueClass>>] A hash containing the tags that were encountered in this
+    #                                                     posting. Values are either the string that was encountered,
+    #                                                     for this tag. Or, true, if no specific string value was
+    #                                                     assigned
+    class RegisterPosting < RVGP::Base::Reader
+      readers :account, :amounts, :totals, :tags
+
+      # This method will return the sum of all commodities in the amount column, in the specified currency.
+      # @param [String] code A three digit currency code, or currency symbol, in which you want to express the amount
+      # @return [RVGP::Journal::Commodity] The amount column, expressed as a sum
+      def amount_in(code)
+        commodities_sum amounts, code
+      end
+
+      # This method will return the sum of all commodities in the total column, in the specified currency.
+      # @param [String] code A three digit currency code, or currency symbol, in which you want to express the total
+      # @return [RVGP::Journal::Commodity] The total column, expressed as a sum
+      def total_in(code)
+        commodities_sum totals, code
+      end
+
+      private
+
+      # Bear in mind that code/conversion is required, because the only reason
+      # we'd have multiple amounts, is if we have multiple currencies.
+      def commodities_sum(commodities, code)
+        currency = RVGP::Journal::Currency.from_code_or_symbol code
+
+        pricer = options[:pricer] || RVGP::Journal::Pricer.new
+        # There's a whole section on default valuation behavior here :
+        # https://hledger.org/hledger.html#valuation
+        date = options[:price_date] || Date.today
+        converted = commodities.map do |a|
+          # There are some outputs, which have no .code. And which only have
+          # a quantity. We don't want to raise an exception for these, if
+          # their quantity is zero, because that's still accumulateable.
+          next if a.quantity.zero?
+
+          a.alphabetic_code == currency.alphabetic_code ? a : pricer.convert(date.to_time, a, code)
+        rescue RVGP::Journal::Pricer::NoPriceError
+          # This seems to be what we want...
+          raise RVGP::Journal::Pricer::NoPriceError
+        end.compact
+
+        # The case of [].sum will return an integer 0, which, isn't quite what
+        # we want. At one point, we returned RVGP::Journal::Commodity.from_symbol_and_amount(code, 0).
+        # However, for some queries, this distorted the output to produce '$ 0.00', when we
+        # really expected nil. This seems to be the best return, that way the caller can just ||
+        # whatever they want, in the case they want to override this behavior.
+        converted.empty? ? nil : converted.sum
+      end
+    end
+
+    # Returns the output of the 'stats' command, parsed into key/value pairs.
+    # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+    #                             details
+    # @return [Hash<String, <String,Array<String>>>] The journal statistics. Values are either a string, or an array
+    #                                                of strings, depending on what was output.
+    def stats(*args)
+      # Somehow, it turned out that both hledger and ledger were similar enough, that I could abstract
+      # this here....
+      args, opts = args_and_opts(*args)
+      # TODO: This should get its own error class...
+      raise StandardError, "Unexpected argument(s) : #{args.inspect}" unless args.empty?
+
+      command('stats', opts).scan(/^\n? *(?:([^:]+?)|(?:([^:]+?) *: *(.*?))) *$/).each_with_object([]) do |match, sum|
+        if match[0]
+          sum.last[1] = [sum.last[1]] unless sum.last[1].is_a?(Array)
+          sum.last[1] << match[0]
+        else
+          sum << [match[1], match[2].empty? ? [] : match[2]]
+        end
+        sum
+      end.to_h
+    end
+
+    # Returns the output of arguments to a pta adapter.
+    #
+    # **NOTE:** If the RVGP_LOG_COMMANDS environment variable is set. (say, to "1") this command will output diagnostic
+    # information to the console. This information will include the fully expanded command being run,
+    # alongside its execution time.
+    #
+    # While args and options are largely fed straight to the pta command, for processing, we support the following
+    # options, which, are removed from the arguments, and handled in this method.
+    # - **:from_s** (String)- If a string is provided here, it's fed to the STDIN of the pta adapter. And "-f -" is
+    #   added to the program's arguments. This instructs the command to treat STDIN as a journal.
+    #
+    # @param [Array<Object>] args Arguments and options, passed to the pta command. See {RVGP::Pta#args_and_opts} for
+    #                             details
+    # @return [String] The output of a pta executable
+    def command(*args)
+      opts = args.pop if args.last.is_a? Hash
+      open3_opts = {}
+      if opts
+        args += opts.map do |k, v|
+          if k.to_sym == :from_s
+            open3_opts[:stdin_data] = v
+            %w[-f -]
+          else
+            [format('--%s', k.to_s), v == true ? nil : v] unless v == false
+          end
+        end.flatten.compact
+      end
+
+      is_logging = ENV.key?('RVGP_LOG_COMMANDS') && !ENV['RVGP_LOG_COMMANDS'].empty?
+
+      cmd = ([bin_path] + args.collect { |a| Shellwords.escape a }).join(' ')
+
+      time_start = Time.now if is_logging
+      output, error, status = Open3.capture3 cmd, open3_opts
+      time_end = Time.now if is_logging
+
+      # Maybe We should send this to a RVGP.logger.trace...
+      if is_logging
+        pretty_cmd = ([bin_path] + args).join(' ')
+
+        puts format('(%.2<time>f elapsed) %<cmd>s', time: time_end - time_start, cmd: pretty_cmd)
+      end
+
+      unless status.success?
+        raise StandardError, format('%<adapter_name>s exited non-zero (%<exitstatus>d): %<msg>s',
+                                    adapter_name: adapter_name,
+                                    exitstatus: status.exitstatus,
+                                    msg: error)
+      end
+
+      output
+    end
+
+    # Given a splatted array, groups and returns arguments into an array of commands, and a hash of options. Options,
+    # are expected to be provided as a Hash, as the last element of the splat.
+    #
+    # Most of the public methods in a Pta adapter, have largely-undefined arguments. This is because these methods
+    # mostly just pass their method arguments, straight to ledger and hledger for handling. Therefore, the 'best'
+    # place to find documentation on what arguments are supported, is the man page for hledger/ledger. The reason
+    # most of the methods exist (#balance, #register, etc), in a pta adapter, are to control how the output of the
+    # command is parsed.
+    #
+    # Here are some examples of how arguments are sent straight to a pta command:
+    # - ledger.balance('Personal:Expenses', file: '/tmp/test.journal') becomes:
+    #   /usr/bin/ledger xml Personal:Expenses --file /tmp/test.journal
+    # - pta.register('Income', monthly: true) becomes:
+    #   /usr/bin/ledger xml Income --sort date --monthly
+    #
+    # That being said - there are some options that don't get passed directly to the pta command. Most of these
+    # options are documented below.
+    #
+    # This method also supports the following options, for additional handling:
+    # - **:hledger_args** - If this is a ledger adapter, this option is removed. Otherwise, the values of this Array
+    #   will be returned in the first element of the return array.
+    # - **:hledger_opts** - If this is a ledger adapter, this option is removed. Otherwise, the values of this Hash will
+    #   be merged with the second element of the return array.
+    # - **:ledger_args** - If this is an hledger adapter, this option is removed. Otherwise, the values of this Array
+    #   will be returned in the first element of the return array.
+    # - **:ledger_opts** - If this is an hledger adapter, this option is removed. Otherwise, the values of this Hash
+    #   will be merged with the second element of the return array.
+    # @return [Array<Object>] A two element array. The first element of this array is an Array<String> containing the
+    #                         string arguments that were provided to this method, and/or which should be passed directly
+    #                         to a pta shell command function. The second element of this array is a
+    #                         Hash<Symbol, Object> containing the options that were provided to this method, and which
+    #                         should be passed directly to a pta shell command function.
+    def args_and_opts(*args)
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+
+      if ledger?
+        opts.delete :hledger_opts
+        opts.delete :hledger_args
+
+        args += opts.delete(:ledger_args) if opts.key? :ledger_args
+        opts.merge! opts.delete(:ledger_opts) if opts.key? :ledger_opts
+      elsif hledger?
+        opts.delete :ledger_opts
+        opts.delete :ledger_args
+
+        args += opts.delete(:hledger_args) if opts.key? :hledger_args
+        opts.merge! opts.delete(:hledger_opts) if opts.key? :hledger_opts
+      end
+
+      [args, opts]
+    end
+
+    # Determines whether this adapter is found in the expected path, and is executable
+    # @return [TrueClass, FalseClass] True if we can expect this adapter to execute
+    def present?
+      File.executable? bin_path
+    end
+
+    # The path to this adapter's binary
+    # @return [String] The path in the filesystem, where this pta bin is located
+    def bin_path
+      # Maybe we should support more than just /usr/bin...
+      self.class::BIN_PATH
+    end
+
+    # The name of this adapter, either :ledger or :hledger
+    # @return [Symbol] The adapter name, in a shorthand form. Downcased, and symbolized.
+    def adapter_name
+      self.class.name.split(':').last.downcase.to_sym
+    end
+
+    # Indicates whether or not this is a ledger pta adapter
+    # @return [TrueClass, FalseClass] True if this is an instance of {RVGP::Pta::Ledger}
+    def ledger?
+      adapter_name == :ledger
+    end
+
+    # Indicates whether or not this is a hledger pta adapter
+    # @return [TrueClass, FalseClass] True if this is an instance of {RVGP::Pta::HLedger}
+    def hledger?
+      adapter_name == :hledger
+    end
+
+    class << self
+      # Return a new instance of RVGP::Pta::Ledger
+      # @return [RVGP::Pta::Ledger]
+      def ledger
+        Ledger.new
+      end
+
+      # Return a new instance of RVGP::Pta::HLedger
+      # @return [RVGP::Pta::HLedger]
+      def hledger
+        HLedger.new
+      end
+
+      # Depending on what's installed and configured, a pta adapter is returned.
+      # The rules that govern what adapter is choosen, works like this:
+      # 1. If {Pta.pta_adapter=} has been set, then, this adapter will be returned.
+      # 2. If ledger is installed on the system, then ledger is returned
+      # 3. If hledger is installed on the system, then hledger is returned
+      # If no pta adapters are available, an error is raised.
+      # @return [RVGP::Pta::Ledger,RVGP::Pta::HLedger]
+      def pta
+        @pta ||= if @pta_adapter
+                   send @pta_adapter
+                 elsif ledger.present?
+                   ledger
+                 elsif hledger.present?
+                   hledger
+                 else
+                   raise StandardError, 'No pta adapter specified, or detected, on system'
+                 end
+      end
+
+      # Override the default adapter, used by {RVGP::Pta.pta}.
+      # This can be set to one of: nil, :hledger, or :ledger.
+      # @param [Symbol] driver The adapter name, in a shorthand form. Downcased, and symbolized.
+      # @return [void]
+      def pta_adapter=(driver)
+        @pta = nil
+        @pta_adapter = driver.to_sym
+      end
+    end
+  end
+end