card 1.91 → 1.92

data/lib/card/mod/dirs.rb

@@ -1,9 +1,58 @@
 class Card
+
+  class << self
+    def config
+      Cardio.config
+    end
+
+    def paths
+      Cardio.paths
+    end
+  end
+
   module Mod
+    # Dirs objects are used to manage the load paths for card mods.
+    # Mods can be loaded as gems and by using directories with mod subdirectories.
+    #
+    # 1. Gemfile
+    # A mod gem needs a metadata attribute with { "card-mod" => "the_mod_name" }
+    # or the name has to start with "card-mod-".
+    # Then you can just add it to your Gemfile. Otherwise it won't be recognized as mod.
+    #
+    # 2. mod directory
+    # Give a path to a directory with mods. The mods will be loaded in alphabetical order.
+    # To change the load order you can add number prefixes to the mod names
+    # (like "01_this_first") or add a Modfile.
+    # In the Modfile you list all the mods you want to be loaded from that directory
+    # in load order with a preceding "mod" command (similar to a Gemfile).
+    # The mods are expected in subdirectories with the mod names.
+    #
+    # Example for a mod directory:
+    #   # my_mod/Modfile
+    #   mod "twitter"
+    #   mod "cache"
+    #
+    #   # directory structure
+    #   my_mods/
+    #     Modfile
+    #     cache/
+    #       set/
+    #         all/
+    #           my_cache.rb
+    #     twitter/
+    #       set/
+    #         type/
+    #           basic.rb
+    #       set_pattern/
+    #         my_pattern.rb
+    #
+    # Dir checks always for gems. You can initialize an Dirs object with an additional
+    # array of paths to card mod directories.
     class Dirs < Array
       attr_reader :mods
 
-      def initialize mod_paths
+      # @param mod_paths [String, Array<String>] paths to directories that contain mods
+      def initialize mod_paths=[]
         @mods = []
         @paths = {}
         mod_paths = Array(mod_paths)
@@ -11,28 +60,35 @@ class Card
           @current_path = mp
           load_from_modfile || load_from_dir
         end
+        load_from_gemfile
         super()
         @mods.each do |mod_name|
           self << @paths[mod_name]
         end
       end
 
-      # add a new mod to mod load paths
-      def add_path mod_name
+      # Add a mod to mod load paths
+      def add_path mod_name, path=nil
         if @mods.include? mod_name
           raise Error,
                 "name conflict: mod with name \"#{mod_name}\" already loaded"
         end
         @mods << mod_name
-        @paths[mod_name] = File.join @current_path, mod_name
+        path ||= File.join @current_path, mod_name
+        @paths[mod_name] = path
       end
 
       alias_method :mod, :add_path
 
+      # @param mod_name [String] the name of a mod
+      # @return the path to mod `mod_name`
       def path mod_name
         @paths[mod_name]
       end
 
+      # Iterate over each mod directory
+      # @param type [Symbol] the type of modification like set, set_pattern, or format.
+      #   It is attached as subdirectory.
       def each type=nil
         super() do |path|
           dirname = type ? File.join(path, type.to_s) : path
@@ -72,6 +128,19 @@ class Card
         end.compact
       end
 
+      def load_from_gemfile
+        Bundler.definition.specs.map do |s|
+          mod_name =
+            if s.name =~ /^decko-mod-(.+)$/
+              $1
+            else
+              s.metadata["card-mod"]
+            end
+          next unless mod_name
+          add_path $1, s.full_gem_path
+        end.compact
+      end
+
       def tmp_dir modname, type
         index = @mods.index modname
         File.join Card.paths["tmp/#{type}"].first,

data/lib/card/mod/load_strategy.rb

