loom-core 0.0.1

data/lib/loom/mods/module.rb

@@ -0,0 +1,113 @@
+module Loom::Mods
+
+  ModActionError = Class.new Loom::LoomError
+  InvalidModActionSignature = Class.new Loom::LoomError
+
+  class Module
+    attr_accessor :shell, :loom_config, :loom, :mods, :action_proxy
+
+    def initialize(shell, loom_config)
+      unless shell && shell.is_a?(Loom::Shell::Core)
+        raise "missing shell for mod #{self} => #{shell}"
+      end
+      unless loom_config && loom_config.is_a?(Loom::Config)
+        raise "missing config for mod #{self} => #{loom_config}"
+      end
+
+      @shell = shell
+      @loom = shell.shell_api
+      @mods = shell.mod_loader
+      @loom_config = loom_config
+
+      # The action proxy is a facade for the mod provided to patterns by the
+      # ShellApi (the 'loom' object). The ShellApi calls back to the mod_loader
+      # on method missing which instantiates a new Module object and returns the
+      # action_proxy.
+      @action_proxy = self.class.action_proxy self, shell.shell_api
+      @action_args = nil
+      @action_block = nil
+    end
+
+    def init_action(*args, &pattern_block)
+      @action_args = args
+      @action_block = pattern_block
+    end
+
+    def execute(*args, &pattern_block)
+      if respond_to? :mod_block
+        Loom.log.debug3(self) { "executing mod block => #{args} #{pattern_block}" }
+        mod_block *args, &pattern_block
+      else
+        Loom.log.debug3(self) { "initing action => #{args}" }
+        init_action *args, &pattern_block
+        action_proxy
+      end
+    end
+
+    class << self
+
+      def register_mod(name, **opts, &block)
+        Loom.log.debug2(self) { "registered mod => #{name}" }
+
+        if block_given?
+          Loom.log.debug2(self) { "acting as mod_block => #{name}:#{block}" }
+          define_method :mod_block, &block
+        end
+
+        # TODO: Currently registering a block for a mod is different than
+        # importing actions because of how the mod gets executed. When actions
+        # are imorted, the mod is treated as an object providing access to the
+        # actions (via the action_proxy), the action proxy is provided to the
+        # calling pattern via {#execute}. When a block is registered, then the
+        # mod is only a sinlge method executed immediately via #{execute}. The
+        # method signature for the block and action proxy method are the
+        # same... this should be simplified.
+        ModLoader.register_mod self, name, **opts
+      end
+
+      def required_commands(*cmds)
+        @required_commands ||= []
+        @required_commands.push *cmds unless cmds.empty?
+        @required_commands
+      end
+
+      def import_actions(action_module, namespace=nil)
+        action_module.instance_methods.each do |action_name|
+          bound_method_name = bind_action(
+            action_name, action_module.instance_method(action_name), namespace)
+
+          action_map.add_action action_name, bound_method_name, namespace
+        end
+      end
+
+      def bind_action(action_name, unbound_method, namespace=nil)
+        bound_method_name = [namespace, action_name].compact.join '_'
+
+        define_method bound_method_name do |*args, &block|
+          Loom.log.debug1(self) { "exec mod action #{self.class}##{bound_method_name}" }
+
+          bound_method = unbound_method.bind self
+          bound_method.call *args, &block
+        end
+        Loom.log.debug2(self) { "bound mod action => #{self.class.name}##{action_name}" }
+
+        bound_method_name
+      end
+
+      ##
+      # This needs more thought
+      def action_proxy(mod, shell_api)
+        @action_proxy_klasses ||= {}
+        @action_proxy_klasses[mod.class.hash] ||=
+          ActionProxy.subclass_for_action_map action_map
+        @action_proxy_klasses[mod.class.hash].new mod, shell_api
+      end
+
+      private
+      def action_map
+        @action_map ||= ActionProxy.new_action_map
+      end
+    end
+
+  end
+end

data/lib/loom/pattern.rb

@@ -0,0 +1,15 @@
+module Loom::Pattern
+
+  # DO NOT ADD METHODS TO THIS MODULE!!!
+
+  class << self
+    def included(pattern_mod)
+      Loom.log.debug2(self) { "pattern module loaded => #{pattern_mod}" }
+      pattern_mod.extend DSL
+    end
+  end
+
+  # DO NOT ADD METHODS TO THIS MODULE!!!
+end
+
+require_relative "pattern/all"

data/lib/loom/pattern/all.rb

@@ -0,0 +1,7 @@
+require_relative "dsl"
+require_relative "hook"
+require_relative "definition_context"
+require_relative "reference"
+require_relative "reference_set"
+require_relative "loader"
+require_relative "result_reporter"

