ansi-sys 0.4.1 → 0.5.0

data/ChangeLog

@@ -1,3 +1,10 @@
+* 2007-11-03 zunda <zunda at freeshell.org>
+- (0.5.0)
+- Formatted RDoc
+
+* 2007-11-01 zunda <zunda at freeshell.org>
+- Formatted RDoc through Screen class
+
 * 2007-10-27 zunda <zunda at freeshell.org>
 - (0.4.1)
 - Updated History.txt

data/History.txt

@@ -1,3 +1,6 @@
+== 0.5.0 2007-11-03
+* Made Rdoc
+
 == 0.4.1 2007-10-27
 
 * All the codes on http://en.wikipedia.org/wiki/ANSI_escape_code

data/lib/ansisys.rb

@@ -11,13 +11,14 @@ require 'webrick'
 module AnsiSys
 	module VERSION	#:nodoc:
 		MAJOR = 0
-		MINOR = 4
-		TINY = 1
+		MINOR = 5
+		TINY = 0
 
 		STRING = [MAJOR, MINOR, TINY].join('.')
 	end
 
 	module CSSFormatter
+		# make a CSS style-let from a Hash of CSS settings
 		def hash_to_styles(hash, separator = '; ')
 			unless hash.empty?
 				return hash.map{|e| "#{e[0]}: #{e[1].join(' ')}"}.join(separator)
@@ -40,16 +41,19 @@ module AnsiSys
 
 		attr_reader :buffer
 
+		# _csis_ is an Array of Code Sequence Introducers
+		# which can be \e[, \x9B, or both
 		def initialize(csis = ["\x1b["])	# CSI can also be "\x9B"
 			@code_start_re = Regexp.union(*(CODE_EQUIVALENT.keys + csis))
 			@buffer = ''
 		end
 
+		# add the String (clear text with some or no escape sequences) to buffer
 		def push(string)
 			@buffer += string
 		end
 
-		# returns array of tokens while deleting the tokenized part of the string
+		# returns array of tokens while deleting the tokenized part from buffer
 		def lex!
 			r = Array.new
 			@buffer.gsub!(/(?:\r\n|\n\r)/, "\n")
@@ -79,19 +83,21 @@ module AnsiSys
 	end
 
 	class Characters
+		# widths of characters
 		WIDTHS = {
 			"\t" => 8,
 		}
 
-		attr_reader :string
-		attr_reader :sgr
-		attr_reader :initial_cursor
+		attr_reader :string	# clear text
+		attr_reader :sgr	# Select Graphic Rendition associated with the text
 
 		def initialize(string, sgr)
 			@string = string
 			@sgr = sgr
 		end
 
+		# echo the string onto the _screen_ with initial cursor as _cursor_
+		# _cursor_ position will be changed as the string is echoed
 		def echo_on(screen, cursor)
 			each_char do |c|
 				w = width(c)
@@ -102,12 +108,14 @@ module AnsiSys
 		end
 
 		private
+		# iterator on each character
 		def each_char(&block)
 			@string.scan(/./).each do |c|
 				yield(c)
 			end
 		end
 
+		# width of a character
 		def width(char)
 			if WIDTHS.has_key?(char)
 				return WIDTHS[char]
@@ -122,12 +130,13 @@ module AnsiSys
 	end
 
 	class Cursor
+		# Escape sequence codes processed in this Class
 		CODE_LETTERS = %w(A B C D E F G H f)
 
-		attr_reader :cur_col
-		attr_reader :cur_row
-		attr_accessor :max_col
-		attr_accessor :max_row
+		attr_reader :cur_col	# current column number (1-)
+		attr_reader :cur_row	# current row number (1-)
+		attr_accessor :max_col	# maximum column number
+		attr_accessor :max_row	# maximum row number
 
 		def initialize(cur_col = 1, cur_row = 1, max_col = 80, max_row = 25)
 			@cur_col = cur_col
@@ -136,6 +145,8 @@ module AnsiSys
 			@max_row = max_row
 		end
 
+		# applies self an escape sequence code that ends with _letter_ as String
+		# and with some _pars_ as Integers
 		def apply_code!(letter, *pars)
 			case letter
 			when 'A'
@@ -178,6 +189,7 @@ module AnsiSys
 			return self
 		end
 
