command-set 0.8.0

data/lib/command-set/results.rb

@@ -0,0 +1,754 @@
+require 'delegate'
+require 'command-set/result-list'
+
+module Kernel
+  def puts(*args)
+    $stdout.puts(*args)
+  end
+end
+
+
+module Command
+  class << self
+    #Call anywhere to be sure that $stdout is replaced by an OutputStandin that
+    #delegates to the original STDOUT IO.  This by itself won't change output behavior.
+    #Requiring 'command-set/command-set' does this for you.  Multiple calls are safe though.
+    def wrap_stdout
+      return if $stdout.respond_to?(:add_dispatcher)
+      $stdout = OutputStandin.new($stdout)
+    end
+
+    #If you need the actual IO for /dev/stdout, you can call this to get it.  Useful inside of
+    #Results::Formatter subclasses, for instance, so that they can actually send messages out to 
+    #the user.
+    def raw_stdout
+      if $stdout.respond_to?(:__getobj__)
+        $stdout.__getobj__
+      else
+        $stdout
+      end
+    end
+
+    #See Command::wrap_stdout
+    def wrap_stderr
+      return if $stdout.respond_to?(:add_dispatcher)
+      $stderr = OutputStandin.new($stderr)
+    end
+
+    #See Command::raw_stdout
+    def raw_stderr
+      if $stderr.respond_to?(:__getobj__)
+        $stderr.__getobj__
+      else
+        $stderr
+      end
+    end
+  end
+
+  #Wraps an IO using DelegateClass.  Dispatches all calls to the IO, until a
+  #Collector is registered, at which point, methods that the Collector
+  #handles will get sent to it. 
+  class OutputStandin < IO
+    def initialize(io)
+      @_dc_obj = io
+      @dispatch_stack = nil
+      unless io.fileno.nil?
+        super(io.fileno,"w")
+      end
+    end
+
+    def method_missing(m, *args)  # :nodoc:
+      unless @_dc_obj.respond_to?(m)
+        super(m, *args)
+      end
+      @_dc_obj.__send__(m, *args)
+    end
+
+    def respond_to?(m)  # :nodoc:
+      return true if super
+      return @_dc_obj.respond_to?(m)
+    end
+
+    def __getobj__  # :nodoc:
+      @_dc_obj
+    end
+
+    def __setobj__(obj)  # :nodoc:
+      raise ArgumentError, "cannot delegate to self" if self.equal?(obj)
+      @_dc_obj = obj
+    end
+
+    def clone  # :nodoc:
+      super
+      __setobj__(__getobj__.clone)
+    end
+
+    def dup  # :nodoc:
+      super
+      __setobj__(__getobj__.dup)
+    end
+
+    #This looks gnarly, but DelegateClass takes out methods defined by
+    #Kernel -- Which usually makes sense, but IO has a bunch of methods that
+    #Kernel defines to basically delegate to an IO.... I have a headache
+    #now.
+    methods = IO.public_instance_methods(false)
+    methods -= self.public_instance_methods(false)
+    methods |= ['class']
+    methods.each do |method|
+      begin
+        module_eval <<-EOS
+          def #{method}(*args, &block)
+            begin
+              @_dc_obj.__send__(:#{method}, *args, &block)
+            rescue
+              $@[0,2] = nil
+              raise
+            end
+          end
+        EOS
+      rescue SyntaxError
+        raise NameError, "invalid identifier %s" % method, caller(3)
+      end
+    end
+
+    def thread_stack_index
+      "standin_dispatch_stack_#{self.object_id}"
+    end
+
+    def relevant_collector
+      Thread.current[thread_stack_index] || @dispatch_stack
+    end
+
+    def dispatched_method(method, *args)# :nodoc:
+      collector = relevant_collector
+      if not collector.nil? and collector.respond_to?(method)
+        return collector.__send__(method, *args)
+      end
+      return __getobj__.__send__(method, *args)
+    end
+
+    def add_thread_local_dispatcher(collector)
+      Thread.current[thread_stack_index]=collector
+      define_dispatch_methods(collector)
+    end
+    alias set_thread_collector add_thread_local_dispatcher
+
+    #Puts the dispatcher in place to handle normal IO methods.
+    def add_dispatcher(collector)
+      @dispatch_stack = collector
+      define_dispatch_methods(collector)
+    end
+    alias set_default_collector add_dispatcher
+
+    def define_dispatch_methods(dispatcher)# :nodoc:
+      dispatcher.dispatches.each do |dispatch|
+        (class << self; self; end).module_eval <<-EOS
+          def #{dispatch}(*args)
+            dispatched_method(:#{dispatch.to_s}, *args)
+          end
+        EOS
+      end
+    end
+
+    #Unregisters the dispatcher.
+    def remove_dispatcher(dispatcher)
+      @dispatch_stack = nil if @dispatch_stack == dispatcher
+    end
+    alias remove_collector remove_dispatcher
+
+    def remove_thread_local_dispatcher(dispatcher)
+      if Thread.current[thread_stack_index] == dispatcher
+        Thread.current[thread_stack_index] = nil
+      end
+    end
+    alias remove_thread_collector remove_thread_local_dispatcher
+  end
+
+  #This is the output management module for CommandSet.  With an eye towards
+  #being a general purpose UI library, and motivated by the need to manage
+  #pretty serious output management, the Results module provides a
+  #reasonably sophisticated output train that runs like this:
+  #
+  #0. An OutputStandin intercepts normal output and feeds it to ...
+  #0. A Collector aggregates output from OutputStandins and explicit #item
+  #   and #list calls and feeds to to ...
+  #0. A Presenter handles the stream of output from Collector objects and
+  #   emits +saw+ and +closed+ events to one or more ...
+  #0. Formatter objects, which interpret those events into user-readable
+  #   output.
+  module Results
+    #Collects the events spawned by dispatchers and sends them to the presenter.
+    #Responsible for maintaining it's own place within the larger tree, but doesn't
+    #understand that other Collectors could be running at the same time - that's the 
+    #Presenter's job.
+    class Collector
+      def initialize(presenter)
+        @presenter = presenter
+        @nesting = []
+      end
+
+      def initialize_copy(original)
+        @presenter = original.instance_variable_get("@presenter")
+        @nesting = original.instance_variable_get("@nesting").dup
+      end
+
+      def items(*objs)
+        if Hash === objs.last
+          options = objs.pop
+        else
+          options = {}
+        end
+        objs.each do |obj|
+          item(obj, options)
+        end
+      end
+
+      def item( obj, options={} )
+        @presenter.item(@nesting.dup + [obj], options)
+      end
+
+      def begin_list( name, options={} )
+        @nesting.push(name)
+        @presenter.begin_list(@nesting.dup, options)
+        if block_given?
+          yield
+          end_list
+        end
+      end
+
+      def open_list(name, options={})
+        @nesting.push(name)
+        unless @presenter.list_open?(@nesting)
+          @presenter.begin_list(@nesting.dup, options)
+        end
+        if block_given?
+          yield
+          end_list
+        end
+      end
+
+      def end_list
+        @presenter.end_list(@nesting.dup)
+        @nesting.pop
+      end
+
+      @dispatches = {}
+
+      def self.inherited(sub)
+        sub.instance_variable_set("@dispatches", @dispatches.dup)
+      end
+
+      def self.dispatches
+        @dispatches.keys
+      end
+
+      def dispatches
+        self.class.dispatches
+      end
+
+      #Use to register an IO +method+ to handle.  The block will be passed a Collector and the
+      #arguments passed to +method+.
+      def self.dispatch(method, &block)
+        @dispatches[method] = true
+        define_method(method, &block)
+      end
+
+      dispatch :puts do |*args|
+        args.each do |arg| 
+          item arg
+        end
+      end
+
+      dispatch :write do |*args|
+        args.each do |arg| 
+          item arg
+        end
+      end
+
+      dispatch :p do |*args|
+        args.each do |arg|
+          item(arg, :string => :inspect, :timing => :immediate)
+        end
+      end
+    end
+
+    #Gets item and list events from Collectors, and emits two kinds of
+    #events to Formatters: 
+    #[+saw+ events] occur in chronological order, with no guarantee regarding timing.  
+    #[+closed+ events] occur in tree order.  
+    #
+    #In general, +saw+ events are good for immediate feedback to the user,
+    #not so good in terms of making sense of things.  They're generated as
+    #soon as the relevant output element enters the system.
+    #
+    #On the other hand, +closed+ events will be generated in the natural
+    #order you'd expect the output to appear in.  Most Formatter subclasses use
+    #+closed+ events.
+    #
+    #A list which has not received a "list_end" event from upstream will
+    #block lists later in tree order until it closes.  A Formatter that
+    #listens only to +closed+ events can present them to the user in a way
+    #that should be reasonable, although output might be halting for any
+    #process that takes noticeable time.
+    class Presenter
+      class Exception < ::Exception; end
+
+      def initialize
+        @results = List.new("")
+        @leading_edge = @results
+        @formatters = []
+      end
+
+      def create_collector
+        return Collector.new(self)
+      end
+
+      def item( item_path, options={} )
+        item = item_path.pop
+        home = get_collection(item_path)
+        item = home.add item
+        item.options = home.options.merge(options)
+        item.depth = item_path.length
+        notify(:saw, item)
+        advance_leading_edge
+      end
+
+      def leading_edge?(list)
+        return list == @leading_edge
+      end
+
+      def register_formatter(formatter)
+        @formatters << formatter
+
+        formatter.notify(:start, nil)
+      end
+
+      def begin_list( list_path, options={} )
+        list = list_path.pop
+        home = get_collection(list_path)
+        list = List.new(list)
+        list.options = home.options.merge(options)
+        list.depth = list_path.length
+        notify(:saw_begin, list)
+        home.add(list)
+        advance_leading_edge
+      end
+
+      def list_open?(list_path)
+        begin 
+          get_collection(list_path)
+          return true
+        rescue Exception
+          return false
+        end
+      end
+
+      def end_list( list_path )
+        list = get_collection( list_path )
+        notify(:saw_end, list)
+        list.close
+        advance_leading_edge
+      end
+
+      def done
+        @results.close
+        advance_leading_edge
+        notify(:done, nil)
+      end
+
+      #Returns the current list of results.  A particularly advanced Formatter might treat +saw_*+ events 
+      #like notifications, and then use the List#filter functionality to discover the specifics about the
+      #item or list just closed.
+      def output
+        @results
+      end
+
+      protected
+      def advance_leading_edge
+        iter = ListIterator.new(@leading_edge.tree_order_next)
+        iter.each do |forward|
+          case forward
+          when ListEnd
+            break if forward.end_of.open?
+            break if forward.end_of.name.empty?
+            notify(:leave, forward.end_of)
+          when List
+            notify(:arrive, forward)
+          when ListItem
+            notify(:arrive, forward)
+          end
+
+          @leading_edge = forward
+        end
+      end
+
+      def notify(msg, item)
+        @formatters.each do |f|
+          f.notify(msg, item)
+        end
+      end
+
+      def get_collection(path)
+        thumb = @results.values
+        list = @results
+        path.each do |step|
+          list = thumb.find{|member| List === member && member.open? && member.name == step}
+          if list.nil?
+            raise Exception, "#{step} in #{path.inspect} missing from #{thumb}!"
+          end
+          thumb = list.values
+        end
+        return list
+      end
+    end
+
+    #The end of the Results train.  Formatter objects are supposed to output to the user events that they
+    #receive from their presenters.  To simplify this process, a number of common IO functions are delegated
+    #to an IO object - usually Command::raw_stdout.
+    #
+    #This class in particular is pretty quiet - probably not helpful for everyday use.
+    #Of course, for some purposes, singleton methods might be very useful
+    class Formatter
+      extend Forwardable
+
+      class FormatAdvisor
+        def initialize(formatter)
+          @advisee = formatter
+        end
+
+        def list(&block)
+          @advisee.advice[:list] << proc(&block)
+        end
+
+        def item(&block)
+          @advisee.advice[:item] << proc(&block)
+        end
+
+        def output(&block)
+          @advisee.advice[:output] << proc(&block)
+        end
+      end
+
+      def notify(msg, item)
+        if msg == :start
+          start
+          return
+        end
+        if msg == :done
+          finish
+          return
+        end
+
+        apply_advice(item)
+
+        if List === item
+          case msg
+          when :saw_begin
+            saw_begin_list(item)
+          when :saw_end
+            saw_end_list(item)
+          when :arrive
+            closed_begin_list(item)
+          when :leave
+            closed_end_list(item)
+          end
+        else
+          case msg
+          when :arrive
+            closed_item(item)
+          when :saw
+            saw_item(item)
+          end
+        end
+      end
+
+      def initialize(io)
+        @out_to = io
+        @advisor = FormatAdvisor.new(self)
+        @advice = {:list => [], :item => [], :output => []}
+      end
+
+      def apply_advice(item)
+        type = List === item ? :list : :item
+
+        item.options[:format_advice] = 
+          @advice[type].inject(default_advice(type)) do |advice, advisor|
+          result = advisor[item]
+          break if result == :DONE
+          advice.merge!(result) if Hash === result
+          advice
+          end
+      end
+
+      attr_reader :advice
+
+      def receive_advice(&block)
+        @advisor.instance_eval(&block)
+      end
+
+      def default_advice(type)
+        {}
+      end
+
+      def_delegators :@out_to, :p, :puts, :print, :printf, :putc, :write, :write_nonblock, :flush
+
+      def self.inherited(sub)
+        sub.extend Forwardable
+        sub.class_eval do
+          def_delegators :@out_to, :p, :puts, :print, :printf, :putc, :write, :write_nonblock, :flush
+        end
+      end
+
+      #Presenter callback: output is beginning
+      def start; end
+
+      #Presenter callback: a list has just started
+      def saw_begin_list(list); end
+
+      #Presenter callback: an item has just been added
+      def saw_item(item); end
+
+      #Presenter callback: a list has just ended
+      def saw_end_list(list); end
+
+      #Presenter callback: a list opened, tree order
+      def closed_begin_list(list); end
+
+      #Presenter callback: an item added, tree order
+      def closed_item(item); end
+
+      #Presenter callback: an list closed, tree order
+      def closed_end_list(list); end
+
+      #Presenter callback: output is done
+      def finish; end
+    end
+
+    #The simplest useful Formatter: it outputs the value of every item in tree order.  Think of
+    #it as what would happen if you just let puts and p go directly to the screen, without the 
+    #annoying consequences of threading, etc.
+    class TextFormatter < Formatter
+      def closed_item(value)
+        puts value
+      end
+    end
+
+    class StrategyFormatter < Formatter
+      class FormatStrategy
+        extend Forwardable
+
+        def initialize(name, formatter)
+          @name = name
+          @formatter = formatter
+          setup
+        end
+
+        def setup; end
+
+        def_delegators :@formatter, :p, :puts, :print, :printf, :putc, :write, :write_nonblock, :flush
+
+        attr_reader :name
+
+        def switch_to(name)
+          @formatter.push_strategy(name)
+        end
+
+        def finish
+          @formatter.pop_strategy(self.name)
+        end
+
+        #Presenter callback: a list has just started
+        def saw_begin_list(list); end
+
+        #Presenter callback: an item has just been added
+        def saw_item(item); end
+
+        #Presenter callback: a list has just ended
+        def saw_end_list(list); end
+
+        #Presenter callback: a list opened, tree order
+        def closed_begin_list(list); 
+          unless list.options[:strategy_start] == self or list.options[:format_advice].nil?
+            switch_to(list.options[:format_advice][:type])
+            if (next_strat = @formatter.current_strategy) != self
+              list.options[:strategy_start] = next_strat
+              next_strat.closed_begin_list(list)
+            end
+          end
+        end
+
+        #Presenter callback: an item added, tree order
+        def closed_item(item); end
+
+        #Presenter callback: an list closed, tree order
+        def closed_end_list(list); 
+          if list.options[:strategy_start] == self
+            finish
+          end
+        end
+      end
+
+      @strategies = {:default => FormatStrategy}
+
+      class << self
+        def strategy(name, base_klass = FormatStrategy, &def_block)
+          @strategies[name.to_sym] = Class.new(base_klass, &def_block)
+        end
+
+        def inherited(sub)
+          self.instance_variables.each do |var|
+            value = self.instance_variable_get(var)
+            if value.nil?
+              sub.instance_variable_set(var, nil)
+            else
+              sub.instance_variable_set(var, value.dup)
+            end
+          end
+        end
+
+        def strategy_set(formatter)
+          set = {}
+          @strategies.each_pair do |name, klass|
+            set[name] = klass.new(name, formatter)
+          end
+          return set
+        end
+      end
+
+      def initialize(io)
+        super(io)
+        @strategies = self.class.strategy_set(self)
+        @strategy_stack = [@strategies[:default]]
+      end
+
+      def_delegators :current_strategy, :saw_begin_list, :saw_item, :saw_end_list, 
+        :closed_begin_list, :closed_item, :closed_end_list
+
+      def current_strategy
+        @strategy_stack.last
+      end
+
+      def push_strategy(name)
+        if @strategies.has_key?(name)
+          @strategy_stack.push(@strategies[name])
+        end
+      end
+
+      def pop_strategy(name)
+        if current_strategy.name == name
+          @strategy_stack.pop
+        end
+      end
+
+      strategy :default do
+        def closed_item(value)
+          puts value
+        end
+      end
+
+      strategy :progress do
+        def closed_begin_list(list)
+          print list.to_s.ljust(50)
+        end
+
+        def closed_item(item)
+          print "."
+          flush
+        end
+
+        def finish
+          super
+          puts
+        end
+      end
+
+      strategy :indent do
+        def setup
+          @indent_level = 0
+        end
+
+        def indent
+          return "  " * [0, @indent_level].max
+        end
+
+        def closed_begin_list(list)
+          puts indent + list.to_s
+          @indent_level += 1
+          super
+        end
+
+        def closed_item(item)
+          item.to_s.split(/\s*\n\s*/).each do |line|
+            puts indent + line
+          end
+          super
+        end
+
+        def closed_end_list(list)
+          @indent_level -= 1
+          super
+        end
+      end
+
+      strategy :invisible do
+        def closed_item(value)
+        end
+      end
+
+      strategy :skip do
+        def closed_begin_list(list)
+          finish
+        end
+      end
+
+      strategy :chatty do
+        def saw_begin_list(list); $stderr.print "B"; end
+        def saw_item(list); $stderr.print "."; end
+        def saw_end_list(list); $stderr.print "E"; end
+        def closed_begin_list(list); 
+          clean_options = list.options.dup
+          clean_options.delete(:strategy_start)
+          puts "> #{list.to_s} (depth=#{list.depth} #{clean_options.inspect})"
+        end
+        def closed_item(list); puts "  " + list.to_s; end
+        def closed_end_list(list); puts "< " + list.to_s; end
+      end
+    end
+
+    #A trivial and obvious Formatter: produces well-formed XML fragments based on events.  It even 
+    #indents.  Might be handy for more complicated output processing, since you could feed the document
+    #to a XSLT processor.
+    class XMLFormatter < Formatter
+      def initialize(io, indent="  ", newline="\n")
+        super(io)
+        @indent = indent
+        @newline = newline
+        @indent_level=0
+      end
+
+      def line(string)
+        print "#{@indent * @indent_level}#{string}#@newline"
+      end
+
+      def closed_begin_list(name)
+        line "<#{name}>"
+        @indent_level += 1
+      end
+
+      def closed_item(value)
+        line "<item value=\"#{value}\" />"
+      end
+
+      def closed_end_list(name)
+        @indent_level -= 1
+        if @indent_level < 0
+          @indent_level = 0 
+          return
+        end
+        line "</#{name}>"
+      end
+    end
+  end
+end
+