sc-ansi 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+.idea

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Colin MacKenzie IV
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,54 @@
+= sc-ansi
+
+Handles every aspect (that I could think of) of dealing with ANSI escape sequences. You can produce ANSI codes easily
+enough:
+
+  require 'sc-ansi'                              # or just require 'ansi' if you prefer.
+  
+  "a string!".red                                #=> a red string!
+  "a string!".blue                               #=> a blue string!
+  "a string!".red + "another string!".blue       #=> a red string and a blue string!
+  
+  # or...
+  include ANSI
+  
+  red  { "a string!" }                           #=> a red string!
+  blue { "a string!" }                           #=> a blue string!
+  
+  red + "a string!" + blue + "another string!"   #=> a red string and a blue string!
+  
+== Parsing ANSI Codes
+
+The unique thing about sc-ansi is that it can also parse ANSI codes out of an input string. Useful if you're writing
+your own console application and you want to interpret, say, the UP arrow for history recall.
+
+  include ANSI                                   # for the escape codes
+  
+  string = move_up + " hello " + move_down       #=> "\e[A hello \e[B"
+  string.ansi_sequences                          #=> [ ANSI::CURSOR_UP, ANSI::CURSOR_DOWN ]
+  
+  string.replace_ansi do |sequence|              # sequence is an instance of ANSI::Match
+    case sequence
+      when ANSI::CURSOR_UP                       # or ANSI::CUU
+        "(up)"
+      when ANSI::CURSOR_DOWN                     # or ANSI::CUD
+        "(down)" 
+    end
+  end
+  #=> "(up) hello (down)"
+  
+
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Colin MacKenzie IV. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sc-ansi"
+    gem.summary = %Q{Handles every aspect (that I could think of) of dealing with ANSI escape sequences.}
+    gem.description = %Q{Handles every aspect (that I could think of) of dealing with ANSI escape sequences.}
+    gem.email = "sinisterchipmunk@gmail.com"
+    gem.homepage = "http://github.com/sinisterchipmunk/sc-ansi"
+    gem.authors = ["Colin MacKenzie IV"]
+    gem.add_dependency "sc-core-ext", ">= 1.2.1"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.rcov_opts << "-x" << "/Library,spec"
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sc-ansi #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/ansi.rb

