nginstack

Class: XMLStreamReader

@nginstack/engine/lib/xml/XMLStreamReader~ XMLStreamReader

new XMLStreamReader(doc)

Implementa um parser para leitura de documentos XML através de uma API de streaming, baseado no StAX.

Parameters:
Name Type Description
doc string

Um documento XML bem-formado, ou seu primeiro segmento, caso o parsing seja sobre um stream de múltiplas partes do documento.
See:
Examples
const XMLStreamReader = require('@nginstack/engine/lib/xml/XMLStreamReader');

const example = '<?xml version="1.0"?><notes><note>Note A</note><note>Note B</note></notes>';
const fileName = File.getTempFileName();
File.fileFromString(fileName, example);

const reader = XMLStreamReader.parseFile(fileName);
if (!reader.readNextStartElement() || reader.name !== 'notes') {
    reader.raiseError('Não foi encontrada a tag "notes".');
}

const notes = [];
while (!reader.atEnd && reader.readNextStartElement()) {
    if (reader.name === 'note') {
        // Sempre que for possível, é recomendado que o dado seja processado em vez
        // de acumulado, evitando alocação de memória desnecessária.
        notes.push(reader.readElementText());
    } else {
        reader.raiseError('Elemento com tag "' + reader.name + '" não esperado.');
    }
}
if (reader.hasError) {
    throw new Error('Erro ao processar o arquivo XML: ' + reader.errorString);
}
reader.close();

notes; // ['Note A', 'Note B']
// Exemplo de um leitura a partir de blocos parciais de dados
const XMLStreamReader = require('@nginstack/engine/lib/xml/XMLStreamReader');
const part1 =  "<xml><head>Hello</head><bo";
const part2 = "dy>World</body></xml>";
const reader = new XMLStreamReader(part1);
reader.readNextStartElement(); // => true
reader.readNextStartElement(); // => true
reader.name; // => "head"
reader.readElementText(); // => "Hello"
if (reader.readNext() === XMLStreamReader.TokenType.Invalid &&
  reader.atEnd &&
  reader.error === XMLStreamReader.ReadError.PrematureEndOfDocumentError
) {
  reader.addData(part2);
}
reader.readNextStartElement(); // => true
reader.name; // => "body"

Members

<static> ReadElementTextBehaviour :ReadElementTextBehaviour

Define o tipo ReadElementTextBehaviour

Type:
  • ReadElementTextBehaviour
See:

<static> ReadError :ReadError

Define o tipo ReadError

Type:
  • ReadError
See:

<static> TokenType :TokenType

Define o tipo TokenType

Type:
  • TokenType
See:

atEnd :boolean

É true se o parser leu até o final do documento XML ou se um erro ocorreu e a leitura foi abortada. Caso contrário, é false. Quando atEnd e hasError são true, e error é igual a ReadError.PrematureEndOfDocumentError, significa que o documento não está completo. Nesse caso, outro segmento pode ser adicionado chamando o método addData, fazendo com que atEnd retorne false.

Type:
  • boolean
See:

attributes :Array.<XmlStreamAttribute>

Type:
  • Array.<XmlStreamAttribute>

documentEncoding :string

Se o tokenType for TokenType.StartDocument, a propriedade informa a codificação utilizada do documento XML.

Type:
  • string
See:

documentVersion :string

Se o tokenType for TokenType.StartDocument, a propriedade informa a versão do documento XML.

Type:
  • string
See:

dtdName :string

Se o tokenType for TokenType.DTD, a propriedade informa o seu nome.

Type:
  • string
See:

dtdPublicId :string

Se o tokenType for TokenType.DTD, a propriedade informa o seu identificador público.

Type:
  • string
See:

dtdSystemId :string

Se o tokenType for TokenType.DTD, a propriedade informa o seu identificador de sistema.

Type:
  • string
See:

error :ReadError

Informa o erro corrente, ou ReadError.NoError se não ocorreu nenhum.

Type:
  • ReadError

errorString :string

Informa a mensagem de erro que foi argumento numa chamada a raiseError.

Type:
  • string
See:

hasError :boolean

Booleano que indica se ocorreu um erro durante a leitura do XML

Type:
  • boolean
See:

isCDATA :boolean

Booleano que sinaliza se o parser está a extrair caracteres que derivam de uma seção CDATA.

Type:
  • boolean

isCharacters :boolean

Booleano que indica se tokenType é igual a TokenType.Characters.

Type:
  • boolean
See:

isComment :boolean

Booleano que indica se tokenType é igual a TokenType.Comments.

Type:
  • boolean
See:

isDTD :boolean

Booleano que indica se tokenType é igual a TokenType.DTD.

Type:
  • boolean
See:

isEndDocument :boolean

Booleano que indica se tokenType é igual a TokenType.EndDocument.

Type:
  • boolean
See:

isEndElement :boolean

Booleano que indica se tokenType é igual a TokenType.EndElement.

