ydl 0.2.06

data/examples/test_page.tex

@@ -0,0 +1,76 @@
+\documentclass{article}
+
+\usepackage{setspace}
+\usepackage{array}
+\usepackage{longtable}
+\usepackage{yfonts}
+\usepackage{calc}
+\usepackage[showframe]{geometry}
+
+\begin{document}
+
+\setlength\extrarowheight{12pt}%
+\newlength{\ldhalfwd}
+\setlength{\ldhalfwd}{((\textwidth) * \real{0.95} - \columnsep)/2}%
+
+\def\ol{%
+%\begin{small}
+  \begin{longtable}{p{\ldhalfwd}p{\ldhalfwd}}%
+    \parbox[t]{\ldhalfwd}{
+      \textsc{Daniel E. Doherty}\\
+Commerce Plaza I\\
+7300 W. 110th Street, Suite 930\\
+Overland Park, KS 66210\\
+\textbf{Phone:} 913-338-7182\\
+\textbf{Fax:} 913-338-7164\\
+\textbf{Email:} \texttt{ded-law@ddoherty.net}\\
+Attorney for Lisa A. Gibbons and Revive Investing LLC
+    }&
+    \parbox[t]{\ldhalfwd}{
+      \textsc{Charles J. Hyland}\\
+Commerce Plaza I\\
+7300 W. 110th Street, Suite 930\\
+Overland Park, KS 66210\\
+\textsc{Hyland Law Firm LLC}\\
+\textbf{Phone:} 913-498-1911\\
+\textbf{Fax:} 913-498-1950\\
+\textbf{Email:} \texttt{charlie@hylandkc.com}\\
+Attorney for Lisa A. Gibbons and Revive Investing LLC
+    }\\
+  \end{longtable}
+%\end{small}
+}
+
+  \thispagestyle{empty}
+  \setcounter{page}{-1}
+  {PreCaption}
+  \begin{center}
+    \hrule
+    \vspace{10pt}
+    \vfil
+    {\Large\gothfamily In th{e}\\
+      {\LARGE ForumName:}}
+    \vfil
+    \hrule
+    \vfil
+    LeftCaptionBlock
+    \vfil
+    \hrule
+    \vfil
+    \textbf{OriginatingCourt}
+    \vfil
+    \hrule
+    \vfil
+    \textsc{\bfseries DocTitle}
+    \vfil
+    \hrule
+    \vfil
+    \begin{singlespace}
+      \mbox{\ol}
+    \end{singlespace}
+    \vfil
+    \vspace{10pt}
+    \hrule
+  \end{center}
+  \clearpage
+\end{document}

data/lib/ydl/core_ext/array.rb

@@ -0,0 +1,6 @@
+# Extension of Array class.
+class Array
+  def xref?
+    select { |v| v.is_a?(String) }.any?(&:xref?)
+  end
+end

data/lib/ydl/core_ext/array_refine.rb

@@ -0,0 +1,16 @@
+module Ydl
+  # Extensions for Array class
+  module ArrayRefinements
+    refine Array do
+      # Return true of this array has other as a prefix.  If self is [:a, :b,
+      # :c, :d], then other is a prefix if it consists of elements equal to
+      # the corresponding element of self through other's whole length.
+      def prefixed_by(other)
+        return false if other.length > length
+
+        residuals = zip(other).drop_while { |(a, b)| a == b }
+        residuals.empty? || residuals.all? { |(a, b)| !a.nil? && b.nil? }
+      end
+    end
+  end
+end

data/lib/ydl/core_ext/boolean.rb

@@ -0,0 +1,13 @@
+# Add xref? to booleans.
+class TrueClass
+  def xref?
+    false
+  end
+end
+
+# Add xref? to booleans.
+class FalseClass
+  def xref?
+    false
+  end
+end

data/lib/ydl/core_ext/date.rb

@@ -0,0 +1,6 @@
+# Add xref? to Date.
+class Date
+  def xref?
+    false
+  end
+end

data/lib/ydl/core_ext/hash.rb

