Class REXML::Entity
In: rexml/entity.rb
Parent: Child

God, I hate DTDs. I really do. Why this idiot standard still plagues us is beyond me.

Methods

matches?   new   normalized   to_s   unnormalized   value   write  

Included Modules

XMLTokens

Constants

PUBIDCHAR = "\x20\x0D\x0Aa-zA-Z0-9\\-()+,./:=?;!*@$_%#"
SYSTEMLITERAL = %Q{((?:"[^"]*")|(?:'[^']*'))}
PUBIDLITERAL = %Q{("[#{PUBIDCHAR}']*"|'[#{PUBIDCHAR}]*')}
EXTERNALID = "(?:(?:(SYSTEM)\\s+#{SYSTEMLITERAL})|(?:(PUBLIC)\\s+#{PUBIDLITERAL}\\s+#{SYSTEMLITERAL}))"
NDATADECL = "\\s+NDATA\\s+#{NAME}"
PEREFERENCE = "%#{NAME};"
ENTITYVALUE = %Q{((?:"(?:[^%&"]|#{PEREFERENCE}|#{REFERENCE})*")|(?:'([^%&']|#{PEREFERENCE}|#{REFERENCE})*'))}
PEDEF = "(?:#{ENTITYVALUE}|#{EXTERNALID})"
ENTITYDEF = "(?:#{ENTITYVALUE}|(?:#{EXTERNALID}(#{NDATADECL})?))"
PEDECL = "<!ENTITY\\s+(%)\\s+#{NAME}\\s+#{PEDEF}\\s*>"
GEDECL = "<!ENTITY\\s+#{NAME}\\s+#{ENTITYDEF}\\s*>"
ENTITYDECL = /\s*(?:#{GEDECL})|(?:#{PEDECL})/um
PEREFERENCE_RE = /#{PEREFERENCE}/um

Attributes

external  [R] 
name  [R] 
ndata  [R] 
pubid  [R] 
ref  [R] 

Public Class methods

matches?(string)

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

[Source]

# File rexml/entity.rb, line 68
                def Entity::matches? string
                        (ENTITYDECL =~ string) == 0
                end
new(stream, value=nil, parent=nil, reference=false)

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 definiton, 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. The best thing to do is dump the stupid DTDs and use XMLSchema instead. 

 e = Entity.new( 'amp', '&' )

[Source]

# File rexml/entity.rb, line 35
                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

Public Instance methods

normalized()

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

[Source]

# File rexml/entity.rb, line 86
                def normalized
                        @value
                end
to_s()

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

[Source]

# File rexml/entity.rb, line 120
                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.

[Source]

# File rexml/entity.rb, line 75
                def unnormalized
                        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"

[Source]

# File rexml/entity.rb, line 135
                def value
                        if @value
                                matches = @value.scan(PEREFERENCE_RE)
                                rv = @value.clone
                                if @parent
                                        matches.each do |entity_reference|
                                                entity_value = @parent.entity( entity_reference[0] )
                                                rv.gsub!( /%#{entity_reference};/um, entity_value )
                                        end
                                end
                                return rv
                        end
                        nil
                end
write(out, indent=-1)

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

out:An object implementing <TT>&lt;&lt;<TT> to which the entity will be output
indent:DEPRECATED and ignored

[Source]

# File rexml/entity.rb, line 98
                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

[Validate]

ruby-doc.org is hosted and maintained by James Britt and Happy Camper Studios, a Ruby application development company in Phoenix, Arizona. The site was created in 2002 as part of the Ruby Documentation Project to promote the Ruby language and to help other Ruby hackers.

Documentation content on ruby-doc.org is provided by remarkable members of the Ruby community.

For more information on the Ruby programming language, visit ruby-lang.org.

Want to help improve Ruby's API docs? See Ruby Documentation Guidelines.