+		# changes current location for a character with _width_ to be echoed
 		def advance!(width = 1)
 			r = nil
 			@cur_col += width
@@ -195,21 +207,38 @@ module AnsiSys
 	class SGR
 		extend CSSFormatter
 
+		# Escape sequence codes processed in this Class
 		CODE_LETTERS = %w(m)
 
-		attr_reader :intensity	# :normal, :bold, or :faint
-		attr_reader :italic	# :off or :on
-		attr_reader :underline	# :none, :single, or :double
-		attr_reader :blink	# :off, :slow, or :rapid
-		attr_reader :image	# :positive or :negative
-		attr_reader :conceal	# :off or :on
-		attr_reader :foreground	# :black, :red, :green, :yellow, :blue, :magenta, :cyan, or :white
-		attr_reader :background	# :black, :red, :green, :yellow, :blue, :magenta, :cyan, or :white
+		# :normal, :bold, or :faint
+		attr_reader :intensity
+
+		# :off or :on
+		attr_reader :italic
+
+		# :none, :single, or :double
+		attr_reader :underline
+
+		# :off, :slow, or :rapid
+		attr_reader :blink
+
+		# :positive or :negative
+		attr_reader :image
+
+		# :off or :on
+		attr_reader :conceal
+
+		# :black, :red, :green, :yellow, :blue, :magenta, :cyan, or :white
+		attr_reader :foreground
+
+		# :black, :red, :green, :yellow, :blue, :magenta, :cyan, or :white
+		attr_reader :background
 
 		def initialize
 			reset!
 		end
 
+		# true if all the attributes are same
 		def ==(other)
 			instance_variables.each do |ivar|
 				return false unless instance_eval(ivar) == other.instance_eval(ivar)
@@ -217,10 +246,13 @@ module AnsiSys
 			return true
 		end
 
+		# resets attributes
 		def reset!
 			apply_code!('m', 0)
 		end
 
+		# applies self an escape sequence code that ends with _letter_ as String
+		# and with some _pars_ as Integers
 		def apply_code!(letter = 'm', *pars)
 			raise AnsiSysError, "Invalid code for SGR: #{letter.inspect}" unless 'm' == letter
 			pars = [0] unless pars
@@ -264,6 +296,8 @@ module AnsiSys
 			return self
 		end
 
+		# renders self as :html or :text _format_ - makes a <span> html scriptlet.
+		# _colors_ can be Screen.default_css_colors(_inverted_, _bright_).
 		def render(format = :html, position = :prefix, colors = Screen.default_css_colors)
 			case format
 			when :html
@@ -288,10 +322,12 @@ module AnsiSys
 			end
 		end
 
+		# CSS stylelet
 		def css_style(colors = Screen.default_css_colors)
 			return CSSFormatter.hash_to_styles(css_styles(colors))
 		end
 
+		# a Hash of CSS stylelet
 		def css_styles(colors = Screen.default_css_colors)
 			r = Hash.new{|h, k| h[k] = Array.new}
 			# intensity is not (yet) implemented
@@ -335,7 +371,7 @@ module AnsiSys
 			25 => [:blink, :off],
 			27 => [:image, :positive],
 			28 => [:conceal, :off],
-		}
+		}	# :nodoc:
 
 		COLOR = {
 			0 => :black,
@@ -346,17 +382,18 @@ module AnsiSys
 			5 => :magenta,
 			6 => :cyan,
 			7 => :white,
-		}
+		}	# :nodoc:
 
 	end
 
 	class Screen
-		CODE_LETTERS = %w()
+		# Escape sequence codes processed in this Class
+		CODE_LETTERS = %w()	# :nodoc:
 
 		def self.default_foreground; :white; end
 		def self.default_background; :black; end
 
