text-format-revised 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dd5b39a8ae855ade9797b43e324ff8d9611ad92e
+  data.tar.gz: 7b12bc913f0f63eb53829b1ab448157072a1bf2a
+SHA512:
+  metadata.gz: 4e0bf57d87869ffaaeb9aca078645c270d10ddf8b7d5f3a0c13074163413795d1e2e71e677cb9f316ed2f54faa4ff9cc11152956091ff26c64c0b38c129bea21
+  data.tar.gz: 3f759682b6b61862077fe71c9636f2de07cdda8a1d2db49306ffb3c76f4eb70a1e1a69ca5ca829d93aad93412874de4f7f7e49e6914d8b8ec98c7254b0f81f31

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'

data/Gemfile.lock

@@ -0,0 +1,22 @@
+PATH
+  remote: .
+  specs:
+    text-format (1.1.0)
+      text-hyphen (~> 1.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.4.3)
+    rake (10.0.4)
+    text-hyphen (1.2)
+    turn (0.9.6)
+      ansi
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  text-format!
+  turn

data/LICENSE

@@ -0,0 +1,61 @@
+Copyright (c) 2013 Austin Ziegler, Chris Ledet
+
+Text::Format is copyrighted free software owned by Austin Ziegler.
+The Owner of this software permits you to redistribute and/or modify 
+the software under either the terms of 
+the GPL version 2 (see the file GPL), or the conditions below ("Ruby License"):
+
+  1. You may make and give away verbatim copies of the source form of this
+     software without restriction, provided that you retain ALL of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+    modifications to Usenet or an equivalent medium, or by allowing
+    the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the Owner.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+    together with instructions (in a manual page or equivalent)
+    on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+    the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the Owner.
+
+  4. You may modify and include parts of the software into any other
+     software (possibly commercial), provided you comply with the terms in
+     Sections 1, 2, and 3 above. But some files in the distribution
+     are not written by the Owner, so they may be made available to you
+     under different terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whoever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README.md

@@ -0,0 +1,16 @@
+## Text::Format fork
+
+### Ruby 1.9 Update
+
+Updated this gem so it works with Ruby 2.0.0. Do not use this gem if you're using for Ruby versions <1.9.2.
+
+### 
+
+### About
+
+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.
+
+### License
+
+Text::Format is originally based on the Perl library of the same name by Gábor Egressy. 
+Licenced under [Ruby's licence](http://www.ruby-lang.org/en/about/license.txt). It is also available under the [Perl Artistic licence](http://dev.perl.org/licenses/artistic.html).

data/Rakefile

@@ -0,0 +1,13 @@
+#! /usr/bin/env rake
+$LOAD_PATH.unshift('lib')
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test

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