123456789_123456789_123456789_123456789_123456789_

Class: REXML::Entity

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Child
Instance Chain:
self, XMLTokens, Child, Node
Inherits: REXML::Child
Defined in: lib/rexml/entity.rb

Constant Summary

XMLTokens - Included

NAME, NAMECHAR, NAME_CHAR, NAME_START_CHAR, NAME_STR, NCNAME_STR, NMTOKEN, NMTOKENS, REFERENCE

Class Method Summary

Child - Inherited

.new

Constructor.

Instance Attribute Summary

Child - Inherited

#next_sibling

Alias for Node#next_sibling_node.
#next_sibling=

Sets the next sibling of this child.
#parent

The Parent of this object.
#parent=

Sets the parent of this child to the supplied argument.
#previous_sibling

Alias for Node#previous_sibling_node.
#previous_sibling=

Sets the previous sibling of this child.

Node - Included

#parent?

Instance Method Summary

  • #normalized

    Returns the value of this entity unprocessed – raw.

  • #to_s

    Returns this entity as a string.

  • #unnormalized

    Evaluates to the unnormalized value of this entity; that is, replacing all entities – both %ent; and &ent; entities.

  • #value

    Returns the value of this entity.

  • #write(out, indent = -1)

    Write out a fully formed, correct entity definition (assuming the Entity object itself is valid.).

  • #resolve_value private

Child - Inherited

#bytes

This doesn’t yet handle encodings.
#document
Returns

the document this child belongs to, or nil if this child belongs to no document.
#remove

Removes this child from the parent.
#replace_with

Replaces this object with another object.

Node - Included

#each_recursive

Visit all subnodes of self recursively.
#find_first_recursive

Find (and return) first subnode (recursively) for which the block evaluates to true.
#indent,
#index_in_parent

Returns the position that self holds in its parent’s array, indexed from 1.
#next_sibling_node, #previous_sibling_node,
#to_s
indent

Constructor Details

.new(stream, value = nil, parent = nil, reference = false) ⇒ Entity

Create a new entity. Simple entities can be constructed by passing a name, value to the constructor; this creates a generic, plain entity reference. For anything more complicated, you have to pass a Source to the constructor with the entity definition, or use the accessor methods. WARNING: There is no validation of entity state except when the entity is read from a stream. If you start poking around with the accessors, you can easily create a non-conformant Entity.

e = Entity.new( 'amp', '&' )
[ GitHub ] 

  


# File 'lib/rexml/entity.rb', line 33



def initialize stream, value=nil, parent=nil, reference=false
  super(parent)
  @ndata = @pubid = @value = @external = nil
  if stream.kind_of? Array
    @name = stream[1]
    if stream[-1] == '%'
      @reference = true
      stream.pop
    else
      @reference = false
    end
    if stream[2] =~ /SYSTEM|PUBLIC/
      @external = stream[2]
      if @external == 'SYSTEM'
        @ref = stream[3]
        @ndata = stream[4] if stream.size == 5
      else
        @pubid = stream[3]
        @ref = stream[4]
      end
    else
      @value = stream[2]
    end
  else
    @reference = reference
    @external = nil
    @name = stream
    @value = value
  end
end


  







Class Method Details



  

    .matches?(string)  ⇒ Boolean 
  



  

    

Evaluates whether the given string matches an entity definition, returning true if so, and false otherwise.


  





  


  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 66



def Entity::matches? string
  (ENTITYDECL =~ string) == 0
end


  







Instance Attribute Details



  

    #external   (readonly)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 22



attr_reader :name, :external, :ref, :ndata, :pubid


  








  

    #name   (readonly)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 22



attr_reader :name, :external, :ref, :ndata, :pubid


  








  

    #ndata   (readonly)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 22



attr_reader :name, :external, :ref, :ndata, :pubid


  








  

    #parent=(other)   (writeonly)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 138



def parent=(other)
  @resolved_value = nil
  super
end


  








  

    #pubid   (readonly)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 22



attr_reader :name, :external, :ref, :ndata, :pubid


  








  

    #ref   (readonly)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 22



attr_reader :name, :external, :ref, :ndata, :pubid


  







Instance Method Details



  

    #normalized  
  



  

    

Returns the value of this entity unprocessed – raw.  This is the normalized value; that is, with all %ent; and &ent; entities intact


  



  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 85



def normalized
  @value
end


  








  

    #resolve_value   (private)
  

  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 144



def resolve_value
  return nil if @value.nil?
  return @value unless @value.match?(PEREFERENCE_RE)

  matches = @value.scan(PEREFERENCE_RE)
  rv = @value.clone
  if @parent
    sum = 0
    matches.each do |entity_reference|
      entity_value = @parent.entity( entity_reference[0] )
      if sum + entity_value.bytesize > Security.entity_expansion_text_limit
        raise "entity expansion has grown too large"
      else
        sum += entity_value.bytesize
      end
      rv.gsub!( /%#{entity_reference.join};/um, entity_value )
    end
  end
  rv
end


  








  

    #to_s  
  



  

    

Returns this entity as a string.  See write().


  



  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 119



def to_s
  rv = ''
  write rv
  rv
end


  








  

    #unnormalized  
  



  

    

Evaluates to the unnormalized value of this entity; that is, replacing all entities – both %ent; and &ent; entities.  This differs from value() in that #value only replaces %ent; entities.


  



  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 73



def unnormalized
  document.record_entity_expansion unless document.nil?
  v = value()
  return nil if v.nil?
  @unnormalized = Text::unnormalize(v, parent)
  @unnormalized
end


  








  

    #value  
  



  

    

Returns the value of this entity.  At the moment, only internal entities are processed.  If the value contains internal references (IE, %blah;), those are replaced with their values.  IE, if the doctype contains:



<!ENTITY % foo "bar">
<!ENTITY yada "nanoo %foo; nanoo>




then:



doctype.entity('yada').value   #-> "nanoo bar nanoo"


  



  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 134



def value
  @resolved_value ||= resolve_value
end


  








  

    #write(out, indent = -1)  
  



  

    

Write out a fully formed, correct entity definition (assuming the Entity object itself is valid.)


out



An object implementing &lt;&lt; to which the entity will be output


indent



DEPRECATED and ignored




  



  [ GitHub ]


  

  


# File 'lib/rexml/entity.rb', line 97



def write out, indent=-1
  out << '<!ENTITY '
  out << '% ' if @reference
  out << @name
  out << ' '
  if @external
    out << @external << ' '
    if @pubid
      q = @pubid.include?('"')?"'":'"'
      out << q << @pubid << q << ' '
    end
    q = @ref.include?('"')?"'":'"'
    out << q << @ref << q
    out << ' NDATA ' << @ndata if @ndata
  else
    q = @value.include?('"')?"'":'"'
    out << q << @value << q
  end
  out << '>'
end