command-set 0.8.0

data/lib/command-set/dsl.rb

@@ -0,0 +1,526 @@
+module Command
+=begin rdoc
+This module collects the domain specific languages for CommandSet.
+This is the first and best place to start if you want to try to understand
+how to make use of CommandSet.  
+
+The sub-modules here are (in rough "nesting" order):
+
+CommandSetDefinition:: the commands with a CommandSet::define_commands block
+CommandDefinition:: the commands with a command setup block that describe how a command functions
+Argument:: the chained descriptors that describe how arguments are interpreted by command definitions
+Action:: utility functions within the command action block
+=end
+  module DSL
+    #These are the commands available within the CommandSet::define_commands
+    #block.  
+    module CommandSetDefinition
+      #Allows other command sets to be composited into this one.  And
+      #optional list of command names will cherry-pick the commands of the
+      #other set, otherwise they're all folded in, with preference given to
+      #the new commands.
+      def include_commands(set, *commands)
+        new_commands = set.command_list
+
+        commands.map!{|c| c.to_s}
+        unless commands.empty?
+          new_commands.delete_if do |name,command|
+            not commands.include? name
+          end
+        end
+
+        new_commands.each_pair do|name, command|
+          if(CommandSet === @command_list[name])
+            next unless CommandSet === command
+            @command_list[name].include_commands(command)
+          else
+            @command_list[name] = command.dup
+            @command_list[name].parent=self
+          end
+          #paths_update(command, name)
+        end
+      end
+
+      #Defines a command.  Either:
+      #- pass a name and a block, which will create the command on 
+      #  the fly - within the block, use methods from
+      #  Command::DSL::CommandDefinition.
+      #- pass a Command subclass - which will be added to the set based on it's name.  
+      #- pass a Command subclass, a name, and a block.  The new command will
+      #  be a subclass of the class you passed in, which is great for a
+      #  series of related commands.
+      def command(name_or_command_class, name_or_nil=nil, &block)
+        @subject_template = nil
+
+        if Class === name_or_command_class && Command > name_or_command_class
+          if block.nil?
+            command = name_or_command_class.dup
+            command.parent = self
+            name = command.name
+          else
+            name = name_or_nil.to_s
+            command = name_or_command_class.setup(self, name, &block)
+          end
+        else
+          if name_or_command_class.nil?
+            name = nil
+          elsif String === name_or_command_class or Symbol === name_or_command_class
+            name = name_or_command_class.to_s
+          else
+            raise RuntimeError, "#{name_or_command_class} is neither a Command class nor a name!"
+          end
+          command = Command.setup(self, name, &block)
+        end
+
+        @command_list[name] = command
+      end
+
+      #Defines a nested CommandSet.  Commands within the nested set will be
+      #referenced by preceding them with the name of the set.
+      #DSL::CommandSetDefinition will be available within the block to be
+      #used on the subcommand 
+      def sub_command(name, &block)
+        @subject_template = nil
+        name = name.to_s
+
+        if (@command_list.has_key? name) && (CommandSet === @command_list[name])
+          command = @command_list[name]
+        else
+          command = CommandSet.new(self, name)
+          @command_list[name] = command
+        end
+
+        command.define_commands(&block)
+        #paths_update(command, name)
+      end
+
+      #Occasionally it makes sense for a subcommand to do something when
+      #invoked on it's own.  Define that command using root_command as you
+      #would a normal command
+      def root_command(&block)
+        command(nil, &block)
+      end
+
+      #This is the method that makes DSL::CommandSetDefinition available.
+      #It's just a wrapper on instance_eval, honestly.
+      def define_commands(&block)
+        instance_eval(&block)
+      end
+    end
+
+    #These are the methods made available by Command::setup, and thus by
+    #DSL::CommandSetDefinition#command
+    module CommandDefinition
+      #See Command::Subject.  If this command will make use of fields of the
+      #subject, it must declare them using subject_methods.  You're then
+      #guaranteed that the subject will either have those fields defined, or
+      #an error will be thrown at runtime.  Pass a list of symbols, as you
+      #would to Class#attribute
+      def subject_methods(*methods)
+        @subject_requirements += [*methods]
+      end
+
+      #The core of the Command.  Define a block that performs the command.
+      #Within it, you can treat your arguments as readable private attributes 
+      #and call methods from DSL::Action
+      def action(&block)
+        define_method(:execute, &block)
+      end
+
+      #Commands should either define an undo block (that will reverse
+      #whatever their action did) or else call doesnt_undo - for things that
+      #don't change any state.  
+      #
+      #One particularly useful feature is that each invocation is it's own
+      #object, so you can set instance variables to save the old state if
+      #you want.
+      def undo(&block)
+        define_method(:undo, &block)
+        define_method(:undoable?) do
+          return true
+        end
+        subject_requirements << :undo_stack
+      end
+
+      #Lets the interpreter know that this command intentionally doesn't
+      #provide an undo block - that there's nothing to undo.  Use it for
+      #informational commands, primarily.  Commands that neither declare
+      #that they 'doesnt_undo' nor provide an undo block will raise a
+      #warning to the user whenever they're called.
+      def doesnt_undo
+        define_method(:undoable?) { return true }
+        define_method(:join_undo) {}
+      end
+
+      #Used to explain to the formatter subsystem how best to format your
+      #output.  It can sometimes be useful to output lots of data, and then
+      #use format_advice to eliminate and shuffle it around.
+      #
+      #For more information see Command::Formatter::FormatAdvisor
+      def format_advice(&block)
+        @advice_block = proc &block
+      end
+
+      #Every command should provide a little text to describe what it does.
+      #This will be nicely formatted on output, so feel free to use heredocs
+      #and indent so that it looks nice in the code.
+      def document(text)
+        @doc_text = text.gsub(%r{\s+}, " ").strip
+      end
+    end
+
+    #The meta-programmatic machinery to create arguments quickly.  Includes
+    #methods such that argument classes can register themselves into the DSL.
+    #Much of this module is unfortunately obtuse - it's designed so that
+    #argument types can be easily extended, which makes the actual DSL
+    #trickier to document.  
+    #
+    #Ultimately, arguments are governed by their basic type (which descends
+    #from Argument) and the ArgumentDecorator objects that wrap it.  
+    #
+    #Within a Command#setup or CommandSet#command block, you can make
+    #decorator and argument calls like:
+    #
+    #  optional.named.string_argument :person, "A Person"
+    #
+    #Which will create a StringArgument and wrap it in the NamedArgument and
+    #OptionalArgument ArgumentDecorators.  This sounds confusing, but the
+    #upshot is that the +person+ argument can be omitted, but if it's
+    #included, it must be preceded with the argument's name: "person" like
+    #so:
+    #  > command person judson
+    #
+    #Which will assign "judson" to the +person+ argument for the command.
+    #
+    #:include: doc/argumentDSL
+    module Argument
+      #Sugar for creating an alternating argument.  Basically, an
+      #alternating argument is a series of arguments, any of which could be
+      #set.  They either need to be of distinct types, or use +named+ to
+      #distinguish between them.
+      def alternating_argument(name, &block)
+        arg = AlternatingArgument.new(self, &block)
+        arg.name(name)
+        embed_argument(arg)
+      end
+
+      @@decorator_map={}
+      #The ArgumentDecorator#register method calls back to this, so that
+      #decorators can quickly register a method to wrap an argument with
+      #themselves.
+      def self.register_decorator(klass, method)
+        @@decorator_map[method] = klass
+        alias_method method, :create_decorator
+      end
+
+      @@argmap={}
+      @@shorthand_map={}
+      #The Argument#register method calls back to this, which creates
+      #methods like +funky_argument+ that are responsible for embedding the
+      #actual arguments in the Commands they're declared for.
+      def self.register_argument(klass, shorthand, type=nil)
+        unless type.nil? or not Class === type or @@argmap.has_key?(type)
+          @@argmap[type]=klass
+        end
+
+        method_name = shorthand + "_argument"
+        @@shorthand_map[method_name] = klass
+
+        alias_method method_name, :special_argument
+      end
+
+      #Generates rdoc ready documentation of the decorator and argument
+      #methods created by #register calls.  Output is included in this
+      #module's documentation.  Also useful if you want to document your own
+      #argument class' contributions.  Try something like:
+      #
+      #  > ruby -r"lib/command-set/arguments.rb" -e "Command::DSL::Argument::document"
+      def self.document
+        docs = <<-EOD 
+        There are two kinds of methods available for #{self.name}.  
+        First there are decorators.  They mark up arguments with extra
+        meaning, like being optional.  The second are actual argument
+        creation calls, which are shorthand for something like 
+          argument FiddlyArgument {}
+
+        In general, you'll use these something like
+
+          decorator.decorator.shorthand_argument "name"
+
+        For instance
+
+          named.optional.file_argument "config"
+
+        Decorator methods, and the classes they add:
+
+        EOD
+
+        @@decorator_map.each_pair do |method, klass|
+          docs += "+#{method}+:: #{klass.name.sub("Command::","")}\n"
+        end
+
+        docs += <<-EOD
+
+        The shorthand argument methods are:
+
+        EOD
+
+        @@shorthand_map.each_pair do |method, klass|
+          docs += "+#{method}+:: #{klass.name.sub("Command::","")}\n"
+        end
+
+        docs += <<-EOD
+
+        Don't forget about #alternating_argument and #argument itself!
+        EOD
+
+        indent = /^\s+/.match(docs)[0]
+        docs.gsub!(/^#{indent}/, "")
+
+        puts docs
+      end
+
+      def self.argument_typemap #:nodoc:
+        @@argmap
+      end
+
+      #When an ArgumentDecorator calls self.register, this method is aliased
+      #with the name the decorator passes It takes care of instantiating the
+      #decorator such that it's available to decorate the eventual argument.
+      #
+      #Don't look to closely at the source.  It does bad things.
+      def create_decorator(&block)
+        me = /:in `([^']*)/.match(caller(0)[0])[1]
+        decorator = @@decorator_map[me].allocate
+        decorator.extend DSL::Argument
+        embed_in = self
+        decorator.instance_eval do
+          initialize(embed_in, &block)
+        end
+        return decorator
+      end
+
+      #This method functions analogously to create_decorator, except it
+      #works for arguments, not decorators.  It's worth looking at as the
+      #call signature for all +funky_argument+ style calls.
+      def special_argument(arg, values=nil, &get_values)
+        me = /:in `([^']*)/.match(caller(0)[0])[1]
+        name = nil
+        argument = nil
+        if(::Command::Argument === arg)
+          name = arg.name
+          argument = arg
+        else
+          name = arg
+          argument = @@shorthand_map[me].new(name, get_values||values)
+        end
+        return self.embed_argument(argument)
+      end
+
+      #The basic argument definition.  If +arg+ is an Argument object, it'll
+      #be used - which means that you can explicitly create and argument and
+      #embed it.  Otherwise, the values of +values+ or +get_values+ will be
+      #used to create the argument
+      def argument(arg, values=nil, &get_values)
+        name = nil
+        argument = nil
+        if(::Command::Argument === arg)
+          name = arg.name
+          argument = arg
+        else
+          name = arg
+          argument = create(name, get_values||values)
+        end
+
+        return self.embed_argument(argument)
+      end
+
+      #The method used to instantiate arguments based on their values.
+      #Searches all registered Argument classes, from children up, until one
+      #admits to being able to create arguments based on the value.
+      def create(name, basis)
+        @@argmap.keys.sort{|r,l|(r>l)?1:-1}.each do |type| #Check child classes first
+          if type === basis
+            return @@argmap[type].new(name, basis)
+          end
+        end
+        raise TypeError, "Don't know how to base an argument " +
+                         "on #{basis.class}"
+      end
+
+      def named_optionals #:nodoc:
+        raise NotImplementedException
+      end
+    end
+
+    #The methods available within the DSL::CommandDefinition#action method
+    #
+    #The trickiest thing to realize about writing Commands is that a
+    #CommandSet is an _object_ that contains several Command _subclasses_;
+    #Commad::setup creates a subclass, and so CommandSet#command does too.
+    #It's when a command is invoked that it's actually instantiated.
+    #
+    #Also note that you can access the arguments of a command as read-only
+    #attributes, and you can write to and read from instance variables,
+    #which will be local to the invocation of the command.  This is
+    #especially useful for undo and redo.
+    module Action
+
+      #:section: Basics
+
+      #Some commands sometimes cause side effects.  When evaluating
+      #arguments, if you discover that undoing doesn't make sense, and will
+      #be confusing to the user, call dont_undo, and the interpreter will
+      #ignore the call for purposes of undoing
+      def dont_undo
+        @should_undo = false
+        return nil
+      end
+
+      #This is how you'll access the Command::Subject object that's the
+      #interface of every command to the program state.
+      def subject
+        @subject
+      end
+
+      #:section: Formatting
+
+      #To create lists and sublist of data, you can use #list to wrap code
+      #in a #begin_list / #end_list pair.  
+      def list(name, options={}) #:yield: 
+        begin_list(name, options)
+        yield if block_given?
+        end_list
+      end
+
+      #Tells the main collector to begin a list.  Subsequent output will be
+      #gathered into that list.  For more, check out Results::Collector
+      def begin_list(name, options={})
+        @main_collector.begin_list(name, options)
+      end
+
+      #Tells the main collector to end the current list.  For more, check out
+      #Results::Collector
+      def end_list  
+        @main_collector.end_list
+      end
+
+      #Clean way to create an item of output.  Allows for various options to
+      #be added.  The normal output method (#puts, #p, #write...) are all
+      #diverted within a command, and effectively create no-option items.
+      def item(name, options={})
+        @main_collector.item(name, options)
+      end
+
+      #:section: Pause and Resume
+
+      #Stop here.  Return control to the user.  If several commands are
+      #chained (c.f. #chain) and the pause is subsequently resumed 
+      #(StandardCommands::Resume) the whole chain will be resumed.
+      def pause(deck = nil)
+        raise ResumeFrom, deck
+      end
+
+      #Stop here and return control to the user.  If several commands are
+      #chained (c.f. #chain) and the pause is subsequently resumed 
+      #(StandardCommands::Resume) the rest of the chain (not this command)
+      #will be dropped.
+      def defer(deck = nil) 
+        raise ResumeFromOnlyThis, deck
+      end
+
+      #Allows for a command to be broken into pieces so that a resume can
+      #pick up within a command.  The block will be executed normally, but
+      #if the command is resumed with a task id, all task blocks until that
+      #id will be skipped.
+      def task(id) #:yield:
+        if not @resume_from.nil?
+          if @resume_from == id
+            @resume_from = nil
+          end
+          return
+        end
+        yield if block_given?
+        @last_completed_task = id
+      end
+
+      #:section: Command compositing
+      
+      #It frequently makes sense to offer shortcut chains to the user, or
+      #even commands that can only be run as part of another command.
+      #Calling chain with either a command class or a command path allows
+      #will cause that command to be invoked before returning control to the
+      #user.
+      def chain(klass_or_path, args)
+        setup = CommandSetup.new
+        setup.command = klass_or_path
+        setup.args_hash = args || {}
+        subject.chain_of_command.push(setup)
+      end
+
+      #Like #chain, but interjects the command being chained to the start of
+      #the queue, immediately after this command completes.
+      def chain_first(klass_or_path, args)
+        setup = CommandSetup.new
+        setup.command = klass_or_path
+        setup.args_hash = args
+        subject.chain_of_command.unshift(setup)
+      end
+
+      #:section: Miscellany 
+
+      #Not normally called from within an #action block, this provides the
+      #default behavior for an undo (raise an exception)
+      def undo(box)
+        raise CommandException, "#{@name} cannot be undone"
+      end   
+
+      #This returns a new Results::Collector, which can allow for some very
+      #sophisticated command output.  Specifically, it can allow a command
+      #to loop over a large amount of data once, depositing output in
+      #multiple lists at once, for instance a status list (with hashmarks)
+      #and results(with useful data) list.
+      def sub_collector
+        @main_collector.dup
+      end
+
+      #This method is deprecated but remains as a nicety.  As it stands, any
+      #command can be interrupted at the command line with Ctrl-C, and
+      #return to the prompt.
+      def interruptable
+        yield
+      end
+
+      #These methods are nodoc'd because at present, they don't work.
+      #They'd be awesome for big jobs - splitting them into subthreads and
+      #such.  But they need to be debugged, and IIRC there's a deadlock
+      #condition
+      def action_thread(&block) #:nodoc:
+        return Thread.new do
+          collector = sub_collector
+          $stdout.set_thread_collector(collector)
+          block.call
+          $stdout.remove_thread_collector(collector)
+        end
+      end
+
+      require 'thwait'
+      def farm_out(array, thread_count, &block) #:nodoc:
+        first_batch = (array[0...thread_count]||[]).map do |item|
+          action_thread { block.call(item) }
+        end
+
+        rest = (array[thread_count..-1] || [])
+
+        waiter = ThreadsWait.new(*first_batch)
+
+        rest.each do |item|
+          waiter.next_wait
+          waiter.join_nowait(action_thread{block.call(item)})
+        end
+
+        waiter.join
+      end
+    end
+  end
+end