clio 0.0.1 → 0.2.0

data/lib/clio/string.rb

@@ -1,147 +1,154 @@
-#require 'facets/rope'
 require 'clio/ansicode'
-require 'facets/string/mask'
+require 'clio/layout/split'
+require 'clio/facets/string'
 
 module Clio
 
-  # = Clio String class.
+  def self.string(str)
+    String.new(str)
+  end
+
+  # Clio Strings stores a regular string (@text) and
+  # a Hash mapping character index to ansicodes (@marks).
+  # For example is we has the string:
+  #
+  #   "Big Apple"
+  #
+  # And applied the color red to it, the marks hash would be:
+  #
+  #   { 0=>[:red] , 9=>[:clear] }
   #
   class String
 
-    ESC_RE = /\e\[[0-9]*\w/
-
-  private
-
-    def initialize(text, ansi=nil)
-      @text = text.to_s
-      @ansi = ansi || text.to_s
-    end
-
-  public
-
     attr :text
+    attr :marks
 
-    attr :ansi
-
-    #
-    def to_s   ; ansi ; end
-
-    #def to_str ; text ; end
-
-    #
-    def +(append)
-      case append
-      when Symbol
-        t = text
-        a = ansi + ANSICode.send(append)
-      when self.class
-        t = text + append.text
-        a = ansi + append.ansi
-      else
-        t = text + append
-        a = ansi + append
-      end
-      self.class.new(t, a)
+    def initialize(text=nil, marks=nil)
+      @text  = text  || ''
+      @marks = marks || Hash.new{ |h,k| h[k]=[] }
     end
 
-    #
-    def <<(append)
-      case append
-      when Symbol
-        @ansi << ANSICode.send(append)
-      when self.class
-        @text << append.text
-        @ansi << append.ansi
-      else
-        @text << append
-        @ansi << append
+    def to_s
+      s = text.dup
+      m = marks.sort{ |a,b| b[0] <=> a[0] }
+      m.each do |index, codes|
+        codes.each do |code|
+          s.insert(index, ANSICode.send(code))
+        end
       end
+      s
     end
 
-    #
     def size ; text.size ; end
-    alias_method(:length, :size)
 
-    # Give the string a color.
-    def color(ansicolor=nil)
-      self.class.new(text, ANSICode.send(ansicolor){ansi})
+    ###
+    def color!(ansicolor)
+      marks[0] << ansicolor
+      marks[size] << :clear
     end
 
-    # Give the string a color.
-    def color!(ansicolor=nil)
-      @ansi = ANSICode.send(ansicolor){ansi}
+    ###
+    def color(ansicolor)
+      m = marks.dup
+      m[0] << ansicolor
+      m[size] << :clear
+      self.class.new(text, m)
     end
 
-    #--
-    # TODO: No doubt the delegation will need to be made more robust.
-    #++
-
-    INPLACE_DELEGATE_METHODS = /(\[\]=|replace|!$)/
-    EXCLUDE_DELEGATE_METHODS = /(split|^to_)/
-
-    # Delegate to underlying text/ansi.
-    def method_missing(s, *a, &b)
-      case s.to_s
-      when EXCLUDE_DELEGATE_METHODS
-        super
-      when INPLACE_DELEGATE_METHODS
-        text.send(s, *a, &b)
-        m = ansi.to_mask
-        e = ansi.to_mask(ESC_RE)
-        n = (e - m)
-        e.instance_delegate.send(s,*a, &b)
-        r = e + n
-        @ansi = r.to_s
+    ###
+    def upcase  ; self.class.new(text.upcase, marks) ; end
+    def upcase! ; text.upcase! ; end
+
+    ###
+    def downcase  ; self.class.new(text.upcase, marks) ; end
+    def downcase! ; text.upcase! ; end
+
+    ###
+    def +(other)
+      case other
+      when String
+        ntext  = text + other.text
+        nmarks = marks.dup
+        other.marks.each{ |i, c| m[i] << c }
       else
-        apply(s, *a, &b)
+        ntext  = text + other.to_s
+        nmarks = marks.dup
       end
+      self.class.new(ntext, nmarks)
     end
 
-  private
-
-    #
-    def apply(s, *a, &b)
-      t = text.send(s, *a, &b)
-      m = ansi.to_mask
-      e = ansi.to_mask(ESC_RE)
-      n = (e - m)
-      x = e.apply(s,*a, &b)
-      r = x + n
-      self.class.new(t, r.to_s)
+    def |(other)
+      Split.new(self, other)
     end
 
-  end
-
-end
-
-
-=begin SPECIFICATION
-
-  require 'quarry/spec'
+    def lr(other, options={})
+      Split.new(self, other, options)
+    end
 
-  Quarry.spec "Clio::String" do
+    ### slice
+    def slice(*args)
+      if args.size == 2
+        index, len = *args
+        endex  = index+len
+        new_text  = text[index, len]
+        new_marks = {}
+        marks.each do |i, v|
+          new_marks[i] = v if i >= index && i < endex
+        end
+        self.class.new(new_text, new_marks)
+      elsif args.size == 1
+        rng = args.first
+        case rng
+        when Range
+          index, endex = rng.begin, rng.end
+          new_text  = text[rng]
+          new_marks = {}
+          marks.each do |i, v|
+            new_marks[i] = v if i >= index && i < endex
+          end
+          self.class.new(new_text, new_marks)
+        else
+          self.class.new(text[rng,1], {rng=>marks[rng]})
+        end
+      else
+        raise ArgumentError
+      end
+    end
 
-    s1 = Clio::String.new("Hi how are you.")
-    s2 = Clio::String.new("Fine thanks.")
+    alias_method :[], :slice
 
-    verify "color" do
-      r = s1.color(:red)
-      e = Clio::ANSICode.red(s1.text)
-      e.assert == r.to_s
+    # TODO: block support and \1, \2 support.
+    def sub(pattern,replacement)
+      if md = pattern.match(@text)
+        delta  = replacement.size - md.size
+        marks2 = shift_marks(md.end, delta)
+        text2  = text.sub(pattern,replacement)
+        self.class.new(text2, marks2)
+      else
+        self.class.new(text, marks)
+      end
     end
 
-    verify "non-in-place delegation" do
-      r = s1.upcase
-      e = s1.text.upcase
-      e.assert == r.to_s
+    #
+    def gsub
     end
 
-    verify "string addition" do
-      r = s1 + s2
-      e = s1.text + s2.text
+  private
+
+    def shift_marks(index, delta)
+      new_marks = {}
+      marks.each do |i, v|
+        case i <=> index
+        when 0, -1
+          new_marks[i] = v
+        when 1
+          new_marks[i+delta] = v
+        end
+      end
+      new_marks
     end
 
   end
 
-=end
+end
 

data/lib/clio/usage.rb

@@ -0,0 +1,184 @@
+require 'clio/usage/main'
+require 'clio/usage/parser'
+
+module Clio
+
+  # = Usage
+  #
+  # Uasge provides a verstile but easy to use system of describing
+  # a commandline interface.
+  #
+  # == Underlying Fluent and Block Notation
+  #
+  # Underlying all usage is a fluent interface for decalaring
+  # a commandline's structure. Here is an example of using
+  # this DSL, albeit rather brutely.
+  #
+  #   usage = Clio::Usage.new
+  #   usage.command(:document).help('generate documentation')
+  #   usage.command(:document).option(:output, :o).type('FILE')
+  #   usage.command(:document).option(:output).help('output directory')
+  #   usage.option(:verbose, :V).help('verbose output')
+  #   usage.option(:quiet, :q).help('run silently').xor(:V)
+  #
+  # The example defines a subcommand 'document' that can take an
+  # 'output' option, and two mutually excluive universal options,
+  # 'verbose' and 'quiet', with respective one-letter aliases.
+  #
+  # As you might expect the fluent notation can be broken down into
+  # block notation which is easier to read.
+  #
+  #   usage = Usage.new
+  #   usage do
+  #     option(:verbose, :v) do
+  #       help('verbose output')
+  #     end
+  #     option(:quiet, :q) do
+  #       help('run silently')
+  #       xor(:V)
+  #     end
+  #     command(:document) do
+  #       help('generate documentation')
+  #       option(:output, :o) do
+  #         type('FILE')
+  #         help('output directory')
+  #       end
+  #       argument('files') do
+  #         multiple
+  #       end
+  #     end
+  #   end
+  #
+  # Clearly block notation is DRY and more elegant the the previous fluent
+  # version, but fluent notation is important because it allows the usage
+  # object to be easily passed around and augmented as needed.
+  #
+  #--
+  # == Abbriviated Notation
+  #
+  # While comprehensble, the core Usage DSL can be a somewhat verbose.
+  # So abbriviated forms of these methods are provided. These methods
+  # go one step further as well, and allow for some additional arguments.
+  #
+  #   cli.usage do
+  #     opt('verbose -v', 'verbose output') |
+  #     opt('quiet -q'  , 'run silently')
+  #     cmd('document', 'generate documentation') do
+  #       opt('output=FILE -o', 'output directory')
+  #       arg('FILE*')
+  #     end
+  #   end
+  #
+  # Notice the use of '|'. This allows us to define mutual exclusion
+  # without resorting to #xor as was done in the first example.
+  #++
+  #
+  # = Method Notation
+  #
+  # This notation is very elegant, but slightly more limited in scope.
+  # For instance, subcommands that use non-letter characters, such as ':',
+  # can not be described with this notation.
+  #
+  #   usage.document('<file*>', '--output=FILE -o')
+  #   usage('--verbose -V','--quiet -q')
+  #
+  #   usage.help(
+  #     'document'     , 'generate documentation',
+  #     'validate'     , 'run tests or specifications',
+  #     '--verbose'    , 'verbose output',
+  #     '--quiet'      , 'run siltently'
+  #   )
+  #
+  #   usage.document.help(
+  #     '--output', 'output directory'
+  #     'file*',    'files to document'
+  #   )
+  #
+  # This notation is slightly more limited in scope... so...
+  #
+  #   usage.command(:document, '--output=FILE -o', '<file*>')
+  #
+  # == Bracket Shorthand Notation
+  #
+  # The core notation can be somewhat verbose. As a further convenience
+  # commandline usage can be defined with a brief <i>bracket shorthand</i>.
+  # This is especailly useful when the usage is simple and statically defined.
+  #
+  #   usage['document']['--output=FILE -o']['FILE*']
+  #
+  # Using a little creativity to improve readabilty we can convert the
+  # whole example from above using this notation.
+  #
+  #   usage['--verbose -V',        'verbose output'       ] \
+  #        ['--quiet -q',          'run silently'         ] \
+  #        ['document',            'generate documention' ] \
+  #        [  '--output=FILE -o',  'output directory'     ] \
+  #        [  'FILE*',             'files to document'    ]
+  #
+  # Alternately the help information can be left out and defined in
+  # a seprate set of usage calls.
+  #
+  #   usage['--verbose -V']['--quiet -q'] \
+  #        ['document']['--output=FILE -o']['FILE*']
+  #
+  #   usage.help(
+  #     'document'  , 'generate documentation',
+  #     'validate'  , 'run tests or specifications',
+  #     '--verbose' , 'verbose output',
+  #     '--quiet'   , 'run siltently'
+  #   )
+  #
+  #   usage['document'].help(
+  #     '--output', 'output directory'
+  #     'FILE',     'files to docment'
+  #   )
+  #
+  # A little more verbose, but a bit more intutive.
+  #
+  # == "Alien" Notation
+  #
+  # As a side note, it is easy enough to alias #[] to #_, so alternatively
+  # one code create a variant shorthand written as:
+  #
+  #   usage do
+  #     _ '--verbose -V',         'verbose output'
+  #     _ '--quiet -q',           'run silently'
+  #     _ 'document',             'generate documentation' do
+  #        _ '--output=FILE -o',  'output directory'
+  #        _ 'FILE*',             'files to document'
+  #     end
+  #   end
+  #
+  # To demonsrtate it's equvalence to bracket shorthand, it can be chained as well.
+  #
+  #   usage._('document')._('--output=FILE -o')._('FILE*')
+  #
+  # This notation is not supported by default, but if it is more your style
+  # it is easy enough to implement by extending Clio::Usage::Command like this:
+  #
+  #   class Clio::Usage::Command
+  #     alias_method :_, :[]
+  #   end
+  #
+  # == Combining Notations
+  #
+  # Since the various notations all translate to same underlying
+  # structures, they can be mixed and matched as suites ones taste.
+  # For example we could mix Method Notation and Bracket Notation.
+  #
+  #   usage.document['--output=FILE -o']['file*']
+  #   usage['--verbose -V']['--quiet -q']
+  #
+  # The important thing to keep in mind when doing this is what is
+  # returned by each type of usage call.
+  #
+  module Usage
+
+    def self.new(name=nil, &block)
+      Main.new(name, &block)
+    end
+
+  end#module Usage
+
+end#module Clio
+

data/lib/clio/usage/argument.rb

@@ -0,0 +1,84 @@
+module Clio
+
+  module Usage #:nodoc:
+
+    # = Usage Argument
+    #
+    class Argument
+      #attr :parent
+      attr :name
+      attr :type
+      attr :help
+      attr :splat
+
+      # New Argument.
+      #def initialize(name, parent=nil, &block)
+      def initialize(name, &block)
+        @name      = name.to_s
+        @type      = name.upcase
+        #@parent    = parent
+        @splat     = false
+        @help      = ''
+        instance_eval(&block) if block
+      end
+
+      #
+      def initialize_copy(o)
+        @name = o.name.dup
+        @type = o.type.dup
+        @help = o.help.dup
+      end
+
+      # Same as +name+ but given as a symbol.
+      def key
+        name.to_sym
+      end
+
+      # Specify the type of the argument.
+      # This is an arbitrary description of the type.
+      # The value given is converted to uppercase.
+      #
+      #   arg.type('file')
+      #   arg.type #=> 'FILE'
+      #
+      def type(string=nil)
+        return @type unless string
+        @type = string.to_s.upcase
+        self
+      end
+
+      #
+      def splat(true_or_false=nil)
+        return @splat if true_or_false.nil?
+        @splat = true_or_false
+      end
+
+      # Specify help text for argument.
+      def help(string=nil)
+        @help.replace(string.to_s) if string
+        @help
+      end
+
+      def to_s
+        if name.upcase == type
+          s = "<#{name}"
+        else
+          s = "<#{name}:#{type}"
+        end
+        s << (splat ? "...>" : ">")
+        s
+      end
+
+      def inspect
+        s  = "<#{name}"
+        s << ":#{type.inspect}" if type
+        s << ">"
+        s
+      end
+
+    end #class Argument
+
+  end #module Usage
+
+end #module Clio
+