rudy 0.4.0 → 0.6.0

data/lib/annoy.rb

@@ -0,0 +1,270 @@
+#---
+# TODO: Use Matrix to give a more accurate annoyance factor
+# TODO: Add trivia questions
+#+++
+
+require 'timeout'
+require 'sysinfo'
+require 'highline'
+
+# = Annoy 
+#
+# Like your annoying friend that asks you questions all the time.
+#
+class Annoy
+  
+  attr_accessor :factor
+  attr_accessor :flavor
+  attr_accessor :answer
+  attr_accessor :writer
+  attr_accessor :period
+  attr_accessor :system
+  
+  @@operators = {
+    :low      => %w(+ -),
+    :medium   => %w(* -),
+    :high     => %w(& * -),
+    :insane   => %w(** << | & *)
+  }.freeze
+  
+  @@strlen = {
+    :low      => 2,
+    :medium   => 3,
+    :high     => 4,
+    :insane   => 32
+  }.freeze
+  
+  @@randsize = {
+    :low      => 10,
+    :medium   => 14,
+    :high     => 50,
+    :insane   => 1000
+  }.freeze
+  
+  @@period = 60.freeze    # max seconds to wait
+  @@flavors = [:numeric, :string].freeze
+  @@skip = false          # skip questions
+  
+  # Calling this method tells Annoy to not prompt for
+  # a response. All questions will return true. 
+  def Annoy.enable_skip; @@skip = true; end
+  # Tells annoy to prompt for a response. 
+  def Annoy.disable_skip; @@skip = false; end
+  # Returns true of Annoy is in skip mode
+  def Annoy.skip?; @@skip; end
+  
+  # * +factor+ annoyance factor, one of :low (default), :medium, :high, :insane
+  # * +flavor+ annoyance flavor, one of :rand (default), :numeric, string
+  # * +writer+ an IO object to write to. Default: STDERR
+  # * +period+ the amount of time to wait in seconds. Default: 60
+  def initialize(opts={:factor=>:medium, :flavor=>:rand, :writer=>STDOUT, :period=>nil})
+    @factor = opts[:factor]
+    @flavor = Annoy.get_flavor(opts[:flavor])
+    @writer = opts[:writer]
+    @period = opts[:period] || @@period
+    unless Annoy.respond_to?("#{@flavor}_question")
+      raise "Hey, hey, hey. I don't know that flavor! (#{@flavor})" 
+    end
+  end
+  
+  # Generates and returns a question. The correct response is available
+  # as +@answer+.
+  def question
+    q, @answer =Annoy.question(@factor, @flavor)
+    q
+  end
+  
+  # A wrapper for string_question and numberic_question
+  def Annoy.question(factor=:medium, flavor=:rand)
+    raise "Come on, you ruined the flavor!" unless flavor
+    Annoy.send("#{flavor}_question", factor)
+  end
+  
+  # Generates a random string
+  def Annoy.string_question(factor=:medium)
+    # Strings don't need to be evaluated so the answer is the
+    # same as the question.
+    str = strand @@strlen[factor]
+    [str,str]
+  end
+  
+  # * Generates a rudimentary numeric equation in the form: (Integer OPERATOR Integer).
+  # * Returns [equation, answer]
+  def Annoy.numeric_question(factor=:medium)
+    equation = answer = 0
+    while answer < 10
+      vals = [rand(@@randsize[factor])+1, 
+              @@operators[factor][ rand(@@operators[factor].size) ],
+              rand(@@randsize[factor])+1 ]
+      equation = "(%d %s %d)" % vals
+      answer = eval(equation)
+    end
+    [equation, answer]
+  end
+  
+  # Prints a question to +writer+ and waits for a response on STDIN. 
+  # It checks whether STDIN is connected a tty so it doesn't block on gets
+  # when there's no human around to annoy. It will return <b>TRUE</b> when
+  # STDIN is NOT connected to a tty (when STDIN.tty? returns false).
+  # * +msg+ The message to print. Default: "Please confirm."
+  # Returns true when the answer is correct, otherwise false.
+  def Annoy.challenge?(msg="Please confirm.", factor=:medium, flavor=:rand, writer=STDOUT, period=nil)
+    return true unless STDIN.tty? # Humans only!
+    return true if Annoy.skip?
+    begin
+      success = Timeout::timeout(period || @@period) do
+        flavor = Annoy.get_flavor(flavor)
+        question, answer = Annoy.question(factor, flavor)
+        msg = "#{msg} To continue, #{Annoy.verb(flavor)} #{question}: "
+        #writer.print msg
+        #if ![:medium, :high, :insane].member?(factor) && flavor == :numeric
+        #writer.print "(#{answer}) " 
+        #writer.flush
+        #end
+        #response = Annoy.get_response(writer)
+        
+        trap("SIGINT") { raise Annoy::GiveUp  }
+        
+        highline = HighLine.new 
+        response = highline.ask(msg) { |q| 
+          q.echo = '*'             # Don't display response
+          q.overwrite = true       # Erase the question afterwards
+          q.whitespace = :strip    # Remove whitespace from the response
+          q.answer_type = Integer  if flavor == :numeric
+        }
+
+        ret = (response == answer)
+        writer.puts "Incorrect" unless ret
+        ret
+      end
+    rescue Annoy::GiveUp => ex
+      writer.puts $/, "Giving up!"
+      false
+    rescue Timeout::Error => ex
+      writer.puts $/, "Times up!"
+      false
+    end
+  end
+  
+  # Runs a challenge with the message, "Are you sure?"
+  # See: Annoy.challenge?
+  def Annoy.are_you_sure?(factor=:medium, flavor=:rand, writer=STDOUT)
+    Annoy.challenge?("Are you sure?", factor, flavor, writer)
+  end
+  
+  # Runs a challenge with the message, "Proceed?"
+  # See: Annoy.challenge?
+  def Annoy.proceed?(factor=:medium, flavor=:rand, writer=STDOUT)
+    Annoy.challenge?("Proceed?", factor, flavor, writer)
+  end
+  
+  # See: Annoy.challenge?
+  # Uses the value of @flavor, @factor, and @writer
+  def challenge?(msg="Please confirm.")
+    Annoy.challenge?(msg, @factor, @flavor, @writer)
+  end
+  
+  # See: Annoy.pose_question
+  # Uses the value of @writer
+  def pose_question(msg, regexp)
+    Annoy.pose_question(msg, regexp, @writer)
+  end
+  
+  # Prints a question to writer and waits for a response on STDIN. 
+  # It checks whether STDIN is connected a tty so it doesn't block on gets.
+  # when there's no human around to annoy. It will return <b>TRUE</b> when
+  # STDIN is NOT connected to a tty.
+  # * +msg+ The question to pose to the user
+  # * +regexp+ The regular expression to match the answer. 
+  def Annoy.pose_question(msg, regexp, writer=STDOUT, period=nil)
+    return true unless STDIN.tty? # Only ask a question if there's a human
+    return true if Annoy.skip?
+    begin
+      success = Timeout::timeout(period || @@period) do
+        regexp &&= Regexp.new regexp
+        writer.print msg 
+        writer.flush if writer.respond_to?(:flush)
+        response = Annoy.get_response
+        regexp.match(response)
+      end
+    rescue Timeout::Error => ex
+      writer.puts $/, "Times up!"
+      false
+    end
+  end
+ 
+  
+ private 
+  def Annoy.get_response(writer=STDOUT)
+    return true unless STDIN.tty? # Humans only
+    return true if Annoy.skip?
+    # TODO: Count the number of keystrokes to prevent copy/paste.
+    # We can probably use Highline. 
+    # We likely need to be more specific but this will do for now.
+    #if ::SystemInfo.new.os == :unix 
+    #  begin
+    #    response = []
+    #    char = nil
+    #    system("stty raw -echo") # Raw mode, no echo
+    #    while char != "\r" || response.size > 5
+    #      char = STDIN.getc.chr
+    #      writer.print char
+    #      writer.flush
+    #      response << char
+    #    end
+    #    writer.print "\n\r"
+    #    response = response.join('')
+    #  rescue => ex
+    #  ensure
+    #    system("stty -raw echo") # Reset terminal mode
+    #  end
+    #else
+      response = (STDIN.gets || "")
+    #end
+    response.chomp.gsub(/["']/, '')
+  end
+  # Returns a verb appropriate to the flavor.
+  # * :numeric => resolve
+  # * :string => type
+  def Annoy.verb(flavor)
+    case flavor
+    when :numeric then "resolve"
+    when :string then "type"
+    else
+      nil
+    end
+  end
+ 
+  # 
+  # Generates a string of random alphanumeric characters.
+  # * +len+ is the length, an Integer. Default: 8
+  # * +safe+ in safe-mode, ambiguous characters are removed (default: true):
+  #       i l o 1 0
+  def Annoy.strand( len=8, safe=true )
+     chars = ("a".."z").to_a + ("0".."9").to_a
+     chars.delete_if { |v| %w(i l o 1 0).member?(v) } if safe
+     str = ""
+     1.upto(len) { |i| str << chars[rand(chars.size-1)] }
+     str
+  end
+  
+  # * +f+ a prospective flavor name
+  def Annoy.get_flavor(f)
+    f.to_sym == :rand ? flavor_rand : f.to_sym
+  end
+  
+  # Return a random flavor
+  def Annoy.flavor_rand
+    @@flavors[rand(@@flavors.size)]
+  end
+
+  
+end
+
+# = Annoy::GiveUp
+#
+# This is what happens when you don't answer Annoy's questions. 
+class Annoy::GiveUp < RuntimeError
+end
+
+

data/lib/console.rb

@@ -4,8 +4,15 @@
 # See: man terminfo
 #+++
 
-
+#
+#
+#
 class String
+  @@print_with_attributes = true
+  def String.disable_colour; @@print_with_attributes = false; end
+  def String.disable_color;  @@print_with_attributes = false; end
+  def String.enable_colour;  @@print_with_attributes = true;  end
+  def String.enable_color;   @@print_with_attributes = true;  end
   
   # +col+, +bgcol+, and +attribute+ are symbols corresponding
   # to Console::COLOURS, Console::BGCOLOURS, and Console::ATTRIBUTES.
@@ -14,6 +21,7 @@ class String
   #     "MONKEY_JUNK".colour(:blue, :white, :blink)  # => "\e[34;47;5mMONKEY_JUNK\e[39;49;0m"
   #
   def colour(col, bgcol = nil, attribute = nil)
+    return self unless @@print_with_attributes
     Console.style(col, bgcol, attribute) +
     self +
     Console.style(:default, :default, :default)
@@ -22,6 +30,7 @@ class String
   
   # See colour
   def bgcolour(bgcol = :default)
+    return self unless @@print_with_attributes
     Console.style(nil, bgcol, nil) +
     self +
     Console.style(nil, :default, nil)
@@ -30,11 +39,16 @@ class String
   
   # See colour
   def att(a = :default)
+    return self unless @@print_with_attributes
     Console.style(nil, nil, a) +
     self +
     Console.style(nil, nil, :default)
   end
   
+  # Shortcut for att(:bright)
+  def bright
+    att(:bright)
+  end
   
   # Print the string at +x+ +y+. When +minus+ is any true value
   # the length of the string is subtracted from the value of x
@@ -46,7 +60,8 @@ class String
     Console.print_at(self, args)
   end
   
-  # Returns the string with escape code attributes removed.
+  # Returns the string with ANSI escape codes removed.
+  #
   # NOTE: The non-printable attributes count towards the string size. 
   # You can use this method to get the "visible" size:
   #
@@ -54,11 +69,13 @@ class String
   #     "\e[34;47;5mMONKEY_JUNK\e[39;49;0m".size            # => 31
   #
   def noatt
-    gsub(/\e\[[\d;]*m/, '')
+    gsub(/\e\[?[0-9;]*[mc]?/, '')
   end
+  alias :noansi :noatt
+  
 end
 
-class Object
+class Object #:nodoc:all
 
   # Executes tput +capnam+ with +args+. Returns true if tcap gives
   # 0 exit status and false otherwise. 
@@ -82,7 +99,7 @@ end
 
 
 
-module Console
+module Console #:nodoc:all
   extend self
   require 'timeout'
   require 'thread'
@@ -127,6 +144,10 @@ module Console
     :random  => 40 + rand(10).to_i
   }.freeze unless defined? BGCOLOURS
   
+  def valid_colour?(colour)
+    COLOURS.has_key? colour
+  end
+  alias :valid_color? :valid_colour? 
   
   def print_left(str, props={})
     props[:x] ||= 0
@@ -159,8 +180,8 @@ module Console
   end
   def print_at(str, props={})
     print_at_lamb = lambda {
-      #props[:x] ||= 0
-      #props[:y] ||= 0
+      props[:x] ||= 0
+      props[:y] ||= 0
       props[:minus] = false unless props.has_key?(:minus)
       props[:x] = props[:x]-str.noatt.size if props[:x] && props[:minus] # Subtract the str length from the position
       Cursor.save
@@ -196,7 +217,7 @@ module Console
   end
 end
 
-module Cursor
+module Cursor #:nodoc:all
   extend self
   
   # Returns [x,y] for the current cursor position.
@@ -291,7 +312,7 @@ module Cursor
   
 end
 
-class Window
+class Window #:nodoc:all
   attr_accessor :row, :col, :width, :height, :text, :fg, :bg
   attr_reader :threads
   

data/lib/escape.rb

@@ -0,0 +1,305 @@
+# escape.rb - escape/unescape library for several formats
+#
+# Copyright (C) 2006,2007 Tanaka Akira  <akr@fsij.org>
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+#  1. Redistributions of source code must retain the above copyright notice, this
+#     list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#  3. The name of the author may not be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
+# WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+# EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+# OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+# IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+# OF SUCH DAMAGE.
+
+# Escape module provides several escape functions.
+# * URI
+# * HTML
+# * shell command
+module Escape #:nodoc:all
+  module_function
+
+  class StringWrapper
+    class << self
+      alias new_no_dup new
+      def new(str)
+        new_no_dup(str.dup)
+      end
+    end
+
+    def initialize(str)
+      @str = str
+    end
+
+    def to_s
+      @str.dup
+    end
+
+    def inspect
+      "\#<#{self.class}: #{@str}>"
+    end
+
+    def ==(other)
+      other.class == self.class && @str == other.instance_variable_get(:@str)
+    end
+    alias eql? ==
+
+    def hash
+      @str.hash
+    end
+  end
+
+  class ShellEscaped < StringWrapper
+  end
+
+  # Escape.shell_command composes
+  # a sequence of words to
+  # a single shell command line.
+  # All shell meta characters are quoted and
+  # the words are concatenated with interleaving space.
+  # It returns an instance of ShellEscaped.
+  #
+  #  Escape.shell_command(["ls", "/"]) #=> #<Escape::ShellEscaped: ls />
+  #  Escape.shell_command(["echo", "*"]) #=> #<Escape::ShellEscaped: echo '*'>
+  #
+  # Note that system(*command) and
+  # system(Escape.shell_command(command)) is roughly same.
+  # There are two exception as follows.
+  # * The first is that the later may invokes /bin/sh.
+  # * The second is an interpretation of an array with only one element: 
+  #   the element is parsed by the shell with the former but
+  #   it is recognized as single word with the later.
+  #   For example, system(*["echo foo"]) invokes echo command with an argument "foo".
+  #   But system(Escape.shell_command(["echo foo"])) invokes "echo foo" command without arguments (and it probably fails).
+  def shell_command(*command)
+    command = [command].flatten.compact # Delano
+    s = command.map {|word| shell_single_word(word) }.join(' ')
+    ShellEscaped.new_no_dup(s)
+  end
+
+  # Escape.shell_single_word quotes shell meta characters.
+  # It returns an instance of ShellEscaped.
+  #
+  # The result string is always single shell word, even if
+  # the argument is "".
+  # Escape.shell_single_word("") returns #<Escape::ShellEscaped: ''>.
+  #
+  #  Escape.shell_single_word("") #=> #<Escape::ShellEscaped: ''>
+  #  Escape.shell_single_word("foo") #=> #<Escape::ShellEscaped: foo>
+  #  Escape.shell_single_word("*") #=> #<Escape::ShellEscaped: '*'>
+  def shell_single_word(str)
+    return unless str
+    str &&= str.to_s # Delano fix
+    if str.empty?
+      ShellEscaped.new_no_dup("''")
+    elsif %r{\A[0-9A-Za-z+,./:=@_-]+\z} =~ str
+      ShellEscaped.new(str)
+    else
+      result = ''
+      str.scan(/('+)|[^']+/) {
+        if $1
+          result << %q{\'} * $1.length
+        else
+          result << "'#{$&}'"
+        end
+      }
+      ShellEscaped.new_no_dup(result)
+    end
+  end
+
+  class PercentEncoded < StringWrapper
+  end
+
+  # Escape.uri_segment escapes URI segment using percent-encoding.
+  # It returns an instance of PercentEncoded.
+  #
+  #  Escape.uri_segment("a/b") #=> #<Escape::PercentEncoded: a%2Fb>
+  #
+  # The segment is "/"-splitted element after authority before query in URI, as follows.
+  #
+  #   scheme://authority/segment1/segment2/.../segmentN?query#fragment
+  #
+  # See RFC 3986 for details of URI.
+  def uri_segment(str)
+    # pchar - pct-encoded = unreserved / sub-delims / ":" / "@"
+    # unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+    # sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+    s = str.gsub(%r{[^A-Za-z0-9\-._~!$&'()*+,;=:@]}n) {
+      '%' + $&.unpack("H2")[0].upcase
+    }
+    PercentEncoded.new_no_dup(s)
+  end
+
+  # Escape.uri_path escapes URI path using percent-encoding.
+  # The given path should be a sequence of (non-escaped) segments separated by "/".
+  # The segments cannot contains "/".
+  # It returns an instance of PercentEncoded.
+  #
+  #  Escape.uri_path("a/b/c") #=> #<Escape::PercentEncoded: a/b/c>
+  #  Escape.uri_path("a?b/c?d/e?f") #=> #<Escape::PercentEncoded: a%3Fb/c%3Fd/e%3Ff>
+  #
+  # The path is the part after authority before query in URI, as follows.
+  #
+  #   scheme://authority/path#fragment
+  #
+  # See RFC 3986 for details of URI.
+  #
+  # Note that this function is not appropriate to convert OS path to URI.
+  def uri_path(str)
+    s = str.gsub(%r{[^/]+}n) { uri_segment($&) }
+    PercentEncoded.new_no_dup(s)
+  end
+
+  
+  def html_form_fast(pairs, sep='&')
+    s = pairs.map {|k, v|
+      # query-chars - pct-encoded - x-www-form-urlencoded-delimiters =
+      #   unreserved / "!" / "$" / "'" / "(" / ")" / "*" / "," / ":" / "@" / "/" / "?"
+      # query-char - pct-encoded = unreserved / sub-delims / ":" / "@" / "/" / "?"
+      # query-char = pchar / "/" / "?" = unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?"
+      # unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+      # sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+      # x-www-form-urlencoded-delimiters = "&" / "+" / ";" / "="
+      k = k.gsub(%r{[^0-9A-Za-z\-\._~:/?@!\$'()*,]}n) {
+        '%' + $&.unpack("H2")[0].upcase
+      }
+      v = v.gsub(%r{[^0-9A-Za-z\-\._~:/?@!\$'()*,]}n) {
+        '%' + $&.unpack("H2")[0].upcase
+      }
+      "#{k}=#{v}"
+    }.join(sep)
+    PercentEncoded.new_no_dup(s)
+  end
+  
+
+  # Escape.html_form composes HTML form key-value pairs as a x-www-form-urlencoded encoded string.
+  # It returns an instance of PercentEncoded.
+  #
+  # Escape.html_form takes an array of pair of strings or
+  # an hash from string to string.
+  #
+  #  Escape.html_form([["a","b"], ["c","d"]]) #=> #<Escape::PercentEncoded: a=b&c=d>
+  #  Escape.html_form({"a"=>"b", "c"=>"d"}) #=> #<Escape::PercentEncoded: a=b&c=d>
+  #
+  # In the array form, it is possible to use same key more than once.
+  # (It is required for a HTML form which contains
+  # checkboxes and select element with multiple attribute.)
+  #
+  #  Escape.html_form([["k","1"], ["k","2"]]) #=> #<Escape::PercentEncoded: k=1&k=2>
+  #
+  # If the strings contains characters which must be escaped in x-www-form-urlencoded,
+  # they are escaped using %-encoding.
+  #
+  #  Escape.html_form([["k=","&;="]]) #=> #<Escape::PercentEncoded: k%3D=%26%3B%3D>
+  #
+  # The separator can be specified by the optional second argument.
+  #
+  #  Escape.html_form([["a","b"], ["c","d"]], ";") #=> #<Escape::PercentEncoded: a=b;c=d>
+  #
+  # See HTML 4.01 for details.
+  def html_form(pairs, sep='&')
+    r = ''
+    first = true
+    pairs.each {|k, v|
+      # query-chars - pct-encoded - x-www-form-urlencoded-delimiters =
+      #   unreserved / "!" / "$" / "'" / "(" / ")" / "*" / "," / ":" / "@" / "/" / "?"
+      # query-char - pct-encoded = unreserved / sub-delims / ":" / "@" / "/" / "?"
+      # query-char = pchar / "/" / "?" = unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?"
+      # unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+      # sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+      # x-www-form-urlencoded-delimiters = "&" / "+" / ";" / "="
+      r << sep if !first
+      first = false
+      k.each_byte {|byte|
+        ch = byte.chr
+        if %r{[^0-9A-Za-z\-\._~:/?@!\$'()*,]}n =~ ch
+          r << "%" << ch.unpack("H2")[0].upcase
+        else
+          r << ch
+        end
+      }
+      r << '='
+      v.each_byte {|byte|
+        ch = byte.chr
+        if %r{[^0-9A-Za-z\-\._~:/?@!\$'()*,]}n =~ ch
+          r << "%" << ch.unpack("H2")[0].upcase
+        else
+          r << ch
+        end
+      }
+    }
+    PercentEncoded.new_no_dup(r)
+  end
+
+  class HTMLEscaped < StringWrapper
+  end
+
+  
+  HTML_TEXT_ESCAPE_HASH = {
+    '&' => '&amp;',
+    '<' => '&lt;',
+    '>' => '&gt;',
+  }
+  
+
+  # Escape.html_text escapes a string appropriate for HTML text using character references.
+  # It returns an instance of HTMLEscaped.
+  #
+  # It escapes 3 characters:
+  # * '&' to '&amp;'
+  # * '<' to '&lt;'
+  # * '>' to '&gt;'
+  #
+  #  Escape.html_text("abc") #=> #<Escape::HTMLEscaped: abc>
+  #  Escape.html_text("a & b < c > d") #=> #<Escape::HTMLEscaped: a &amp; b &lt; c &gt; d>
+  #
+  # This function is not appropriate for escaping HTML element attribute
+  # because quotes are not escaped.
+  def html_text(str)
+    s = str.gsub(/[&<>]/) {|ch| HTML_TEXT_ESCAPE_HASH[ch] }
+    HTMLEscaped.new_no_dup(s)
+  end
+
+  
+  HTML_ATTR_ESCAPE_HASH = {
+    '&' => '&amp;',
+    '<' => '&lt;',
+    '>' => '&gt;',
+    '"' => '&quot;',
+  }
+  
+
+  class HTMLAttrValue < StringWrapper
+  end
+
+  # Escape.html_attr_value encodes a string as a double-quoted HTML attribute using character references.
+  # It returns an instance of HTMLAttrValue.
+  #
+  #  Escape.html_attr_value("abc") #=> #<Escape::HTMLAttrValue: "abc">
+  #  Escape.html_attr_value("a&b") #=> #<Escape::HTMLAttrValue: "a&amp;b">
+  #  Escape.html_attr_value("ab&<>\"c") #=> #<Escape::HTMLAttrValue: "ab&amp;&lt;&gt;&quot;c">
+  #  Escape.html_attr_value("a'c") #=> #<Escape::HTMLAttrValue: "a'c">
+  #
+  # It escapes 4 characters:
+  # * '&' to '&amp;'
+  # * '<' to '&lt;'
+  # * '>' to '&gt;'
+  # * '"' to '&quot;'
+  #
+  def html_attr_value(str)
+    s = '"' + str.gsub(/[&<>"]/) {|ch| HTML_ATTR_ESCAPE_HASH[ch] } + '"'
+    HTMLAttrValue.new_no_dup(s)
+  end
+end