@@ -0,0 +1,16 @@
+require 'tsort'
+
+# Extend Hash for use with TSort and add xref?.
+class Hash
+  include TSort
+
+  alias tsort_each_node each_key
+
+  def tsort_each_child(node, &block)
+    fetch(node).each(&block)
+  end
+
+  def xref?
+    values.select { |v| v.is_a?(String)}.any?(&:xref?)
+  end
+end

data/lib/ydl/core_ext/numeric.rb

@@ -0,0 +1,6 @@
+# Add xref? to Numerics.
+class Numeric
+  def xref?
+    false
+  end
+end

data/lib/ydl/core_ext/string.rb

@@ -0,0 +1,16 @@
+require 'active_support/core_ext/string'
+
+# Some useful monkey patching for Ydl
+class String
+  def singular?
+    singularize == self
+  end
+
+  def plural?
+    !singular?
+  end
+
+  def xref?
+    clean.match?(%r{\Aydl:/?})
+  end
+end

data/lib/ydl/core_ext.rb

@@ -0,0 +1,7 @@
+require 'ydl/core_ext/array'
+require 'ydl/core_ext/array_refine'
+require 'ydl/core_ext/boolean'
+require 'ydl/core_ext/date'
+require 'ydl/core_ext/hash'
+require 'ydl/core_ext/numeric'
+require 'ydl/core_ext/string'

data/lib/ydl/errors.rb

@@ -0,0 +1,5 @@
+module Ydl
+  class UserError < RuntimeError; end
+  class CircularReference < RuntimeError; end
+  class BadXRef < RuntimeError; end
+end

data/lib/ydl/node.rb