data/lib/loom/pattern/definition_context.rb

@@ -0,0 +1,74 @@
+module Loom::Pattern
+
+  ##
+  # Pattern::DefinitionContext is the collection of facts, hooks, and
+  # parent contexts a pattern is defined along side of. The context
+  # includes all contexts of parent modules.
+  class DefinitionContext
+
+    def initialize(pattern_module, parent_context=nil)
+      @fact_map = pattern_module.facts.dup
+      @let_map = pattern_module.let_map.dup
+
+      @hooks = pattern_module.hooks.dup
+      @parent_context = parent_context
+
+      @merged_fact_map = merged_fact_map
+      @merged_let_map = merged_let_map
+    end
+
+    attr_reader :let_map, :fact_map, :hooks
+
+    ##
+    # Merges the facts defined by the pattern context with the host
+    # fact_set
+    def fact_set(host_fact_set)
+      host_fact_set.merge merged_fact_map
+    end
+
+    # TODO: #define_let_readers is a TERRIBLE name. Rename this method.
+    #
+    # The method is called by Reference#call with the Reference::RunContext
+    # instance. The "let" defined local declarations are added as method
+    # definitions on each RunContext instance. The @merged_let_map is the map of
+    # let definitions, merged from the associated module, up the namespace
+    # graph, allowing for inheriting and overriding +let+ declarations.
+    def define_let_readers(scope_object, fact_set)
+      @merged_let_map.each do |let_key, block|
+        raise "no let block" unless block
+        value = scope_object.instance_exec fact_set, &block
+        scope_object.define_singleton_method(let_key) { value }
+      end
+    end
+
+    def before_hooks
+      Hook.before_hooks merged_hooks
+    end
+
+    def after_hooks
+      Hook.after_hooks merged_hooks.reverse
+    end
+
+    private
+    def merged_fact_map
+      merged_contexts.map(&:fact_map).reduce({}) do |merged_map, next_map|
+        merged_map.merge! next_map
+      end
+    end
+
+    def merged_let_map
+      merged_contexts.map(&:let_map).reduce({}) do |merged_map, next_map|
+        merged_map.merge! next_map
+      end
+    end
+
+    def merged_hooks
+      return hooks if @parent_context.nil?
+      merged_contexts.map(&:hooks).flatten
+    end
+
+    def merged_contexts
+      [@parent_context, self].flatten.compact
+    end
+  end
+end

data/lib/loom/pattern/dsl.rb