Type:
  • boolean
See:

isEntityReference :boolean

Booleano que indica se tokenType é igual a TokenType.EntityReference.

Type:
  • boolean
See:

isProcessingInstruction :boolean

Booleano que indica se tokenType é igual a TokenType.ProcessingInstruction.

Type:
  • boolean
See:

isStandaloneDocument :boolean

É igual a true se o documento foi declarado como Standalone na declaração do XML. É falso se nenhuma declaração foi encontrada durante o parsing.

Type:
  • boolean

isStartDocument :boolean

É igual a true se o tokenType for igual a TokenType.StartDocument.

Type:
  • boolean
See:

isWhitespace :boolean

Informa se há somente caracteres de espaço em branco.

Type:
  • boolean

lineNumber :number

Informa o número de linha corrente, iniciando a contagem em 1.

Type:
  • number

name :string

Informa o nome local de um TokenType.StartElement, TokenType.EndElement ou TokenType.EntityReference.

Type:
  • string
See:

namespaceDeclarations :Array.<XmlStreamNamespaceDeclaration>

Type:
  • Array.<XmlStreamNamespaceDeclaration>

namespaceUri :string

Informa a URI de namespace de um TokenType.StartElement ou TokenType.EndElement.

Type:
  • string
See:

prefix :string

Informa o prefixo de um TokenType.StartElement ou TokenType.EndElement.

Type:
  • string
See:

processingInstructionData :string

Informa o dado associado se isProcessingInstruction for true.

Type:
  • string
See:

qualifiedName :string

Informa o nome qualificado de um TokenType.StartElement ou TokenType.EndElement.

Type:
  • string
See:

tokenString :string

Informa a string correspondente ao token corrente do Reader.

Type:
  • string
See:

tokenType :TokenType

Informa o tipo do token corrente do Reader.

Type:
  • TokenType
See:

Methods

<static> parseFile(filePath)

Faz o parsing diretamente sobre um arquivo XML, sem carrega-lo todo em memória.

Parameters:
Name Type Description
filePath string

O path do arquivo com um documento XML bem-formado que sofrerá o parsing
See:
Returns:

Uma instância do parser associada ao arquivo XML

Type
XMLStreamReader

addData(data)

Adiciona um segmento do documento XML durante o seu parsing. Usado quando o documento completo não foi fornecido no momento que o parser foi instanciado.

Parameters:
Name Type Description
data string

O segmento do documento
See:

close()

Fecha o arquivo aberto durante o parsing através do método parseFile. Necessário chamar somente quando é necessário liberar o arquivo imediatamente, sem aguardar que o Garbage Collector o libere no momento da destruição do Reader.

See:

raiseError(msg)

Lança um erro custom com a mensagem informada nos argumentos.

Parameters:
Name Type Description
msg string

Mensagem de erro

readElementText( [behaviour])

Método conveniente para ser chamada no momento que um TokenType.StartElement foi lido. Prossegue com o parsing até o correspondente TokenType.EndElement ser alcançado. Após sua chamada, o token corrente será o TokenType.EndElement.

Parameters:
Name Type Argument Default Description
behaviour ReadElementTextBehaviour <optional>
 ReadElementTextBehaviour.ErrorOnUnexpectedElement

Seleciona o comportamento desejado quando algo é lido antes de alcançar o TokenType.EndElement: Incluir o texto dos elementos filhos, ignorar os elementos filhos ou lançar o erro ReadError.UnexpectedElementError e retornar o que foi lido até o momento.
See:
Returns:

Todo o texto entre o TokenType.StartElement e TokenType.EndElement.

Type
string

readNext()

Prossegue o parsing, retornando o próximo token. Com uma única exceção, uma vez um erro seja relatado por readNext, não é mais possível prosseguir com o parsing. Nesse momento, atEnd e hasError são true, e a função retorna TokenType.Invalid. A exceção é quando error é igual a ReadError.PrematureEndOfDocumentError. Esse erro é relatado quando é chegado ao final de um segmento de um documento XML bem-formado. Nesse caso, o parsing pode ser continuado chamando o método addData para adicionar outro segmento do documento XML.

See:
Returns:

token lido

Type
TokenType

readNextStartElement()

Prossegue o parsing até encontrar o próximo TokenType.StartElement dentro do elemento corrente, ou o elemento corrente acabar. O elemento corrente é o mais recente TokenType.StartElement encontrado, cujo correspondente TokenType.EndElement ainda não foi alcançado.

Returns:

true se um TokenType.StartElement foi encontrado

Type
boolean

skipCurrentElement()

Prossegue o parsing até o final do elemento corrente, saltando elementos filhos. Esse método é útil para saltar elementos desconhecidos. O Elemento corrente é o mais recente TokenType.StartElement encontrado, cujo correspondente TokenType.EndElement ainda não foi alcançado. Quando o parser o alcança, o elemento parente torna-se o elemento corrente.