-		# intensity -> color
+		# a Hash of color names for each intensity
 		def self.default_css_colors(inverted = false, bright = false)
 			r = {
 				:normal => {
@@ -407,6 +444,7 @@ module AnsiSys
 			return r
 		end
 
+		# a Hash of CSS stylelet to be used in <head>
 		def self.css_styles(colors = Screen.default_css_colors, max_col = nil, max_row = nil)
 			h = {
 				'color' => [colors[:normal][:white]],
@@ -418,12 +456,17 @@ module AnsiSys
 			return h
 		end
 
+		# CSS stylelet to be used in <head>
 		def self.css_style(*args)
 			return "pre.screen {\n\t" + CSSFormatter.hash_to_styles(self.css_styles(*args), ";\n\t") + ";\n}\n"
 		end
 
+		# a Hash of keys as rows,
+		# which each value a Hash of keys columns and each value as
+		# an Array of character, its width, and associated SGR
 		attr_reader :lines
 
+		# a Screen
 		def initialize(colors = Screen.default_css_colors, max_col = nil, max_row = nil)
 			@colors = colors
 			@max_col = max_col
@@ -431,14 +474,19 @@ module AnsiSys
 			@lines = Hash.new{|hash, key| hash[key] = Hash.new}
 		end
 
+		# CSS stylelet to be used in <head>
 		def css_style
 			self.class.css_style(@colors, @max_col, @max_row)
 		end
 
+		# register the _char_ at a specific location on Screen
 		def write(char, char_width, col, row, sgr)
 			@lines[Integer(row)][Integer(col)] = [char, char_width, sgr.dup]
 		end
 
+		# render the characters into :html or :text
+		# Class name in CSS can be specified as _css_class_.
+		# Additional stylelet can be specified as _css_style_.
 		def render(format = :html, css_class = 'screen', css_style = nil)
 			result = case format
 			when :text
@@ -490,24 +538,33 @@ module AnsiSys
 			return result
 		end
 
-		def apply_code!(letter, *pars)	# TODO - some codes
+		# applies self an escape sequence code that ends with _letter_ as String
+		# and with some _pars_ as Integers
+		def apply_code!(letter, *pars)
 			return self
-		end
+		end	# :nodoc:
 	end
 
 	class Terminal
+		# Escape sequence codes processed in this Class
 		CODE_LETTERS = %w(J K S T n s u)
 
+		# _csis_ is an Array of Code Sequence Introducers
+		# which can be \e[, \x9B, or both
 		def initialize(csis = ["\x1b["])
 			@lexer = Lexer.new(csis)
 			@stream = Array.new
 		end
 
+		# echoes _data_, a String of characters or escape sequences
+		# to the Terminal.
+		# This method actually just buffers the echoed data.
 		def echo(data)
 			@lexer.push(data)
 			return self
 		end
 
+		# CSS stylelet to be used in <head>
 		def css_style(format = :html, max_col = 80, max_row = nil, colors = Screen.default_css_colors)
 			case format
 			when :html
@@ -517,6 +574,9 @@ module AnsiSys
 			end
 		end
 
+		# renders the echoed data as _format_ of :html or :text.
+		# _max_col_, _max_row_ can be specified as Integer.
+		# _colors_ can be Screen.default_css_colors(_inverted_, _bright_).
 		def render(format = :html, max_col = 80, max_row = nil, colors = Screen.default_css_colors, css_class = 'screen', css_style = nil)
 			screens = populate(format, max_col, max_row, colors)
 			separator = case format
@@ -528,6 +588,8 @@ module AnsiSys
 			return screens.map{|screen| screen.render(format, css_class, css_style)}.join(separator)
 		end
 
+		# applies self an escape sequence code that ends with _letter_ as String
+		# and with some _pars_ as Integers
 		def apply_code!(letter, *pars)
 			case letter
 			when 'J'
@@ -628,6 +690,11 @@ module AnsiSys
 end
 
 if defined?(Hiki) and Hiki::Plugin == self.class
+	# a Hiki plugin method to render a file of text with ANSI escape sequences.
+	# Attached file name should be specified as _file_name_.
+	# _max_row_ can be specified.
+	# _invert_ and _bright_ can be specified to change colors.
+	# _page_ can be specified to show a file attached to another page.
 	def ansi_screen(file_name, max_row = 80, invert = false, bright = true, page = @page)
 		return '' unless file_name =~ /\.(txt|rd|rb|c|pl|py|sh|java|html|htm|css|xml|xsl|sql|yaml)\z/i 
 		page_file_name = "#{page.untaint.escape}/#{file_name.untaint.escape}"

data/website/index.html

@@ -35,10 +35,7 @@
       <p>Get Version</p>
       <a href="http://rubyforge.org/projects/ansi-sys" class="numbers">0.4.1</a>
     </div>
-    <h1>&#x2192; &#8216;ansi-sys&#8217;</h1>
-
-
-	<h2>What</h2>
+    <h2>What</h2>
 
 
 	<p>MS-DOS console (with <code>DEVICE=ANSI.SYS</code>), Linux
@@ -85,9 +82,12 @@ misc/plugin directory and configure Hiki to enable the plugin.</p>
 	<p>As a Ruby library:</p>
 
 
-<pre>terminal = Terminal.new
+<pre>
+require 'ansisys'
+terminal = AnsiSys::Terminal.new
 terminal.echo("ansi-escaped-text")
-terminal.render #=&gt; HTML fragment</pre>
+terminal.render #=&gt; HTML fragment
+</pre>
 
 	<p>As a Hiki plugin:</p>
 
@@ -110,7 +110,7 @@ terminal.render #=&gt; HTML fragment</pre>
 	<p>Please refer
 <a href="rdoc/files/License_txt.html">License.txt</a></p>
     <p class="coda">
-      zunda, 21st October 2007<br>
+      zunda, 3rd November 2007<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

data/website/index.txt

@@ -1,8 +1,5 @@
 h1. Ruby-ANSI.SYS
 
-h1. → 'ansi-sys'
-
-
 h2. What
 
 MS-DOS console (with <code>DEVICE=ANSI.SYS</code>), Linux
@@ -41,9 +38,12 @@ h2. Usage
 
 As a Ruby library:
 
-<pre>terminal = Terminal.new
+<pre>
+require 'ansisys'
+terminal = AnsiSys::Terminal.new
 terminal.echo("ansi-escaped-text")
-terminal.render #=> HTML fragment</pre>
+terminal.render #=> HTML fragment
+</pre>
 
 As a Hiki plugin:
 

data/website/stylesheets/screen.css

@@ -1,12 +1,12 @@
 body {
-  background-color: #E1D1F1;
+  background-color: #FFB;
   font-family: "Georgia", sans-serif;
   line-height: 1.6em;
   padding: 1.6em 0 0 0;
-  color: #333;
+  color: #000;
 }
 h1, h2, h3, h4, h5, h6 {
-  color: #444;
+  color: #008;
 }
 h1 { 
   font-family: sans-serif;
@@ -22,7 +22,7 @@ li {
   list-style-type: square;
 }
 a {
-  color: #5E5AFF;
+  color: #008;
   font-weight: normal;
   text-decoration: underline;
 }
@@ -45,14 +45,14 @@ blockquote {
 
 table {
   line-height: 1.4em;
-  color: #ff8;
+  color: #008;
   background-color: #111;
   padding: 2px 10px 2px 10px;
 	border-style: dashed;
 }
 
 th {
-	color: #fff;
+	color: #008;
 }
 
 td {
@@ -75,8 +75,8 @@ pre, code {
   line-height: 1.4em;
 }
 pre {
-  color: #ff8;
-  background-color: #111;
+  color: #0F0;
+  background-color: #010;
   padding: 2px 10px 2px 10px;
 }
 .comment { color: #aaa; font-style: italic; }
@@ -95,12 +95,12 @@ pre {
   text-align: right;
   font-family: sans-serif;
   font-weight: normal;
-  background-color: #B3ABFF;
-  color: #141331;
+  background-color: #FFF;
+  color: #008;
   padding: 15px 20px 10px 20px;
   margin: 0 auto;
 	margin-top: 15px;
-  border: 3px solid #141331;
+  border: 3px solid #000;
 }
 
 #version .numbers {
@@ -113,16 +113,16 @@ pre {
 
 #version p {
   text-decoration: none;
-	color: #141331;
-	background-color: #B3ABFF;
+	color: #008;
+	background-color: #FFF;
 	margin: 0;
 	padding: 0;
 }
 
 #version a {
   text-decoration: none;
-	color: #141331;
-	background-color: #B3ABFF;
+	color: #008;
+	background-color: #FFF;
 }
 
 .clickable {

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.4
+rubygems_version: 0.9.2
 specification_version: 1
 name: ansi-sys
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
-date: 2007-10-27 00:00:00 -10:00
+  version: 0.5.0
+date: 2007-11-03 00:00:00 -10:00
 summary: Ruby-ANSI.SYS is a library to render texts with ANSI escape sequences.
 require_paths: 
 - lib