optics-ansi 0.3.7

data/History.txt

@@ -0,0 +1,87 @@
+
+0.3.7 / 2009-06-19
+
+Finish Hoefile
+ * Create Manifest
+
+0.3.6 / 2009-06-19
+
+Create Rakefile
+ * Add lib/dir methods to /lib/version.rb
+
+0.3.5 / 2009-06-19
+
+Finish documentation for Optics.methods
+ * Add :unhide alias for Optics.normal
+
+0.3.4 / 2009-06-19
+
+Add documentation for String methods
+
+0.3.3 / 2009-06-19
+
+Clean up clerical files
+
+0.3.2 / 2009-06-19
+
+Add C_STRUCTURE Constant in ANSI
+ * Use to Meta-program COLOR functions
+ * Condense color.to_s into one string in Optics.method
+
+0.3.1 / 2009-06-19
+
+Restructure EFFECTS constant
+ * Move codes and aliases into a seperate hash
+ * Represent aliases as an Array
+ * Print aliases from EFFECTS[:e][:alias] Array
+
+0.3.0 / 2009-06-19
+
+Add aliases for dk_color and lt_color
+ * all exising methods and aliases working well
+
+== 0.2.6 / 2009-06-19
+
+Condense all effects methods into meta-prog functions
+ * condense ansi.rb and optics.rb
+ * add ANSI::COLOR_CLASSES Constant
+
+== 0.2.4 / 2009-06-19
+
+Move all Optics.methods into class << self
+ * add aliases for most methods
+ * add Optics.bold alias
+ * add Optics.dark_color shorthands
+ * add Optics.color alias
+
+== 0.2.3 / 2009-06-19
+
+Add Optics.method shorthands for all colors
+
+== 0.2.2 / 2009-06-19
+
+Fix bugs in the color method blocks
+ * add 'clear' alias for 'reset' in Optics.methods
+
+== 0.2.1 / 2009-06-19
+
+Allow Optics.color methods to accept blocks
+ * Divide ANSI into seperate file
+
+== 0.2.0 / 2009-06-19
+
+Add Optics.methods to the Optics class
+ * allow open, unclosed optics
+ * add no_underline, blink_off, normalize
+ * need to add blocks to Optics.methods
+
+== 0.1.2 / 2009-06-19
+
+Add light-colored foreground and background
+ * rename 'foreground' to 'dark'
+ * add additional effects
+ * clean up syntax
+
+== 0.1.1 / 2009-06-18
+
+Add Version module

data/Manifest.txt

@@ -0,0 +1,11 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/optics
+lib/ansi.rb
+lib/optics.rb
+lib/version.rb
+spec/optics_spec.rb
+spec/spec_helper.rb
+test/test_optics.rb

data/README.txt