@@ -0,0 +1,64 @@
+require_relative "load_strategy/eval"
+require_relative "load_strategy/pattern_tmp_files"
+require_relative "load_strategy/set_binding_magic"
+require_relative "load_strategy/set_tmp_files"
+require_relative "load_strategy/tmp_files"
+
+class Card
+  module Mod
+    # Shared code for the three different load strategies: Eval, TmpFiles and BindingMagic
+    class LoadStrategy
+
+      def self.klass symbol
+        case symbol
+          when :tmp_files     then TmpFiles
+          when :binding_magic then BindingMagic
+          else                     Eval
+        end
+      end
+
+      def initialize mod_dirs, loader
+        @mod_dirs = mod_dirs
+        @loader = loader
+      end
+
+      private
+
+      def module_type
+        @loader.class.module_type
+      end
+
+      def module_template
+        @loader.class.module_class_template
+      end
+
+      def each_file &block
+        @mod_dirs.each module_type do |base_dir|
+          if module_type == :set
+            # I'm not sure if we really need this ordering by pattern for sets -pk
+            Card::Set::Pattern.in_load_order.each do |pattern|
+              each_file_in_dir base_dir, pattern.to_s, &block
+            end
+          else
+            each_file_in_dir base_dir, &block
+          end
+        end
+      end
+
+      def each_file_in_dir base_dir, subdir=nil
+        pattern = File.join(*[base_dir, subdir, "**/*.rb"].compact)
+        Dir.glob(pattern).sort.each do |abs_path|
+          rel_path = abs_path.sub("#{base_dir}/", "")
+          const_parts = parts_from_path rel_path
+          yield abs_path, const_parts
+        end
+      end
+
+      def parts_from_path path
+        # remove file extension and number prefixes
+        parts = path.gsub(/\.rb/, "").gsub(%r{(?<=\A|/)\d+_}, "").split(File::SEPARATOR)
+        parts.map &:camelize
+      end
+    end
+  end
+end

data/lib/card/mod/load_strategy/eval.rb

@@ -0,0 +1,16 @@
+class Card
+  module Mod
+    class LoadStrategy
+      # Put everything for the module definition in one string and the evaluate
+      # it immediately with ruby's eval method.
+      class Eval < LoadStrategy
+        def load_modules
+          each_file do |abs_path, module_names|
+            template = module_template.new module_names, abs_path
+            template.build
+          end
+        end
+      end
+    end
+  end
+end

data/lib/card/mod/load_strategy/pattern_tmp_files.rb

@@ -0,0 +1,29 @@
+class Card
+  module Mod
+    class LoadStrategy
+      # The {TmpFiles} load strategy version for set pattern modules/
+      class PatternTmpFiles < TmpFiles
+        private
+
+        def load_tmp_files
+          load_dir tmp_dir
+        end
+
+        def generate_tmp_files
+          prepare_tmp_dir "tmp/set_pattern"
+          seq = 100
+          each_file do |abs_path, const_parts|
+            pattern = const_parts.first
+            to_file = "#{tmp_dir}/#{seq}-#{pattern}.rb"
+            write_tmp_file abs_path, to_file, const_parts
+            seq += 1
+          end
+        end
+
+        def tmp_dir
+          Card.paths["tmp/set_pattern"].first
+        end
+      end
+    end
+  end
+end

data/lib/card/mod/load_strategy/set_binding_magic.rb

@@ -0,0 +1,48 @@
+class Card
+  module Mod
+    # Tries to build the module with as little string evaluation as possible.
+    # The problem here is that in methods like `module_eval` the Module.nesting
+    # list gets lost so all references in mod files to constants in the
+    # Card::Set namespace don't work.
+    # The solution is to construct a binding with the right Module.nesting list.
+    class BindingMagic < LoadStrategy
+      def load_modules
+        each_file do |abs_path, const_parts|
+          sm = SetModule.new const_parts, abs_path
+
+          set_module = sm.to_const
+          set_module.extend Card::Set unless sm.helper_module?
+          set_module.module_eval do
+            def self.source_location
+              abs_path
+            end
+          end
+
+          # Since module_eval doesn't take a binding argument, we have to
+          # execute module_eval with eval.
+          eval "#{set_module}.module_eval ::File.read('#{abs_path}'), '#{abs_path}'",
+               module_path_binding(set_module)
+        end
+      end
+
+      # Get a binding with a Module.nesting list that contains the
+      # given module and all of its containing modules as described
+      # by its fully qualified name in inner-to-outer order.
+      def module_path_binding mod
+        raise ArgumentError.new(
+          "Can't determine path nesting for a module with a blank name"
+        ) if mod.name.to_s.empty?
+        m, b = nil, TOPLEVEL_BINDING
+        mod.name.split('::').each do |part|
+          m, b =
+            eval(
+              "[ #{part} , #{part}.module_eval('binding') ]",
+              b
+            )
+        end
+        raise "Module found at name path not same as specified module" unless m == mod
+        b
+      end
+    end
+  end
+end

data/lib/card/mod/load_strategy/set_tmp_files.rb