@@ -0,0 +1,190 @@
+module Ydl
+  # A Node in a Ydl::Tree
+  class Node
+    attr_reader :path, :tree_id
+    attr_accessor :val, :klass, :children
+
+    def initialize(path, val, klass = nil, tree_id:)
+      # The path is an array of symbols representing the series of references
+      # taken from the root of the tree to this Node.
+      @path = path
+      # The Object id for the root Node of the tree of which this Node is a
+      # part.
+      @tree_id = tree_id
+      # The uninterpreted value for this Node, which when instantiated, will
+      # be an instance of klass.  Either a Hash or a primitive type.
+      @val = val
+
+      # The class into which this Node should be instantiated.
+      @klass = klass
+      # child Nodes built from val; always a Hash, but keys may be numeric
+      # symbols, such a :'1', :'88', etc, where an sequential array-like
+      # structure is wanted.
+      @children = {}
+    end
+
+    # Return a reference to the Ydl::Tree to which this Node belongs, in case we
+    # instantiate more than one tree.
+    def our_tree
+      ObjectSpace._id2ref(tree_id)
+    end
+
+    # Return an Array of the
+    def prerequisites
+      result = []
+      if children.size.positive?
+        children.each_value do |child|
+          result += child.prerequisites
+        end
+      elsif val.instance_of?(String)
+        result << val if val.xref?
+      end
+      result.flatten
+    end
+
+    # Return the /val/ of child at key +key+ or nil if there is none
+    def [](key)
+      return nil if children.empty?
+
+      key = key.to_s.to_sym if key.is_a?(Numeric)
+      children[key]
+    end
+
+    # Return the xref for this Node.
+    def xref
+      Tree.path_to_xref(path)
+    end
+
+    # Record a dependency of this Node on a foreign Node by virtue of a
+    # cross-reference to the foreign Node.  The argument foreign can be a
+    # string in the form of a Node xref or an array of xrefs.
+    def depends_on(foreign)
+      our_tree.workq.add_dependency(xref, foreign) unless foreign.empty?
+    end
+
+    # Convert this Node's children to a Hash or Array.
+    def to_params
+      return {} if children.empty?
+
+      make_arr = children.keys.map(&:to_s).all? { |k| k =~ /\A[0-9]+\z/ }
+      result = make_arr ? [] : {}
+
+      children.each_pair do |k, child|
+        k = make_arr ? k.to_s.to_i : k
+        result[k] =
+          if child.children.empty? || child.instantiated?
+            child.val
+          else
+            child.to_params
+          end
+      rescue TypeError
+        warn "ydl: cannot convert #{path} with value '#{child.val}' to params"
+      end
+      result
+    end
+
+    # Recursively build the subtree of Nodes starting at this Node and set
+    # this node's instance variables.
+    #
+    # This Node's val is either (1) a String (not a cross-reference), (2) a
+    # String that is a cross reference, in which case we need to record its
+    # dependence on the referenced node in the Tree.workq, (3) a Hash in which
+    # case its elements become the children of this Node and should have their
+    # klass set to the class corresponding to this Node's last path key if
+    # it's a registered class, or (4) an Array, in which case its elements
+    # become the children of this Node converted into a Hash (with their
+    # numeric indices as keys) and its children have their klass set as with a
+    # Hash.
+    def build_subtree
+      child_klass = Ydl.class_for(path.last) unless path.empty?
+      case val
+      when Hash
+        warn "Build from Hash for class '#{child_klass}': #{val.keys.join('|')}" if child_klass
+        # Build child subtrees first
+        val.each_pair do |k, v|
+          # If this node names a registered class, its /children/ should be
+          # instantiated into that class, but this node itself should not be.
+          # E.g., if this node's path ends in :persons, then it is a container
+          # for the class Person, and its children should be instantiated into
+          # that class, but not the container itself.  This node may also
+          # simply represent a parameter for a class above it, e.g., :name,
+          # for a Person class.  We set the klass of the child to nil if it is
+          # either a container node or a parameter node, but we set it to the
+          # class if it is to be instantiated.
+          child = Node.new(path + [k], v, child_klass, tree_id: tree_id)
+          # Depth-first recursion on building the Tree.
+          children[k] = child.build_subtree
+        end
+        # Record the cross-reference dependencies for this Node
+        depends_on(prerequisites)
+        self.val = nil
+      when Array
+        warn "Build from Array for class '#{child_klass}'" if child_klass
+        val.each_with_index do |v, k|
+          child = Node.new(path + [k.to_s.to_sym], v, child_klass, tree_id: tree_id)
+          children[k.to_s.to_sym] = child.build_subtree
+        end
+        depends_on(prerequisites)
+        self.klass = nil
+        self.val = nil
+      when String
+        if val.xref?
+          warn "Noted cross-reference to '#{xref}'"
+          depends_on(val)
+        else
+          self.klass = String
+        end
+        self.children = {}
+      else
+        # E.g., Numeric, Date, DateTime
+        self.children = {}
+        self.klass = val.class
+      end
+      self
+    end
+
+    # Return an object of class @klass if one can be initialized with the Hash
+    # val or the current Node converted to a params hash.
+    def instantiate
+      return nil if klass.blank?
+      return val if instantiated?
+
+      warn "Instantiating #{path} to #{klass} ..."
+      result =
+        if val.instance_of?(Hash)
+          klass.send(konstructor, **val)
+        else
+          klass.send(konstructor, **to_params)
+        end
+      warn "Instantiated #{path} to #{klass}" if result
+      self.val = result
+    end
+
+    def instantiated?
+      klass && val.instance_of?(klass)
+    end
+
+    # Do a depth-first instantiation of this node's children, then this node.
+    def instantiate_subtree
+      children.each_value do |child|
+        next if child.instantiated?
+
+        child.val =
+          if child.children.empty?
+            child.instantiate
+          else
+            child.instantiate_subtree
+          end
+      end
+      self.val = instantiate
+    end
+
+    # Return a symbol for the constructor method for klass: either :new or the
+    # user-defined constructor from the config.
+    def konstructor
+      return nil if klass.blank?
+
+      Ydl.class_init(klass.to_s)
+    end
+  end
+end

data/lib/ydl/top_queue.rb

@@ -0,0 +1,40 @@
+module Ydl
+  # A class for keeping track of dependencies among nodes in a Ydl::Tree caused
+  # by the use of cross-references. This class collects those dependencies with
+  # #add_dependency and can return a "total ordering" consistent with the
+  # dependencies with its #tsort method.
+  class TopQueue
+    def initialize
+      @dependencies = {}
+    end
+
+    def add_dependency(dependent, depends_on)
+      depends_on =
+        case depends_on
+        when Array
+          depends_on
+        else
+          [depends_on]
+        end
+      @dependencies[dependent] ||= []
+      @dependencies[dependent] += depends_on
+      # Add an empty dependency for all the depends_on members; the TSort
+      # module expects this to indicate that the ref depends on nothing else.
+      depends_on.each do |ref|
+        @dependencies[ref] = [] unless @dependencies.key?(ref)
+      end
+      self
+    end
+
+    def print_out
+      puts 'Dependencies:'
+      pp @dependencies.tsort
+    end
+
+    def topological_xrefs
+      @dependencies.tsort
+    rescue TSort::Cyclic => e
+      raise Ydl::CircularReference, e.to_s
+    end
+  end
+end

