abid 0.3.0.pre.alpha.3 → 0.3.0.pre.alpha.4

data/lib/abid/dsl/job.rb

@@ -0,0 +1,58 @@
+require 'forwardable'
+
+module Abid
+  module DSL
+    # Common interface for RakeJob and AbidJob
+    class Job
+      extend Forwardable
+
+      def self.interface(name, args = [])
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}(#{args.join(', ')})
+          raise NotImplementedError
+        end
+        RUBY
+      end
+      private_class_method :interface
+
+      interface :name
+      interface :arg_names
+      interface :worker
+      interface :prerequisites
+      interface :execute, %w(args)
+
+      interface :volatile?
+      interface :concerned?
+      interface :needed?
+
+      def initialize(task, params)
+        @task = task
+        @params = params
+        @options = task.application.options
+      end
+      attr_reader :task, :params, :options
+      def_delegators :task, :name, :arg_names
+
+      def trace_invoke
+        return unless @task.application.options.trace
+        @task.application.trace "** Invoke #{@task.name}"
+      end
+
+      def to_s
+        ParamsFormat.format_with_name(name, params)
+      end
+
+      def repair?
+        @options.repair
+      end
+
+      def dryrun?
+        @options.dryrun
+      end
+
+      def preview?
+        @options.preview
+      end
+    end
+  end
+end

data/lib/abid/dsl/job_manager.rb

@@ -0,0 +1,53 @@
+require 'monitor'
+
+module Abid
+  module DSL
+    # JobManager manages jobs.
+    class JobManager
+      def initialize(application)
+        @app = application
+        @tasks = Hash.new { |h, k| h[k] = {} }
+        @mon = Monitor.new
+      end
+
+      # Resolves params using params_spec and bind the task and resolved params.
+      # @param name [String,Symbol] task name
+      # @param params [Hash]
+      # @param scope [Rake::Scope]
+      # @return [Abid::DSL::TaskInstance]
+      def [](name, params = {}, scope = nil)
+        task = @app[name, scope]
+        resolved = resolve_params(task, params)
+        bind(task.name, resolved)
+      end
+
+      # Binds the task and params.
+      # @param name [String,Symbol] task name
+      # @param params [Hash]
+      # @return [Abid::DSL::TaskInstance]
+      def bind(name, params)
+        return @tasks[name][params] if @tasks[name][params]
+
+        @mon.synchronize do
+          @tasks[name][params.dup.freeze] ||= @app[name].bind(params)
+        end
+      end
+
+      def resolve_params(task, params)
+        ret = task.params_spec.each_with_object({}) do |(key, spec), h|
+          h[key] = fetch_param(task, key, spec, params, @app.global_params)
+        end
+        ParamsFormat.validate_params!(ret)
+        ret
+      end
+
+      def fetch_param(task, key, spec, *params_list)
+        found = params_list.find { |params| params.include?(key) }
+        return found[key] if found
+        return spec[:default] if spec.include?(:default)
+        raise "#{task.name}: param #{key} is not specified"
+      end
+      private :fetch_param
+    end
+  end
+end

data/lib/abid/dsl/mixin.rb

@@ -0,0 +1,52 @@
+require 'abid/dsl/play_core'
+
+module Abid
+  module DSL
+    # `mixin` definition is evaluated in Mixin module context.
+    #
+    #     mixin :foo do
+    #       # this is evaluated in Mixin module context
+    #     end
+    #
+    module Mixin
+      # Create new Mixin object.
+      # @param task [Rake::Task] owner task
+      def self.create(task)
+        mod = self
+        Module.new do
+          include mod
+          extend Mixin::ClassMethods
+          include task.application.global_mixin
+          extend helpers
+          self.task = task
+        end
+      end
+
+      # Create new global mixin.
+      # `global_mixin` does not include Application#global_mixin.
+      def self.create_global_mixin
+        Module.new do
+          include Mixin
+          extend Mixin::ClassMethods
+        end
+      end
+
+      include PlayCore
+
+      module ClassMethods
+        include PlayCore::ClassMethods
+
+        def included(obj)
+          return unless obj.is_a? PlayCore::ClassMethods
+          merge_helpers(obj)
+        end
+
+        def merge_helpers(obj)
+          my_helpers = helpers
+          obj.helpers.module_eval { include my_helpers }
+          obj.extend(obj.helpers) # re-extend by helpers
+        end
+      end
+    end
+  end
+end

data/lib/abid/dsl/params_spec.rb

@@ -0,0 +1,64 @@
+module Abid
+  module DSL
+    # ParamsSpec manages params specifications declared in a play definition.
+    #
+    # Ancestors' params_spec are inherited.
+    class ParamsSpec
+      include Enumerable
+
+      attr_reader :specs
+      protected :specs
+
+      def initialize(play_class)
+        @play_class = play_class
+        @specs = {}
+      end
+
+      # @param key [Symbol] param name
+      # @return [Hash] param specification
+      def [](key)
+        @play_class.superplays.each do |sp|
+          h = sp.params_spec.specs
+          return h[key] if h.include?(key)
+        end
+        nil
+      end
+
+      # @param key [Symbol] param name
+      # @param val [Hash] param specification
+      def []=(key, val)
+        @specs[key] = val
+      end
+
+      # Mark given param as deleted.
+      # It does not affect ancestors' params_spec.
+      # @param key [Symbol] param name
+      def delete(key)
+        val = self[key]
+        @specs[key] = nil
+        val
+      end
+
+      # @yield [key, val] param name and spec
+      def each(&block)
+        to_h.each(&block)
+      end
+
+      def to_h
+        h = {}
+        @play_class.superplays.reverse.each do |sp|
+          h.update(sp.params_spec.specs)
+        end
+        h.reject { |_, v| v.nil? }
+      end
+
+      def inspect
+        to_h.inspect
+      end
+
+      def to_s
+        to_h.to_s
+      end
+    end
+  end
+end

data/lib/abid/dsl/play.rb

@@ -0,0 +1,35 @@
+require 'abid/dsl/play_core'
+
+module Abid
+  module DSL
+    # `play` definition is evaluated in Play class context.
+    #
+    #     play :foo do
+    #       # this is evaluated in Play class context
+    #     end
+    #
+    class Play
+      def self.create(task)
+        Class.new(self) do
+          include task.application.global_mixin
+          extend helpers
+          self.task = task
+        end
+      end
+
+      include PlayCore
+      extend PlayCore::ClassMethods
+
+      def initialize(params)
+        @params = params
+        @prerequisite_tasks = []
+      end
+
+      # default settings
+      worker :default
+      volatile false
+      set :concerned, true
+      set :needed,    true
+    end
+  end
+end

data/lib/abid/dsl/play_core.rb

@@ -0,0 +1,354 @@
+module Abid
+  module DSL
+    # Common methods for Play and Mixin
+    module PlayCore
+      attr_reader :prerequisite_tasks
+      attr_reader :params
+
+      # Declared prerequisite tasks.
+      #
+      #     play :foo do
+      #       setup do
+      #         needs :TASK_NAME, bar: 0
+      #       end
+      #     end
+      #
+      # @param task_name [Symbol, String] task name
+      # @param params [Hash] task params
+      def needs(task_name, **params)
+        t = task.application[task_name, @scope_in_actions]
+        (@prerequisite_tasks ||= []) << [t, self.params.merge(params)]
+      end
+
+      def run
+        # noop
+      end
+
+      def task
+        self.class.task
+      end
+
+      # Evaluates each actions in the task scope where the action is declared.
+      # @param tag [Symbol] action name
+      # @param args [Array] arguments
+      def call_action(tag, *args)
+        self.class.actions[tag].each do |scope, block|
+          @scope_in_actions = scope
+          instance_exec(*args, &block)
+        end
+      ensure
+        @scope_in_actions = nil
+      end
+
+      # @!visibility private
+      def eval_setting(value = nil, &block)
+        return instance_exec(&value) if value.is_a? Proc
+        return value unless value.nil?
+        return instance_exec(&block) if block_given?
+        true
+      end
+      private :eval_setting
+
+      def logger
+        task.application.logger
+      end
+
+      def preview?
+        task.application.options.dryrun || task.application.options.preview
+      end
+
+      # Play definition's body is extended by ClassMethods.
+      #
+      module ClassMethods
+        attr_accessor :task
+        private :task=
+
+        # Task params specification.
+        def params_spec
+          @params_spec ||= ParamsSpec.new(self)
+        end
+
+        # Actions include `setup` blocks and `after` blocks.
+        #
+        #     play :foo do
+        #       setup { 'this block is added to actions[:setup]' }
+        #       after { ... }
+        #     end
+        def actions
+          @actions ||= Actions.new(self)
+        end
+
+        # Define helper methods.
+        #
+        #     play :foo do
+        #       helpers do
+        #         def country
+        #           :jp
+        #         end
+        #       end
+        #
+        #       today #=> :jp
+        #     end
+        #
+        # `helpers` block is evaluated in the helpers module context, which
+        # extends the play class.
+        #
+        # If no block given, it returns the helper module.
+        #
+        # @return [Module] helpers module
+        def helpers(*extensions, &block)
+          @helpers ||= Module.new
+          @helpers.module_eval(&block) if block_given?
+          @helpers.module_eval { include(*extensions) } if extensions.any?
+          @helpers
+        end
+
+        # Declared setting.
+        #
+        #     play :foo do
+        #       set :first_name, 'Taro'
+        #       set :family_name, 'Yamada'
+        #       set :full_name, -> { first_name + ' ' + family_name }
+        #
+        #       def run
+        #         full_name #=> 'Taro Yamada'
+        #       end
+        #     end
+        #
+        # Settings are defiend as an intance methods of the play.
+        #
+        # If a param is declared with the same name of the setting, the param is
+        # undefined.
+        #
+        #     mixin :bar do
+        #       param :country
+        #     end
+        #
+        #     play :baz do
+        #       include :bar
+        #       set :country, :jp
+        #
+        #       params_spec #=> {}
+        #     end
+        #
+        # When block is given, it is lazily evaluated in the play context.
+        def set(name, value = nil, &block)
+          var = :"@#{name}"
+
+          params_spec.delete(name) # undef param
+          define_method(name) do
+            unless instance_variable_defined?(var)
+              val = eval_setting(value, &block)
+              instance_variable_set(var, val)
+            end
+            instance_variable_get(var)
+          end
+        end
+
+        # Declare task param.
+        #
+        #     play :foo do
+        #       param :city
+        #       param :country, default: 'Japan'
+        #
+        #       params_spec # => { city: {}, country: { default: 'Japan'} }
+        #
+        #       def run
+        #         puts "#{city}, #{country}"
+        #       end
+        #     end
+        #
+        #     $ abid foo city=Tokyo
+        #     Tokyo, Japan
+        #
+        # An instance method of the same name is defined.
+        #
+        # @param name [Symbol] param name
+        # @param spec [Hash] specification
+        # @option spec [Object] :default default value
+        def param(name, **spec)
+          define_method(name) do
+            raise NoParamError, "undefined param `#{name}' for #{task.name}" \
+              unless params.include?(name)
+            params[name]
+          end
+          params_spec[name] = spec
+        end
+
+        #
+        # Setting Helpers
+        #
+
+        # @!visibility private
+        def self.def_setting_helper(name)
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}(val = nil, &block)
+            set :#{name}, val, &block
+          end
+          RUBY
+        end
+
+        # @!method worker(val = nil, &block)
+        #   Set :worker name.
+        #
+        #       play :foo do
+        #         worker :my_worker
+        #         action { ... }
+        #       end
+        #
+        #   This is short-hand style of `set :worker, :my_worker`
+        def_setting_helper :worker
+
+        # @!method volatile(val = nil, &block)
+        #   Set :volatile flag.
+        #
+        #       play :foo do
+        #         volatile
+        #         action { ... }
+        #       end
+        #
+        #   This is short-hand style of `set :volatile, true`
+        def_setting_helper :volatile
+
+        # Delete the param from params_spec.
+        #
+        #     mixin :bar do
+        #       param :country
+        #     end
+        #
+        #     play :baz do
+        #       include :bar
+        #
+        #       params_spec #=> { country: {} }
+        #
+        #       undef_param :country
+        #       params_spec #=> {}
+        #     end
+        def undef_param(name)
+          params_spec.delete(name)
+        end
+
+        #
+        # Actions
+        #
+
+        # @!visibility :private
+        def self.define_action(name)
+          define_method(name) do |&block|
+            actions.add(name, task.scope, block)
+          end
+        end
+
+        # @!method setup(&block)
+        #   Register _setup_ action.
+        #
+        #   Setup action is called before #run.
+        #   All prerequisites should be declared inside the setup blocks.
+        #
+        #       play :foo do
+        #         setup do
+        #           needs :bar
+        #           puts 'Setup!'
+        #         end
+        #
+        #         def run
+        #           puts 'Running!'
+        #         end
+        #       end
+        #
+        #       $ abid foo
+        #       ... (:bar is executed)
+        #       Setup!
+        #       Running!
+        define_action :setup
+
+        # @!method action(&block)
+        #   Register main action.
+        #
+        #       play :foo do
+        #         action { |args| ... }
+        #       end
+        #
+        #   `action` block is not executed in dryrun mode nor preview mode.
+        #
+        #   Main actions of mixis are inherited to play, while `run` method is
+        #   overwritten.
+        #
+        #   @yieldparam args [Rake::TaskArguments]
+        define_action :action
+
+        # @!method safe_action(&block)
+        #   Register safe action.
+        #   `safe_action` is similar to `action`, but this block is executed
+        #   in preview mode.
+        #
+        #   You should guard dangerous operations in a safe_action block.
+        #   This is useful to preview detail behavior of play.
+        #
+        #   @yieldparam args [Rake::TaskArguments]
+        define_action :safe_action
+
+        # @!method after(&block)
+        #   Register _after_ action.
+        #
+        #   After action is called after #run.
+        #
+        #       play :foo do
+        #         def run
+        #           ...
+        #         end
+        #
+        #         after do |error|
+        #           next if error.nil?
+        #           $syserr.puts "[ERROR] #{task.name} failed:"
+        #           $syserr.puts "[ERROR]   #{error}"
+        #         end
+        #       end
+        #
+        #   `after` block is not executed in dryrun mode nor preview mode.
+        #
+        #   @yieldparam error [StandardError, nil] if run method failed,
+        #     otherwise nil.
+        define_action :after
+
+        # Include mixins.
+        #
+        # All methods, actions, settings and params_spec are inherited.
+        #
+        #     mixin :foo do
+        #       param :country
+        #     end
+        #
+        #     play :bar do
+        #       include :bar
+        #       params_spec #=> { country: {} }
+        #     end
+        #
+        # When Module objects are given, it includes them as usual.
+        #
+        # @param mod [Array<Symbol, String, Module>] mixin name or module.
+        def include(*mod)
+          ms = mod.map { |m| resolve_mixin(m) }
+          super(*ms)
+        end
+        private :include
+
+        # @!visibility private
+        def resolve_mixin(mod)
+          return mod if mod.is_a? Module
+
+          mixin_task = task.application[mod.to_s, task.scope]
+          raise "#{mod} is not a mixin" unless mixin_task.is_a? MixinTask
+
+          mixin_task.internal
+        end
+        private :resolve_mixin
+
+        # Return a list of Mixin objects included.
+        def superplays
+          ancestors.select { |o| o.is_a? PlayCore::ClassMethods }
+        end
+      end
+    end
+  end
+end