@@ -0,0 +1,33 @@
+class Card
+  module Mod
+    class LoadStrategy
+      # The {TmpFiles} load strategy version for set modules
+      class SetTmpFiles < LoadStrategy::TmpFiles
+
+        private
+
+        def generate_tmp_files
+          return unless prepare_tmp_dir "tmp/set"
+          @mod_dirs.each_with_tmp(:set) do |mod_dir, mod_tmp_dir|
+            Dir.mkdir mod_tmp_dir
+            Dir.glob("#{mod_dir}/**/*.rb").each do |abs_path|
+              rel_path = abs_path.sub "#{mod_dir}/", ""
+              tmp_filename = File.join mod_tmp_dir, rel_path
+              const_parts = parts_from_path rel_path
+              write_tmp_file abs_path, tmp_filename, const_parts
+            end
+          end
+        end
+
+        def load_tmp_files
+          @mod_dirs.each_tmp(:set) do |set_tmp_dir|
+            Card::Set::Pattern.in_load_order.each do |pattern|
+              pattern_dir = "#{set_tmp_dir}/#{pattern}"
+              Loader.load_dir "#{pattern_dir}/**" if Dir.exist? pattern_dir
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/card/mod/load_strategy/tmp_files.rb

@@ -0,0 +1,38 @@
+class Card
+  module Mod
+    class LoadStrategy
+      # LoadStrategy for mod modules. It writes the code to tmp files
+      # and then loads the tmp files. (deprecated)
+      class TmpFiles < LoadStrategy
+        def load_modules
+          generate_tmp_files if rewrite_tmp_files?
+          load_temp_files
+        end
+
+        private
+
+        def prepare_tmp_dir path
+          return unless rewrite_tmp_files?
+          p = Card.paths[path]
+          FileUtils.rm_rf p.first, secure: true if p.existent.first
+          Dir.mkdir p.first
+        end
+
+        def rewrite_tmp_files?
+          if defined?(@rewrite)
+            @rewrite
+          else
+            @rewrite = !(Rails.env.production? &&
+              Card.paths["tmp/set"].existent.first)
+          end
+        end
+
+        def write_tmp_file from_file, to_file, const_parts
+          FileUtils.mkdir_p File.dirname(to_file)
+          mt = module_template.new const_parts, from_file
+          File.write to_file, mt.to_s
+        end
+      end
+    end
+  end
+end

data/lib/card/mod/loader.rb

@@ -2,37 +2,59 @@
 
 require_dependency "card/set"
 require_dependency "card/set_pattern"
+require_dependency "card/mod/loader/set_loader"
+require_dependency "card/mod/loader/set_pattern_loader"
 
 class Card
-  class << self
-    def config
-      Cardio.config
-    end
+  module Mod
+    # Card::Mod::Loader is used to load all part of a mod,
+    # i.e. initializers, patterns, formats, chunks, layouts and sets
+
+    # A Loader object provides tools for generating and loading sets and set patterns,
+    # each of which are typically written using a Decko DSL.
+
+    # The mods are given by a Mod::Dirs object.
+    # SetLoader can use three different strategies to load the set modules.
+
+    class Loader
+      def initialize(load_strategy=:eval, mod_dirs=nil)
+        mod_dirs ||= Mod.dirs
+        klass = load_strategy_class load_strategy
+        @load_strategy = klass.new mod_dirs, self
+      end
+
+      def load_strategy_class load_strategy
+        case load_strategy
+          when :tmp_files     then LoadStrategy::TmpFiles
+          when :binding_magic then LoadStrategy::BindingMagic
+          else                     LoadStrategy::Eval
+        end
+      end
+
+      def load
+        @load_strategy.load_modules
+      end
 
-    def paths
-      Cardio.paths
-    end
-  end
 
-  module Mod
-    module Loader
       class << self
+        attr_reader :module_type
+
         def load_mods
           load_initializers
-          load_set_patterns
+          SetPatternLoader.new.load
           load_formats
-          load_sets
+          SetLoader.new.load
         end
 
         def load_chunks
-          mod_dirs.each(:chunk) do |dir|
+          Mod.dirs.each(:chunk) do |dir|
             load_dir dir
           end
         end
 
         def load_layouts
           hash = {}
-          mod_dirs.each(:layout) do |dirname|
+          Mod.dirs.each(:layout) do |dirname|
             Dir.foreach(dirname) do |filename|
               next if filename =~ /^\./
               layout_name = filename.gsub(/\.html$/, "")
@@ -42,135 +64,28 @@ class Card
           hash
         end
 
-        def mod_dirs
-          @mod_dirs ||= Mod::Dirs.new(Card.paths["mod"].existent)
-        end
-
-        def refresh_script_and_style
-          update_if_source_file_changed Card[:all, :script]
-          update_if_source_file_changed Card[:all, :style]
+        def module_class_template
+          const_get :Template
         end
 
         private
 
