ydl 0.2.06

data/lib/ydl/ydl.rb

@@ -0,0 +1,244 @@
+require 'ydl'
+require 'fat_core/string'
+require 'active_support/core_ext/hash/deep_merge'
+require 'active_support/core_ext/hash/keys'
+# For singularize, camelize
+require 'active_support/core_ext/string'
+
+# Name-space module for the ydl gem.
+module Ydl
+  using ArrayRefinements
+
+  SYSTEM_DIR = '/usr/local/share/ydl'.freeze
+  CONFIG_FILE = File.join(ENV['HOME'], '.ydl/config.yaml')
+
+  @@config_printed = false
+
+  class << self
+    # Configuration hash for Ydl, read from ~/.ydl/config.yaml on require.
+    attr_accessor :config
+
+    # Holder of all the data read from the .ydl files as a Hash
+    attr_accessor :data
+  end
+  self.config = { class_map: {}, class_init: {} }
+  self.data = {}
+
+  # Load all .ydl files, subject to the given options.  After loading, the data
+  # in the .ydl files will be available in Ydl.data and accessible with Ydl[].
+  #
+  # The following options affect which files are loaded:
+  #
+  # - ignore: String :: ignore all .ydl files whose base name matches the given
+  #   string.
+  # - ignore: /regexp/ :: ignore all .ydl files whose base name matches the
+  #   given regexp.
+  # - ignore: [String|/regexp/] :: ignore all .ydl files whose base name matches
+  #   any of the given strings or regexp's in the given Array.
+  #
+  # @param [Hash] options selectively ignore files; use alternative config
+  # @return [Hash] data read from .ydl files as a Hash
+  def self.load(base = '*', ignore: nil, verbose: true)
+    Ydl.read_config
+    # Load each file in order to self.data.  Note that there may be many files
+    # with the same basename and, hence, will be merged into the same
+    # top-level hash key with the later files overriding the earlier ones.
+    # Thus, it is important that ydl_files returns the file names starting
+    # with those having the lowest priority and ending with those having the
+    # highest.
+    yaml = {}
+    file_names = ydl_files(glob: base, ignore: ignore)
+    warn "ydl: files found:" if verbose
+    file_names.each do |fn|
+      file_hash = Ydl.load_file(fn)
+      yaml = yaml.deep_merge(file_hash)
+    end
+
+    # At this point, all of the files are incorporated into a single hash with
+    # the top-level keys corresponding to the basenames of the files read in,
+    # but all of the leaf nodes are simple ruby objects, not yet instantiated
+    # into application-level objects.  That is what the Ydl::Tree class is
+    # designed to accomplish, including resolving any cross-reference strings
+    # of the form 'ydl:/path/to/other/part/of/ydl/tree'.  It does this by
+    # constructing a Ydl::Tree from the yaml hash.
+    tree = Tree.new(yaml)
+
+    # After the leaf nodes of the tree have been instantiated by the Tree
+    # object, we need to convert the Tree back into a hash, but only down to
+    # the level above the reified ruby objects.  By this time, all the ruby
+    # objects will have been instantiated and all cross-references resolved.
+    self.data = data.merge(tree.to_hash)
+
+    # Just return the base name's branch if base is set
+    base = base.to_sym
+    if data.key?(base)
+      data[base]
+    else
+      data
+    end
+  rescue UserError, CircularReference, BadXRef => e
+    warn e
+    exit 1
+  end
+
+  # Return a Hash of a Hash with a single top-level key of the basename of the
+  # given file and a value equal to the result of reading in the given YAML
+  # file.  The single top-level hash key will determine the class into which
+  # each of the elements of the inner Hash will be instantiated.  For example,
+  # reading the file "persons.ydl" might result in a Hash of
+  #
+  # result[:person] = {jsmith: {first: 'John', middle: 'A.', last: 'Smith',
+  # address: {street1: '123 Main', city: 'Middleton', state: 'KS', zip:
+  # '66213'}, sex: 'male'}, fordmotor: {name: 'Ford Motor Company, Inc.'},
+  # sex: 'entity', ...}
+  #
+  # Thus, each of jsmith and fordmotor will eventually get instantiated into a
+  # Person object using the hash to initialize it.  Some of the keys in that
+  # hash, e.g., :address, might themselves represent classes to be initialized
+  # with their sub-hashes, and so forth recursively.
+
+  def self.load_file(name, verbose: true)
+    key = File.basename(name, '.ydl').to_sym
+    warn "ydl: loading file #{name}..." if verbose
+    result = {}
+    begin
+      result[key] = Psych.safe_load_file(name, permitted_classes: [Date, DateTime])
+    rescue Psych::SyntaxError => e
+      usr_msg = "#{File.expand_path(name)}: #{e.problem} #{e.context} at line #{e.line} column #{e.column}"
+      raise UserError, usr_msg
+    end
+    result[key].deep_symbolize_keys! if result[key].is_a?(Hash)
+    result
+  end
+
+  # Return the component at key from Ydl.data.
+  def self.[](key)
+    msg = "no key '#{key}' in Ydl data"
+    raise UserError, msg unless data.key?(key)
+
+    Ydl.data[key]
+  end
+
+  # Return a list of all the .ydl files in order from lowest to highest
+  # priority, ignoring those whose basenames match the ignore parameter, which
+  # can be a String, a Regexp, or an Array of either (all of which are matched
+  # against the basename without the .ydl extension).
+  def self.ydl_files(glob: '*', ignore: nil, verbose: true)
+    read_config
+    warn "ydl: gathering ydl files #{glob}.ydl..." if verbose
+    warn "ydl: ignoring files #{ignore}.ydl..." if verbose && ignore
+    sys_ydl_dir = Ydl.config[:system_ydl_dir] || '/etc/ydl'
+    file_names = []
+    unless sys_ydl_dir.blank?
+      file_names += Dir.glob("#{sys_ydl_dir}/**/#{glob}.ydl")
+    end
+    file_names += Dir.glob(File.join(ENV['HOME'], ".ydl/**/#{glob}.ydl"))
+
+    # Find directories from pwd to home (or root), then reverse
+    dir_list = []
+    dir = Dir.pwd
+    while dir != File.expand_path('~/..') && dir != '/'
+      dir_list << dir
+      dir = Pathname.new(dir).parent.to_s
+    end
+    dir_list = dir_list.reverse
+
+    # Gather the .ydl files in those directories
+    dir_list.each do |d|
+      file_names += Dir.glob("#{d}/#{glob}.ydl")
+    end
+
+    # Filter out any files whose base name matches options[:ignore]
+    file_names = filter_ignores(file_names, ignore) unless ignore.blank?
+    file_names.each { |f| warn "  ->reading #{f}" } if verbose
+    file_names
+  end
+
+  # From the list of file name paths, names, delete those whose basename
+  # (without the .ydl extension) match the pattern or patterns in ~ignores~,
+  # which can be a String, a Regexp, or an Array of either.  Return the list
+  # thus filtered.
+  def self.filter_ignores(names, ignores)
+    ignores = [ignores] unless ignores.is_a?(Array)
+    return names if ignores.empty?
+
+    names.reject { |n| ignores.any? { |ig| File.basename(n).match(ig) } }
+  end
+
+  mattr_accessor :class_for_cache
+  self.class_for_cache = {}
+
+  def self.class_for(key)
+    return nil if key.blank?
+    return class_for_cache[key] if class_for_cache[key]
+    return class_map(key) if class_map(key)
+
+    klasses = candidate_classes(key, Ydl.config[:class_modules])
+    return nil if klasses.empty?
+
+    class_for_cache[key] = klasses.first
+    klasses.first
+  end
+
+  def self.class_map(key)
+    return nil if key.blank?
+    return nil if key.is_a?(Numeric)
+
+    key = key.to_sym
+    return nil unless Ydl.config[:class_map].key?(key)
+
+    klass_name = Ydl.config[:class_map][key]
+    klass_name.constantize
+  rescue NameError
+    raise "no declared class named '#{klass_name}'"
+  end
+
+  def self.class_init(klass_name)
+    klass_name = klass_name.to_sym
+    klass_config = Ydl.config[:class_init]
+    return :new unless klass_config.key?(klass_name)
+
+    klass_config[klass_name].to_sym
+  end
+
+  mattr_accessor :all_classes
+
+  def self.candidate_classes(key, modules = nil)
+    # Add all known classes to module attribute as a cache on first call; except
+    # Errno
+    all_classes ||=
+      ObjectSpace.each_object(Class)
+        .map(&:to_s)
+        .select { |klass| klass =~ %r{^[A-Z]} }
+        .reject { |klass| klass =~ %r{^Errno::} }
+
+    suffix = key.to_s.singularize.camelize
+    modules = modules.split(',').map(&:clean) if modules.is_a?(String)
+    all_classes.select { |cls|
+      if modules
+        # If modules given, restrict to those classes within the modules, where
+        # a blank string is the main module.
+        modules.any? do |mod|
+          cls =~ (mod.blank? ? /\A#{suffix}\z/ : /\A#{mod}::#{suffix}\z/)
+        end
+      else
+        # Otherwise, all classes ending with suffix.
+        cls == suffix || cls =~ /::#{suffix}\z/
+      end
+    }.sort.map(&:constantize)
+  end
+
+  # Set the Ydl.config hash to the configuration given in the YAML string, cfg,
+  # or read the config from the file ~/.ydl/config.yaml if cfg is nil
+  def self.read_config
+    cfg_file = ENV['YDL_CONFIG_FILE'] || CONFIG_FILE
+    cfg_file = File.expand_path(cfg_file)
+    Ydl.config ||= {}
+    Ydl.config = YAML.load_file(cfg_file) if File.exist?(cfg_file)
+    Ydl.config.deep_symbolize_keys!
+    Ydl.config[:class_map] ||= {}
+    Ydl.config[:class_init] ||= {}
+    Ydl.config[:system_ydl_dir] ||= SYSTEM_DIR
+    Ydl.config
+  end
+end

data/lib/ydl.rb

@@ -0,0 +1,15 @@
+require 'active_support'
+require 'psych'
+require 'yaml'
+require 'fat_core'
+
+# Name space for the ydl app.
+module Ydl
+  require 'ydl/version'
+  require 'ydl/errors'
+  require 'ydl/core_ext'
+  require 'ydl/top_queue'
+  require 'ydl/node'
+  require 'ydl/tree'
+  require 'ydl/ydl'
+end

data/spec/array_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+module Ydl
+  using ArrayRefinements
+  RSpec.describe ArrayRefinements do
+    it 'can detect if other array is its prefix' do
+      arr_a = [:a, :b, :c, :d]
+      arr_b = [:a, :b, :c]
+      expect(arr_a.prefixed_by(arr_b)).to be true
+      expect(arr_a.prefixed_by(arr_a)).to be true
+      expect(arr_b.prefixed_by(arr_a)).to be false
+    end
+  end
+end

data/spec/core_ext/array_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+module Ydl
+  using ArrayRefinements
+  RSpec.describe ArrayRefinements do
+    it 'can detect if other array is its prefix' do
+      arr_a = [:a, :b, :c, :d]
+      arr_b = [:a, :b, :c]
+      expect(arr_a.prefixed_by(arr_b)).to be true
+      expect(arr_a.prefixed_by(arr_a)).to be true
+      expect(arr_b.prefixed_by(arr_a)).to be false
+    end
+  end
+
+  RSpec.describe Array do
+    it 'can detect if it contains any cross-refs' do
+      arr_a = ['ydl is not a ref', 3.14159, Date.today, 'ydl:/this/is/a/ref']
+      arr_b = ['ydl is not a ref', 3.14159, Date.today, true, :symbol]
+      expect(arr_a.xref?).to be true
+      expect(arr_b.xref?).to be false
+    end
+  end
+end

data/spec/core_ext/boolean_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+module Ydl
+  RSpec.describe 'Boolean extensions' do
+    it 'can detect if it is a cross-ref' do
+      expect(true.xref?).to be false
+      expect(false.xref?).to be false
+    end
+  end
+end

data/spec/core_ext/date_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+module Ydl
+  RSpec.describe 'Date extensions' do
+    it 'can detect if it is a cross-ref' do
+      expect(Date.today.xref?).to be false
+    end
+  end
+end

data/spec/core_ext/hash_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module Ydl
+  RSpec.describe Hash do
+    it 'can be topologically sorted if values are arrays' do
+      hash_a = {:a => [:d], :b => [:d, :c], :c => [],
+                :d => [:g, :h], :g => [], :h => []}
+      expect(hash_a.tsort).to eq([:g, :h, :d, :a, :c, :b])
+    end
+
+    it 'can tell its not a cross-ref' do
+      hash_a = {:a => [:d], :b => [:d, :c], :c => [],
+                :d => [:g, :h], :g => [], :h => []}
+      expect(hash_a.xref?).to be false
+      hash_b = {:a => true, :b => 'ydl:hello/world'}
+      expect(hash_b.xref?).to be true
+    end
+  end
+end

data/spec/core_ext/numeric_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+module Ydl
+  RSpec.describe 'Numeric extensions' do
+    it 'can detect if it is a cross-ref' do
+      require 'bigdecimal'
+      expect(25.xref?).to be false
+      expect(3.14159.xref?).to be false
+      expect(BigDecimal('18.578').xref?).to be false
+      expect(Rational(2, 3).xref?).to be false
+    end
+  end
+end

data/spec/core_ext/string_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+module Ydl
+  RSpec.describe 'String extensions' do
+    it 'can detect if it is a cross-ref' do
+      expect('hello, world'.xref?).to be false
+      expect('   ydl:this/is/a/cross-reference '.xref?).to be true
+      expect('   ydl:/this/is/a/cross-reference '.xref?).to be true
+    end
+
+    it 'can determine whether it is singular' do
+      expect('person'.singular?).to be true
+      expect('people'.singular?).to be false
+      expect('dogs'.singular?).to be false
+      expect('dog'.singular?).to be true
+      expect('sheep'.singular?).to be true
+    end
+
+    it 'can determine whether it is plural' do
+      expect('person'.plural?).to be false
+      expect('people'.plural?).to be true
+      expect('dogs'.plural?).to be true
+      expect('dog'.plural?).to be false
+      expect('sheep'.plural?).to be false
+    end
+  end
+end

data/spec/example_files/err/person_err.ydl

@@ -0,0 +1,6 @@
+person:
+  name: Daniel E. Doherty
+  hobbies:
+    - ruby programming
+    + hello
+    - bicycling

data/spec/example_files/home/user/.ydl/config_template.yaml

@@ -0,0 +1,40 @@
+# You can set the system-wide ydl directory here; otherwise it defaults to
+# /usr/local/share/ydl.
+
+# system_ydl_dir: /usr/local/share/ydl
+
+# For automatic instantiation, search for classes prefixed by the given modules
+# in the order given. For example, if the key 'breed' is to be instantiated, you
+# can restrict the search for classes named 'Breed' only in modules, 'Dog' and
+# 'Cat' with this:
+#
+#   class_modules
+#     - Dog
+#     - Cat
+#
+# then, only Dog::Breed and Cat::Breed will be searched for an existing breed
+# class. Otherwise, any class ending in Breed could be used, and they will be
+# searched in alphabetical order, and the first found will be used.  A blank
+# value means to consider classes in the main, global module level.  You can
+# always disambiguate the class selected with the class_map option below.
+
+class_modules:
+  -
+  - LawDoc
+  - Company::Employee
+
+# By default, each key will be camelized and singularized to find the matching
+# class. So, the key 'dogs' will look for a class named 'Dog', and 'dog_faces'
+# will look for a class 'DogFace'. You can override this heuristic here by
+# saying exactly which class a given key should map to.
+
+class_map:
+  address: LawDoc::Address
+  persons: LawDoc::Person
+  fax: LawDoc::Phone
+
+# Specify constructors for classes whose .new method will not take a Hash as an
+# argument to initialize the class.
+
+class_init:
+  LawDoc::Person: from_hash

data/spec/example_files/home/user/.ydl/courts/courts.ydl

@@ -0,0 +1,28 @@
+sdny:
+  name: United States District Court for the Southern District of New York
+  address:
+    street: '40 Centre Street'
+    city: 'New York'
+    state: 'NY'
+    zip: '10007--1581'
+  division: 'Centre Street'
+  state: 'NY'
+
+dco:
+  name: 'United States District Court for the District of Colorado'
+  address:
+    street: '901 19th Street, Room A105'
+    city: 'Denver'
+    state: 'CO'
+    zip: '80294-3589'
+  state: 'CO'
+
+jocolimited:
+  name: 'District Court for Johnson County, Kansas'
+  address:
+    street: '100 N. Kansas Ave'
+    city: 'Olathe'
+    state: 'KS'
+    zip: '66061'
+  division: '61, Room 222'
+  state: 'KS'

data/spec/example_files/home/user/.ydl/lawyers.ydl

@@ -0,0 +1,40 @@
+# This is a comment
+ded:
+  sex: male
+  last: Doherty
+  first: Daniel
+  middle: E.
+  address:
+    street: 7300 W. 110th Street, Suite 930
+    city: Overland Park
+    state: KS
+    zip: 66210
+  phone: 913-338-7182
+  fax: 913-338-7182
+  email: ded-law@ddoherty.net
+  bar_numbers:
+    KS: "12761"
+    MO: "33482"
+    NY: "DD-2145"
+  esig: /s/ Daniel E. Doherty
+  sig: "\\DEDSig"
+
+cjh:
+  sex: male
+  last: Hyland
+  first: Charles
+  middle: J.
+  address:
+    street: 7300 W. 110th Street, Suite 930
+    city: Overland Park
+    state: KS
+    zip: "66210"
+  phone: 913-338-7182
+  fax: 913-338-7182
+  email: charlie@hylandlawkc.com
+  bar_numbers:
+    KS: "12761"
+    MO: "33482"
+    NY: "DD-2145"
+  esig: /s/ Charles J. Hyland
+  sig: "\\CJHSig"

data/spec/example_files/home/user/.ydl/persons.ydl

@@ -0,0 +1,9 @@
+revive:
+  sex: entity
+  name: Revive Investing LLC
+
+mdg:
+  sex: male
+  first: Michael
+  middle: D.
+  last: Gibbons

data/spec/example_files/home/user/project/cases.ydl

@@ -0,0 +1,59 @@
+erickson:
+  number: 14-CV-09061
+  complaint_date: 2014-11-17
+  court: ydl:/courts/sdny
+  judge: ydl:/judges/kbf
+  parties:
+    -
+      person: ydl:/persons/mdg
+      role: Plaintiff
+      lawyers:
+        - ydl:/lawyers/ded
+        - ydl:/lawyers/cjh
+    -
+      person: ydl:/persons/revive
+      role: Plaintiff
+      lawyers: ydl:/cases/erickson/parties/0/lawyers
+    -
+      person: ydl:/persons/morgan
+      role: Defendant
+      lawyers:
+        - ydl:/lawyers/rjones
+        - ydl:/lawyers/mcrisp
+        - ydl:/lawyers/tfarrell
+    -
+      person: ydl:/persons/zmpef1
+      role: Defendant
+      lawyers:
+        - ydl:/lawyers/rjones
+        - ydl:/lawyers/mcrisp
+        - ydl:/lawyers/tfarrell
+    -
+      person: ydl:/persons/zmpef2
+      role: Defendant
+      lawyers:
+        - ydl:/lawyers/rjones
+        - ydl:/lawyers/mcrisp
+        - ydl:/lawyers/tfarrell
+    -
+      person: ydl:/persons/erickson
+      role: Nominal Defendant
+      lawyers:
+        - ydl:/lawyers/dclarke
+        - ydl:/lawyers/jclarke
+
+mainstreet:
+  court: ydl:/courts/jocolimited
+  number: 21LA04135
+  judge: ydl:/judges/vokins
+  parties:
+    -
+      person: ydl:/persons/tdoherty
+      role: Defendant
+      lawyers:
+        - ydl:/lawyers/ded
+    -
+      person: ydl:/persons/mainstreet
+      role: Plaintiff
+      lawyers:
+        - ydl:/lawyers/pittenger

data/spec/example_files/home/user/project/courts.ydl

@@ -0,0 +1,7 @@
+sdny:
+  name: United States District Court for the Southern District of New York
+  address:
+    street: 40 Centre Street
+    city: New York
+    state: NY
+    zip: '10007-1581'

data/spec/example_files/home/user/project/judges.ydl

@@ -0,0 +1,27 @@
+kbf:
+  sex: female
+  hon: Hon.
+  first: Katherine
+  middle: B.
+  last: Forrest
+  initials: KBF
+  title: District Court Judge
+  address:
+    street:
+      - United States Courthouse
+      - 500 Pearle Street, Room 1320
+    city: New York
+    state: NY
+    zip: '10007-1320'
+
+vokins:
+  name: Daniel W. Vokins
+  title: District Court Judge
+  initials: DWV
+  address:
+    street: '100 N. Kansas Ave'
+    city: 'Olathe'
+    state: 'KS'
+    zip: '66061'
+  phone: 913-715-3356
+  email: DCC-Chapter61@jocogov.org

data/spec/example_files/home/user/project/lawyers.ydl

@@ -0,0 +1,52 @@
+# This is a comment
+ded:
+  sex: male
+  last: Doherty
+  first: Daniel
+  middle: E.
+  address:
+    street: 7300 W. 110th Street, Suite 930
+    city: Overland Park
+    state: KS
+    zip: 66210
+  phone: 913-338-7182
+  fax: 913-338-7182
+  email: ded-law@ddoherty.net
+  bar_numbers:
+    KS: "12761"
+    MO: "33482"
+    NY: "DD-2145"
+  esig: /s/ Daniel E. Doherty
+  sig: "\\DEDSig"
+
+cjh:
+  sex: male
+  last: Hyland
+  first: Charles
+  middle: J.
+  address:
+    street: 7300 W. 110th Street, Suite 930
+    city: Overland Park
+    state: KS
+    zip: "66210"
+  phone: 913-338-7182
+  fax: 913-338-7182
+  email: charlie@hylandlawkc.com
+  bar_numbers:
+    KS: "12761"
+    MO: "33482"
+    NY: "DD-2145"
+  esig: /s/ Charles J. Hyland
+  sig: "\\CJHSig"
+
+pittenger:
+  name: Brandon T. Pittenger
+  address:
+    street:
+      - 6900 College Blvd., Suite 325
+    city: Overland Park
+    state: KS
+    zip: 66211
+  phone: (913) 323-4595
+  fax: (913) 661-1747
+  email: pittengerlawgroup@pittengerlawgroup.com

data/spec/example_files/home/user/project/persons.ydl

@@ -0,0 +1,5 @@
+mainstreet:
+  name: Mainstreet Credit Union
+
+tdoherty:
+  name: Timothy M. Doherty