@@ -0,0 +1,176 @@
+=begin
+
+# .loom File DSL
+
+Loom::Pattern::DSL is the mixin that defines the declarative API for all .loom
+file defined modules. It is included into Loom::Pattern by default. The outer
+most module that a .loom file declares has Loom::Pattern mixed in by
+default. Submodules must explicitly include Loom::Pattern, and will receive DSL.
+
+To follow the code path for .loom file loading see:
+
+    Loom::Runner#load
+      -> Loom::Pattern::Loader.load
+         -> Loom::Pattern::ReferenceSet.load_from_file
+            -> Loom::Pattern::ReferenceSet::Builder.create
+
+The Loom::Pattern::ReferenceSet::Builder creates a ReferenceSet from a .loom
+file. A ReferenseSet being a collection of references with uniquely named
+slugs. The slug of a reference is computed from the module namespace and
+instance method name. For example, given the following .loom file:
+
+``` ~ruby
+def top_level; end
+
+module Outer
+
+  desc 'The first pattern'
+  pattern :first do |loom, facts|; end
+
+  module Inner
+    desc 'The second pattern'
+    pattern :second do |loom, facts|; end
+  end
+end
+```
+
+It declares a reference set with slugs:
+
+* top_level
+* outer:first
+* outer:inner:second
+
+Defining the same pattern slug twice raises a DuplicatPatternRef error.
+
+Module Inner inherits all +let+ declarations from its outer contexts, both ::
+(root) and ::Outer. +before+ hooks are run from a top-down module ordering,
++after+ hooks are run bottom-up. For example, given the following .loom file:
+
+``` ~ruby
+let(:var_1) { "v1 value" }
+let(:var_2) { "v2 value" }
+
+before { puts "runs first +before+" }
+after { puts "runs last +after+" }
+
+def top_level; end
+
+module Submod
+  let(:var_1) { "submod value" }
+
+  before { puts "runs second +before+" }
+  after { puts "runs first +after+" }
+
+  pattern :a_pattern { |loom, facts}
+end
+```
+
+
+If running `loom submod:a_pattern`, then let declarations would declare values:
+
+    { :var_1 => "submod value", :var_2 => "v2 value" }
+
+Each let value is effectively available as an `attr_reader` declaration from
+::Submod#a_pattern. Before and After hook ordering with pattern execution would
+look like:
+
+    => runs first +before+
+      => runs second +before+
+        => `submod:a_pattern`
+      => runs first +after+
+    => runs last +after+
+
+For the code that executes before hooks, pattern, after hooks see
+Loom::Pattern::Reference::RunContext#run.
+
+The Loom::Pattern::Reference::RunContext acts as the the binding object for each
+pattern slug. i.e. When running a pattern slug, the RunContext is the self
+object. Let definitions, before and after hooks, and fact maps are unique to
+each RunContext, for each RunContext they are defined in the
+Loom::Pattern::DefinitionContext. Each DefinitionContext is merged from it's
+parent module, see Loom::Pattern::DefinitionContext#merge_contexts for info.
+
+The RunContext#run method is the actual execution of the pattern. A pattern,
+before association to a RunContext instance is an unbound method. During
+RunContext#initialize the pattern is bound to the RunContext instance and
+executed during RunContext#run with the associated Loom::Shell::Api and
+Loom::Facts::FactSet as parameters.
+
+=end
+module Loom::Pattern
+  module DSL
+
+    loom_accessor :namespace
+
+    def description(description)
+      @next_description = description
+    end
+    alias_method :desc, :description
+
+    def with_facts(**new_facts, &block)
+      @facts ||= {}
+      @facts.merge! new_facts
+      yield_result = yield @facts if block_given?
+      @facts = yield_result if yield_result.is_a? Hash
+    end
+
+    def let(name, &block)
+      @let_map ||= {}
+      @let_map[name.to_sym] = block
+    end
+
+    def pattern(name, &block)
+      Loom.log.debug3(self) { "defined pattern method => #{name}" }
+      @pattern_methods ||= []
+      @pattern_method_map ||= {}
+      @pattern_descriptions ||= {}
+
+      method_name = name.to_sym
+
+      @pattern_methods << method_name
+      @pattern_method_map[method_name] = true
+      @pattern_descriptions[method_name] = @next_description
+      @next_description = nil
+
+      define_method method_name, &block
+    end
+
+    def hook(scope, &block)
+      @hooks ||= []
+      @hooks << Hook.new(scope, &block)
+    end
+
+    def before(&block)
+      hook :before, &block
+    end
+
+    def after(&block)
+      hook :after, &block
+    end
+
+    def pattern_methods
+      @pattern_methods || []
+    end
+
+    def pattern_description(name)
+      @pattern_descriptions[name]
+    end
+
+    def pattern_method(name)
+      raise UnknownPatternMethod, name unless @pattern_method_map[name]
+      instance_method name
+    end
+
+    def hooks
+      @hooks || []
+    end
+
+    def facts
+      @facts || {}
+    end
+
+    def let_map
+      @let_map || {}
+    end
+  end
+end

data/lib/loom/pattern/hook.rb

@@ -0,0 +1,28 @@
+module Loom::Pattern
+  class Hook
+
+    class << self
+      def around_hooks(hooks)
+        hooks.find_all { |h| h.scope == :around }
+      end
+
+      def before_hooks(hooks)
+        hooks.find_all { |h| h.scope == :before }
+      end
+
+      def after_hooks(hooks)
+        hooks.find_all { |h| h.scope == :after }
+      end
+    end
+
+    def initialize(scope, &block)
+      unless [:before, :around, :after].include? scope
+        raise 'invalid Pattern::DSL hook scope'
+      end
+      @scope = scope
+      @block = block
+    end
+
+    attr_reader :scope, :block
+  end
+end

data/lib/loom/pattern/loader.rb

@@ -0,0 +1,48 @@
+module Loom::Pattern
+
+  SiteFileNotFound = Class.new Loom::LoomError
+
+  class Loader
+    class << self
+      def load(config)
+        loader = Loader.new config.files.loom_files
+        loader.load_patterns
+        loader
+      end
+    end
+
+    def initialize(pattern_files)
+      @loom_pattern_files = pattern_files
+      @reference_set = ReferenceSet.new
+    end
+
+    def slugs
+      @reference_set.slugs
+    end
+
+    def patterns(slugs=nil)
+      if slugs.nil?
+        @reference_set.pattern_refs
+      else
+        slugs.map { |slug| get_pattern_ref(slug) }
+      end
+    end
+
+    def get_pattern_ref(slug)
+      @reference_set[slug]
+    end
+    alias_method :[], :get_pattern_ref
+
+    def load_patterns
+      @loom_pattern_files.each do |f|
+        raise SiteFileNotFound, f unless File.exists? f
+        load_pattern_file f
+      end
+    end
+
+    private
+    def load_pattern_file(f)
+      @reference_set.merge! ReferenceSet.load_from_file(f)
+    end
+  end
+end