rvgp 0.3.2

data/README.md

@@ -0,0 +1,223 @@
+# rvgp - A plain text accounting framework for ruby on rake. 
+[![Gem Version](https://badge.fury.io/rb/rvgp.svg)](https://badge.fury.io/rb/rvgp)
+What follows is a workflow tool, and accounting framework, to automate: 
+1. **R**econciliation of your bank-downloaded csv's into categorized pta journals. (interactively!)
+1. **V**alidation of your output, to protect against errors. (in ruby)
+1. **G**rid'ing the data - Make 'spreadsheets' based on analytic calculations from your journals. (ruby here, too)
+1. **P**lotting grids, and generate meaningful graphs of your finances. (using gnuplot, or google sheets)
+
+Plus more! There's a bunch of tools included for: managing commodities, working with tables, parse journals... too much to list. There's plenty of ruby goodness inside to save you time with your accounting, and keep you from reinvent wheels.
+
+## 📑 Table of Contents
+
+- [The Quick Pitch](#-the-quick-pitch)
+- [Getting Started](#-getting-started)
+- [How do project files relate?](#-how-do-project-files-relate)
+- [Understanding the Workflow](#-understanding-the-workflow)
+- [Documentation](#-documentation)
+- [License](#-license)
+
+## 📽 The Quick Pitch
+If you like ruby, and you want something akin to rails... but for your finances - this is what you're looking for! This tool offers an easy workflow,
+for the ruby literate, to: 
+
+1. Build PTA Journals, given a csv, and applying reconciliation rules from a provided yaml file
+2. Run validations (provided in ruby) to ensure the journals meet your expectations
+3. Generate Pretty Plots! using either gnuplot, or Google sheets. Take a look:
+
+| Gnuplot Output                                              |
+| :---                                                        |
+| ![Cashflow](resources/README.MD/2022-cashflow.png)          |
+| ![Wealth Report](resources/README.MD/all-wealth-growth.png) |
+
+Or, publish to google, and share it with your accountant:
+
+| 2022 Cashflow (Google Sheet Screenshot)                          |  Wealth Report (Google Sheet Screenshot)                                   |
+| :---                                                             |  :----                                                                     |
+| ![Cashflow Google](resources/README.MD/2022-cashflow-google.png) |  ![Wealth Report Google](resources/README.MD/all-wealth-growth-google.png) |
+
+Plus, you get a bunch of other nice features. Like...
+* A TUI cashflow output, for understanding your monthly cashflow on a dashboard
+* Lots of versatility in your Plots. The code is very open ended, and supports a good number of 2d plot formats, and features
+* No extraneous gem dependencies. Feel free to include activesupport in your project if you'd like. But, we're not imposing that on our requirements!
+* A Reconciliation mode in vim, to split-screen edit your yaml, with a hot-loaded output pane
+* Git friendly! Store your finances in an easily audited git repo.
+* Automatic transactions, for generating transactions via ruby logic, instead of sourcing from a csv file.
+* Additional modules for currency conversion, mortgage interest/principle calculations
+* Add your own commands and tasks to the rake process, simply by adding commands them your app/commands folder
+* Multi-threaded for faster throughput
+* An easy quickstart generator, for setting up your first project (see the new_project command)
+* Shortcuts for working with finance, currency, gnuplot, hledger, i18n and more 
+
+## 🐦‍ Getting Started
+
+The quickest way to get started, once you've installed the gem, is by way of the 'new_project' command.  
+```
+~> rvgp -d ~/ledger new_project
+Whose project is this? A person's full name or a company name will work: Yukihiro Matsumoto
+You entered "Yukihiro Matsumoto". Is that correct? (Type "Yes" to continue) : Yes
+
+📖 New Project
+   Initializing Project directory ........................................... 🟢
+   Initializing Randomized bank feeds ....................................... 🟢
+   Initializing Randomized reconcilers ...................................... 🟢
+
+The new project has been generated successfully.
+Though you may want to add the following line to your ~/.bashrc:
+  export LEDGER_FILE="/home/matz/yukihiro-matsumoto.journal"
+
+You're ready to begin working on this project. Try cd'ing into its directory, and running `rake`.
+~>
+```
+
+Per the suggestion, you'll benefit from adding the LEDGER_FILE environment variable to your shell's startup script. This will keep you from having to specify the directory every time you run rvgp (or having to specify it to ledger and hledger). If you're working with more than one project, you may not want to use this feature. 
+
+> **Note**
+> You can specify a company name, instead of person's name. (If that's what you're intent on managing with this project)
+
+From here, you're all set to run your first build. cd into your project directory, and run rake. Here's roughly the output you can expect. We abridged this a bit, to cut down on ... paper :smiley: . Your output may differ, in any case, depending on how your cpu decides to schedule threads:
+```
+~> cd ~/ledger
+~/ledger> rake
+🏗️ Building Journals from Feeds
+   Expanding Personal AcmeBank:Checking (2018) .............................. 🟢
+   Expanding Personal AcmeBank:Checking (2023) .............................. 🟢
+
+📒 Inspecting Individual Journal Files
+   Validating Personal AcmeBank:Checking (2018) ............................. 🟢
+   🟡 No balance checkpoints found.
+   Validating Personal AcmeBank:Checking (2023) ............................. 🟢
+   🟡 No balance checkpoints found.
+
+▦ Generating Grids
+   Calculating Cashflows by month (2018) .................................... 🟢
+   Calculating Wealth Growth by month (2023) ................................ 🟢
+
+📈 Generating Plots
+   Plotting 2018-cashflow ................................................... 🟢
+   Plotting all-wealth-growth ............................................... 🟢
+
+~/ledger>
+```
+
+The output of this process, is now visible in the `build` folder under your project's root. 
+
+> **Note**
+> The "No balance checkpoints found." warning indicates that your reconciler definition, is missing a balance checkpoint. Since new_projects use 'fake' data, there's no balance checkpoint specified in the reconciler yaml. With your data, you'll want to enter the balance, and date, on some of your statements, into the 'balances' section of this file, to ensure accuracy against the financial institution's records. (Or, you can just disable this feature) More on that later. Nonetheless, these warnings are safe to ignore for now.
+
+Now you can begin to explore your build. If you'd like to see the net worth of your project, try running `gnuplot build/plots/all-wealth-growth.gpi`. If you'd like to publish some plots to google, you can populate your config/ directory with google API settings, and run `rvgp publish_gsheets -a`. Or, just run a `hledger bal` (or `ledger bal`) to see your account balances.
+   
+From here, you're ready to start populating this project with your data, instead of the randomly generated feeds. The easiest way to get started, is to run a `rake clean` (Thus undo'ing the above rake work, and clearing the build/ directory). And to then, remove unnecessary files in your `feeds/` and `app/reconcilers/` directories. Go ahead from there, and download your banking institution's csv files into the `feeds/` directory. And create yaml files for each of them, in your `app/reconcilers` directory. Use an existing yaml file for quick reference. 
+
+Probably though, you'll want to read the rest of this README, to better understand how the project workflow is structured, and how these files work with that process.
+
+## 🐒 How do project files relate?
+Let's take a moment, to understand the project directory structure. Here's what that looks like, in the "Yukihiro Matsumoto" project that we just created:
+
+```
+~/ledger> lsd *
+ Rakefile   yukihiro-matsumoto.journal
+
+app:
+ commands   grids   plots   reconcilers   validations
+
+build:
+ grids   journals   plots
+
+config:
+ csv-format-acme-checking.yml   google-secrets.yml   rvgp.yml
+
+feeds:
+ 2018-personal-basic-checking.csv   2020-personal-basic-checking.csv   2022-personal-basic-checking.csv
+ 2019-personal-basic-checking.csv   2021-personal-basic-checking.csv   2023-personal-basic-checking.csv
+
+journals:
+ opening-balances.journal   prices.db
+~/ledger>
+```
+
+In the root of this project, is your 'main' journal, alongside the Rakefile, and a few directories. Let's look at these directories one by one.
+* **journals** These are where your 'manually entered' PTA journals belong. As your project grows, you can insert as many .journal files in here as you'd like. These will be automatically included by the yukihiro-matsumoto.journal. And, to get you started, there is an opening-balances.journal, which, nearly every project should have.
+* **feeds** This folder exists to keep your 'source' files. Which, would principally be csv's that have been downloaded from banks. PTA '.journal' files are also supported. I synchronize the journal output from [cone](https://play.google.com/store/apps/details?id=info.tangential.cone&hl=en_US&gl=US), into journal files here.
+* **build** This folder, is where the output of rvgp goes. There's really no good reason to write to this folder, outside the rvgp libraries. Be careful about putting anything in here that you don't want to lose. A `rake clean` erases just about anything that's in here. We'll better address this folder, by examining the app folder, a bit further down.
+* **app** Here's where the magic happens. This folder contains the ruby and yaml, that reconciles the contents of your feeds, into a finished product. There are a number of subfolders, each containing logic dedicated to a specific part of the build process. (See below) 
+* **config** This is self explanatory. This directory exists to contain application feed settings. You can look through the default config files, for an overview of what's possible here.
+
+Drilling into the app folder, we see the following sub-folders:
+
+* **app/reconcilers** This folder contains yaml files, which are used to reconcile your feeds, into pta journals. These yaml files support an extensive featureset to 'match entries', and then tag and categorize those matches. The output of this reconcile, is stored in the build/journals folder, once executed.
+* **app/validations** This folder contains ruby files, inside which, are tests that ensure validity of the output, for the above reconcilers. These ruby files contain classes which inherit from either the RVGP::Base::SystemValidation, or, the RVGP::Base::JournalValidation, depending on whether they validate the system as a whole (Perhaps, checking for any transactions tagged 'vacation', but which aren't also tagged with a 'location'). Or, whether they are specifically designed for a given reconciler's output file. There is no build output on these files. Validations either trigger an warning on the console, or abort a build from continuing (with an error on the console).
+* **app/grids** This folder contains ruby files, containing classes which build 'grids'. Grids, are csv files, that contain calculated outputs, based on your journals. These grids can be used for many purposes, but, probably should be considered 'excel sheets' that are later plotted, or referenced by a command elsewhere. Typically, these grids are composed of 'hledger monthly' queries. However, they can just as easily be generated independent of your journals. Which is useful for tracking 'business projections' and financial models that you wrote yourself. The output of these grids, are stored in your build/grids folder.
+* **app/plots** This folder contains the yaml files which contain the gnuplot and google settings that draw your plots. These settings determine what will gpi files are generated in your build/plots folder.
+* **app/commands** This folder contains any additional commands you wish to extend the rvgp app with. And which are then suitable for insertion into the rake workflow. These files are ruby files, containing classes which inherit from the RVGP::Base::Command object.
+
+These directories contain the bulk of your workload, in your rvgp projects. These components will be further documented further down in this README. In the meantime, it may help to illustrate the typical workflow cycle, that rvgp executes using these files.
+
+> **Note**
+> Feel free to add as many directories to your project root as you'd like. Useful ideas for additional directories might include: 'bank statements', 'test', 'orgs', 'documents', etc
+
+## 🪅 Understanding the Workflow
+
+The significance of the Rakefile approach, to your accounting, can't be understated. This design decision offers us a number of features. The implicit dependency-tracking ensures that changes are only applied downstream in your build. A small adjustment at a given year, doesn't require an entire rebuild of the project. This offers us better performance, git-friendly accounting, and simplified auditing.
+
+> **Note**
+> There shouldn't be any reason to avoid, or instigate, a `rake clean` when working on a project. The Rakefile is very smart about figuring out what to change. However, if you feel the need to recalculate the entire project - a rake clean won't hurt.
+
+To better understand how your files, are processed by rvgp, here's a diagram of how the rakefile processes your build. Hopefully this reduces confusion.
+
+```mermaid
+  graph TD;
+    subgraph Reconciliation[Reconciliation Cycle]
+      Reconcilers("app/reconcilers/*.yml").->JournalBuild("<br>🏗 Journal Build<br><br>");
+      Feeds("feeds/*.csv").->JournalBuild;
+      JournalBuild-->JournalOutput("build/journals/*.journal");
+    end
+    JournalOutput-->JValidations;
+    JValidationInput("app/validations/*.rb<br>(RVGP::Base::JournalValidation)").->JValidations;
+    JValidations("<br>📒 Journal Validate<br><br>");
+    SValidationInput("app/validations/*.rb<br>(RVGP::Base::SystemValidation)").->SValidations;
+    JValidations-->SValidations("<br>📚 System Validate<br><br>");
+    GridInput("app/grids/*.rb<br>(RVGP::Base::Grid)").->GridBuild("<br>▦ Grid Build<br><br>");
+    SValidations-->GridBuild;
+    GridBuild-->GridOutput("build/grids/*.csv");
+    PlotInput("app/plots/*.yml").->PlotBuild("<br>📈 Plot Build<br><br>");
+    GridOutput-->PlotBuild;
+    PlotBuild-->PlotOutput("build/plots/*.gpi");
+    
+    style Reconciliation fill:#fdf6e3,stroke:#b58900;
+
+    style Reconcilers fill:#e3e4f4,stroke:#6c71c4;
+    style Feeds fill:#e3e4f4,stroke:#6c71c4;
+    style JValidationInput fill:#e3e4f4,stroke:#6c71c4;
+    style SValidationInput fill:#e3e4f4,stroke:#6c71c4;
+    style GridInput fill:#e3e4f4,stroke:#6c71c4;
+    style PlotInput fill:#e3e4f4,stroke:#6c71c4;
+    
+    style JournalOutput fill:#d1f3f0,stroke:#2aa198;
+    style GridOutput fill:#d1f3f0,stroke:#2aa198;
+    style PlotOutput fill:#d1f3f0,stroke:#2aa198;
+
+    style JournalBuild fill:#d5e9f7,stroke:#268bd2;
+    style JValidations fill:#d5e9f7,stroke:#268bd2;
+    style SValidations fill:#d5e9f7,stroke:#268bd2;
+    style GridBuild fill:#d5e9f7,stroke:#268bd2;
+    style PlotBuild fill:#d5e9f7,stroke:#268bd2;
+```
+
+In this lifecycle, the major tasks are circled in blue, with cyan output files in-between these tasks. Input files, that you provide, are peppered along the process, and are denoted in purple. Any `commands` that you define, are inserted in-between the blue tasks, depending on whether and where you define those commands to insert themselves.
+
+## 📚 Documentation
+
+Here are some links around the yard documentation, to particularly useful component and feature references:
+- [Reconciler yaml](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Reconcilers)
+- [JournalValidation base class](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Base/JournalValidation)
+- [SystemValidation base class](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Base/SystemValidation)
+- [Grid base class](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Base/Grid)
+- [Plot yaml](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Plot)
+- [PTA class(es)](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Pta)
+- [Commodity class](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Journal/Commodity)
+- [ComplexCommodity class](https://www.rubydoc.info/gems/rvgp/0.3.2/RVGP/Journal/ComplexCommodity)
+
+## 📜 License
+
+This software is licensed under the [LGPL-2.1](https://github.com/rvgp/blob/master/LICENSE) © [Chris DeRose](https://github.com/brighton36).

data/Rakefile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'rubocop/rake_task'
+require 'bundler/gem_tasks'
+
+require_relative 'lib/rvgp'
+
+task default: 'all'
+
+desc 'All'
+task all: %i[test yard lint build]
+
+desc 'Run the minitests'
+task :test do
+  Dir[RVGP::Gem.root('test/test*.rb')].sort.each { |f| require f }
+end
+
+desc 'Check code notation'
+RuboCop::RakeTask.new(:lint) do |task|
+  task.patterns = RVGP::Gem.ruby_files
+  task.formatters += ['html']
+  task.options += ['--fail-level', 'convention', '--out', 'rubocop.html']
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = RVGP::Gem.ruby_files.reject do |f|
+    %r{\A(?:(?:test|resources/skel)/.*|.*finance_gem_hacks\.rb\Z)}.match f
+  end
+  t.options = ['--no-private', '--protected', '--markup=markdown']
+  t.stats_options = ['--list-undoc']
+end

data/bin/rvgp

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# vim: syntax=ruby
+# -*- mode: ruby -*-
+# frozen_string_literal: true
+
+require_relative '../lib/rvgp/commands'
+
+RVGP::Commands.dispatch!(*ARGV)

data/lib/rvgp/application/config.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative '../pta'
+
+module RVGP
+  class Application
+    # This class provides the app configuration options accessors and parsing logic.
+    class Config
+      include RVGP::Pta::AvailabilityHelper
+      attr_reader :prices_path, :project_journal_path
+
+      # Given the provided project path, this object will parse and store the
+      # config/rvgp.yaml, as well as provide default values for otherwise unspecified attributes
+      # in this file.
+      # @param project_path [String] The path, to an RVGP project directory.
+      def initialize(project_path)
+        @project_path = project_path
+        @build_path = format('%s/build', project_path)
+
+        config_path = project_path 'config/rvgp.yml'
+        @yaml = RVGP::Utilities::Yaml.new config_path, project_path if File.exist? config_path
+
+        RVGP::Pta.pta_adapter = @yaml[:pta_adapter].to_sym if @yaml.key? :pta_adapter
+
+        @prices_path = @yaml.key?(:prices_path) ? @yaml[:prices_path] : project_path('journals/prices.db')
+
+        if @yaml.key?(:project_journal_path)
+          @project_journal_path = project_path @yaml[:project_journal_path]
+        else
+          journals_in_project_path = Dir.glob format('%s/*.journal', @project_path)
+          if journals_in_project_path.length != 1
+            raise StandardError,
+                  format(
+                    'Unable to automatically determine the project journal. Probably you want one of these ' \
+                    'files: %<files>s. Set the project_journal_path parameter in ' \
+                    'your config file, to the relative pathname, of the project journal.',
+                    files: journals_in_project_path.join(', ')
+                  )
+          end
+          @project_journal_path = journals_in_project_path.first
+        end
+
+        # I'm not crazy about this default.. Mabe we should raise an error if
+        # this value isn't set...
+        @grid_starting_at = @yaml[:grid_starting_at] if @yaml.key? :grid_starting_at
+        @grid_starting_at ||= default_grid_starting_at
+
+        # NOTE: pta_adapter.newest_transaction_date.year works in lieu of Date.today,
+        #       but that query takes time. (and it requires that we've already
+        #       performed a build step at the time it's called) so, we use
+        #       Date.today instead.
+        @grid_ending_at = @yaml[:grid_ending_at] if @yaml.key? :grid_ending_at
+        @grid_ending_at ||= default_grid_ending_at
+      end
+
+      # Return the contents of the provided attr, from the project's config/rvgp.yaml
+      # @return [Object] the value corresponding to the provided attr
+      def [](attr)
+        @yaml[attr]
+      end
+
+      # Returns a boolean indicating whether a value for the provided attr was specified in the project's
+      # config/rvgp.yaml
+      # @return [TrueClass, FalseClass] whether the key was specified
+      def key?(attr)
+        @yaml.key? attr
+      end
+
+      # Returns the starting date, for all grids that will be generated in this project.
+      # @return [Date] when to commence grid building
+      def grid_starting_at
+        call_or_return_date @grid_starting_at
+      end
+
+      # Returns the ending date, for all grids that will be generated in this project.
+      # @return [Date] when to finish grid building
+      def grid_ending_at
+        call_or_return_date @grid_ending_at
+      end
+
+      # The years, for which we will be building grids
+      # @return [Array<Integer>] What years to expect in our build/grids directory (and their downstream targets)
+      def grid_years
+        grid_starting_at.year.upto(grid_ending_at.year)
+      end
+
+      # Returns the full path, to a file or directory, in the project. If no relpath was provided, this
+      # method returns the full path to the project directory.
+      # @param relpath [optional, String] The relative path, to a filesystem object in the current project
+      # @return [String] The full path to the requested resource
+      def project_path(relpath = nil)
+        relpath ? [@project_path, relpath].join('/') : @project_path
+      end
+
+      # Returns the full path, to a file or directory, in the project's build/ directory. If no relpath was provided,
+      # this method returns the full path to the project build directory.
+      # @param relpath [optional, String] The relative path, to a filesystem object in the current project
+      # @return [String] The full path to the requested resource
+      def build_path(relpath = nil)
+        relpath ? [@build_path, relpath].join('/') : @build_path
+      end
+
+      # This is a bit of a kludge. We wanted this in a few places, so, I DRY'd it here. tldr: this returns an array
+      # of years (as integers), which, were groked from the file names found in the app/reconcilers directory.
+      # It's a rough shorthand, that, ends up being a better 'guess' of start/end dates, than Date.today
+      # @!visibility private
+      def reconciler_years
+        Dir.glob(project_path('app/reconcilers/*.yml')).map do |f|
+          ::Regexp.last_match(1).to_i if /\A(\d{4}).+/.match File.basename(f)
+        end.compact.uniq.sort
+      end
+
+      private
+
+      def default_grid_starting_at
+        years = reconciler_years
+        years.empty? ? (Date.today << 12) : Date.new(years.first, 1, 1)
+      end
+
+      # We want/need grid tasks that are defined by (year)-gridname. However, we want
+      # an exact end date, that's based off the output of the build step.
+      #
+      # So, what we do, is check for the prescence of journal files, and if they're
+      # not there, we just return the end of the current year.
+      #
+      # If we find the journal files, we return the last 'full month' of data
+      #
+      # NOTE: we probably could/should cache the newest_transaction_date, but,
+      # that would be a PITA right now
+      def default_grid_ending_at
+        # It's important that we return a lambda, so that the call_or_return()
+        # re-runs this code after the grids are generated
+        # TODO: This lambda is goofy. Let's see if we can nix it
+        lambda do
+          unless Dir[build_path('journals/*.journal')].count.positive?
+            years = reconciler_years
+            return years.empty? ? Date.today : Date.new(years.last, 12, 31)
+          end
+
+          # TODO: I think this is why our rake / rake clean output is mismatching atm
+          end_date = pta.newest_transaction_date file: project_journal_path
+
+          return end_date if end_date == Date.civil(end_date.year, end_date.month, -1)
+
+          if end_date.month == 1
+            Date.civil end_date.year - 1, 12, 31
+          else
+            Date.civil end_date.year, end_date.month - 1, -1
+          end
+        end
+      end
+
+      def call_or_return_date(value)
+        ret = value.respond_to?(:call) ? value.call : value
+        ret.is_a?(Date) ? ret : Date.strptime(ret)
+      end
+    end
+  end
+end

data/lib/rvgp/application/descendant_registry.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RVGP
+  class Application
+    # This module contains a system by which RVGP maintains an application registry,
+    # of child classes, for a given parent class. These registries are stored in
+    # the RVGP namespace, under a provided name (usually something resembling the
+    # superclass name), and facilitates an easy form of child class enumeration,
+    # throughout the RVGP system.
+    #
+    # Thus far, the parent classes which are using this functionality, are:
+    # {RVGP::Base::Command}, {RVGP::Base::Grid}, {RVGP::Base::JournalValidation}, and {RVGP::Base::SystemValidation}.
+    #
+    # This means that, for example, a class which inherits from {RVGP::Base::Command},
+    # is added to the array of its siblings in {RVGP.commands}. Similarly, there are
+    # containers for {RVGP.grids}, {RVGP.journal_validations}, and {RVGP.system_validations}.
+    module DescendantRegistry
+      # This basic class resembles an array, and is used to house a regsitry of
+      # children classes. Typically, this class is instantiated inside of RVGP, at
+      # the time a child inherits from a parent.
+      #
+      # @attr_reader [Array<Object>] classes The undecorated classes that are contained in this object
+      class ClassRegistry
+        include Enumerable
+
+        attr_reader :classes
+
+        # Declare the registry, and initialize with the relevant options
+        # @param [Hash] opts what options to configure this registry with
+        # @option opts [Hash<String, Proc>] :accessors what methods to dispatch to the instances of this collection
+        def initialize(opts = {})
+          @classes = []
+          @accessors = opts[:accessors] || {}
+        end
+
+        # Call the provided block, for each element of the registry
+        # @yield [obj] The block you wish to call, once per element of the registry
+        # @return [void]
+        def each(&block)
+          classes.each(&block)
+        end
+
+        # Add the provided object to the {#classes} collection
+        # @param [Object] klass The object class, you wish to add
+        # @return [void]
+        def add(klass)
+          @classes << klass
+        end
+
+        # The names of all the classes that are defined in this registry
+        # @return [Array<String>]
+        def names
+          classes.collect(&:name)
+        end
+
+        # @!visibility private
+        def respond_to_missing?(name, _include_private = false)
+          @accessors.key? name
+        end
+
+        # In the case that a method is called on this registry, that isn't explicitly defined,
+        # this method checks the accessors provided in {#initialize} to see if there's a matching
+        # block, indexing to the name of the missing method. And calls that.
+        # @param [Symbol] name The method attempting to be called
+        def method_missing(name)
+          @accessors.key?(name) ? @accessors[name].call(self) : super(name)
+        end
+      end
+
+      # @!visibility private
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+
+      # This module defines the parent's class methods, which are attached to a parent
+      # class, at the time it includes the DescendantRegistry
+      module ClassMethods
+        # This method is the main entrypoint for all of the descendent registry features. This method
+        # installs a registry, into the provided namespace, given the provided options
+        # @param [Object] in_klass This is class, under which, this registry will be created
+        # @param [Symbol] with_name The name of the registry, which will be the name of the reader, created in in_klass
+        # @param [Hash] opts what options to configure this registry with
+        # @option opts [Hash<String, Proc>] :accessors A list of public methods to create, alongside their
+        #                                              implementation,in the base of the newly created collection.
+        # @option opts [Regexp] :name_capture This regex is expected to contain a single capture, that will be used to
+        #                                     construct a class name, given a classes #to_s output, and before sending
+        #                                     to underscorize.
+        def register_descendants(in_klass, with_name, opts = {})
+          @descendant_registry = { klass: in_klass,
+                                   name: with_name,
+                                   name_capture: opts.key?(:name_capture) ? opts[:name_capture] : /\A.*:(.+)\Z/ }
+          define_singleton_method(:descendant_registry) { @descendant_registry }
+
+          in_klass.instance_eval do
+            iv_sym = "@#{with_name}".to_sym
+            instance_variable_set iv_sym, ClassRegistry.new(opts)
+            define_singleton_method(with_name) { instance_variable_get iv_sym }
+          end
+        end
+
+        # The name of this base class, after applying its to_s to :name_capture,
+        # and underscore'izing the capture
+        # @return [String] A string that can be used for various metaprogramming requirements of this
+        #                  DescendantRegistry
+        def name
+          name_capture = superclass.descendant_registry[:name_capture]
+          name = name_capture.match(to_s) ? ::Regexp.last_match(1) : to_s
+
+          # underscorize the capture:
+          name.scan(/[A-Z][^A-Z]*/).join('_').downcase
+        end
+
+        private
+
+        def inherited(descendant)
+          super(descendant)
+          @descendant_registry[:klass].send(@descendant_registry[:name]).add descendant
+        end
+      end
+    end
+  end
+end