Class: REXML::Text

Class | REXML::Text
In: | rexml/text.rb
Parent: | Child

Represents text nodes in an XML document

### Methods

<< <=> clone empty? indent_text inspect new node_type normalize read_with_substitution to_s unnormalize value value= wrap write write_with_substitution xpath

### Included Modules

Comparable

### Constants

SPECIALS | = | [ /&(?!#?[\w-]+;)/u, /</u, />/u, /"/u, /'/u, /\r/u ] |  | The order in which the substitutions occur
SUBSTITUTES | = | ['&amp;', '&lt;', '&gt;', '&quot;', '&apos;', '&#13;']
SLAICEPS | = | [ '<', '>', '"', "'", '&' ] |  | Characters which are substituted in written strings
SETUTITSBUS | = | [ /&lt;/u, /&gt;/u, /&quot;/u, /&apos;/u, /&amp;/u ]
ILLEGAL | = | /(<|&(?!(#{Entity::NAME})|(#0*((?:\d+)|(?:x[a-fA-F0-9]+)));))/um
NUMERICENTITY | = | /&#0*((?:\d+)|(?:x[a-fA-F0-9]+));/
REFERENCE | = | /#{Entity::REFERENCE}/
EREFERENCE | = | /&(?!#{Entity::NAME};)/

### Attributes

raw | [RW] | If `raw` is true, then REXML leaves the value alone

### Public Class methods

new(arg, respect_whitespace=false, parent=nil, raw=nil, entity_filter=nil, illegal=ILLEGAL )

Constructor `arg` if a String, the content is set to the String. If a Text, the object is shallowly cloned.

`respect_whitespace` (boolean, false) if true, whitespace is respected

`parent` (nil) if this is a Parent object, the parent will be set to this.

`raw` (nil) This argument can be given three values. If true, then the value of used to construct this object is expected to contain no unescaped XML markup, and REXML will not change the text. If this value is false, the string may contain any characters, and REXML will escape any and all defined entities whose values are contained in the text. If this value is nil (the default), then the raw value of the parent will be used as the raw value for this node. If there is no raw value for the parent, and no value is supplied, the default is false.

      Text.new( "<&", false, nil, false ) #-> "&lt;&amp;"
      Text.new( "<&", false, nil, true )  #-> IllegalArgumentException
      Text.new( "&lt;&amp;", false, nil, true )  #-> "&lt;&amp;"
      # Assume that the entity "s" is defined to be "sean"
      # and that the entity    "r" is defined to be "russell"
      Text.new( "sean russell" )          #-> "&s; &r;"
      Text.new( "sean russell", false, nil, true ) #-> "sean russell"

`entity_filter` (nil) This can be an array of entities to match in the supplied text. This argument is only useful if `raw` is set to false.

      Text.new( "sean russell", false, nil, false, ["s"] ) #-> "&s; russell"
      Text.new( "sean russell", false, nil, true, ["s"] ) #-> "sean russell"

In the last example, the `entity_filter` argument is ignored.

`pattern` INTERNAL USE ONLY

[Source]

    # File rexml/text.rb, line 57
        def initialize(arg, respect_whitespace=false, parent=nil, raw=nil,
          entity_filter=nil, illegal=ILLEGAL )

          @raw = false

          if parent
            super( parent )
            @raw = parent.raw
          else
            @parent = nil
          end

          @raw = raw unless raw.nil?
          @entity_filter = entity_filter
          @normalized = @unnormalized = nil

          if arg.kind_of? String
            @string = arg.clone
            @string.squeeze!(" \n\t") unless respect_whitespace
          elsif arg.kind_of? Text
            @string = arg.to_s
            @raw = arg.raw
          elsif
            raise "Illegal argument of type #{arg.type} for Text constructor (#{arg})"
          end

          @string.gsub!( /\r\n?/, "\n" )

          # check for illegal characters
          if @raw
            if @string =~ illegal
              raise "Illegal character '#{$1}' in raw string \"#{@string}\""
            end
          end
        end

normalize( input, doctype=nil, entity_filter=nil )

Escapes all possible entities

[Source]

    # File rexml/text.rb, line 284
        def Text::normalize( input, doctype=nil, entity_filter=nil )
          copy = input.clone
          # Doing it like this rather than in a loop improves the speed
          if doctype
            copy = copy.gsub( EREFERENCE, '&amp;' )
            doctype.entities.each_value do |entity|
              copy = copy.gsub( entity.value,
                "&#{entity.name};" ) if entity.value and
                  not( entity_filter and entity_filter.include?(entity) )
            end
          else
            copy = copy.gsub( EREFERENCE, '&amp;' )
            DocType::DEFAULT_ENTITIES.each_value do |entity|
              copy = copy.gsub(entity.value, "&#{entity.name};" )
            end
          end
          copy
        end

read_with_substitution( input, illegal=nil )

Reads text, substituting entities

[Source]

    # File rexml/text.rb, line 258
        def Text::read_with_substitution( input, illegal=nil )
          copy = input.clone

          if copy =~ illegal
            raise ParseException.new( "malformed text: Illegal character #$& in \"#{copy}\"" )
          end if illegal

          copy.gsub!( /\r\n?/, "\n" )
          if copy.include? ?&
            copy.gsub!( SETUTITSBUS[0], SLAICEPS[0] )
            copy.gsub!( SETUTITSBUS[1], SLAICEPS[1] )
            copy.gsub!( SETUTITSBUS[2], SLAICEPS[2] )
            copy.gsub!( SETUTITSBUS[3], SLAICEPS[3] )
            copy.gsub!( SETUTITSBUS[4], SLAICEPS[4] )
            copy.gsub!( /&#0*((?:\d+)|(?:x[a-f0-9]+));/ ) {|m|
              m=$1
              #m='0' if m==''
              m = "0#{m}" if m[0] == ?x
              [Integer(m)].pack('U*')
            }
          end
          copy
        end

unnormalize( string, doctype=nil, filter=nil, illegal=nil )

Unescapes all possible entities

[Source]

    # File rexml/text.rb, line 304
        def Text::unnormalize( string, doctype=nil, filter=nil, illegal=nil )
          rv = string.clone
          rv.gsub!( /\r\n?/, "\n" )
          matches = rv.scan( REFERENCE )
          return rv if matches.size == 0
          rv.gsub!( NUMERICENTITY ) {|m|
            m=$1
            m = "0#{m}" if m[0] == ?x
            [Integer(m)].pack('U*')
          }
          matches.collect!{|x|x[0]}.compact!
          if matches.size > 0
            if doctype
              matches.each do |entity_reference|
                unless filter and filter.include?(entity_reference)
                  entity_value = doctype.entity( entity_reference )
                  re = /&#{entity_reference};/
                  rv.gsub!( re, entity_value ) if entity_value
                end
              end
            else
              matches.each do |entity_reference|
                unless filter and filter.include?(entity_reference)
                  entity_value = DocType::DEFAULT_ENTITIES[ entity_reference ]
                  re = /&#{entity_reference};/
                  rv.gsub!( re, entity_value.value ) if entity_value
                end
              end
            end
            rv.gsub!( /&amp;/, '&' )
          end
          rv
        end

### Public Instance methods

<<( to_append )

Appends text to this text node. The text is appended in the `raw` mode of this text node.

[Source]

    # File rexml/text.rb, line 109
        def <<( to_append )
          @string << to_append.gsub( /\r\n?/, "\n" )
        end

<=>( other )

`other` a String or a Text `returns` the result of (to_s <=> arg.to_s)

[Source]

    # File rexml/text.rb, line 116
        def <=>( other )
          to_s() <=> other.to_s
        end

clone()

[Source]

    # File rexml/text.rb, line 102
        def clone
          return Text.new(self)
        end

empty?()

[Source]

    # File rexml/text.rb, line 97
        def empty?
          @string.size==0
        end

indent_text(string, level=1, style="\t", indentfirstline=true)

[Source]

    # File rexml/text.rb, line 199
         def indent_text(string, level=1, style="\t", indentfirstline=true)
          return string if level < 0
           new_string = ''
           string.each { |line|
             indent_string = style * level
             new_line = (indent_string + line).sub(/[\s]+$/,'')
             new_string << new_line
           }
           new_string.strip! unless indentfirstline
           return new_string
         end

inspect()

[Source]

    # File rexml/text.rb, line 147
        def inspect
          @string.inspect
        end

node_type()

[Source]

    # File rexml/text.rb, line 93
        def node_type
          :text
        end

to_s()

Returns the string value of this text node. This string is always escaped, meaning that it is a valid XML text node string, and all entities that can be escaped, have been inserted. This method respects the entity filter set in the constructor.

      # Assume that the entity "s" is defined to be "sean", and that the
      # entity "r" is defined to be "russell"
      t = Text.new( "< & sean russell", false, nil, false, ['s'] )
      t.to_s   #-> "&lt; &amp; &s; russell"
      t = Text.new( "< & &s; russell", false, nil, false )
      t.to_s   #-> "&lt; &amp; &s; russell"
      u = Text.new( "sean russell", false, nil, true )
      u.to_s   #-> "sean russell"

[Source]

    # File rexml/text.rb, line 134
        def to_s
          return @string if @raw
          return @normalized if @normalized

          doctype = nil
          if @parent
            doc = @parent.document
            doctype = doc.doctype if doc
          end

          @normalized = Text::normalize( @string, doctype, @entity_filter )
        end

value()

Returns the string value of this text. This is the text without entities, as it might be used programmatically, or printed to the console. This ignores the ‘raw’ attribute setting, and any entity_filter.

      # Assume that the entity "s" is defined to be "sean", and that the
      # entity "r" is defined to be "russell"
      t = Text.new( "< & sean russell", false, nil, false, ['s'] )
      t.string   #-> "< & sean russell"
      t = Text.new( "< & &s; russell", false, nil, false )
      t.string   #-> "< & sean russell"
      u = Text.new( "sean russell", false, nil, true )
      u.string   #-> "sean russell"

[Source]

    # File rexml/text.rb, line 164
        def value
          @unnormalized if @unnormalized
          doctype = nil
          if @parent
            doc = @parent.document
            doctype = doc.doctype if doc
          end
          @unnormalized = Text::unnormalize( @string, doctype )
        end

value=( val )

Sets the contents of this text node. This expects the text to be unnormalized. It returns self.

      e = Element.new( "a" )
      e.add_text( "foo" )   # <a>foo</a>
      e[0].value = "bar"    # <a>bar</a>
      e[0].value = "<a>"    # <a>&lt;a&gt;</a>

[Source]

    # File rexml/text.rb, line 192
        def value=( val )
          @string = val.gsub( /\r\n?/, "\n" )
          @unnormalized = nil
          @normalized = nil
          @raw = false
        end

wrap(string, width, addnewline=false)

[Source]

    # File rexml/text.rb, line 174
         def wrap(string, width, addnewline=false)
           # Recursivly wrap string at width.
           return string if string.length <= width
           place = string.rindex(' ', width) # Position in string with last ' ' before cutoff
           if addnewline then
             return "\n" + string[0,place] + "\n" + wrap(string[place+1..-1], width)
           else
             return string[0,place] + "\n" + wrap(string[place+1..-1], width)
           end
         end

write( writer, indent=-1, transitive=false, ie_hack=false )

[Source]

    # File rexml/text.rb, line 211
        def write( writer, indent=-1, transitive=false, ie_hack=false )
          s = to_s()
          if not (@parent and @parent.whitespace) then
            s = wrap(s, 60, false) if @parent and @parent.context[:wordwrap] == :all
            if @parent and not @parent.context[:indentstyle].nil? and indent > 0 and s.count("\n") > 0
              s = indent_text(s, indent, @parent.context[:indentstyle], false)
            end
            s.squeeze!(" \n\t") if @parent and !@parent.whitespace
          end
          writer << s
        end

write_with_substitution(out, input)

Writes out text, substituting special characters beforehand. `out` A String, IO, or any other object supporting <<( String ) `input` the text to substitute and the write out

      z=utf8.unpack("U*")
      ascOut=""
      z.each{|r|
        if r <  0x100
          ascOut.concat(r.chr)
        else
          ascOut.concat(sprintf("&#x%x;", r))
        end
      }
      puts ascOut

[Source]

    # File rexml/text.rb, line 245
        def write_with_substitution out, input
          copy = input.clone
          # Doing it like this rather than in a loop improves the speed
          copy.gsub!( SPECIALS[0], SUBSTITUTES[0] )
          copy.gsub!( SPECIALS[1], SUBSTITUTES[1] )
          copy.gsub!( SPECIALS[2], SUBSTITUTES[2] )
          copy.gsub!( SPECIALS[3], SUBSTITUTES[3] )
          copy.gsub!( SPECIALS[4], SUBSTITUTES[4] )
          copy.gsub!( SPECIALS[5], SUBSTITUTES[5] )
          out << copy
        end

xpath()

FIXME This probably won’t work properly

[Source]

    # File rexml/text.rb, line 225
        def xpath
          path = @parent.xpath
          path += "/text()"
          return path
        end

[Validate]