-        # regenerates the machine output if a source file of a input card
-        # has been changed
-        def update_if_source_file_changed machine_card
-          return unless machine_card
-          mtime_output = machine_card.machine_output_card.updated_at
-          return unless mtime_output
-          regenerate = false
-          input_cards_with_source_files(machine_card) do |i_card, files|
-            files.each do |path|
-              next unless File.mtime(path) > mtime_output
-              i_card.expire_machine_cache
-              regenerate = true
-              break
-            end
-          end
-          return unless regenerate
-          machine_card.regenerate_machine_output
-        end
-
-        def input_cards_with_source_files card
-          card.machine_input_card.extended_item_cards.each do |i_card|
-            next unless i_card.codename
-            next unless i_card.respond_to?(:existing_source_paths)
-            yield i_card, i_card.existing_source_paths
-          end
-        end
-
-        def source_files card
-          files = []
-          card.machine_input_card.extended_item_cards.each do |i_card|
-            next unless i_card.codename
-            next unless i_card.respond_to?(:existing_source_paths)
-            files << i_card.existing_source_paths
-          end
-          files.flatten
-        end
-
         def load_initializers
-          Card.config.paths["mod/config/initializers"].existent
-              .sort.each do |initializer|
+          Card.config.paths["mod/config/initializers"].existent.sort.each do |initializer|
             load initializer
           end
         end
 
-        def load_set_patterns
-          generate_set_pattern_tmp_files if rewrite_tmp_files?
-          load_dir Card.paths["tmp/set_pattern"].first
-        end
-
-        def generate_set_pattern_tmp_files
-          prepare_tmp_dir "tmp/set_pattern"
-          seq = 100
-          mod_dirs.each(:set_pattern) do |dirname|
-            Dir.entries(dirname).sort.each do |filename|
-              m = filename.match(/^(\d+_)?([^\.]*).rb/)
-              key = m && m[2]
-              next unless key
-              filename = [dirname, filename].join("/")
-              Set::Pattern.write_tmp_file key, filename, seq
-              seq += 1
-            end
-          end
-        end
-
+        # {Card::Format}
         def load_formats
-          # cheating on load issues now by putting all inherited-from formats in
-          # core mod.
-          mod_dirs.each(:format) do |dir|
+          # cheating on load issues now by putting all inherited-from formats in core mod.
+          Mod.dirs.each(:format) do |dir|
             load_dir dir
           end
         end
 
-        def load_sets
-          generate_tmp_set_modules
-          load_tmp_set_modules
-          Set.process_base_modules
-          Set.clean_empty_modules
-        end
-
-        def generate_tmp_set_modules
-          return unless prepare_tmp_dir "tmp/set"
-          mod_dirs.each_with_tmp(:set) do |mod_dir, mod_tmp_dir|
-            Dir.mkdir mod_tmp_dir
-            Dir.glob("#{mod_dir}/**/*.rb").each do |abs_filename|
-              rel_filename = abs_filename.gsub "#{mod_dir}/", ""
-              tmp_filename = "#{mod_tmp_dir}/#{rel_filename}"
-              Set.write_tmp_file abs_filename, tmp_filename, rel_filename
-            end
-          end
-        end
-
-        def load_tmp_set_modules
-          patterns = Card.set_patterns.reverse.map(&:pattern_code)
-                         .unshift "abstract"
-          mod_dirs.each_tmp(:set) do |set_tmp_dir|
-            patterns.each do |pattern|
-              pattern_dir = "#{set_tmp_dir}/#{pattern}"
-              load_dir "#{pattern_dir}/**" if Dir.exist? pattern_dir
-            end
-          end
-        end
-
-        def prepare_tmp_dir path
-          return unless rewrite_tmp_files?
-          p = Card.paths[path]
-          FileUtils.rm_rf p.first, secure: true if p.existent.first
-          Dir.mkdir p.first
-        end
-
-        def rewrite_tmp_files?
-          if defined?(@rewrite)
-            @rewrite
-          else
-            @rewrite = !(Rails.env.production? &&
-                         Card.paths["tmp/set"].existent.first)
-          end
-        end
-
+        # load all files in directory
+        # @param dir [String] directory name
         def load_dir dir
           Dir["#{dir}/*.rb"].sort.each do |file|
             # puts Benchmark.measure("from #load_dir: rd: #{file}") {