rdx 0.9.0.pre

data/lib/rdx/text.rb

@@ -0,0 +1,688 @@
+
+module RDX
+	
+	#
+	# Various utilities for text processing.
+	#
+	module Text
+		
+		#
+		# Contains some useful +Regexp+ patterns.
+		#
+		module REGEXP
+
+			# Matches a number token.
+			TK_NUMBER = /(?>
+				\d+
+				(?: _\d+ )*
+			)/x
+			
+			# Matches a literal Integer (without tag <tt>0[bodx]?</tt>).
+			INT = INT_P = /(?>
+				[-+]? #{TK_NUMBER}
+			)/ox
+
+			# Matches the result of Rational#to_s.
+			RTNL = %r%(?>
+				[-+]? #{TK_NUMBER} / #{TK_NUMBER}
+			)%ox
+
+			# Matches the result of Rational#inspect.
+			RTNL_P = %r%(?> \(
+				#{RTNL}
+			\) )%ox
+			
+			# Matches a literal Float.
+			FLT = FLT_P = /(?>
+				[-+]? #{TK_NUMBER} \. #{TK_NUMBER}
+				(?: [Ee] [-+]? #{TK_NUMBER} )?
+			)/ox
+
+			# Matches a literal Integer or Float.
+			INT_FLT = FLT_INT = INT_FLT_P = FLT_INT_P = /(?>
+				#{FLT} | #{INT}
+			)/ox
+
+			# Matches a literal Integer, Float and the result of Rational#to_s.
+			REAL = /(?>
+				#{RTNL} | #{INT_FLT}
+			)/ox
+			
+			# Matches a literal Integer, Float and the result of Rational#inspect.
+			REAL_P = /(?>
+				#{RTNL_P} | #{INT_FLT_P}
+			)/ox
+
+			# Matches the text <tt>[+-]?Infinity</tt> and +NaN+ other than real numbers.
+			IPERREAL_P = /(?>
+				[-+]? Infinity | NaN | #{REAL_P}
+			)/ox
+
+			# Matches the result of Complex#to_s.
+			CMPLX = /(?>
+				#{REAL} [-+] #{REAL} i
+			)/ox
+			
+			# Matches the result of Complex#inspect.
+			CMPLX_P = /(?> \(
+				#{IPERREAL_P} [-+] #{IPERREAL_P} \*? i
+			\) )/ox
+
+			# Matches the result of Numeric#to_s.
+			NUMERIC = %r%(?>
+				#{CMPLX} | #{REAL}
+			)%ox
+			
+			# Matches the result of Numeric#inspect
+			NUMERIC_P = %r%(?>
+				#{CMPLX_P} | #{REAL_P}
+			)%ox
+
+			# Matches an identifier token.
+			TK_ID = /(?>
+				(?! true | false | nil | self | __FILE__ | __LINE__ | __ENCODING__  )
+				[A-Za-z_[^[:ascii:]]]\w*
+			)/x
+			
+			# Matches a literal class (constant) name.
+			CLASS = CONSTANT = TK_CONST = /(?> (?:
+				(?: :: )?+   [A-Z]   \w*+
+			)++ )/x
+			
+			# Matches an instance variable token.
+			TK_IVAR = /(?>
+				@ \w+
+			)/x
+			
+			# Matches a class variable token.
+			TK_CVAR = /(?>
+				@@ \w+
+			)/x
+			
+			# Matches a global variable token.
+			TK_GVAR = /(?>
+				$ \w+
+			)/x
+			
+			# Matches a fetching token.
+			FETCH = Regexp.union TK_CONST, TK_ID, TK_IVAR, TK_CVAR, TK_GVAR
+
+			# Matches a literal double-quoted string (without interpolation).
+			DQ_STRING = /(?> "
+				(?:
+					[^"#\\]*+
+					(?: \\. )?+
+					(?: \#(?![{@$]) )?+
+				)*+
+			" )/x
+			
+			# Matches a literal single-quoted string.
+			SQ_STRING = /(?> '
+				(?:
+					[^'\\]*+
+					(?: \\. )?+
+				)*+
+			' )/x
+			
+			# Matches the rest of line if it has no more code (spaces and comment).
+			END_CODE_IN_LINE = /[^\S\n]*(?:#.*)?$/
+			
+			# Matches the magic comment of the string (eventual shebang line) and captures it.
+			MAGIC_COMMENT = %r%\A(?>
+				(?: \#! .* \n )?                    # Optional shebang line
+				[^\S\n]* ( \# .*? coding[:=] .* )   # Magic comment
+			)%x
+			
+			# Matches the result of Time#to_s (but also invalid ones).
+			TIME = %r%(?>
+				\d{4,}-\d\d-\d\d \  \d\d:\d\d:\d\d \  [-+]\d{4}
+			)%x
+			
+		end
+		
+		extend self
+		
+		#
+		# Converts _numeric_str_ to a +Numeric+ using +to_c+, +to_r+, +to_f+
+		# or +to_i+ according to the given +String+.
+		# 
+		#   RDX::Text.numeric_from_str "12"   #=> 12    # Integer
+		#   RDX::Text.numeric_from_str "1.2"  #=> 1.2   # Float
+		#   RDX::Text.numeric_from_str "1/2"  #=> 1/2   # Rational
+		#   RDX::Text.numeric_from_str "1+2i" #=> 1+2i  # Complex
+		#   
+		# If the string isn't valid can return unexpected results.
+		#
+		def numeric_from_str(numeric_str)
+			case numeric_str = numeric_str.to_str
+			when /i/
+				numeric_str.to_c
+			when /\//
+				numeric_str.to_r
+			when /[.eE]/
+				numeric_str.to_f
+			else
+				numeric_str.to_i
+			end
+		end
+		
+		#
+		# Replaces every potential object id (hexadecimal number) in the given _string_ with
+		# _replacement_.
+		# 
+		#   RDX::Text.generalize_object_ids "#<Class:0x0007a89f>"     #=> "#<Class:0xXXXXXX>"
+		#   RDX::Text.generalize_object_ids "#<Class:0x00012b40af>"   #=> "#<Class:0xXXXXXX>"
+		#   RDX::Text.generalize_object_ids "An hexadecimal number: 0X14a58ef"
+		#                                                                #=> "An hexadecimal number: 0xXXXXXX"
+		#
+		def generalize_object_ids string, replacement='0xXXXXXX'
+			return string unless string.respond_to?(:to_str)
+			return string if Object.const_defined?(:Encoding) and
+				!string.encoding.ascii_compatible? || !string.valid_encoding?
+			string = string.to_str.dup
+			string.gsub!(/0[Xx]\h+/, replacement)
+			string
+		end
+		
+		#
+		# Replace all occurrences of Numeric#to_s in the given _string_
+		# with _replacement_.
+		# 
+		#   RDX::Text.generalize_numerics "1.2e+7"    #=> "0"
+		#   RDX::Text.generalize_numerics "12and-7"   #=> "0and0"
+		#   RDX::Text.generalize_numerics "12/7"      #=> "0"
+		#   RDX::Text.generalize_numerics "12 / 7"    #=> "0 / 0"
+		#
+		def generalize_numerics string, replacement='0'
+			return string unless string.respond_to?(:to_str)
+			return string if Object.const_defined?(:Encoding) and
+				!string.encoding.ascii_compatible? || !string.valid_encoding?
+			string.to_str.gsub REGEXP::NUMERIC, replacement
+		end
+		
+		#
+		# Replace all occurrences of Time#to_s in the given _string_
+		# with _replacement_.
+		# 
+		#   txt = "Now it's: #{Time.now}"
+		#   RDX::Text.generalize_times txt #=> "Now it's: 0000-01-01 00:00:00 +0000"
+		#
+		def generalize_times string, replacement=Time.utc(0).getlocal("+00:00").to_s
+			return string unless string.respond_to?(:to_str)
+			return string if Object.const_defined?(:Encoding) and
+				!string.encoding.ascii_compatible? || !string.valid_encoding?
+			string.to_str.gsub REGEXP::TIME, replacement
+		end
+		
+		#
+		# Normalizes all floats in the given _string_ and replace them rounding with
+		# at most _digits_ significant digits. If _zero_threshold_ isn't +nil+ determines
+		# the threshold under which floats are considered <tt>0.0</tt>.
+		# 
+		#   RDX::Text.normalize_floats "12.345678"      #=> "+12.3457"
+		#   RDX::Text.normalize_floats "+12.345678"     #=> "+12.3457"
+		#   RDX::Text.normalize_floats "-123456.0", 3   #=> "-1.23e+05"
+		#   RDX::Text.normalize_floats "-1.23E5"        #=> "-123000.0"
+		#   RDX::Text.normalize_floats "-1.23E5", 3     #=> "-1.23e+05"
+		#   RDX::Text.normalize_floats "0.0000001"      #=> "+0.0"
+		#   RDX::Text.normalize_floats "0.0000001", 2, nil
+		#                                               #=> "+1.0e-07"
+		#   RDX::Text.normalize_floats "1_2.0000001"    #=> "+12.0"
+		#   RDX::Text.normalize_floats "1.2345678+1.2_345678i", 3
+		#                                               #=> "+1.23+1.23i"
+		#   RDX::Text.normalize_floats "6.0221412927e23", 4
+		#                                               #=> "+6.022e+23"
+		#
+		def normalize_floats string, digits=6, zero_threshold=10.0**-digits
+			return string unless string.respond_to?(:to_str)
+			return string if Object.const_defined?(:Encoding) and
+				!string.encoding.ascii_compatible? || !string.valid_encoding?
+			string.to_str.gsub REGEXP::FLT do |float_str|
+				float = float_str.to_f
+				float = 0.0 if zero_threshold and float.abs < zero_threshold
+				str = "%+.#{digits}g" % float
+				str.sub! /(?:e[-+]?\d+)?$/, '.0\&' unless str.include? '.'
+				str
+			end
+		end
+		
+		#
+		# Normalizes all occurrences of Time#to_s in the given _string_ to the result
+		# of the corresponding +UTC+ time.
+		# 
+		#   t0_cst = "1969-12-31 18:00:00 -0600"
+		#   RDX::Text.normalize_times t0_cst
+		#        #=> "1970-01-01 00:00:00 UTC"
+		#
+		def normalize_times string
+			return string unless string.respond_to?(:to_str)
+			return string if Object.const_defined?(:Encoding) and
+				!string.encoding.ascii_compatible? || !string.valid_encoding?
+			string.to_str.gsub REGEXP::TIME do |time_str|
+				*nums,offset = time_str.split /(?<=\d)[- :]/
+				time = Time.new *nums.map(&:to_i), offset.insert(3,':')
+				time.getutc.to_s
+			end
+		end
+		
+		#
+		# Normalizes the spaces in the given _output_ string, removing invisible or
+		# redundant differences according to the given parameters.
+		# 
+		#   RDX::Text.normalize_output_spacing <<EOS
+		#     This output is indented,
+		#     contains spaces at the end of this line,\s\s\s
+		#     four spaces separate these \s\s words,
+		#     contains tab \t characters
+		#     and ends with three line terminator\n\n
+		#   EOS
+		#   # =>
+		#   # <<EOS.chomp("\n")
+		#   # This output is indented,
+		#   # contains spaces at the end of this line,
+		#   # four spaces separate these words,
+		#   # contains tab characters
+		#   # and ends with three line terminator
+		#   # EOS
+		#
+		def normalize_output_spacing output, flush_left=true, squeeze_spaces=true, strip_newlines=true
+			return output unless output.respond_to?(:to_str)
+			output = remove_trailing_inline_spaces expand_tabs output.to_str
+			output = flush_left output if flush_left
+			if squeeze_spaces
+				output.squeeze! ' '
+				output.gsub! /\n{3,}/, "\n\n"
+			end
+			output = strip_newlines(output) if strip_newlines
+			output
+		end
+		
+		#
+		# Replaces in the given _string_ all the occurrences of _root_ with the _replacement_.
+		# 
+		#   dir = path = nil
+		#   Dir.mktmpdir do |tmpdir|
+		#     dir = tmpdir
+		#     fname = 'a_file'
+		#     path = File.join tmpdir, fname
+		#   end
+		#   RDX::Text.normalize_path path, dir, '<tmpdir>' #=> "<tmpdir>/a_file"
+		#
+		def normalize_path string, root=Dir.pwd, replacement='<relative_path>'
+			return string unless string.respond_to?(:to_str)
+			string.to_str.gsub root.to_str, replacement.to_str
+		end
+		
+		#
+		# Normalizes the _output_ string through #normalize_output_spacing, #normalize_floats
+		# and #generalize_object_ids in cascade (the details removed are considered negligible
+		# for an output).
+		#
+		def normalize_output output
+			normalize_floats generalize_object_ids normalize_output_spacing output
+		end
+		
+		#
+		# Removes minor details from an exception message _msg_ (the most important is that
+		# newlines are converted to regular spaces, so that the message can be written in
+		# multiple lines).
+		# 
+		#   RDX::Text.normalize_exception_message <<EOS
+		#   undefined method `a_method'
+		#   for "a quite long string":String
+		#   EOS
+		#   # => %Q{undefined method `a_method' for "a quite long string":string}
+		#
+		def normalize_exception_message msg
+			return msg unless msg.respond_to?(:to_str)
+			msg.to_str.strip.chomp('.').gsub(/\s+/,' ').downcase
+		end
+		
+		#
+		# Splits the given _string_ to an exception class and message according to _mode_,
+		# which specifies the format of the string:
+		# * +:class+ : _class_
+		# * +:message+ : _message_
+		# * +:class_message+ : _class_ <tt>:</tt> _message_
+		# * +:message_class+ : _message_ <tt>(</tt> _class_ <tt>)</tt>
+		# If a field is not detected it's replaced with +nil+.
+		# 
+		#   # IRB style (rescued exception):
+		#   str = "ArgumentError: wrong number of arguments (1 for 0)"
+		#   RDX::Text.split_exception_string str, :class_message
+		#   #=> ["ArgumentError", "wrong number of arguments (1 for 0)"]
+		#   RDX::Text.split_exception_string str, :message_class
+		#   #=> [nil, "ArgumentError: wrong number of arguments (1 for 0)"]
+		#   
+		#   # Command line style (unhandled exception):
+		#   str = "no implicit conversion of Fixnum into String (TypeError)"
+		#   RDX::Text.split_exception_string str, :message_class
+		#   #=> ["TypeError", "no implicit conversion of Fixnum into String"]
+		#   RDX::Text.split_exception_string str, :class_message
+		#   #=> [nil, "no implicit conversion of Fixnum into String (TypeError)"]
+		#
+		def split_exception_string string, mode=:class_message
+			string = string.to_str
+			case mode
+			when :class
+				message = nil
+				klass = string.match(/\A\s*(#{REGEXP::CLASS})\s*\z/) && $1
+			when :message
+				message = string
+				klass = nil
+			when :class_message
+				message = string.strip
+				klass = message.slice!(/\A(#{REGEXP::CLASS})\s*:\s*/) && $1
+			when :message_class
+				message = string.strip
+				klass = message.slice!(/\s*\((#{REGEXP::CLASS})\)\z/) && $1
+			end
+			message = nil if message && message.empty?
+			[klass,message]
+		end
+		
+		#
+		# Removes in _string_ the enclosing module (or class) _mod_ from the namespace.
+		# 
+		#   mod = Module.new
+		#   wrapper = class << mod   # creates a new lexical scope
+		#     module Wrapped
+		#     end
+		#     self
+		#   end
+		#   str = "The wrapped module is: #{wrapper::Wrapped}"
+		#     #-> "The wrapped module is: #<Class:0x36e7108>::Wrapped"
+		#   RDX::Text.remove_enclosing_module str, wrapper
+		#     #=> "The wrapped module is: Wrapped"
+		#
+		def remove_enclosing_module string, mod
+			return string unless string.respond_to?(:to_str)
+			return string if Object.const_defined?(:Encoding) and
+				!string.encoding.ascii_compatible? || !string.valid_encoding?
+			raise unless mod.is_a?(Module)
+			string = string.to_str
+			mod_str1 = mod.to_s
+			# For some reason, in nested constants' names is used Object#to_s and not Module#to_s
+			# The result is that for singleton classes we don't get the information about the attached object.
+			# So we have to bypass the inheritance chain:
+			mod_str2 = Object.instance_method(:to_s).bind(mod).call
+			mod_str = Regexp.escape(mod_str1) + '|' + Regexp.escape(mod_str2)
+			mod_rgxp = /(?:#{mod_str})::/
+			string.gsub(mod_rgxp,'')
+		end
+		alias remove_enclosing_class remove_enclosing_module
+		
+		#
+		# Returns a +Regexp+ that matches _content_ (may be a +String+ or +Regexp+)
+		# wrapped into any of the one HTML _tags_ given (does not handle HTML escaping).
+		# If one tag is +nil+ the unwrapped _content_ is also allowed.
+		# 
+		#   RDX::Text.add_html_tags 'text', 'b'        #=> %r%<b>text</b>%
+		#   RDX::Text.add_html_tags 'dot.', 'u', nil   #=> %r%dot\.|<u>dot\.</u>%
+		#   RDX::Text.add_html_tags 'Fixnum', 'tt', 'code'
+		#                                              #=> %r%<tt>Fixnum</tt>|<code>Fixnum</code>%
+		#   # One very used by RDX:
+		#   RDX::Text.add_html_tags /[Pp]roduces:?/, 'em', 'i'
+		#     #=> %r%<em>(?-mix:[Pp]roduces:?)</em>|<i>(?-mix:[Pp]roduces:?)</i>%
+		#
+		def add_html_tags content, *tags
+			content = Regexp.escape(content.to_str) unless content.is_a?(Regexp)
+			pattern = []
+			pattern << content if tags.compact!
+			tags.each do |tag|
+				re_tag = Regexp.escape(tag.to_str)
+				wrapped = "<#{re_tag}>#{content}</#{re_tag}>"
+				pattern << wrapped
+			end
+			Regexp.compile pattern.join('|')
+		end
+		alias add_html_tag add_html_tags
+		
+		#
+		# Returns a +Regexp+ pattern that matches any of the given _prompts_ at the beginning
+		# of a string (for definition). Leading spaces are allowed, one trailing is required to avoid
+		# the matching of another prompt.
+		# 
+		#   # Perhaps the most important for RDX:
+		#   re = RDX::Text.build_prompt '=>'   # => /\A\s*(?>=>)\s/
+		#   str = " => 15"
+		#   str.slice! re; str #=> "15"
+		#   str = "=>> 24"   # another prompt
+		#   str.slice! re #=> nil
+		#
+		def build_prompt *prompts
+			prompts.flatten!
+			prompts.map! do |prompt|
+				prompt.is_a?(Regexp) ? prompt.to_s : Regexp.escape(prompt.to_str)
+			end
+			pat = prompts.uniq.join '|'
+			return /\A\s*(?>#{pat})\s/
+		end
+		
+		#
+		# Assembles a +Regexp+ pattern that matches the given _parts_ in sequence,
+		# allowing inline spaces between them.
+		# Each part can be:
+		# *   a +Regexp+
+		# *   a +String+, which is interpreted literally
+		# *   a +Symbol+, which represent a REGEXP constant
+		#     (if begins with <tt>CAPTURE_</tt> the pattern is surrounded capturing parhentesis)
+		# 
+		#   str = "=> Float::MIN"
+		#   re = RDX::Text.build_pattern '=>', :CLASS
+		#   str.match re # > #<MatchData "=> Float::MIN">
+		#   re = RDX::Text.build_pattern '=>', :CAPTURE_CLASS
+		#   str[re,1] #=> "Float::MIN"
+		#
+		def build_pattern *parts
+			parts.map! do |part|
+				if part.is_a?(Regexp)
+					part
+				elsif part.is_a?(Symbol)
+					name = part.to_s
+					capturing = name.slice! /^CAPTURE_/
+					re = REGEXP.const_get(name,false)
+					capturing ? /(#{re})/ : re
+				else
+					Regexp.escape part.to_str
+				end
+			end
+			return Regexp.compile parts.join('[^\S\n]*')
+		end
+		
+		#
+		# Substitutes the content of each line in _string_ (but not newlines themselves) with _replacement_
+		# (which is the empty string by default).
+		# 
+		#   RDX::Text.collect_newlines <<EOS
+		#   useless data
+		#   where line count matters
+		#   EOS
+		#   # => "\n\n"
+		#   RDX::Text.collect_newlines <<EOS, '#'
+		#   # This is a useless
+		#   # ruby comment
+		#   EOS
+		#   # => "#\n#\n"
+		#
+		def collect_newlines string, replacement=nil
+			replacement ||= ''
+			string.to_str.gsub /^.*$/, replacement
+		end
+		
+		#
+		# If _string_ is formatted like a C-style comments strips the stars without
+		# consuming newlines characters.
+		# 
+		#   RDX::Text.strip_stars <<EOS
+		#   /*
+		#    * C comment
+		#    */
+		#   EOS
+		#   # => "  \n   C comment\n   \n"
+		#--
+		# This method is adapted from RDoc::Text#strip_stars
+		#   rb_cmt = <<EOS
+		#   ##
+		#   # Strips /* */ style comments
+		#   EOS
+		#   RDX::Text.strip_stars rb_cmt #=> rb_cmt
+		#
+		def strip_stars string
+			string = string.to_str
+			return string unless string =~ %r%\A\s*/\*.*\*/\s*\z%m
+
+			encoding = string.encoding if Object.const_defined? :Encoding
+
+		#	text = text.gsub %r%Document-method:\s+[\w:.#=!?]+%, ''   # handled in RDoc::Parser::C
+
+			space = ' '
+			space.force_encoding encoding if encoding
+
+			string.sub!  %r%/\*+%          do space*$&.length      end
+			string.sub!  %r%(\*+/)(\s*)\z% do space*$1.length + $2 end
+			string.gsub! %r%^[^\S\n]*\*?%  do space * $&.length    end
+
+		#	empty = ''
+		#	empty.force_encoding encoding if encoding
+		#	text.gsub(/^\s+$/, empty)
+
+			string
+		end
+		
+		#
+		# If _string_ is formatted like a Ruby-style comment strips hashes
+		# (and leading inline spaces before them), without consuming newlines characters.
+		# If _multihash_ is +true+ removes consecutive hashes.
+		# 
+		#   RDX::Text.strip_hashes <<EOS
+		#    # A
+		#   # Ruby
+		#     #  comment
+		#   EOS
+		#   # => " A\n Ruby\n  comment\n"
+		#   RDX::Text.strip_hashes "## meta-comment"       #=> "# meta-comment"
+		#   RDX::Text.strip_hashes "## meta-comment", true #=> " meta-comment"
+		#--
+		# This method is adapted from RDoc::Text#strip_hashes
+		#
+		def strip_hashes string, multihash=false
+			string = string.to_str
+			return string if string =~ /^[^\S\n]*+[^#]/
+
+			empty = ''
+			empty.force_encoding string.encoding if Object.const_defined? :Encoding
+			
+			replacement = multihash ? empty : '\1'
+			string.gsub /^[^\S\n]*+#(#*)/, replacement
+		end
+	
+		#
+		# Expands tab characters in _string_ to eight spaces.
+		#--
+		# Adapted from RDoc::Text#expand_tabs
+		#
+		def expand_tabs string
+			string = string.to_str
+			expanded = []
+
+			string.each_line do |line|
+				line.gsub!(/^((?:.{8})*?)([^\t\r\n]{0,7})\t/) do
+					r = "#{$1}#{$2}#{' ' * (8 - $2.size)}"
+					r.force_encoding string.encoding if Object.const_defined? :Encoding
+					r
+				end until line !~ /\t/
+
+				expanded << line
+			end
+
+			expanded.join ''
+		end
+		
+		#
+		# Flush _string_ left based on the shortest line.
+		# 
+		#   RDX::Text.flush_left <<EOS
+		#     this is
+		#       indented
+		#   EOS
+		#   # =>
+		#   # <<EOS
+		#   # this is
+		#   #   indented
+		#   # EOS
+		#--
+		# Taken as is from RDoc::Text#flush_left
+		#
+		def flush_left string
+			string = string.to_str
+			indent = string.each_line.map{ |ln| ln=~/\S/ }.compact.min
+			empty = ''
+			empty.force_encoding string.encoding if Object.const_defined? :Encoding
+			string.gsub /^ {0,#{indent}}/, empty   # unlimited if indent == nil
+		end
+		
+		#
+		# Removes trailing spaces (invisible) from each line of _string_.
+		# 
+		#   RDX::Text.remove_trailing_inline_spaces <<EOS
+		#     lines ending\t\s
+		#       with spaces\s\s\s
+		#   EOS
+		#   # => <<EOS
+		#   #   lines ending
+		#   #     with spaces
+		#   # EOS
+		#
+		def remove_trailing_inline_spaces string
+			string.to_str.gsub %r%[^\S\n]+$%, ''
+		end
+		
+		#
+		# Removes leading and trailing newlines from _string_.
+		# 
+		#   RDX::Text.strip_newlines "\nthe text\n\n" #=> "the text"
+		#
+		def strip_newlines string, leading=true, trailing=true
+			string = string.to_str.dup
+			string.slice! /\A\n+/ if leading
+			string.slice! /\n+\z/ if trailing
+			string
+		end
+		
+		#
+		# Strips stars, hashes, expands tabs, flushes _text_ to the left.
+		# 
+		#   RDX::Text.normalize_comment <<EOS
+		#   #
+		#   # This is a
+		#   # typical Ruby comment
+		#   #
+		#   EOS
+		#   # => "\nThis is a\ntypical Ruby comment\n\n"
+		#   
+		#   RDX::Text.normalize_comment <<EOS
+		#   /*
+		#    * This is a
+		#    * typical C comment
+		#    */
+		#   EOS
+		#   # => "\nThis is a\ntypical C comment\n\n"
+		#   
+		#--
+		# Method adapted from RDoc::Text#normalize_comment
+		#
+		def normalize_comment string, multihash=false
+			string = string.to_str
+			return string if string.empty?
+			string = strip_stars  string
+			string = strip_hashes string, multihash
+			string = expand_tabs  string
+			string = flush_left   string
+		#	string = strip_newlines string
+			string
+		end
+		
+	end
+	
+end