nginstack

Class: XMLStreamReader

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

new XMLStreamReader(doc [, options])

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

O parser de modo geral consiste em:

  • Um conjunto métodos de leitura que avançam de diferentes maneiras em um documento XML e retornam o tipo do token corrente.
  • Um conjunto de propriedades que acessam informações do token corrente.
  • Um conjunto de métodos de checagem do tipo do token corrente.

Os tipos de tokens são "Declaration", "StartElement", "EndElement", "EmptyElement", "Characters", "Comment", "ProcessingInstruction", "DoctypeDefinition", "CData", "EndDocument", "NoToken" (para quando a leitura ainda não foi iniciada) e "Error" (para indicar que houve erro na leitura).

Parameters:
Name Type Argument Description
doc string

Um documento XML bem-formado.
options XMLStreamReaderOptions <optional>

Parâmetros de criação. São eles:

  • trimText: Retira automaticamente espaços em branco das extremidades das sequências de caracteres lidas.
  • expandEmpty: Expande automaticamente tags vazias para pares de tag de abertura e encerramento de um elemento.

Os parâmetros são falsos por padrão.
See:
  • module:@nginstack/engine/lib/xml/TokenType Os métodos de leitura utilizam o conceito de escopo, que pode ser o elemento corrente ou a raiz do documento. No início da leitura, o escopo é a raiz do documento. Ao encontrar um "StartElement" (`TokenType.START_ELEMENT`), o escopo passa a ser aquele elemento corrente. Ao encontrar um "EndElement" (`TokenType.END_ELEMENT`), o escopo corrente volta a ser o escopo pai daquele elemento. Uma vez que um erro seja relatado por um método de leitura, não é mais possível prosseguir com o parsing.
Example
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 reader = new XMLStreamReader(example);

// Avança para o próximo token de abertura dentro do atual escopo. que seria `<notes>`.
// O escopo corrente passa a ser o elemento delimitado pelas tags `<notes>` e `</notes>`.
reader.readNextStartElement();

if (reader.name !== 'notes') {
    throw new Error('Não foi encontrada a tag "notes".');
}

const notes = [];

// Avança novamente ao próximo token de abertura dentro do atual escopo,
// que no caso é a primeira tag `<note>` do documento.
reader.readNextStartElement();

while (!reader.done && reader.name === 'note') {
    // Lê o token seguinte, que seria uma sequência de caracteres, e guarda o seu texto.
    // Observação: sempre que for possível, é recomendado que o dado seja processado em vez
    // de acumulado, evitando alocação de memória desnecessária.
    reader.readNext();
    notes.push(reader.text);

    // Pula para o fim do elemento corrente, e depois busca o início do próximo elemento.
    reader.skipToNextStartElement();
}

notes; // ['Note A', 'Note B']

Members

attributes :*

Se o tokenType for TokenType.START_ELEMENT ou TokenType.EMPTY_ELEMENT, a propriedade informa um objeto com os pares de nome local e valor dos atributos daquele token. A propriedades desse objeto são case insensitive.

Type:
  • *

documentEncoding :string

Informa a codificação utilizada do documento XML. Deve ser acessado apenas após a leitura da declaração do XML. Caso o XML não possua declaração, ou caso ainda não tenha sido lida, o leitor assumirá que o documento está codificado em UTF-8.

Type:
  • string
See:

documentVersion :string

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

Type:
  • string
See:

done :boolean

True se a leitura tiver sido concluída.

É possível que a leitura tenha sido concluída em sucesso ou em erro. Isso pode ser verificado usando o método hasError.

Type:
  • boolean
See:

error :string

Caso tenha ocorrido um erro na leitura, informa a string do erro. Caso contrário, informa uma string vazia.

Type:
  • string

localName :string

Se tokenType for TokenType.START_ELEMENT, TokenType.END_ELEMENT ou TokenType.EMPTY_ELEMENT, a propriedade informa o nome local do token. O nome local é o nome sem prefixo.

Type:
  • string
See:

name :string

Se tokenType for TokenType.START_ELEMENT, TokenType.END_ELEMENT ou TokenType.EMPTY_ELEMENT, a propriedade informa o nome qualificado do token. O nome qualificado é o nome exato como está na tag, incluindo o prefixo com o namespace.

Type:
  • string
See:

