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
-
namespaceDeclarations :Array.<XmlStreamNamespaceDeclaration>
-
Type:
- Array.<XmlStreamNamespaceDeclaration>
-
namespaceUri :string
-
Informa a URI de namespace de um TokenType.StartElement ou TokenType.EndElement.
Type:
- string
-
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
-
qualifiedName :string
-
Informa o nome qualificado de um TokenType.StartElement ou TokenType.EndElement.
Type:
- string
-
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
-
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.
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.
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.