# REXML::Entity (Class)

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

## 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 | = | ""
GEDECL | = | ""
ENTITYDECL | = | /\s*(?:#{GEDECL})|(?:#{PEDECL})/um
PEREFERENCE_RE | = | /#{PEREFERENCE}/um

## Attributes

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

## Included Modules

XMLTokens

## Public Class methods

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

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

## Public Instance methods

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

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

write(out, indent=-1)

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

[Source]

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

to_s()

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

[Source]

    # File rexml/entity.rb, line 114
                    def to_s
                            rv = ''
                            write rv
                            rv
                    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 129
                    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

[Validate]