namespaceUri :string

Se tokenType for TokenType.START_ELEMENT, TokenType.END_ELEMENT ou TokenType.EMPTY_ELEMENT, a propriedade informa a URI associada ao namespace a que pertence o token.

Type:
  • string
See:

prefix :string

Se tokenType for TokenType.START_ELEMENT, TokenType.END_ELEMENT ou TokenType.EMPTY_ELEMENT, a propriedade informa o prefixo do nome do token.

Type:
  • string
See:

resolvedAttributes :Array.<ResolvedAttribute>

Se o tokenType for TokenType.START_ELEMENT ou TokenType.EMPTY_ELEMENT, a propriedade informa uma lista com os atributos resolvidos daquele token.

Cada elemento da lista é um objeto contendo as seguintes informações do atributo: name, localName, prefix, namespaceUri e value.

Type:
  • Array.<ResolvedAttribute>

standaloneDocument :boolean

Se o tokenType for TokenType.DECLARATION, a propriedade informa se o documento foi declarado como standalone.

Type:
  • boolean
See:

text :string

Texto do token corrente.

Type:
  • string

tokenType :TokenString

Informa o tipo do token corrente.

Type:
  • TokenString
See:

Methods

<static> parseFile(filePath [, options])

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

Parameters:
Name Type Argument Description
filePath string

O caminho do arquivo com um documento XML bem-formado que sofrerá o parsing.
options XMLStreamReaderOptions <optional>

Os mesmos parâmetros do construtor: trimText e `expandEmpty.
See:
Returns:

Uma instância do parser associada ao arquivo XML.

Type
XMLStreamReader

close()

Fecha o leitor interno do XMLStreamReader. Necessário chamar somente quando o reader foi criado usando parseFile e seja necessário liberar o arquivo imediatamente, sem aguardar que o Garbage Collector o libere no momento da destruição do reader.

See:

hasError()

Retorna true se tokenType for igual a TokenType.ERROR. Isso acontece quando uma chamada a algum dos métodos de leitura resulta em erro. A string do erro pode ser acessada pela propriedade XMLStreamReader.error.

See:
Returns:
Type
boolean

isCData()

Retorna true se tokenType for igual a TokenType.CDATA.

See:
Returns:
Type
boolean

isCharacters()

Retorna true se tokenType for igual a TokenType.CHARACTERS.

See:
Returns:
Type
boolean

isComment()

Retorna true se tokenType for igual a TokenType.COMMENT.

See:
Returns:
Type
boolean

isDeclaration()

Retorna true se tokenType for igual a TokenType.DECLARATION.

See:
Returns:
Type
boolean

isDTD()

Retorna true se tokenType for igual a TokenType.DOCTYPE_DEFINITION.

See:
Returns:
Type
boolean

isEmptyElement()

Retorna true se tokenType for igual a TokenType.EMPTY_ELEMENT.

See:
Returns:
Type
boolean

isEndElement()

Retorna true se tokenType for igual a TokenType.END_ELEMENT.

See:
Returns:
Type
boolean

isProcessingInstruction()

Retorna true se tokenType for igual a TokenType.PROCESSING_INSTRUCTION.

See:
Returns:
Type
boolean

isStartElement()

Retorna true se tokenType for igual a TokenType.START_ELEMENT.

See:
Returns:
Type
boolean

readNext()

Método de leitura padrão. Prossegue o parsing, retornando o próximo token.

See:
Returns:

token lido.

Type
TokenString

readNextStartElement()

Prossegue o parsing até encontrar um token de abertura (TokenType.START_ELEMENT) dentro do atual escopo. A busca para caso chegue ao fim do escopo.

See:
Returns:

token em que busca foi encerrada.

Type
TokenString

skipCurrentElement()

Prossegue o parsing até chegar ao fim do escopo corrente, que pode ser o token de fechamento correspondente (TokenType.END_ELEMENT) ou o fim do documento (TokenType.END_DOCUMENT).

See:
Returns:

token em que a busca foi encerrada.

Type
TokenString

skipToNextStartElement()

Equivale a chamar skipCurrentElement e readNextStartElement em sequência.

Na prática, prossegue o parsing até encontrar o próximo elemento irmão ou até chegar ao final do escopo pai.

See:
Returns:

token em que a busca foi encerrada

Type
TokenString