XmlDocument

Description

sealed class Tinman.Core.Xml.XmlDocument

Derived from

XmlNode abstract

Represents an XML document:

<?xml version="1.0" encoding="utf-8"?>
<!-- This is a comment in the preamble part. -->
<?pi This is a processing instruction in the preamble. ?>
<!DOCTYPE hello-world PUBLIC 'HELLO' 'WORLD'>
<!-- This is a 'Hello World' element -->
<hello-world name="value">
  Text
  <?trim leading and trailing whitespaces?>
  <![CDATA[
    More Text
  ]]>
</hello-world>

Use the FromFile method for loading an XML file into a XmlDocument object. Use the following factory methods to obtain XmlNode objects from XML code:

To assemble an XmlDocument programmatically, use the following methods methods:

Public / Constructors

From​File

public static method FromFile → (1)

xml in : Path

[not-null]
The XML file to parse.

returns → XmlDocument

The parsed XmlDocument.

Parses the given XML file and returns an XmlDocument for it.

This method loads the content of the given file and then delegates to FromSource.

IOException

If an I/O error has occurred.

ValidatingException

If xml in is malformed.

From​Source

public static method FromSource → (1)

xml in : string

[not-empty]
The XML string to parse.

returns → XmlDocument

The parsed XmlDocument.

Parses the given XML document and returns an XmlDocument for it:
Extensible Markup Language (XML) 1.0 (Fifth Edition)
W3C Recommendation 26 November 2008
https://www.w3.org/TR/xml/

This is the Grammar of an XML document string, which uses some relaxations in order to parse common violations against the official XML specification (e.g. zero or multiple document root elements, non 1.* version numbers):

document              := xml? preamble? doctype? content* ;
element               := element-start content* ;
literal               := attrib-value ;

content               := space | char-data | entity | element-end | element-start
                         | comment | cdata-section | pi ;
doctype               := '<!DOCTYPE' ws1 name (ws1 external-id)? ws0 ('[' dtd ']'
                         ws0)? '>' ;
preamble              := (space | comment | pi)+ ;
xml                   := '<?xml' xml-version xml-encoding? xml-standalone? ws0
                         '?>' ;

!cdata-section        := '<![CDATA[' char \ ']]>'* ']]>' ;
char-data             := ]<&[+ ;
dtd                   := (dtd-markup | dtd-separator)* ;
element-end           := '</' name ws0 '>' ;
element-start         := '<' name (ws1 attrib)* ws0 ('>' | '/>') ;
space                 := ws1 ;
xml-encoding          := ws1 'encoding' equal ('"' encoding-name '"' | '\''
                         encoding-name '\'') ;
xml-standalone        := ws1 'standalone' equal ('\'' xml-standalone-value '\'' |
                         '"' xml-standalone-value '"') ;
xml-version           := ws1 'version' equal ('\'' version-number '\'' | '"'
                         version-number '"') ;

attrib                := name equal attrib-value ;
dtd-markup            := dtd-element | dtd-attlist | dtd-entity | dtd-notation | pi
                         | comment ;
dtd-separator         := dtd-entity-param-ref | ws1 ;
!encoding-name        := letter (letter-or-digit | [_-.])* ;
!version-number       := digit+ '.' digit+ ;
xml-standalone-value  := 'yes' | 'no' ;

!comment              := '<!--' char \ '-->'* '-->' ;
dtd-attlist           := '<!ATTLIST' ws1 name dtd-attrib* ws0 '>' ;
dtd-element           := '<!ELEMENT' ws1 name ws1 dtd-content ws0 '>' ;
dtd-entity            := '<!ENTITY' ws1 (name ws1 dtd-entity-def dtd-ndata-decl?
                         | '%' ws1 name ws1 dtd-entity-def) ws0 '>' ;
dtd-notation          := '<!NOTATION' ws1 name ws1 (external-id | public-id) ws0
                         '>' ;
equal                 := ws0 '=' ws0 ;
!pi                   := '<?' name (ws1 char \ '?>'*)? '?>' ;

char                  := ' '..'\xD7FF' | [\t\r\n] | '\xE000'..'\xFFFD' ;
dtd-attrib            := ws1 name ws1 dtd-attrib-type ws1 dtd-attrib-default ;
dtd-content           := 'EMPTY' | 'ANY' | dtd-mixed | dtd-children ;
dtd-entity-def        := dtd-entity-value | external-id ;
dtd-ndata-decl        := ws1 'NDATA' ws1 name ;

dtd-attrib-default    := '#REQUIRED' | '#IMPLIED' | ('#FIXED' ws1)? attrib-value ;
dtd-attrib-type       := 'CDATA' | dtd-type-tokenized | dtd-type-enumerated ;
dtd-children          := dtd-choice | dtd-sequence !> dtd-count ;
!dtd-entity-value     := '"' (]"%&[ | dtd-entity-param-ref | entity)* '"' | '\''
                         (]%&'[ | dtd-entity-param-ref | entity)* '\'' ;
dtd-mixed             := '(' ws0 '#PCDATA' (ws0 '|' ws0 name)* ws0 ')*' | '(' ws0
                         '#PCDATA' ws0 ')' ;
!external-id          := ('SYSTEM' ws1 | public-id ws1) ('"' ]"[* '"' | '\'' ]'[*
                         '\'') ;