@@ -0,0 +1,305 @@
+=Optics::ANSI
+* by Mike Zazaian
+* http://optics-ansi.rubyforge.org
+
+== DESCRIPTION:
+
+The most flexible, syntactically elegant library for the colorization
+of text in ANSI terminals. Has more options and better support for
+adding effects to entire areas than the Rainbow gem, and with a more
+elegant syntax than the ssoroka-ansi gem.
+
+== FEATURES/PROBLEMS:
+
+* Adds colors and text effects to instances of the String object.
+* Allows user to toggle colors and effects for all text in the
+terminal through the Optics module.
+
+== SYNOPSIS:
+
+=== Optics::ANSI String methods
+
+==== Font Color
+
+If you want to apply effects to the text only in a single string,
+then you can access the Optics::ANSI methods included in the
+String class, like this:
+
+  "this will be blue".dark(:blue)
+  "this will be blue".color(:blue) # alias
+  "this will be blue".dark_color(:blue) # alias
+
+or, if you want a nice, lighter color:
+
+  "this will be yellow".light(:yellow)
+  "this will be yellow".light_color(:yellow) # alias
+  "this will be yellow".pale(:yellow) # alias
+
+Optics supports all of the standard ANSI colors :
+
+  :black
+  :red
+  :green
+  :yellow
+  :blue
+  :magenta
+  :cyan
+  :white
+  :default
+  
+==== Background Color
+
+Works just like the text color methods.  To call a dark background:
+
+  "this has a dark cyan background".dark_bg(:cyan)
+
+And a light one:
+
+  "this has a light magenta background".light_bg(:magenta)
+
+==== Effects
+
+There are also a number of methods that Optics::ANSI includes in the
+String class for adding other effects.  For the most part, they're all
+pretty self-explanatory:
+  
+  # Bold
+  "this will be bold".bold
+  "this will be bold".bright  # alias
+
+  # Italic
+  "this will be italicized".italic
+  "this will be italicized".italics # alias
+  "this will be italicized".italicize # alias
+
+  # Underline
+  "this will be underlined".underline
+
+  # Blink: makes the text blink
+  "this will blink".blink
+
+  # Inverse: swaps the text and background colors
+  "this will appear inverted".inverse
+  "this will appear inverted".invert #alias
+
+  # Conceal: hides the text
+  "you won't be able to see this".conceal
+  "you won't be able to see this".hide # alias
+
+Dark colors will always be converted to their lighter variant when
+the bold or bright methods are applied.
+
+==== Stacking effects and colors
+
+You can also stack effects on a string.  This will print text to the
+terminal in a bolded, light blue font with an underline:
+
+  puts "this will be very pretty".light(:blue).bold.underline
+
+or
+
+  puts "this will also be pretty".dark(:green).light_bg(:green).italics.blink
+
+==== A note on 'puts'
+
+If you're testing this in irb, all of the methods above will only
+return the encoded string.  To actually see the effects, you'll need
+to print them to the terminal like this:
+
+  puts "this actually looks pretty".color(:white).light_bg(:yellow).bright
+
+
+=== Methods in the Optics module
+
+Calling these effects directly from the Optics module works exactly
+as it does on String objects, but with a few exceptions, being:
+
+* When you call a method from the Optics module, it doesn't close
+itself.
+
+* Some methods in the Optics module take blocks {}.
+
+* There are more aliases available for colors.
+
+* There are methods for cancelling colors or effects:
+ * Optics.cancel
+ * Optics.normal
+ * Optics.no_underline
+ * Optics.blink_off
+ * Optics.reveal
+
+==== Optics.color
+
+The Optics.color methods initialize the use of a color in the
+terminal until cancelled or overwritten.  This code will make
+everything in the terminal dark blue until Optics.cancel is called:
+
+  puts Optics.dark(:blue)
+
+The Optics module also has method aliases for each color, so all of
+following are valid ways to call Optics.dark(:blue):
+
+  puts Optics.blue # alias
+  puts Optics.dk_blue # alias
+  puts Optics.dark_blue # alias
+
+The lighter variant of blue can be initialized with:
+
+  puts Optics.light(:blue)
+  puts Optics.lt_blue # alias
+  puts Optics.light_blue # alias
+
+Background colors can be initialized with:
+
+  puts Optics.dark_bg(:yellow)
+  puts Optics.light_bg(:red)
+
+When you want things to stop being blue, you can reset them with:
+
+  puts Optics.reset
+
+or:
+
+  puts Optics.cancel
+
+Note that these will also cancel ALL other effects that have been
+activated in the terminal, including bolding, underline and italics.
+
+==== Optics.color {"string"}
+
+The base, non-alias Optics.color methods can also take blocks in
+order to act like the "string".color methods.
+
+For example, this will print a green "snaaaaaaaaaaaaaaake" in the terminal:
+
+  puts Optics.light(:green) { "snnaaaaaaaaaaaake" }
+
+This will also work with:
+  
+  puts Optics.dark(:green) { "snnaaaaaaaaaaaaake" }
+  puts Optics.dark_bg(:green) { "snnaaaaaaaaaaaaake" }
+  puts Optics.light_bg(:green) { "snnaaaaaaaaaaaaake" }
+
+But because none of the aliases can take blocks, the following
+examples WILL NOT WORK:
+
+  puts Optics.dark_green { "snaaaaaaaaaaake" }
+  puts Optics.light_yellow { "canary" }
+  puts Optics.black { "crow" }
+
+However, because these { blocks } call the Optics.reset method to
+stop the color at the end of the word, calling one of these WILL
+ALSO CANCEL ALL OTHER EFFECTS IN THE TERMINAL.
+
+==== Optics.effects
+
+Because effects called by Optics.effects don't automatically close
+themselves, they're a little more flexible.
+
+You can, for example, turn on an underline (in addition to any
+existing colors or effects), then turn it off later without
+cancelling the other active effects, like this:
+
+  puts Optics.underline
+
+Then, to turn it back off:
+
+  puts Optics.no_underline.
+
+The following pairs work in the same way:
+
+  *# Blink*
+  puts Optics.blink
+
+  *# No Blink*
+  puts Optics.blink_off
+  puts Optics.no_blink # alias
+
+  *# Bright*
+  puts Optics.bright
+  puts Optics.bold # alias
+
+  *# No Bright*
+  puts Optics.normal
+  puts Optics.normalize # alias
+  puts Optics.unbold # alias
+
+  *# Conceal*
+  puts Optics.conceal
+  puts Optics.hide # alias
+
+  *# No Conceal (Reveal)*
+  puts Optics.reveal
+  puts Optics.unhide # alias
+
+There are also a couple of Optics methods that don't have their own
+closing methods, and can only be cleared with Optics.reset:
+
+  # Italic
+  Optics.italic
+  Optics.italics # alias
+  Optics.italicize # alias
+
+  # Inverse
+  Optics.inverse
+  Optics.invert # alias
+
+
+== REQUIREMENTS:
+
+You must have rubygems installed to use Optics as a gem.  To install
+Rubygems on a debian or ubuntu linux system, do:
+
+  sudo aptitude update && sudo aptitude install rubygems
+
+== INSTALL:
+
+=== As a Rubygem
+
+  sudo gem install --remote optics-ansi
+
+Then, add Optics to your script with:
+
+  require 'rubygems'
+  require 'optics'
+
+=== Directly into your script
+
+If you want to include Optics directly into your script, you can
+download Optics as a .tgz or .zip package from the Optics homepage at:
+
+  http://optics-ansi.rubygems.org
+
+Once you have the package, add Optics to your script's directory, add
+the optics directory to your $LOAD_PATH variable...
+
+  $LOAD_PATH << "./optics"
+
+.. and require Optics at the top of your script:
+
+  require 'optics'
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Mike Zazaian
+
+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/Rakefile

