tap 0.18.0 → 0.19.0

data/lib/tap/parser.rb

@@ -0,0 +1,268 @@
+require 'shellwords'
+
+module Tap
+  
+  # A parser for workflows defined on the command line.
+  class Parser
+    class << self
+      def parse(argv=ARGV)
+        parse!(argv.dup)
+      end
+      
+      def parse!(argv=ARGV)
+        argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
+        sig, obj = argv.shift, nil
+        
+        if sig =~ OBJECT
+          obj, sig = $1, $2
+        end
+        
+        [obj, sig, argv]
+      end
+    end
+    
+    # The escape begin argument
+    ESCAPE_BEGIN = "-."
+
+    # The escape end argument
+    ESCAPE_END = ".-"
+
+    # The parser end flag
+    END_FLAG = "---"
+  
+    # Matches any breaking arg. Examples:
+    #
+    #   --
+    #   --:
+    #   --[1,2][3]
+    #   --@
+    #   --/var
+    #   --.
+    #
+    # After the match:
+    #
+    #   $1:: The string after the break, or nil
+    #        (ex: '--' => nil, '--:' => ':', '--[1,2][3,4]' => '[1,2][3,4]')
+    #
+    BREAK =  /\A--(?:\z|([\:\[\/\.@].*?)\z)/
+  
+    # The node modifier.
+    NODE_BREAK = nil
+  
+    # The join modifier.
+    JOIN_BREAK = "."
+  
+    # Matches a sequence break. After the match:
+    #
+    #   $1:: The modifier string, or nil
+    #        (ex: ':' => nil, ':i' => 'i')
+    #
+    SEQUENCE = /\A:(.+)?\z/
+  
+    # Matches a generic join break. After the match:
+    #
+    #   $1:: The inputs string.
+    #        (ex: '[1,2,3][4,5,6]' => '1,2,3')
+    #   $2:: The outputs string.
+    #        (ex: '[1,2,3][4,5,6]' => '4,5,6')
+    #   $3:: The modifier string, or nil
+    #        (ex: '[][]is' => 'is')
+    #
+    JOIN = /\A\[(.*?)\]\[(.*?)\](.+)?\z/
+  
+    # Matches a join modifier. After the match:
+    #
+    #   $1:: The modifier flag string.
+    #        (ex: 'is.sync' => 'is')
+    #   $2:: The class string.
+    #        (ex: 'is.sync' => 'sync')
+    #
+    JOIN_MODIFIER = /\A([A-z]*)(?:\.(.*))?\z/
+  
+    # Matches an enque modifier. After the match:
+    #
+    #   $1:: The modifier string, or nil
+    #        (ex: '@var' => 'var')
+    #
+    ENQUE = /\A@(.+)?\z/
+    
+    # Matches a signal break. After the match:
+    #
+    #   $1:: The object string, or nil
+    #        (ex: 'obj/sig' => 'obj')
+    #   $2:: The signal string
+    #        (ex: 'obj/sig' => 'sig')
+    #
+    SIGNAL = /\A\/(?:(.*)\/)?(.*)\z/
+    
+    # Splits a signal into an object string and a signal string.  If OBJECT
+    # doesn't match, then the string can be considered a signal, and the
+    # object is nil. After a match:
+    #
+    #   $1:: The object string
+    #        (ex: 'obj/sig' => 'obj')
+    #   $2:: The signal string
+    #        (ex: 'obj/sig' => 'sig')
+    #
+    OBJECT = /\A(.*)\/(.*)\z/
+    
+    attr_reader :specs
+    
+    def initialize(specs=[])
+      @specs = specs
+    end
+    
+    def parse(argv)
+      argv = argv.dup unless argv.kind_of?(String)
+      parse!(argv)
+    end
+
+    # Same as parse, but removes parsed args from argv.
+    def parse!(argv)
+      argv = Shellwords.shellwords(argv) if argv.kind_of?(String)
+      return argv if argv.empty?
+      
+      unless argv[0] =~ BREAK
+        argv.unshift("--") 
+      end
+      
+      @current_type = nil
+      @current_index = -1
+      @current = nil
+      escape = false
+      
+      while !argv.empty?
+        arg = argv.shift
+
+        # if escaping, add escaped arguments 
+        # until an escape-end argument
+        if escape
+          if arg == ESCAPE_END
+            escape = false
+          else
+            current << arg
+          end
+          next
+        end
+      
+        # handle breaks and parser flags
+        case arg
+        when BREAK
+          begin
+            @current_type = nil
+            @current_index += 1
+            @current = parse_break($1)
+          rescue
+            raise "invalid break: #{arg} (#{$!.message})"
+          end
+          next
+
+        when ESCAPE_BEGIN
+          escape = true
+          next
+
+        when END_FLAG
+          break
+        
+        end if arg[0] == ?-
+      
+        # add all remaining args to the current argv
+        current << arg
+      end
+      
+      @current_type = nil
+      @current_index = nil
+      @current = nil
+      
+      argv
+    end
+    
+    private
+    
+    def spec(*argv) # :nodoc:
+      specs << argv
+      argv
+    end
+    
+    # returns the current argv or a new spec argv for the current type/index
+    def current # :nodoc:
+      @current ||= spec(@current_type, nil, 'set', @current_index.to_s)
+    end
+  
+    # determines the type of break and modifies self appropriately
+    def parse_break(one) # :nodoc:
+      case one
+      when NODE_BREAK
+        set_type(:node)
+      when JOIN_BREAK
+        set_type(:join)
+      when SEQUENCE
+        parse_sequence($1)
+      when JOIN
+        parse_join($1, $2, $3)
+      when ENQUE
+        parse_enque($1)
+      when SIGNAL
+        parse_signal($1, $2)
+      else
+        raise "invalid modifier"
+      end
+    end
+    
+    # sets the type of the next spec
+    def set_type(type) # :nodoc:
+      @current_type = type
+      nil
+    end
+    
+    # parses the match of a SEQUENCE regexp
+    def parse_sequence(one) # :nodoc:
+      unless @current_index > 0
+        raise "no prior entry"
+      end
+      
+      @current_type = :node
+      @current = nil
+      argv = current
+      parse_join_spec(one, "#{@current_index - 1}", @current_index.to_s)
+      argv
+    end
+    
+    # parses the match of a JOIN regexp
+    def parse_join(one, two, three) # :nodoc:
+      parse_join_spec(three, one, two)
+    end
+    
+    # parses a join modifier string into an argv.
+    def parse_join_spec(modifier, inputs, outputs) # :nodoc:
+      argv = [:join, nil, 'set', nil]
+      
+      case 
+      when modifier.nil?
+        argv << 'tap:join'
+        argv << inputs
+        argv << outputs
+      when modifier =~ JOIN_MODIFIER
+        argv << ($2 || 'join')
+        argv << inputs
+        argv << outputs
+        $1.split("").each {|char| argv << "-#{char}"}
+      else
+        raise "invalid join modifier"
+      end
+      
+      specs << argv
+      argv
+    end
+    
+    # parses the match of an ENQUE regexp
+    def parse_enque(one) # :nodoc:
+      spec(:signal, nil, 'enque', one)
+    end
+    
+    # parses the match of a SIGNAL regexp
+    def parse_signal(one, two) # :nodoc:
+      spec(:signal, one, two)
+    end
+  end
+end

data/lib/tap/prompt.rb

@@ -0,0 +1,36 @@
+require 'tap/app/api'
+require 'readline'
+
+module Tap
+  
+  # :startdoc::prompt
+  #
+  # A prompt to signal a running app. Any signals that return app (ie /run
+  # /stop /terminate) will exit the prompt.
+  class Prompt < App::Api
+    
+    def call
+      puts "starting prompt (help for help):"
+      loop do
+        begin
+          line = Readline.readline('--/', true).strip
+          next if line.empty?
+
+          args = Shellwords.shellwords(line)
+          "/#{args.shift}" =~ Tap::Parser::SIGNAL
+
+          result = app.call('obj' => $1, 'sig' => $2, 'args' => args)
+          if result == app
+            break
+          else
+            puts "=> #{result}"
+          end
+        rescue
+          puts $!.message
+          puts $!.backtrace if app.debug?
+        end
+      end
+    end
+  end
+end
+    

data/lib/tap/root.rb

@@ -54,14 +54,14 @@ module Tap
     include Utils
   
     # The root directory.
-    config_attr(:root, '.', :writer => false, :set_default => false)
+    config_attr(:root, '.', :writer => false, :init => false)
   
     # A hash of (alias, relative path) pairs for aliased paths relative
     # to root.
-    config_attr(:relative_paths, {}, :writer => false, :set_default => false, :type => :hash)
+    config_attr(:relative_paths, {}, :writer => false, :init => false, :type => :hash)
   
     # A hash of (alias, relative path) pairs for aliased absolute paths.
-    config_attr(:absolute_paths, {}, :reader => false, :writer => false, :set_default => false, :type => :hash)
+    config_attr(:absolute_paths, {}, :reader => false, :writer => false, :init => false, :type => :hash)
   
     # A hash of (alias, expanded path) pairs for expanded relative and
     # absolute paths.

data/lib/tap/signals.rb

@@ -0,0 +1,26 @@
+require 'tap/signals/module_methods'
+
+module Tap
+  
+  # Signals is a module providing signaling capbilities for objects.  Signals
+  # are effectively bound to methods with pre-processing that allows inputs
+  # from the command line (ie an ARGV) or from interfaces like HTTP that
+  # commonly produce a parameters hash.
+  #
+  module Signals
+    def signal(sig, &block)
+      sig = sig.to_s
+      unless signal = self.class.signals[sig]
+        raise "unknown signal: #{sig} (#{self.class})"
+      end
+      
+      signal.new(self, &block)
+    end
+    
+    def signal?(sig)
+      sig = sig.to_s
+      self.class.signals.has_key?(sig.to_s)
+    end
+  end
+end
+

data/lib/tap/signals/class_methods.rb

@@ -0,0 +1,222 @@
+require 'tap/signals/signal'
+
+module Tap
+  module Signals
+    module ClassMethods
+      SIGNALS_CLASS = Configurable::ClassMethods::CONFIGURATIONS_CLASS
+      
+      # A hash of (key, Signal) pairs defining signals available to the class.
+      attr_reader :signal_registry
+      
+      def self.initialize(base)
+        unless base.instance_variable_defined?(:@signal_registry)
+          base.instance_variable_set(:@signal_registry, SIGNALS_CLASS.new)
+        end
+        
+        unless base.instance_variable_defined?(:@signals)
+          base.instance_variable_set(:@signals, nil)
+        end
+        
+        unless base.instance_variable_defined?(:@use_signal_constants)
+          base.instance_variable_set(:@use_signal_constants, true)
+        end
+      end
+      
+      # A hash of (key, Signal) pairs representing all signals defined on this
+      # class or inherited from ancestors.  The signals hash is generated on
+      # each call to ensure it accurately reflects any signals added on
+      # ancestors.  This slows down signal calls through instance.signal.
+      #
+      # Call cache_signals after all signals have been declared in order
+      # to prevent regeneration of signals and to significantly improve
+      # performance.
+      def signals
+        return @signals if @signals
+
+        signals = SIGNALS_CLASS.new
+        ancestors.reverse.each do |ancestor|
+          next unless ancestor.kind_of?(ClassMethods)
+          ancestor.signal_registry.each_pair do |key, value|
+            if value.nil?
+              signals.delete(key)
+            else
+              signals[key] = value
+            end
+          end
+        end
+
+        signals
+      end
+
+      # Caches the signals hash so as to improve peformance.  Call with on set to
+      # false to turn off caching.
+      def cache_signals(on=true)
+        @signals = nil
+        @signals = self.signals if on
+      end
+      
+      protected
+      
+      def use_signal_constants(input=true)
+        @use_signal_constants = input
+      end
+      
+      # Defines a signal to call a method using an argument vector. The argv
+      # is sent to the method using a splat, so any method may be signaled.
+      # A signature of keys may be specified to automatically generate an argv
+      # from a hash; values for the keys are collected in order.
+      #
+      # A block may also be provided to pre-process the argv before it is sent
+      # to the method; the block return is sent to the method (and so should
+      # be an argv).
+      def signal(sig, opts={}) # :yields: sig, argv
+        signature = opts[:signature] || []
+        remainder = opts[:remainder] || false
+        
+        signal = define_signal(sig, opts) do |args|
+          argv = convert_to_array(args, signature, remainder)
+          block_given? ? yield(self, argv) : argv
+        end
+        
+        register_signal(sig, signal, opts)
+      end
+      
+      # Defines a signal to call a method that receives a single hash as an
+      # input.  A signature may be specified to automatically generate a
+      # hash from an array input.
+      #
+      # A block may also be provided to pre-process the hash before it is sent
+      # to the method; the block return is sent to the method (and so should
+      # be a hash).
+      def signal_hash(sig, opts={}) # :yields: sig, argh
+        signature = opts[:signature] || []
+        remainder = opts[:remainder]
+        
+        signal = define_signal(sig, opts) do |args|
+          argh = convert_to_hash(args, signature, remainder)
+          [block_given? ? yield(self, argh) : argh]
+        end
+        
+        register_signal(sig, signal, opts)
+      end
+      
+      def signal_class(sig, signal_class=Signal, opts={}, &block) # :yields: sig, argv
+        if block_given?
+          signal = Class.new(signal_class)
+          signal.class_eval(&block)
+        else
+          signal = signal_class
+        end
+        
+        register_signal(sig, signal, opts)
+      end
+      
+      # Removes a signal much like remove_method removes a method.  The signal
+      # constant is likewise removed unless the :remove_const option is set to
+      # to true.
+      def remove_signal(sig, opts={})
+        sig = sig.to_s
+        unless signal_registry.has_key?(sig)
+          raise NameError.new("#{sig} is not a signal for #{self}")
+        end
+
+        unregister_signal(sig, opts)
+      end
+
+      # Undefines a signal much like undef_method undefines a method.  The signal
+      # constant is likewise removed unless the :remove_const option is set to
+      # to true.
+      #
+      # ==== Implementation Note
+      #
+      # Signals are undefined by setting the key to nil in the registry. Deleting
+      # the signal is not sufficient because the registry needs to convey to self
+      # and subclasses to not inherit the signal from ancestors.
+      #
+      # This is unlike remove_signal where the signal is simply deleted from
+      # the signal_registry.
+      #
+      def undef_signal(sig, opts={})
+        # temporarily cache as an optimization
+        signals_cache = signals
+        sig = sig.to_s
+        unless signals_cache.has_key?(sig)
+          raise NameError.new("#{sig} is not a signal for #{self}")
+        end
+        
+        unregister_signal(sig, opts)
+        signal_registry[sig] = nil
+        signals_cache[sig]
+      end
+      
+      private
+      
+      def inherited(base) # :nodoc:
+        ClassMethods.initialize(base)
+        
+        unless base.instance_variable_defined?(:@use_signal_constants)
+          base.instance_variable_set(:@use_signal_constants, true)
+        end
+        
+        super
+      end
+      
+      def define_signal(sig, opts={}, &block) # :nodoc:
+        # generate a subclass of signal
+        klass = opts[:class] || Signal
+        signal = Class.new(klass)
+        
+        # bind the new signal
+        method_name = opts.has_key?(:bind) ? opts[:bind] : sig
+        if method_name
+          signal.send(:define_method, :call) do |args|
+            args = process(args)
+            obj.send(method_name, *args, &self.block)
+          end
+        end
+        
+        if block_given?
+          signal.send(:define_method, :process, &block)
+        end
+        
+        signal
+      end
+      
+      def register_signal(sig, signal, opts={}) # :nodoc:
+        if signal.respond_to?(:desc=)
+          signal.desc ||= Lazydoc.register_caller(Lazydoc::Trailer, 2)
+        end
+        
+        signal_registry[sig.to_s] = signal
+        cache_signals(@signals != nil)
+        
+        # set the new constant, if specified
+        if @use_signal_constants
+          const_name = opts.has_key?(:const_name) ? opts[:const_name] : sig.to_s.capitalize
+          const_name = const_name.to_s
+          
+          if const_name =~ /\A[A-Z]\w*\z/ && !const_defined?(const_name)
+            const_set(const_name, signal)
+          end
+        end
+        
+        signal
+      end
+      
+      def unregister_signal(sig, opts={}) # :nodoc:
+        signal = signal_registry.delete(sig.to_s)
+        
+        remove_const = opts.has_key?(:remove_const) ? opts[:remove_const] : true
+        if @use_signal_constants && remove_const
+          const_name = signal.to_s.split("::").pop.to_s
+          if const_name =~ /\A[A-Z]\w*\z/ && const_defined?(const_name)
+            remove_const(const_name)
+          end
+        end
+        
+        cache_signals(@signals != nil)
+        signal
+      end
+    end
+  end
+end