data/lib/ydl/tree.rb

@@ -0,0 +1,95 @@
+module Ydl
+  # The Tree class holds the data read from the .ydl files while any
+  # cross-references are being resolved and objects are being instantiated.
+  # After all that work is done, its nodes are merged into the main Ydl.data
+  # hash to be referenced by the application.
+  class Tree
+    attr_reader :tree_id, :root, :workq
+
+    # A new Tree is initialized with a Hash, which is itself a tree structure,
+    # but not of instantiated classes of the type we want.  The nodes of the
+    # input hash will be basic ruby objects such as Strings, Dates, Numerics,
+    # and so forth, just as they are read from the ydl files by Psych.  Some
+    # of the String objects will be in the form of cross-references to other
+    # parts of this tree, or of other trees that my not even exist at the time
+    # this one is being built.
+    def initialize(hsh)
+      @tree_id = object_id
+      @root = Node.new([], hsh, tree_id: @tree_id)
+      # A Queue of unresolved Nodes as a Hash keyed by the path to the dependent
+      # nodes with a value of the nodes on which that node depends.
+      @workq = Ydl::TopQueue.new
+      # Depth-first recursive build and instantiation of root node
+      # cross reference paths.
+      @root.build_subtree
+      instantiate
+    end
+
+    def inspect
+      "Tree<#{object_id}> with top-level keys: #{@root.children.keys.join(', ')}"
+    end
+
+    def to_hash
+      @root.to_params
+    end
+
+    # Resolution.  Note: a 'xref' means a string of the form
+    # 'ydl:/path/to/other/object' referencing an object in another part of the
+    # root tree.  A 'path' is an Array of Symbols such as [:path, :to, :other,
+    # :object], which can correspond to an xref and vice-versa.  A 'node'
+    # means a ruby reference to the object instatiated at some path.
+
+    # Instantiate nodes in the tree in the order of any cross-references,
+    # topologically sorted.  That is, instantiate those on which others depend
+    # first, and those dependent on earlier nodes last.
+    def instantiate
+      workq.topological_xrefs.each do |ref|
+        node = node_at_xref(ref)
+        if node.val.instance_of?(String) && node.val.xref?
+          node.val = node_at_xref(node.val).val
+        else
+          node.instantiate
+        end
+      end
+      @root.instantiate_subtree
+      self
+    end
+
+    # Return the Ydl::Node at path in Ydl.data or nil if there is no node at
+    # the given path.
+    def node_at_path(path)
+      node = @root
+      partial_path = []
+      path.each do |key|
+        if node[key].nil?
+          xref = Tree.path_to_xref(path)
+          pxref = Tree.path_to_xref(partial_path)
+          klass = node.klass
+          msg = "can\'t resolve cross-ref '#{xref}' beyond #{klass} object '#{pxref}'"
+          raise Ydl::BadXRef, msg
+        end
+        partial_path << key
+        node = node[key]
+      end
+      node
+    end
+
+    # Return the Node referenced by the given xref string
+    def node_at_xref(xref)
+      node_at_path(Tree.xref_to_path(xref))
+    end
+
+    # Return an Array of symbols representing a the path described by a ydl xref
+    # string. Return nil if str is not an xref string.
+    def self.xref_to_path(xref)
+      match = xref.to_s.clean.match(%r{\Aydl:/(?<path_str>.*)\z})
+      return nil unless match
+
+      match[:path_str].split('/').map(&:to_sym)
+    end
+
+    def self.path_to_xref(path)
+      "ydl:/#{path.map(&:to_s).join('/')}"
+    end
+  end
+end

data/lib/ydl/version.rb

@@ -0,0 +1,3 @@
+module Ydl
+  VERSION = '0.2.06'.freeze
+end