text-format 1.0.0

data/Changelog

@@ -0,0 +1,89 @@
+== Text::Format 1.0.0
+* Changed installer: added a .gem package.
+* Changed installer: moving to a variant of setup.rb by Minero Aoki.
+* Fixed significant problems with #hard_margin wrapping and fallback issues,
+  eliminating all known possibilities for an infinite loop in wrapping. Some
+  of the formatting changes involved with this result in different and more
+  subtle wrapping and splitting of words; please read the full documentation
+  for details.
+* Clarified the API for #hyphenate_to (delineated the return value required if
+  the hyphenator cannot hyphenate the word to the specified size).
+* Changed a number of public and private API calls to work better. As long as
+  the constants provided by Text::Format have been used (and not direct access
+  to the constant values), there will be no issues presented by most of these
+  changes.
+* Changed the initialization of the Text::Format object. The documentation has
+  also been updated to be correct. Note that this will mean that some uses of
+  Text::Format will not work, as Text::Format.new now yields +self+ if a block
+  is given instead of evaluating the block with Object#instance_eval.
+* Added text numbering generators (Text::Format::Alpha, Text::Format::Number,
+  and Text::Format::Roman) to work with #tag_paragraphs and #tag_text to
+  generate numbered paragraphs.
+* #nobreak_regex must be a hash of regular expressions, not strings that are
+  converted to regular expressions. This Perlism has finally been removed.
+* The performance has been improved; the number of times that lines are joined
+  together and then split apart has been reduced.
+* Changed the dependency to Text::Hyphen from TeX::Hyphen.
+* Added auto-split capabilities to #paragraphs. See the updated documentation.
+
+== Text::Format 0.64
+* Fixed a bug where a NoMethod exception would be raised if #paragraphs was
+  called with either (" ") or ([" "]).
+
+== Text::Format 0.63
+* Fixed a bug where a crash would occur when a hyphenator returned nil instead
+  of "".
+
+== Text::Format 0.62
+* Modified the API for hyphenators. Previously, a hyphenator could only be
+  defined as an object containing a method #hyphenate_to with the signature:
+      #hyphenate_to(word, size)
+  Now, the #hyphenate_to method may be the above signature or:
+      #hyphenate_to(word, size, formatter)
+  So that the hyphenator may access information about the formatting object,
+  if necessary. Thanks to Tim Bates for suggesting a case where this would be
+  useful.
+* Fixed a bug for strings matching /\A\s*\Z/ raising a NameError.
+* Fixed a test case that failed uner 1.6.8. The following no longer works:
+      l, m1, m2 = /((?:\S+\s+){11})(.+)/.match(line)
+  This has been replaced with an explicit use of l[1] and l[2]. Thanks to Tim
+  Bates for finding this problem.
+* Changed installer to Phil Thomson's install-package wrapper.
+
+== Text::Format 0.61
+* Fixed a problem with the installer. Note that Text::Format is no longer case
+  sensitive for require purposes. It will be required as:
+      require 'text/format'
+  Versions earlier than 0.60 were case-sensitive. Please be aware of this if
+  you are installing Text::Format over an older version. It may not replace
+  the existing library in the way that you expect.
+
+== Text::Format 0.60
+* Added Symbol equivalents for the Hash initialization. Hash initialization
+  has been modified so that values are set as follows (Symbols are highest
+  priority; strings are middle; defaults are lowest):
+    @columns = arg[:columns] || arg['columns'] || @columns
+* Fixed a problem with Text::Format::RIGHT_FILL handling where a single word
+  is larger than #columns.
+* Removed Comparable mixin (<=> doesn't make sense; == does).
+* Added #hard_margins, #split_rules, #hyphenator, and #split_words. Text
+  formatted with #hard_margins will have words larger than #columns split
+  forcibly. Words forcibly split will be placed into #split_words. See the
+  documentation for important information on how this feature works.
+
+== Text::Format 0.52.2
+* Fixed the ordering of #<=> in cases of Boolean values.
+* Fixed #expand and #unexpand Array handling.
+* Added a Changelog.
+
+== Text::Format 0.52.1
+* Fixed a problem when tabs aren't counted properly.
+* Changed #abbreviations from Hash to Array to better suit Ruby's
+  capabilities.
+* Fixed problems with the way that Array arguments are handled in calls to the
+  major object types.
+
+== Text::Format 0.52
+* Initial release
+
+$Id: Changelog,v 1.6 2005/06/24 19:49:09 austin Exp $

data/Install

@@ -0,0 +1,6 @@
+Installing this package is as simple as:
+
+% ruby setup.rb
+
+Alternatively, you can use the RubyGem version of Text::Format available as
+text-format-1.0.0.gem from the usual sources.

data/README

@@ -0,0 +1,13 @@
+Text::Format 1.0.0
+==================
+Text::Format is provides the ability to nicely format fixed-width text with
+knowledge of the writeable space (number of columns), margins, and indentation
+settings. Text::Format can work with either TeX::Hyphen or Text::Hyphen to
+hyphenate words when formatting.
+
+This is release 1.0, containing both feature enhancements and bug fixes over
+the previous version, 0.64.
+
+Text::Format is originally based on the Perl library of the same name by G�bor
+Egressy. It is copyright 2002 - 2005 by Austin Ziegler and is licenced under
+Ruby's licence. It is also available under the Perl Artistic licence.

data/Rakefile

@@ -0,0 +1,113 @@
+#! /usr/bin/env rake
+$LOAD_PATH.unshift('lib')
+
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'text/format'
+require 'archive/tar/minitar'
+require 'zlib'
+
+DISTDIR = "text-format-#{Text::Format::VERSION}"
+TARDIST = "../#{DISTDIR}.tar.gz"
+
+DATE_RE = %r<(\d{4})[./-]?(\d{2})[./-]?(\d{2})(?:[\sT]?(\d{2})[:.]?(\d{2})[:.]?(\d{2})?)?>
+
+if ENV['RELEASE_DATE']
+  year, month, day, hour, minute, second = DATE_RE.match(ENV['RELEASE_DATE']).captures
+  year ||= 0
+  month ||= 0
+  day ||= 0
+  hour ||= 0
+  minute ||= 0
+  second ||= 0
+  ReleaseDate = Time.mktime(year, month, day, hour, minute, second)
+else
+  ReleaseDate = nil
+end
+
+task :test do |t|
+  require 'test/unit/testsuite'
+  require 'test/unit/ui/console/testrunner'
+
+  runner = Test::Unit::UI::Console::TestRunner
+
+  $LOAD_PATH.unshift('tests')
+  $stderr.puts "Checking for test cases:" if t.verbose
+  Dir['tests/tc_*.rb'].each do |testcase|
+    $stderr.puts "\t#{testcase}" if t.verbose
+    load testcase
+  end
+
+  suite = Test::Unit::TestSuite.new("Text::Format")
+
+  ObjectSpace.each_object(Class) do |testcase|
+    suite << testcase.suite if testcase < Test::Unit::TestCase
+  end
+
+  runner.run(suite)
+end
+
+spec = eval(File.read("text-format.gemspec"))
+spec.version = Text::Format::VERSION
+desc "Build the RubyGem for Text::Format"
+task :gem => [ :test ]
+Rake::GemPackageTask.new(spec) do |g|
+  g.need_tar    = false
+  g.need_zip    = false
+  g.package_dir = ".."
+end
+
+desc "Build a Text::Format .tar.gz distribution."
+task :tar => [ TARDIST ]
+file TARDIST => [ :test ] do |t|
+  current = File.basename(Dir.pwd)
+  Dir.chdir("..") do
+    begin
+      files = Dir["#{current}/**/*"].select { |dd| dd !~ %r{(?:/CVS/?|~$)} }
+      files.map! do |dd|
+        ddnew = dd.gsub(/^#{current}/, DISTDIR)
+        mtime = ReleaseDate || File.stat(dd).mtime
+        if File.directory?(dd)
+          { :name => ddnew, :mode => 0755, :dir => true, :mtime => mtime }
+        else
+          if dd =~ %r{bin/}
+            mode = 0755
+          else
+            mode = 0644
+          end
+          data = File.read(dd)
+          { :name => ddnew, :mode => mode, :data => data, :size => data.size,
+            :mtime => mtime }
+        end
+      end
+
+      ff = File.open(t.name.gsub(%r{^\.\./}o, ''), "wb")
+      gz = Zlib::GzipWriter.new(ff)
+      tw = Archive::Tar::Minitar::Writer.new(gz)
+
+      files.each do |entry|
+        if entry[:dir]
+          tw.mkdir(entry[:name], entry)
+        else
+          tw.add_file_simple(entry[:name], entry) { |os| os.write(entry[:data]) }
+        end
+      end
+    ensure
+      tw.close if tw
+      gz.close if gz
+    end
+  end
+end
+task TARDIST => [ :test ]
+
+desc "Build the RDoc documentation for Text::Format"
+task :docs do
+  require 'rdoc/rdoc'
+  rdoc_options = %w(--title Text::Format --main README --line-numbers)
+  files = FileList[*%w(README ChangeLog Install bin/**/*.rb lib/**/*.rb)]
+  rdoc_options += files.to_a
+  RDoc::RDoc.new.document(rdoc_options)
+end
+
+desc "Build everything."
+task :default => [ :tar, :gem ]

data/ToDo

@@ -0,0 +1,8 @@
+Text::Format To Do
+==================
+* Margin markers: the ability to place markers in the margin when
+  formatting.
+* Line numbering: the ability to number lines in the margin when
+  formatting, including numering lines by step (every fifth line, etc.).
+* Email attribution quoting reformatting.
+* Proportional width support for GUI formatting.

data/lib/text/format.rb

@@ -0,0 +1,1043 @@
+# :title: Text::Format
+# :main: Text::Format
+#--
+# Text::Format for Ruby
+# Version 1.0.0
+#
+# Copyright (c) 2002 - 2005 Austin Ziegler
+#
+# $Id: format.rb,v 1.5 2005/04/20 01:43:55 austin Exp $
+#++
+unless defined?(Text)
+  module Text; end
+end
+
+  # = Introduction
+  #
+  # Text::Format provides the ability to nicely format fixed-width text with
+  # knowledge of the writeable space (number of columns), margins, and
+  # indentation settings.
+  #
+  # Copyright::   Copyright (c) 2002 - 2005 by Austin Ziegler
+  # Version::     1.0.0
+  # Based On::    Perl
+  #               Text::Format[http://search.cpan.org/author/GABOR/Text-Format0.52/lib/Text/Format.pm],
+  #               Copyright (c) 1998 G�bor Egressy
+  # Licence::     Ruby's, Perl Artistic, or GPL version 2 (or later)
+  #
+class Text::Format
+  VERSION = '1.0.0'
+
+  SPACES_RE   = %r{\s+}mo.freeze
+  NEWLINE_RE  = %r{\n}o.freeze
+  TAB         = "\t".freeze
+  NEWLINE     = "\n".freeze
+
+    # Global common English abbreviations. More can be added with
+    # #abbreviations.
+  ABBREV = %w(Mr Mrs Ms Jr Sr Dr)
+
+    # Formats text flush to the left margin with a visual and physical
+    # ragged right margin.
+    #
+    #      >A paragraph that is<
+    #      >left aligned.<
+  LEFT_ALIGN  = :left
+    # Formats text flush to the right margin with a visual ragged left
+    # margin. The actual left margin is padded with spaces from the
+    # beginning of the line to the start of the text such that the right
+    # margin will be flush.
+    #
+    #      >A paragraph that is<
+    #      >     right aligned.<
+  RIGHT_ALIGN = :right
+    # Formats text flush to the left margin with a visual ragged right
+    # margin. The line is padded with spaces from the end of the text to the
+    # right margin.
+    #
+    #      >A paragraph that is<
+    #      >right filled.      <
+  RIGHT_FILL  = :fill
+    # Formats the text flush to both the left and right margins. The last
+    # line will not be justified if it consists of a single word (it will be
+    # treated as +RIGHT_FILL+ in this case). Spacing between words is
+    # increased to ensure that the textg is flush with both margins.
+    #
+    #      |A paragraph  that|
+    #      |is     justified.|
+    #
+    #      |A paragraph  that is|
+    #      |justified.          |
+  JUSTIFY     = :justify
+
+    # When #hard_margins is enabled, a word that extends over the right
+    # margin will be split at the number of characters needed. This is
+    # similar to how characters wrap on a terminal. This is the default
+    # split mechanism when #hard_margins is enabled.
+    #
+    #      repre
+    #      senta
+    #      ion
+  SPLIT_FIXED                     = 1
+    # When #hard_margins is enabled, a word that extends over the right
+    # margin will be split at one less than the number of characters needed
+    # with a C-style continuation character (\). If the word cannot be split
+    # using the rules of SPLIT_CONTINUATION, and the word will not fit
+    # wholly into the next line, then SPLIT_FIXED will be used.
+    #
+    #       repr\
+    #       esen\
+    #       tati\
+    #       on
+  SPLIT_CONTINUATION              = 2
+    # When #hard_margins is enabled, a word that extends over the right
+    # margin will be split according to the hyphenator specified by the
+    # #hyphenator object; if there is no hyphenation library supplied, then
+    # the hyphenator of Text::Format itself is used, which is the same as
+    # SPLIT_CONTINUATION. See #hyphenator for more information about
+    # hyphenation libraries. The example below is valid with either
+    # TeX::Hyphen or Text::Hyphen. If the word cannot be split using the
+    # hyphenator's rules, and the word will not fit wholly into the next
+    # line, then SPLIT_FIXED will be used.
+    #
+    #       rep-
+    #       re-
+    #       sen-
+    #       ta-
+    #       tion
+    #
+  SPLIT_HYPHENATION               = 4
+    # When #hard_margins is enabled, a word that extends over the right
+    # margin will be split at one less than the number of characters needed
+    # with a C-style continuation character (\). If the word cannot be split
+    # using the rules of SPLIT_CONTINUATION, then SPLIT_FIXED will be used.
+  SPLIT_CONTINUATION_FIXED        = SPLIT_CONTINUATION | SPLIT_FIXED
+    # When #hard_margins is enabled, a word that extends over the right
+    # margin will be split according to the hyphenator specified by the
+    # #hyphenator object; if there is no hyphenation library supplied, then
+    # the hyphenator of Text::Format itself is used, which is the same as
+    # SPLIT_CONTINUATION. See #hyphenator for more information about
+    # hyphenation libraries. The example below is valid with either
+    # TeX::Hyphen or Text::Hyphen. If the word cannot be split using the
+    # hyphenator's rules, then SPLIT_FIXED will be used.
+  SPLIT_HYPHENATION_FIXED         = SPLIT_HYPHENATION | SPLIT_FIXED
+    # Attempts to split words according to the rules of the supplied
+    # hyphenator (e.g., SPLIT_HYPHENATION); if the word cannot be split
+    # using these rules, then the rules of SPLIT_CONTINUATION will be
+    # followed. In all cases, if the word cannot be split using either
+    # SPLIT_HYPHENATION or SPLIT_CONTINUATION, and the word will not fit
+    # wholly into the next line, then SPLIT_FIXED will be used.
+  SPLIT_HYPHENATION_CONTINUATION  = SPLIT_HYPHENATION | SPLIT_CONTINUATION
+    # Attempts to split words according to the rules of the supplied
+    # hyphenator (e.g., SPLIT_HYPHENATION); if the word cannot be split
+    # using these rules, then the rules of SPLIT_CONTINUATION will be
+    # followed. In all cases, if the word cannot be split using either
+    # SPLIT_HYPHENATION or SPLIT_CONTINUATION, then SPLIT_FIXED will be
+    # used.
+  SPLIT_ALL                       = SPLIT_HYPHENATION | SPLIT_CONTINUATION | SPLIT_FIXED
+
+    # Words forcibly split by Text::Format will be stored as split words.
+    # This class represents a word forcibly split.
+  class SplitWord
+      # The word that was split.
+    attr_reader :word
+      # The first part of the word that was split.
+    attr_reader :first
+      # The remainder of the word that was split.
+    attr_reader :rest
+
+    def initialize(word, first, rest)
+      @word   = word
+      @first  = first
+      @rest   = rest
+    end
+  end
+
+    # Indicates punctuation characters that terminates a sentence, as some
+    # English typesetting rules indicate that sentences should be followed
+    # by two spaces. This is an archaic rule, but is supported with
+    # #extra_space. This is the default set of terminal punctuation
+    # characters. Additional terminal punctuation may be added to the
+    # formatting object through #terminal_punctuation.
+  TERMINAL_PUNCTUATION  = %q(.?!)
+    # Indicates quote characters that may follow terminal punctuation under
+    # the current formatting rules. This satisfies the English formatting
+    # rule that indicates that sentences terminated inside of quotes should
+    # have the punctuation inside of the quoted text, not outside of the
+    # terminal quote. Additional terminal quotes may be added to the
+    # formatting object through #terminal_quotes. See TERMINAL_PUNCTUATION
+    # for more information.
+  TERMINAL_QUOTES       = %q('")
+
+    # This method returns the regular expression used to detect the end of a
+    # sentence under the current definition of TERMINAL_PUNCTUATION,
+    # #terminal_punctuation, TERMINAL_QUOTES, and #terminal_quotes.
+  def __sentence_end_re
+    %r{[#{TERMINAL_PUNCTUATION}#{self.terminal_punctuation}][#{TERMINAL_QUOTES}#{self.terminal_quotes}]?$}
+  end
+  private :__sentence_end_re
+
+    # Returns a regular expression for a set of characters (at least one
+    # non-whitespace followed by at least one space) of the specified size
+    # followed by one or more of any character.
+  RE_BREAK_SIZE = lambda { |size| %r[((?:\S+\s+){#{size}})(.+)] }
+
+    # Compares the formatting rules, excepting #hyphenator, of two
+    # Text::Format objects. Generated results (e.g., #split_words) are not
+    # compared.
+  def ==(o)
+    (@text                  == o.text)                  and
+    (@columns               == o.columns)               and
+    (@left_margin           == o.left_margin)           and
+    (@right_margin          == o.right_margin)          and
+    (@hard_margins          == o.hard_margins)          and
+    (@split_rules           == o.split_rules)           and
+    (@first_indent          == o.first_indent)          and
+    (@body_indent           == o.body_indent)           and
+    (@tag_text              == o.tag_text)              and
+    (@tabstop               == o.tabstop)               and
+    (@format_style          == o.format_style)          and
+    (@extra_space           == o.extra_space)           and
+    (@tag_paragraph         == o.tag_paragraph)         and
+    (@nobreak               == o.nobreak)               and
+    (@terminal_punctuation  == o.terminal_punctuation)  and
+    (@terminal_quotes       == o.terminal_quotes)       and
+    (@abbreviations         == o.abbreviations)         and
+    (@nobreak_regex         == o.nobreak_regex)
+  end
+
+    # The default text to be manipulated. Note that value is optional, but
+    # if the formatting functions are called without values, this text is
+    # what will be formatted.
+    #
+    # *Default*::       <tt>[]</tt>
+    # <b>Used in</b>::  All methods
+  attr_accessor :text
+
+    # The total width of the format area. The margins, indentation, and text
+    # are formatted into this space. Any value provided is silently
+    # converted to a positive integer.
+    #
+    #                             COLUMNS
+    #  <-------------------------------------------------------------->
+    #  <-----------><------><---------------------------><------------>
+    #   left margin  indent  text is formatted into here  right margin
+    #
+    # *Default*::       <tt>72</tt>
+    # <b>Used in</b>::  #format, #paragraphs, #center
+  attr_accessor :columns
+  def columns=(col) #:nodoc:
+    @columns = col.to_i.abs
+  end
+
+    # The number of spaces used for the left margin. The value provided is
+    # silently converted to a positive integer value.
+    #
+    #                             columns
+    #  <-------------------------------------------------------------->
+    #  <-----------><------><---------------------------><------------>
+    #   LEFT MARGIN  indent  text is formatted into here  right margin
+    #
+    # *Default*::       <tt>0</tt>
+    # <b>Used in</b>::  #format, #paragraphs, #center
+  attr_accessor :left_margin
+  def left_margin=(left) #:nodoc:
+    @left_margin = left.to_i.abs
+  end
+
+    # The number of spaces used for the right margin. The value provided is
+    # silently converted to a positive integer value.
+    #
+    #                             columns
+    #  <-------------------------------------------------------------->
+    #  <-----------><------><---------------------------><------------>
+    #   left margin  indent  text is formatted into here  RIGHT MARGIN
+    #
+    # *Default*::       <tt>0</tt>
+    # <b>Used in</b>::  #format, #paragraphs, #center
+  attr_accessor :right_margin
+  def right_margin=(right) #:nodoc:
+    @right_margin = right.to_i.abs
+  end
+
+    # The number of spaces to indent the first line of a paragraph. The
+    # value provided is silently converted to a positive integer value.
+    #
+    #                             columns
+    #  <-------------------------------------------------------------->
+    #  <-----------><------><---------------------------><------------>
+    #   left margin  INDENT  text is formatted into here  right margin
+    #
+    # *Default*::       <tt>4</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :first_indent
+  def first_indent=(first) #:nodoc:
+    @first_indent = first.to_i.abs
+  end
+
+    # The number of spaces to indent all lines after the first line of a
+    # paragraph. The value provided is silently converted to a positive
+    # integer value.
+    #
+    #                             columns
+    #  <-------------------------------------------------------------->
+    #  <-----------><------><---------------------------><------------>
+    #   left margin  INDENT  text is formatted into here  right margin
+    #
+    # *Default*::       <tt>0</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :body_indent
+  def body_indent=(body) #:nodoc:
+    @body_indent = body.to_i.abs
+  end
+
+    # Normally, words larger than the format area will be placed on a line
+    # by themselves. Setting this value to +true+ will force words larger
+    # than the format area to be split into one or more "words" each at most
+    # the size of the format area. The first line and the original word will
+    # be placed into #split_words. Note that this will cause the output to
+    # look *similar* to a #format_style of JUSTIFY. (Lines will be filled as
+    # much as possible.)
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :hard_margins
+
+    # An array of words split during formatting if #hard_margins is set to
+    # +true+.
+    #   #split_words << Text::Format::SplitWord.new(word, first, rest)
+  attr_reader :split_words
+
+    # The object responsible for hyphenating. It must respond to
+    # #hyphenate_to(word, size) or #hyphenate_to(word, size, formatter) and
+    # return an array of the word split into two parts (e.g., <tt>[part1,
+    # part2]</tt>; if there is a hyphenation mark to be applied,
+    # responsibility belongs to the hyphenator object. The size is the
+    # MAXIMUM size permitted, including any hyphenation marks.
+    #
+    # If the #hyphenate_to method has an arity of 3, the current formatter
+    # (+self+) will be provided to the method. This allows the hyphenator to
+    # make decisions about the hyphenation based on the formatting rules.
+    #
+    # #hyphenate_to should return <tt>[nil, word]</tt> if the word cannot be
+    # hyphenated.
+    #
+    # *Default*::       +self+ (SPLIT_CONTINUATION)
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :hyphenator
+  def hyphenator=(h) #:nodoc:
+    h ||= self
+
+    raise ArgumentError, "#{h.inspect} is not a valid hyphenator." unless h.respond_to?(:hyphenate_to)
+    arity = h.method(:hyphenate_to).arity
+    raise ArgumentError, "#{h.inspect} must have exactly two or three arguments." unless arity.between?(2, 3)
+
+    @hyphenator       = h
+    @hyphenator_arity = arity
+  end
+
+    # Specifies the split mode; used only when #hard_margins is set to
+    # +true+. Allowable values are:
+    #
+    # * +SPLIT_FIXED+
+    # * +SPLIT_CONTINUATION+
+    # * +SPLIT_HYPHENATION+
+    # * +SPLIT_CONTINUATION_FIXED+
+    # * +SPLIT_HYPHENATION_FIXED+
+    # * +SPLIT_HYPHENATION_CONTINUATION+
+    # * +SPLIT_ALL+
+    #
+    # *Default*::       <tt>Text::Format::SPLIT_FIXED</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :split_rules
+  def split_rules=(s) #:nodoc:
+    raise ArgumentError, "Invalid value provided for #split_rules." if ((s < SPLIT_FIXED) or (s > SPLIT_ALL))
+    @split_rules = s
+  end
+
+    # Indicates whether sentence terminators should be followed by a single
+    # space (+false+), or two spaces (+true+). See #abbreviations for more
+    # information.
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :extra_space
+
+    # Defines the current abbreviations as an array. This is only used if
+    # extra_space is turned on.
+    #
+    # If one is abbreviating "President" as "Pres." (abbreviations =
+    # ["Pres"]), then the results of formatting will be as illustrated in
+    # the table below:
+    #
+    #                         abbreviations
+    #   extra_space | #include?("Pres") | not #include?("Pres")
+    #   ------------+-------------------+----------------------
+    #       true    | Pres. Lincoln     | Pres.  Lincoln
+    #       false   | Pres. Lincoln     | Pres. Lincoln
+    #   ------------+-------------------+----------------------
+    #   extra_space | #include?("Mrs")  | not #include?("Mrs")
+    #       true    | Mrs. Lincoln      | Mrs.  Lincoln
+    #       false   | Mrs. Lincoln      | Mrs. Lincoln
+    #
+    # Note that abbreviations should not have the terminal period as part of
+    # their definitions.
+    #
+    # This automatic abbreviation handling *will* cause some issues with
+    # uncommon sentence structures. The two sentences below will not be
+    # formatted correctly:
+    #
+    #   You're in trouble now, Mr.
+    #   Just wait until your father gets home.
+    #
+    # Under no circumstances (because Mr is a predefined abbreviation) will
+    # this ever be separated by two spaces.
+    #
+    # *Default*::       <tt>[]</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :abbreviations
+
+    # Specifies additional punctuation characters that terminate a sentence,
+    # as some English typesetting rules indicate that sentences should be
+    # followed by two spaces. This is an archaic rule, but is supported with
+    # #extra_space. This is added to the default set of terminal punctuation
+    # defined in TERMINAL_PUNCTUATION.
+    #
+    # *Default*::       <tt>""</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :terminal_punctuation
+    # Specifies additional quote characters that may follow
+    # terminal punctuation under the current formatting rules. This
+    # satisfies the English formatting rule that indicates that sentences
+    # terminated inside of quotes should have the punctuation inside of the
+    # quoted text, not outside of the terminal quote. This is added to the
+    # default set of terminal quotes defined in TERMINAL_QUOTES.
+    #
+    # *Default*::       <tt>""</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :terminal_quotes
+
+    # Indicates whether the formatting of paragraphs should be done with
+    # tagged paragraphs. Useful only with #tag_text.
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :tag_paragraph
+
+    # The text to be placed before each paragraph when #tag_paragraph is
+    # +true+. When #format is called, only the first element (#tag_text[0])
+    # is used. When #paragraphs is called, then each successive element
+    # (#tag_text[n]) will be used once, with corresponding paragraphs. If
+    # the tag elements are exhausted before the text is exhausted, then the
+    # remaining paragraphs will not be tagged. Regardless of indentation
+    # settings, a blank line will be inserted between all paragraphs when
+    # #tag_paragraph is +true+.
+    #
+    # The Text::Format package provides three number generators,
+    # Text::Format::Alpha, Text::Format::Number, and Text::Format::Roman to
+    # assist with the numbering of paragraphs.
+    #
+    # *Default*::       <tt>[]</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :tag_text
+
+    # Indicates whether or not the non-breaking space feature should be
+    # used.
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :nobreak
+
+    # A hash which holds the regular expressions on which spaces should not
+    # be broken. The hash is set up such that the key is the first word and
+    # the value is the second word.
+    #
+    # For example, if +nobreak_regex+ contains the following hash:
+    #
+    #   { %r{Mrs?\.?} => %r{\S+}, %r{\S+} => %r{(?:[SJ])r\.?} }
+    #
+    # Then "Mr. Jones", "Mrs Jones", and "Jones Jr." would not be broken. If
+    # this simple matching algorithm indicates that there should not be a
+    # break at the current end of line, then a backtrack is done until there
+    # are two words on which line breaking is permitted. If two such words
+    # are not found, then the end of the line will be broken *regardless*.
+    # If there is a single word on the current line, then no backtrack is
+    # done and the word is stuck on the end.
+    #
+    # *Default*::       <tt>{}</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :nobreak_regex
+
+    # Indicates the number of spaces that a single tab represents. Any value
+    # provided is silently converted to a positive integer.
+    #
+    # *Default*::       <tt>8</tt>
+    # <b>Used in</b>::  #expand, #unexpand,
+    #                   #paragraphs
+  attr_accessor :tabstop
+  def tabstop=(tabs) #:nodoc:
+    @tabstop = tabs.to_i.abs
+  end
+
+    # Specifies the format style. Allowable values are:
+    # *+LEFT_ALIGN+
+    # *+RIGHT_ALIGN+
+    # *+RIGHT_FILL+
+    # *+JUSTIFY+
+    #
+    # *Default*::       <tt>Text::Format::LEFT_ALIGN</tt>
+    # <b>Used in</b>::  #format, #paragraphs
+  attr_accessor :format_style
+  def format_style=(fs) #:nodoc:
+    raise ArgumentError, "Invalid value provided for format_style." unless [LEFT_ALIGN, RIGHT_ALIGN, RIGHT_FILL, JUSTIFY].include?(fs)
+    @format_style = fs
+  end
+
+    # Indicates that the format style is left alignment.
+    #
+    # *Default*::       +true+
+    # <b>Used in</b>::  #format, #paragraphs
+  def left_align?
+    @format_style == LEFT_ALIGN
+  end
+
+    # Indicates that the format style is right alignment.
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  def right_align?
+    @format_style == RIGHT_ALIGN
+  end
+
+    # Indicates that the format style is right fill.
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  def right_fill?
+    @format_style == RIGHT_FILL
+  end
+
+    # Indicates that the format style is full justification.
+    #
+    # *Default*::       +false+
+    # <b>Used in</b>::  #format, #paragraphs
+  def justify?
+    @format_style == JUSTIFY
+  end
+
+    # The formatting object itself can be used as a #hyphenator, where the
+    # default implementation of #hyphenate_to implements the conditions
+    # necessary to properly produce SPLIT_CONTINUATION.
+  def hyphenate_to(word, size)
+    if (size - 2) < 0
+      [nil, word]
+    else
+      [word[0 .. (size - 2)] + "\\", word[(size - 1) .. -1]]
+    end
+  end
+
+    # Splits the provided word so that it is in two parts, <tt>word[0 ..
+    # (size - 1)]</tt> and <tt>word[size .. -1]</tt>.
+  def split_word_to(word, size)
+    [word[0 .. (size - 1)], word[size .. -1]]
+  end
+
+    # Formats text into a nice paragraph format. The text is separated into
+    # words and then reassembled a word at a time using the settings of this
+    # Format object.
+    #
+    # If +text+ is +nil+, then the value of #text will be worked on.
+  def format_one_paragraph(text = nil)
+    text ||= @text
+    text = text[0] if text.kind_of?(Array)
+
+      # Convert the provided paragraph to a list of words.
+    words = text.split(SPACES_RE).reverse.reject { |ww| ww.nil? or ww.empty? }
+
+    text = []
+
+      # Find the maximum line width and the initial indent string.
+      # TODO 20050114 - allow the left and right margins to be specified as
+      # strings. If they are strings, then we need to use the sizes of the
+      # strings. Also: allow the indent string to be set manually and
+      # indicate whether the indent string will have a following space.
+    max_line_width = @columns - @first_indent - @left_margin - @right_margin
+    indent_str = ' ' * @first_indent
+
+    first_line = true
+
+    if words.empty?
+      line        = []
+      line_size   = 0
+      extra_space = false
+    else
+      line        = [ words.pop ]
+      line_size   = line[-1].size
+      extra_space = __add_extra_space?(line[-1])
+    end
+
+    while next_word = words.pop
+      next_word.strip! unless next_word.nil?
+      new_line_size = (next_word.size + line_size) + 1
+
+      if extra_space
+        if (line[-1] !~ __sentence_end_re)
+          extra_space = false
+        end
+      end
+
+        # Increase the width of the new line if there's a sentence
+        # terminator and we are applying extra_space.
+      new_line_size += 1 if extra_space
+
+        # Will the word fit onto the current line? If so, simply append it
+        # to the end of the line.
+
+      if new_line_size <= max_line_width
+        if line.empty?
+          line << next_word
+        else
+          if extra_space
+            line << "  #{next_word}"
+          else
+            line << " #{next_word}"
+          end
+        end
+      else
+          # Forcibly wrap the line if nonbreaking spaces are turned on and
+          # there is a condition where words must be wrapped. If we have
+          # returned more than one word, readjust the word list.
+        line, next_word = __wrap_line(line, next_word) if @nobreak
+        if next_word.kind_of?(Array)
+          if next_word.size > 1
+            words.push(*(next_word.reverse))
+            next_word = words.pop
+          else
+            next_word = next_word[0]
+          end
+          next_word.strip! unless next_word.nil?
+        end
+
+          # Check to see if the line needs to be hyphenated. If a word has a
+          # hyphen in it (e.g., "fixed-width"), then we can ALWAYS wrap at
+          # that hyphenation, even if #hard_margins is not turned on. More
+          # elaborate forms of hyphenation will only be performed if
+          # #hard_margins is turned on. If we have returned more than one
+          # word, readjust the word list.
+        line, new_line_size, next_word = __hyphenate(line, line_size, next_word, max_line_width)
+        if next_word.kind_of?(Array)
+          if next_word.size > 1
+            words.push(*(next_word.reverse))
+            next_word = words.pop
+          else
+            next_word = next_word[0]
+          end
+          next_word.strip! unless next_word.nil?
+        end
+
+        text << __make_line(line, indent_str, max_line_width, next_word.nil?) unless line.nil?
+
+        if first_line
+          first_line = false
+          max_line_width = @columns - @body_indent - @left_margin - @right_margin
+          indent_str = ' ' * @body_indent
+        end
+
+        if next_word.nil?
+          line          = []
+          new_line_size = 0
+        else
+          line          = [ next_word ]
+          new_line_size = next_word.size
+        end
+      end
+
+      line_size   = new_line_size
+      extra_space = __add_extra_space?(next_word) unless next_word.nil?
+    end
+
+    loop do
+      break if line.nil? or line.empty?
+      line, line_size, ww = __hyphenate(line, line_size, ww, max_line_width)#if @hard_margins
+      text << __make_line(line, indent_str, max_line_width, ww.nil?)
+      line = ww
+      ww = nil
+    end
+
+    if (@tag_paragraph and (not text.empty?))
+      if @tag_cur.nil? or @tag_cur.empty?
+        @tag_cur = @tag_text[0]
+      end
+
+      fchar = /(\S)/o.match(text[0])[1]
+      white = text[0].index(fchar)
+
+      unless @tag_cur.nil?
+        if ((white - @left_margin - 1) > @tag_cur.size) then
+          white = @tag_cur.size + @left_margin
+          text[0].gsub!(/^ {#{white}}/, "#{' ' * @left_margin}#{@tag_cur}")
+        else
+          text.unshift("#{' ' * @left_margin}#{@tag_cur}\n")
+        end
+      end
+    end
+
+    text.join('')
+  end
+  alias format format_one_paragraph
+
+    # Considers each element of text (provided or internal) as a paragraph.
+    # If #first_indent is the same as #body_indent, then paragraphs will be
+    # separated by a single empty line in the result; otherwise, the
+    # paragraphs will follow immediately after each other. Uses #format to
+    # do the heavy lifting.
+    #
+    # If +to_wrap+ responds to #split, then it will be split into an array
+    # of elements by calling #split with the value of +split_on+. The
+    # default value of split_on is $/, or the default record separator,
+    # repeated twice (e.g., /\n\n/).
+  def paragraphs(to_wrap = nil, split_on = /(#{$/}){2}/o)
+    to_wrap = @text if to_wrap.nil?
+    if to_wrap.respond_to?(:split)
+      to_wrap = to_wrap.split(split_on)
+    else
+      to_wrap = [to_wrap].flatten
+    end
+
+    if ((@first_indent == @body_indent) or @tag_paragraph) then
+      p_end = NEWLINE
+    else
+      p_end = ''
+    end
+
+    cnt = 0
+    ret = []
+    to_wrap.each do |tw|
+      @tag_cur = @tag_text[cnt] if @tag_paragraph
+      @tag_cur = '' if @tag_cur.nil?
+      line = format(tw)
+      ret << "#{line}#{p_end}" if (not line.nil?) and (line.size > 0)
+      cnt += 1
+    end
+
+    ret[-1].chomp! unless ret.empty?
+    ret.join('')
+  end
+
+    # Centers the text, preserving empty lines and tabs.
+  def center(to_center = nil)
+    to_center = @text if to_center.nil?
+    to_center = [to_center].flatten
+
+    tabs = 0
+    width = @columns - @left_margin - @right_margin
+    centered = []
+    to_center.each do |tc|
+      s = tc.strip
+      tabs = s.count(TAB)
+      tabs = 0 if tabs.nil?
+      ct = ((width - s.size - (tabs * @tabstop) + tabs) / 2)
+      ct = (width - @left_margin - @right_margin) - ct
+      centered << "#{s.rjust(ct)}\n"
+    end
+    centered.join('')
+  end
+
+    # Replaces all tab characters in the text with #tabstop spaces.
+  def expand(to_expand = nil)
+    to_expand = @text if to_expand.nil?
+
+    tmp = ' ' * @tabstop
+    changer = lambda do |text|
+      res = text.split(NEWLINE_RE)
+      res.collect! { |ln| ln.gsub!(/\t/o, tmp) }
+      res.join(NEWLINE)
+    end
+
+    if to_expand.kind_of?(Array)
+      to_expand.collect { |te| changer[te] }
+    else
+      changer[to_expand]
+    end
+  end
+
+    # Replaces all occurrences of #tabstop consecutive spaces with a tab
+    # character.
+  def unexpand(to_unexpand = nil)
+    to_unexpand = @text if to_unexpand.nil?
+
+    tmp = / {#{@tabstop}}/
+    changer = lambda do |text|
+      res = text.split(NEWLINE_RE)
+      res.collect! { |ln| ln.gsub!(tmp, TAB) }
+      res.join(NEWLINE)
+    end
+
+    if to_unexpand.kind_of?(Array)
+      to_unexpand.collect { |tu| changer[tu] }
+    else
+      changer[to_unexpand]
+    end
+  end
+
+    # Return +true+ if the word may have an extra space added after it. This
+    # will only be the case if #extra_space is +true+ and the word is not an
+    # abbreviation.
+  def __add_extra_space?(word)
+    return false unless @extra_space
+    word = word.gsub(/\.$/o, '') unless word.nil?
+    return false if ABBREV.include?(word)
+    return false if @abbreviations.include?(word)
+    true
+  end
+  private :__add_extra_space?
+
+  def __make_line(line, indent, width, last = false) #:nodoc:
+    line_size = line.inject(0) { |ls, el| ls + el.size }
+    lmargin = " " * @left_margin
+    fill = " " * (width - line_size) if right_fill? and (line_size <= width)
+
+    unless last
+      if justify? and (line.size > 1)
+        spaces      = width - line_size
+        word_spaces = spaces / (line.size / 2)
+        spaces      = spaces % (line.size / 2) if word_spaces > 0
+        line.reverse.each do |word|
+          next if (word =~ /^\S/o)
+
+          word.sub!(/^/o, " " * word_spaces)
+
+          next unless (spaces > 0)
+
+          word.sub!(/^/o, " ")
+          spaces -= 1
+        end
+      end
+    end
+
+    line = "#{lmargin}#{indent}#{line.join('')}#{fill}\n" unless line.empty?
+
+    if right_align? and (not line.nil?)
+      line.sub(/^/o, " " * (@columns - @right_margin - (line.size - 1)))
+    else
+      line
+    end
+  end
+# private :__make_line
+
+  def __hyphenate(line, line_size, next_word, width) #:nodoc:
+    return [ line, line_size, next_word ] if line.nil? or line.empty?
+    rline = line.dup
+    rsize = line_size
+
+    rnext = []
+    rnext << next_word.dup unless next_word.nil?
+
+    loop do
+      break if rnext.nil? or rline.nil?
+
+      if rsize == width
+        break
+      elsif rsize > width
+        word = rline.pop
+        size = width - rsize + word.size
+
+        if (size < 1)
+          rnext.unshift word
+          next
+        end
+
+        first = rest = nil
+
+          # TODO: Add the check to see if the word contains a hyphen to
+          # split on automatically.
+          # Does the word already have a hyphen in it? If so, try to use
+          # that to split the word.
+#       if word.index('-') < size
+#         first = word[0 ... word.index("-")]
+#         rest  = word[word.index("-") .. -1]
+#       end
+
+        if @hard_margins
+          if first.nil? and (@split_rules & SPLIT_HYPHENATION) == SPLIT_HYPHENATION
+            if @hyphenator_arity == 2
+              first, rest = @hyphenator.hyphenate_to(word, size)
+            else
+              first, rest = @hyphenator.hyphenate_to(word, size, self)
+            end
+          end
+
+          if first.nil? and (@split_rules & SPLIT_CONTINUATION) == SPLIT_CONTINUATION
+            first, rest = self.hyphenate_to(word, size)
+          end
+
+          if first.nil?
+            if (@split_rules & SPLIT_FIXED) == SPLIT_FIXED
+              first, rest = split_word_to(word, size)
+            elsif (not rest.nil? and (rest.size > size))
+              first, rest = split_word_to(word, size)
+            end
+          end
+        else
+          first = word if first.nil?
+        end
+
+        if first.nil?
+          rest = word
+        else
+          rsize = rsize - word.size + first.size
+          if rline.empty?
+            rline << first
+          else
+            rsize += 1
+            rline << " #{first}"
+          end
+          @split_words << SplitWord.new(word, first, rest)
+        end
+        rnext.unshift rest unless rest.nil?
+        break
+      else
+        break if rnext.empty?
+        word = rnext.shift.dup
+        size = width - rsize - 1
+
+        if (size <= 0)
+          rnext.unshift word
+          break
+        end
+
+        first = rest = nil
+
+          # TODO: Add the check to see if the word contains a hyphen to
+          # split on automatically.
+          # Does the word already have a hyphen in it? If so, try to use
+          # that to split the word.
+#       if word.index('-') < size
+#         first = word[0 ... word.index("-")]
+#         rest  = word[word.index("-") .. -1]
+#       end
+
+        if @hard_margins
+          if (@split_rules & SPLIT_HYPHENATION) == SPLIT_HYPHENATION
+            if @hyphenator_arity == 2
+              first, rest = @hyphenator.hyphenate_to(word, size)
+            else
+              first, rest = @hyphenator.hyphenate_to(word, size, self)
+            end
+          end
+
+          if first.nil? and (@split_rules & SPLIT_CONTINUATION) == SPLIT_CONTINUATION
+            first, rest = self.hyphenate_to(word, size)
+          end
+
+          if first.nil?
+            if (@split_rules & SPLIT_FIXED) == SPLIT_FIXED
+              first, rest = split_word_to(word, size)
+            elsif (not rest.nil? and (rest.size > width))
+              first, rest = split_word_to(word, size)
+            end
+          end
+        else
+          first = word if first.nil?
+        end
+
+          # The word was successfully split. Does it fit?
+        unless first.nil?
+          if (rsize + first.size) < width
+            @split_words << SplitWord.new(word, first, rest)
+
+            rsize += first.size + 1
+            rline << " #{first}"
+          else
+            rest = word
+          end
+        else
+          rest = word unless rest.nil?
+        end
+            
+        rnext.unshift rest
+        break
+      end
+    end
+    [ rline, rsize, rnext ]
+  end
+  private :__hyphenate
+
+    # The line must be broken. Typically, this is done by moving the last
+    # word on the current line to the next line. However, it may be possible
+    # that certain combinations of words may not be broken (see
+    # #nobreak_regex for more information). Therefore, it may be necessary
+    # to move multiple words from the current line to the next line. This
+    # function does this.
+  def __wrap_line(line, next_word)
+    no_break = false
+
+    word_index  = line.size - 1
+
+    @nobreak_regex.each_pair do |first, second|
+      if line[word_index] =~ first and next_word =~ second
+        no_break = true
+      end
+    end
+
+      # If the last word and the next word aren't to be broken, and the line
+      # has more than one word in it, then we need to go back by words to
+      # ensure that we break as allowed.
+    if no_break and word_index.nonzero?
+      word_index -= 1
+
+      while word_index.nonzero?
+        no_break = false
+        @nobreak_regex.each_pair { |first, second|
+          if line[word_index] =~ first and line[word_index + 1] =~ second
+            no_break = true
+          end
+        }
+
+        break unless no_break
+        word_index -= 1
+      end
+
+      if word_index.nonzero?
+        words = line.slice!(word_index .. -1)
+        words << next_word
+      end
+    end
+
+    [line, words]
+  end
+  private :__wrap_line
+
+    # Create a Text::Format object. Accepts an optional hash of construction
+    # options (this will be changed to named paramters in Ruby 2.0). After
+    # the initial object is constructed (with either the provided or default
+    # values), the object will be yielded (as +self+) to an optional block
+    # for further construction and operation.
+  def initialize(options = {}) #:yields self:
+    @text                 = options[:text]                  || []
+    @columns              = options[:columns]               || 72
+    @tabstop              = options[:tabstop]               || 8
+    @first_indent         = options[:first_indent]          || 4
+    @body_indent          = options[:body_indent]           || 0
+    @format_style         = options[:format_style]          || LEFT_ALIGN
+    @left_margin          = options[:left_margin]           || 0
+    @right_margin         = options[:right_margin]          || 0
+    @extra_space          = options[:extra_space]           || false
+    @tag_paragraph        = options[:tag_paragraph]         || false
+    @tag_text             = options[:tag_text]              || []
+    @abbreviations        = options[:abbreviations]         || []
+    @terminal_punctuation = options[:terminal_punctuation]  || ""
+    @terminal_quotes      = options[:terminal_quotes]       || ""
+    @nobreak              = options[:nobreak]               || false
+    @nobreak_regex        = options[:nobreak_regex]         || {}
+    @hard_margins         = options[:hard_margins]          || false
+    @split_rules          = options[:split_rules]           || SPLIT_FIXED
+    @hyphenator           = options[:hyphenator]            || self
+
+    @hyphenator_arity     = @hyphenator.method(:hyphenate_to).arity
+    @tag_cur              = ""
+    @split_words          = []
+
+    yield self if block_given?
+  end
+end