@@ -0,0 +1,177 @@
+# The main module for producing and/or parsing ANSI escape sequences. You can include this module into your class, or
+# access it directly:
+#
+#   ANSI.red { "a red string" }
+#
+#   include ANSI
+#   red { "a red string" }
+#
+#
+# To see which ANSI escape sequences can be generated, take a look at the following files:
+#   lib/ansi/cursor.rb   - sequences related to the cursor position
+#   lib/ansi/color.rb    - sequences related to text color and decoration
+#   lib/ansi/display.rb  - sequences related to the display, such as resolution
+#   lib/ansi/vt100.rb    - sequences compatible with VT100 terminals
+#
+# You can also define your own ANSI sequences. Obviously, they won't actually work unless the target system supports
+# them, but this is useful in case you need one that I somehow missed.
+#
+#   ANSI.define("sequence_name", "sn") { |an_argument| "the sequence with #{an_argument}" }
+# 
+# Now you can use the new sequence like so:
+#
+#   ANSI.sequence_name(1) #=> "the sequence with 1"
+#   ANSI.sn(7)            #=> "the sequence with 7"
+#
+# You can also define sequences that take blocks. In this case, the block argument will be the last argument:
+#
+#   ANSI.define("block_sequence", "bss") { |arg1, block| "the seq #{arg1} with #{block.call}" }
+#
+#   ANSI.block_sequence(1) { 55 }
+#   #=> "the seq 1 with 55"
+#
+#   ANSI.bss(35) { 72 }
+#   #=> "the seq 35 with 72"
+#
+# Obviously, the ability to define these sequences (with or without blocks) is probably more useful to me than to you
+# -- but it's in there if you need it.
+#
+module ANSI
+  class << self
+    def codes
+      @codes ||= []
+    end
+    
+    # Causes ANSI to unload all generated methods and wipe out the #codes index, and then reload
+    # its internal files. The codes stored in #codes themselves are unaffected, though they will
+    # float into oblivion and be processed by the garbage collector if you haven't captured them
+    # in some way.
+    def reset!
+      codes.clear
+      dynamically_defined_methods.each { |c| undef_method(c) }
+      dynamically_defined_methods.clear
+      arities.clear
+      
+      load File.join(File.dirname(__FILE__), "ansi/cursor.rb")
+      load File.join(File.dirname(__FILE__), "ansi/display.rb")
+      load File.join(File.dirname(__FILE__), "ansi/color.rb")
+      load File.join(File.dirname(__FILE__), "ansi/vt100.rb")
+    end
+    
+    def dynamically_defined_methods
+      @dynamically_defined_methods ||= []
+    end
+    
+    # The arity of the block that was used to define a particular method.
+    def arities
+      @arities ||= {}
+    end
+    
+    # Dynamically generates an escape sequence for the specified method name. Arguments are replaced
+    # with "{?}".
+    def generate_sequence(method_name)
+      test_sequence(arities[method_name]) { |*args| send(method_name, *args) }
+    end
+    
+    def test_sequence(arity, &block)
+      args = []
+      arity.times { args << "{?}" } if arity
+      begin
+        return block.call(*args)
+      rescue TypeError => err
+        if err.message =~ /\(expected Proc\)/
+          args.pop
+          args << nil
+          retry
+        else
+          raise err
+        end
+      end
+    end
+    
+    # Attempts to find an ANSI escape sequence which matches the specified string. The string
+    # is expected to use the notation "{?}" for each parameter instead of a real value. For
+    # instance, the sequence which would return MOVE_UP would look like: "\e[{?}A" instead of
+    # "\e[1A"
+    def recognize(str)
+      match = nil
+      String::ANSI_ESCAPE_SEQUENCE_RX =~ str
+      if $~ && args = $~[2].split(";")
+        codes.uniq.each do |code|
+          _args = args.dup
+          begin
+            result = code.generate(*_args)
+          rescue TypeError => err
+            if err.message =~ /\(expected Proc\)/ && !_args.empty?
+              _args.pop
+              retry
+            end
+            next
+          end
+          
+          if result == str
+            match ||= ANSI::Match.new(_args)
+            match << code
+          end
+        end
+      end
+      return match if match
+      raise "ANSI sequence not found: #{str.inspect}"
+    end
+    
+    # Aliases a specific code with the given names. This way you don't need to redefine a new constant, so performance
+    # is improved a little bit. Note that the code is expected to be an actual instance of ANSI::Code, and not an
+    # arbitrary string.
+    def alias_code(code, *names, &block)
+      code.add_methods! *names
+      delegate_names_for(code, *names, &block)
+    end
+    
+    def define(*names, &block)
+      # this just seems like a Really Bad Idea (TM). Let's just let the user create aliases the hard way.
+#      @cross ||= {}
+#      code = @cross[test_sequence(block.arity) { |*args| instance_exec(*args, &block) }] ||= ANSI::Code.new(&block)
+      code = ANSI::Code.new(&block)
+      code.add_methods!(*names)
+      
+      #code = ANSI::Code.new(*names, &block)
+      codes << code
+      delegate_names_for(code, *names, &block)
+      code
+    end
+    
+    private
+    def delegate_names_for(code, *names, &block) #:nodoc:
+      code_index = codes.index(code)
+      names.flatten.each do |name|
+        const_name = name.to_s.upcase
+        const_set(const_name, code) unless const_defined?(const_name)
+        
+        arities[name] = code.arity
+        if method_defined?(name) && $DEBUG
+          warn "Warning: about to overwrite method #{name}..."
+        end
+        
+        line = __LINE__ + 1
+        rbcode = <<-end_code
+          def #{name}(*args, &block)                                      # def red(*args, &block)
+            args << block if block_given?                                 #   args << block if block_given?
+            ANSI.codes[#{code_index}].send(#{name.inspect}, *args)        #   ANSI.code[1].send('red', *args)
+          end                                                             # end
+        end_code
+        
+        class_eval rbcode, __FILE__, line
+        ANSI.instance_eval rbcode
+        @dynamically_defined_methods << name
+      end
+    end
+  end
+end
+
+require 'sc-core-ext'
+require File.join(File.dirname(__FILE__), 'ansi/code')
+require File.join(File.dirname(__FILE__), "core_ext/object")
+require File.join(File.dirname(__FILE__), "core_ext/string")
+require File.join(File.dirname(__FILE__), "ansi/match")
+
+ANSI.reset!

data/lib/ansi/code.rb

@@ -0,0 +1,91 @@
+module ANSI
+  # The object that calling ANSI.define(...) actually creates. This is managed internally and you should rarely
+  # have to interface with it directly.
+  class Code
+    attr_reader :method_name, :arity, :block
+    include ANSI
+    
+    # The name of this code. This is assigned to the first non-nil method name that this object uses.
+    def name
+      @name || (@method_name.kind_of?(String) ? @name = @method_name : @method_name.to_s).upcase
+    end
+
+    alias to_s name
+    alias inspect name
+    
+    # Returns true if the other object is a kind_of ANSI::Code, *or* if the other object is a kind_of
+    # ANSI::Match and this ANSI::Code is contained in that match. In other words:
+    #
+    #   code = ANSI::Code.new("a_code") {}
+    #   match = ANSI::Match.new
+    #
+    #   code === match 
+    #   #=> false
+    #
+    #   match << code
+    #   code === match
+    #   #=> true
+    #
+    def ===(other)
+      if other.kind_of?(ANSI::Code)
+        return true
+      elsif other.kind_of?(ANSI::Match) && other == self
+        return true
+      else
+        return false
+      end
+    end
+    
+    # Creates methods with the specified names which are aliases of #generate. These methods are singletons
+    # of this instance of ANSI::Code, so adding method names using this method is only useful within the
+    # context of this instance.
+    #
+    def add_methods!(*names) #:nodoc:
+      names = names.flatten
+      return if names.empty?
+      @method_name ||= names.first.to_s
+
+      names.each do |name|
+        eigen.instance_eval do
+          alias_method name, :generate
+        end
+      end
+    end
+    
+    # Takes an optional list of method aliases, which are sent to #add_methods!, and a mandatory block argument
+    # which is bound to the #generate method.
+    def initialize(*names, &block)
+      @arity = block.arity || 0
+      @block = block
+      
+      eigen.instance_eval do
+        if block.arity > 0
+          # we need a list of arguments to pass to it.
+          define_method "generate" do |*args|
+            # this is to get around the warnings in Ruby 1.8
+            if args.length > block.arity && block.arity == 1
+              raise ArgumentError, "too many arguments (#{args.length} for #{block.arity})", caller
+            end
+            
+            # omitted args should be made nil. We do this explicitly to silence warnings in 1.8.
+            if (len = block.arity - args.length)
+              len.times { args << nil }
+            end
+  
+            instance_exec(*args, &block)
+          end
+        else
+          define_method("generate", &block)
+        end
+      end
+
+      add_methods! *names
+    end
+    
+    private
+    # the singleton class of this instance.
+    def eigen #:nodoc:
+      (class << self; self; end)
+    end
+  end
+end

data/lib/ansi/color.rb

@@ -0,0 +1,127 @@
+module ANSI
+  # Defines various ANSI escape sequences relating to terminal color manipulation.
+  #
+  # A few low-level methods are defined:
+  #
+  # * set_color(*values)
+  #   * takes 1 or more numeric color/attribute codes and produces the appropriate escape sequence.
+  # * reset_color
+  #   * takes no arguments and resets terminal color and attributes to normal.
+  #
+  # A number of higher-level methods are defined. None of them take any arguments, and they have the effect
+  # that their name implies:
+  #
+  # Attribute methods:
+  #   regular    (same as reset_color)
+  #   bold
+  #   underscore
+  #   blink
+  #   reverse_video
+  #   concealed
+  #
+  # Foreground color methods:
+  #   black   / fg_black
+  #   red     / fg_red
+  #   green   / fg_green
+  #   yellow  / fg_yellow
+  #   blue    / fg_blue
+  #   magenta / fg_magenta
+  #   cyan    / fg_cyan
+  #   white   / fg_white
+  #
+  # Background color methods:
+  #   bg_black
+  #   bg_red
+  #   bg_green
+  #   bg_yellow
+  #   bg_blue
+  #   bg_magenta
+  #   bg_cyan
+  #   bg_white
+  #
+  # Every combination of the above is also generated as a single method call, producing results including (but not
+  # limited to):
+  #   regular_red
+  #   bold_red
+  #   underscore_red
+  #   blink_red
+  #   reverse_video_red
+  #   concealed_red
+  #   red_on_white / regular_red_on_white
+  #   bold_red_on_white
+  #   underscore_red_on_white
+  #   blink_red_on_white
+  #   . . .
+  #   
+  module Color
+    class << ANSI
+      # Defines the escape sequence, and then delegates to it from within String. This makes it possible to do things
+      # like "this is red".red and so forth. Note that to keep a clean namespace, we'll undef and unalias all of this
+      # at the end of the Color module.
+      def define_with_extension(*names, &block) #:nodoc:
+        _define(*names, &block)
+        names.flatten.each do |name|
+          String.class_eval { define_method(name) { ANSI.send(name) { self } } }
+          Symbol.class_eval { define_method(name) { self.to_s.send(name) } }
+        end
+      end
+      
+      alias _define define #:nodoc:
+      alias define define_with_extension #:nodoc:
+    end
+    
+    ANSI.define("set_color",   "color") do |*values|
+      block = values.last.kind_of?(Proc) ? values.pop : nil
+      colr = "\e[#{values.join(";")}m"
+      if block
+        colr + block.call.to_s + reset_color
+      else
+        colr
+      end
+    end
+    ANSI.define("reset_color", "reset") { color(0) }
+    
+    # Various combinations of colors and text attributes:
+    #   bold, underscore, blink, reverse_video, concealed
+    #   red, fg_red, bg_red, red_on_red, bold_red, bold_red_on_red
+    # etc.
+    colors = %w(black red green yellow blue magenta cyan white)
+    attrs  = { "regular" => 0, "bold" => 1, "underscore" => 4, "blink" => 5, "reverse_video" => 7, "concealed" => 8 }
+    
+    attrs.each do |attr_name, attr_value|
+      ANSI.define(attr_name) { |block| color(attr_value, &block) }              # 0-8
+    end
+    
+    colors.each_with_index do |fg_name, fg_value|
+      fg_value += 30
+      ANSI.define(fg_name, "fg_#{fg_name}") { |block| color(fg_value, &block) } # 30-37  (ie red, fg_red)
+      ANSI.define("bg_#{fg_name}") { |block| color(fg_value + 10, &block) }     # 40-47  (ie bg_red)
+        
+      attrs.each do |attr_name, attr_value|
+        if attr_name.length > 0
+          # (ie bold_red)
+          ANSI.define("#{attr_name}_#{fg_name}") { |block| color(attr_value, fg_value, &block) }
+        end
+      end
+
+      colors.each_with_index do |bg_name, bg_value|
+        bg_value += 40
+        # (ie red_on_blue)
+        ANSI.define("#{fg_name}_on_#{bg_name}") { |block| color(fg_value, bg_value, &block) }
+    
+        attrs.each do |attr_name, attr_value|
+          ANSI.define("#{attr_name}_#{fg_name}_#{bg_name}", "#{attr_name}_#{fg_name}_on_#{bg_name}") do |block|
+            color(attr_value, fg_value, bg_value, &block)
+          end
+        end
+      end
+    end
+    
+    class << ANSI
+      # Cleaning up after ourselves...
+      alias define _define #:nodoc:
+      undef define_with_extension
+      undef _define
+    end
+  end
+end