!attrib-value         := '"' (]<"&[+ | entity)* '"' | '\'' (]<&'[+ |
                         entity)* '\'' ;
!dtd-entity-param-ref := '%' name ';' ;
dtd-type-enumerated   := dtd-type-notation | dtd-type-enumeration ;
dtd-type-tokenized    := 'ENTITIES' | 'ENTITY' | 'IDREFS' | 'IDREF' | 'ID' |
                         'NMTOKENS' | 'NMTOKEN' ;
!public-id            := 'PUBLIC' ws1 ('"' public-id-char* '"' | '\'' public-id-char
                          \ '\''* '\'') ;

dtd-type-enumeration  := '(' ws0 dtd-nmtoken (ws0 '|' ws0 dtd-nmtoken)* ws0 ')' ;
dtd-type-notation     := 'NOTATION' ws1 '(' ws0 name (ws0 '|' ws0 name)* ws0 ')' ;
entity                := '&' (name | '#' ('x' hex-digit+ | digit+)) ';' ;
public-id-char        := ' ' | '\r' | '\n' | letter-or-digit |
                         [(_$-#!+*/).=%,?;'@:] ;

!dtd-nmtoken          := name-char+ ;
hex-digit             := digit | 'a'..'f' | 'A'..'F' ;
letter-or-digit       := letter | digit ;
ws1                   := [\t\r \n]+ ;

dtd-child             := name | dtd-choice | dtd-sequence !> dtd-count ;
dtd-choice            := '(' ws0 dtd-child (ws0 '|' ws0 dtd-child)+ ws0 ')' ;
dtd-sequence          := '(' ws0 dtd-child (ws0 ',' ws0 dtd-child)* ws0 ')' ;

!name                 := name-char-start name-char* ;

name-char             := name-char-start | digit | [-.] | '\x00B7' |
                         '\x0300'..'\x036F' | '\x203F'..'\x2040' ;

name-char-start       := letter | [_:] | '\x00C0'..'\x00D6' | '\x00D8'..'\x00F6' |
                         '\x00F8'..'\x02FF' | '\x0370'..'\x037D' |
                         '\x037F'..'\x1FFF' | '\x200C'..'\x200D' |
                         '\x2070'..'\x218F' | '\x2C00'..'\x2FEF' |
                         '\x3001'..'\xD7FF' | '\xF900'..'\xFDCF' |
                         '\xFDF0'..'\xFFFD' ;

digit                 := '0'..'9' ;
dtd-count             := '?' | '*' | '+' ;
letter                := 'a'..'z' | 'A'..'Z' ;
ws0                   := [\t\r \n]* ;

If present, the internal document type definition (see doctype rule) is parsed, but not otherwise evaluated or processed by the XmlDocument class.

ValidatingException

If xml in is malformed.

Xml​Document

public constructor XmlDocument → (9)

name opt : XmlName = default(XmlName)

See Name.

systemId opt : string = null

See SystemId. If invalid, null will be used.

publicId opt : string = null

See PublicId. If invalid, null will be used.

versionMajor opt : int32 = 1

[>=1]
See Version.

versionMinor opt : int32 = 0

[>=0]
See Version.

encoding opt : string = "utf-8"

See Encoding. If invalid, null will be used.

standAlone opt : int32 = 0

See StandAlone.

preamble opt : IBagConst<XmlNode> = null

The preamble item list or null for an empty list. See Preamble. All non-preamble nodes will be ignored (see XmlNode.IsDocumentPreamble).

content opt : IBagConst<XmlNode> = null

The content node list or null for an empty list. See Content. All non-content nodes will be ignored (see XmlNode.IsDocumentContent).

Creates a new instance of XmlDocument.

Public / Methods

Add​Content

public method AddContent → (1)

node in : XmlNode

[not-null]
The content node to add to Content, if it has a compatible type.

returns → XmlDocument

this

Adds a content node to this document.

See also

XmlNode.IsDocumentContent

Add​Entity

public method AddEntity → (2)

name in : XmlName

The entity name.

value in : string

[not-null]
The entity value.

returns → XmlDocument

this

Adds a custom external entity to the document.

The XmlNode.ToText1 method of XmlEntity nodes that refer to the given name in will return the entity value in. The values of the predefined entities cannot be modified.

See also

XmlDocument.Entities

Add​Preamble

public method AddPreamble → (1)

node in : XmlNode

[not-null]
The preamble node to add to Preamble, if it has a compatible type.

returns → XmlDocument

this

Adds a preamble node to this document.

Public / Attributes

Content

[Constant]
public attribute Content → (get)

value : IVectorConst<XmlNode>

[not-null]
The content nodes.

Returns the content nodes of the document, see XmlNode.IsDocumentContent.

A valid XML document must contain exactly one root element in its sequence of content items. However, it is not unusual that XML files have no root element or multiple root elements.

See also

XmlComment
XmlElement
XmlInstruction
XmlSpace

Encoding

[Constant]
public attribute Encoding → (get)

value : string

The attribute value or null iff not present.

Returns the value of the attribute 'encoding' in the <?xml…​?> part.

A valid encoding name matches the encoding-name rule, see FromSource.

Entities

[Constant]
public attribute Entities → (get)

value : ISortedMapConst<XmlName, string>

[not-null]
The custom external entities.

Returns the custom external entities for this document.

The custom external entities are not part of the XML document and are thus ignored by ICopyable.Copy (i.e. not copied) and IEquatable.Equals (i.e. not compared).

See also

XmlDocument.AddEntity

Name

[Constant]
public attribute Name → (get)

value : XmlName

The root element name or XmlName.Invalid iff the whole part is not present.

Returns the root element name in the <!DOCTYPE…​> part.

Preamble

[Constant]
public attribute Preamble → (get)

value : IVectorConst<XmlNode>

[not-null]
The preamble nodes.

Returns the preamble nodes of the document, see XmlNode.IsDocumentPreamble.

The preamble part is defined as the sequence of compatible XML nodes that immediately follow the <?xml…​?> part and appear before the <!DOCTYPE…​> part.

See also

XmlComment
XmlInstruction
XmlSpace

Public​Id

[Constant]
public attribute PublicId → (get)

value : string

The valid PUBLIC identifier or null iff not specified.

Returns the PUBLIC identifier in the <!DOCTYPE…​> part.

A valid PUBLIC identifier is a sequence of zero or more public-id-char characters, see FromSource.

Root

public attribute Root → (get)

value : XmlElement

The first element or null if there are no elements.

Returns the first element in the sequence of content items.

See also

XmlDocument.Content

Stand​Alone

[Constant]
public attribute StandAlone → (get)

value : int32

The attribute value:
-1 : 'no'
+1 : 'yes'
0 : not present

Returns the value of the attribute 'standalone' in the <?xml…​?> part.

System​Id

[Constant]
public attribute SystemId → (get)

value : string

The valid SYSTEM identifier or null iff not specified.

Returns the SYSTEM identifier in the <!DOCTYPE…​> part.

A valid SYSTEM identifier never contains both " and ' characters.

Version

[Constant]
public attribute Version → (get)

value : Vec2I

The version number:
Vec2I.X : major part
Vec2I.Y : minor part

Returns the value of the attribute 'version' in the <?xml…​?> part.