@@ -0,0 +1,30 @@
+
+require 'rubygems'
+require 'hoe'
+$:.unshift(File.dirname(__FILE__) + "/lib")
+require 'optics'
+
+Hoe.new('optics', Optics::VERSION.pretty) do |p|
+  p.name = "optics-ansi"
+  p.developer "Mike Zazaian", 'zazaian@gmail.com'
+  p.url = "http://optics-ansi.rubyforge.org"
+
+  p.rubyforge_name = "optics-ansi"
+  p.summary = "Flexible, easy colorization for terminal output."
+  p.description = <<-EOL
+    A flexible, easy-to-use module for adding color and effects to
+    text in ANSI terminals.
+  EOL
+
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.remote_rdoc_dir = '' # Release to root
+end
+
+desc "Simple test on packaged files to make sure they are all there"
+task :verify => :package do
+  # An error message will be displayed if files are missing
+  if system %(ruby -e "require 'pkg/optics-#{Optics::VERSION}/lib/optics'")
+    puts "\nThe library files are present"
+  end
+end
+

data/bin/optics

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib optics]))
+
+# EOF

data/lib/ansi.rb

@@ -0,0 +1,138 @@
+
+module Optics
+  module Optics::ANSI
+    
+    COLORS = { 
+      :black => 0,
+      :red => 1,
+      :green => 2,
+      :yellow => 3,
+      :blue => 4,
+      :magenta => 5,
+      :cyan => 6,
+      :white => 7,
+      :default => 9
+    }
+    
+    EFFECTS = {
+      :reset => {
+        :code => 0,
+        :alias => [:clear]
+        },
+      :bright => {
+        :code => 1,
+        :alias => [:bold]
+        },
+      :italic => {
+        :code => 3,
+        :alias => [:italicize, :italics]
+        },
+      :underline => {
+        :code => 4
+        },
+      :blink => {
+        :code => 5
+        },
+      :inverse => {
+        :code => 7,
+        :alias => [:invert]
+        },
+      :conceal => {
+        :code => 8,
+        :alias => [:hide]
+        },
+      :normal => {
+        :code => 22,
+        :alias => [:normalize, :unbold]
+        },
+      :no_underline => {
+        :code => 24
+        },
+      :blink_off => {
+        :code => 25,
+        :alias => [:no_blink]
+        },
+      :reveal => {
+        :code => 28,
+        :alias => [:unhide]
+        }
+    }
+    
+    CLASSES = {
+      :dark => 30,
+      :light => 90,
+      :dark_bg => 40,
+      :light_bg => 100
+    }
+
+    C_STRUCTURE = {
+      :dark => {
+        :text => 30,
+        :bg => 40
+        },
+      :light => {
+        :text => 90,
+        :bg => 100
+        }
+      }
+    
+    # Dark-colored text
+  	def dark(color)
+  	  base(color, 3)
+    end
+    alias_method :dark_color, :dark
+    alias_method :color, :dark
+    
+    # Light-colored text
+  	def light(color)
+  	  base(color, 9)
+    end
+    alias_method :light_color, :light
+    alias_method :pale, :light
+    
+    # Dark-colored background
+    def dark_bg(color)
+      base(color,4)
+    end
+    
+    # Light-colored background
+    def light_bg(color)
+      base(color,10)
+    end
+    
+    
+    # Define all text EFFECTS
+    EFFECTS.keys.each do |e|
+      send :define_method, e do
+        encode(EFFECTS[e][:code])
+      end
+      
+      # Add each alias listed in the EFFECTS Constant
+      if EFFECTS[e][:alias]
+        EFFECTS[e][:alias].each do |a|
+          alias_method a, e
+        end
+      end
+    end 
+   
+    protected
+    def encode(code) #:nodoc:
+      out = self
+      match = out.match(/^(\e\[([\d;]+)m)*/)
+      out.insert(match.end(0), "\e[#{code}m")
+      out.concat("\e[0m") unless out =~ /\e\[0m$/
+      out
+    end
+  	
+    def base(color, tens) #:nodoc:
+      color = color.to_sym
+      ANSI.validate(color)
+      encode(COLORS[color] + tens * 10)
+  	end
+    
+    def ANSI.validate(color) #:nodoc:
+      raise ArgumentError.new("Unknown color, valid colors: #{COLORS.keys.join(', ')}") \
+        unless COLORS.keys.include?(color)
+    end
+  end
+end

data/lib/optics.rb

@@ -0,0 +1,127 @@
+#= Optics
+#== Written by Mike Zazaian
+#== zazaian (at) gmail.com
+
+$LOAD_PATH << "./"
+require 'ansi'
+require 'version'
+
+module Optics
+  
+  include Optics::VERSION
+  include Optics::ANSI
+
+  class << self # Optics.methods
+ 
+    #= COLOR-SPECIFIC-METHODS
+    
+    #== Define shorthand methods for each color
+    Optics::ANSI::COLORS.keys.each do |c|
+      s = c.to_s # Color as String
+      light = "light_#{s}".to_sym
+      lt = "lt_#{s}".to_sym
+      dark = "dark_#{s}".to_sym
+      dk = "dk_#{s}".to_sym
+      
+      #=== Dark
+      send :define_method, c do
+        encode(ANSI::COLORS[c] + 30)
+      end
+      alias_method dark, c
+      alias_method dk, c
+      
+      #=== Light
+      next if [:default].member?(c)
+      send :define_method, light do
+        encode(ANSI::COLORS[c] + 90)
+      end
+      alias_method lt, light
+    end
+
+    #=== Dark-colored text
+  	def dark(color, &block)
+  	  o = base(color, 3)
+      if block_given?
+        o += yield
+        o += reset
+      end
+      o
+    end
+    alias_method :dark_color, :dark
+    alias_method :color, :dark
+    
+    #=== Light-colored text
+  	def light(color, &block)
+  	  o = base(color, 9)
+      if block_given?
+        o += yield
+        o += reset
+      end
+      o
+    end
+    alias_method :light_color, :light
+    alias_method :pale, :light
+    
+    #=== Dark-colored background
+    def dark_bg(color, &block)
+  	  o = base(color, 4)
+      if block_given?
+        o += yield
+        o += reset
+      end
+      o
+    end
+    
+    #=== Light-colored background
+    def light_bg(color, &block)
+  	  o = base(color, 10)
+      if block_given?
+        o += yield
+        o += reset
+      end
+      o
+    end
+    
+    #= Define shorthand methods for each EFFECT
+    Optics::ANSI::EFFECTS.keys.each do |e|
+      send :define_method, e do
+        encode(ANSI::EFFECTS[e][:code])
+      end      
+      # Define aliases for each Optics.effect
+      if ANSI::EFFECTS[e][:alias]
+        ANSI::EFFECTS[e][:alias].each do |a|
+          alias_method a, e
+        end
+      end
+    end 
+    
+    protected
+    def encode(code) #:nodoc:
+      "\e[#{code}m"
+    end
+  	
+    def base(color, tens) #:nodoc:
+      color = color.to_sym
+      ANSI.validate(color)
+      encode(ANSI::COLORS[color] + tens * 10)
+  	end
+  end
+end  # module Optics
+
+
+begin
+  require 'Win32/Console/ANSI' if RUBY_PLATFORM =~ /win32/
+rescue LoadError
+#  raise 'You must gem install win32console to use color on Windows'
+  module Optics::ANSI
+    protected
+    def encode(code)
+      self
+    end
+  end
+end
+
+Optics.require_all_libs_relative_to(__FILE__)
+String.send(:include, Optics::ANSI)
+
+# EOF

data/lib/version.rb

@@ -0,0 +1,39 @@
+
+# :stopdoc:
+module Optics
+  module VERSION
+    MAJOR = 0
+    MINOR = 3
+    TINY = 7
+    REVISION = 19
+  
+    class << self
+      def pretty
+        "#{MAJOR}.#{MINOR}.#{TINY}"
+      end
+      alias_method :print, :pretty
+    end
+  end
+
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module Optics

data/spec/optics_spec.rb

@@ -0,0 +1,11 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Optics do
+  <<-EOL
+    A flexible, easy-to-use module for adding color and effects to
+    text in ANSI terminals.
+  EOL
+end
+
+# EOF

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib prism]))
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+# EOF

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: optics-ansi
+version: !ruby/object:Gem::Version 
+  version: 0.3.7
+platform: ruby
+authors: 
+- Mike Zazaian
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-20 00:00:00 +10:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.12.2
+    version: 
+description: A flexible, easy-to-use module for adding color and effects to text in ANSI terminals.
+email: 
+- zazaian@gmail.com
+executables: 
+- optics
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/optics
+- lib/ansi.rb
+- lib/optics.rb
+- lib/version.rb
+- spec/optics_spec.rb
+- spec/spec_helper.rb
+- test/test_optics.rb
+has_rdoc: true
+homepage: http://optics-ansi.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: optics-ansi
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Flexible, easy colorization for terminal output.
+test_files: 
+- test/test_optics.rb