xml — `n_pbt_xml` #

← Referência dos componentes · Índice do guia

Escrever um XML elemento a elemento — aberturas, atributos, texto, fechos — com o escape feito por si, e depois ler um com XPath real: of_load, of_get_value, of_get_attr, of_count. O PowerBuilder 10 não tem analisador XML; este assenta no DOMParser e no document.evaluate do motor WebView2, chamados de forma síncrona.

▶ Ver ao vivo — Aplicação de demonstração, mosaico XML: os resultados, o código que os produz e esta página, lado a lado.

Em resumo #

O lado de construção é PowerScript puro (montar uma string não precisa de motor). O lado de leitura abre uma página oculta na primeira consulta. O XPath é a versão 1.0, tal como o navegador o avalia.

Início rápido #

n_pbt_xml  lnv_xml

// Read : load, then query with XPath
lnv_xml.of_load('<order id="4152"><customer>Ada</customer></order>')
IF lnv_xml.of_is_valid() THEN
	MessageBox("Customer", lnv_xml.of_get_value("/order/customer"))   // Ada
	MessageBox("Id", lnv_xml.of_get_attr("/order", "id"))              // 4152
END IF

// Build : element by element, escaping done for you
lnv_xml.of_clear()
lnv_xml.of_start_element("order")
lnv_xml.of_element_attr("id", "4152")
lnv_xml.of_leaf("customer", "Ada & Co")
lnv_xml.of_end_element()
// lnv_xml.of_xml() -> <order id="4152"><customer>Ada &amp; Co</customer></order>

Propriedades #

Membro	Função
`string is_last_error`	Porque a última leitura devolveu vazio ou um código negativo: documento malformado, XPath sem correspondência, limite demo. Vazio após um sucesso

Construir um documento #

Membro	Função
`of_start_element (string as_name)`	Abre um elemento (os elementos aninham: uma tag aberta é fechada primeiro)
`of_element_attr (string as_name, string as_value)`	Adiciona um atributo ao elemento aberto, valor com escape (antes de filho ou texto)
`of_element_text (string as_text)`	O conteúdo de texto do elemento atual, com escape
`of_end_element ( )`	Fecha o elemento atual (vazio, é auto-fechado `<name/>`)
`of_leaf (string as_name, string as_text)`	Um elemento folha numa chamada — `<name>texto</name>`, com escape
`of_clear ( )` → `long`	Esvazia o builder para outro documento. Devolve `0`
`of_xml ( )` → `string`	O documento tal como está: o que construiu ou carregou (`of_load`), após qualquer alteração — a saída única, para enviar, guardar ou reescrever. Um documento construído não precisa de página (qualquer elemento aberto é fechado) ; um carregado é serializado pelo motor. `of_pretty` é a forma indentada

Ler um documento (XPath) #

Membro	Função
`of_load (string as_xml)` → `long`	Carrega um texto XML (analisado pelo DOMParser do motor). Devolve `0` se bem formado, `-5` se vazio, `-4` se XML inválido, `-2` se a página oculta falhar
`of_is_valid ( )` → `boolean`	Verdadeiro quando o último `of_load` teve sucesso e há um documento carregado
`of_exists (string as_xpath)` → `boolean`	Verdadeiro quando o XPath corresponde a pelo menos um nó
`of_get_value (string as_xpath)` → `string`	O conteúdo de texto do PRIMEIRO nó correspondente. Vazio se nenhum
`of_get_attr (string as_xpath, string as_name)` → `string`	O valor do atributo `as_name` no primeiro nó correspondente. Vazio se ausente
`of_count (string as_xpath)` → `long`	Quantos nós o XPath seleciona. `0` se nenhum (uma contagem XPath nunca é negativa)
`of_name (string as_xpath)` → `string`	O nome da tag do primeiro nó correspondente. Vazio se nenhum
`of_pretty ( )` → `string`	O documento tal como está — construído ou carregado, o que `of_xml` devolve — reindentado para leitura. Vazio se não houver nada, ou se um documento construído não estiver bem formado

Vários nós, e o documento #

Membro	Função
`of_get_values (string as_xpath, ref string as_values[])` → `long`	O conteúdo de texto de CADA nó correspondente, em `as_values`; devolve a contagem. Onde `of_get_value` só devolve o primeiro
`of_get_attrs (string as_xpath, string as_name, ref string as_values[])` → `long`	O valor do atributo `as_name` em CADA nó correspondente (o id de cada linha); devolve a contagem
`of_get_attr_names (string as_xpath, ref string as_names[])` → `long`	Os nomes de todos os atributos do primeiro nó correspondente (enumeração); devolve a contagem

Modificar um documento #

O lado de escrita altera a árvore carregada no lugar; of_xml devolve o resultado. Cada uma visa o PRIMEIRO nó correspondente (exceto of_remove, que os toma todos), devolve 0 em sucesso, -4 quando nada corresponde, -5 num argumento vazio.

Membro	Função
`of_set_value (string as_xpath, string as_text)` → `long`	Define o texto do primeiro nó correspondente (os seus filhos são substituídos)
`of_set_attr (string as_xpath, string as_name, string as_value)` → `long`	Define (ou adiciona) um atributo no primeiro nó correspondente
`of_remove_attr (string as_xpath, string as_name)` → `long`	Remove um atributo do primeiro nó correspondente
`of_add_child (string as_xpath, string as_tag, string as_text)` → `long`	Adiciona um elemento filho `<as_tag>as_text</as_tag>` sob o primeiro nó correspondente (o filho herda o espaço de nomes do pai)
`of_add_xml (string as_xpath, string as_fragment)` → `long`	Enxerta um fragmento XML já formado (um ou vários elementos irmãos) sob o primeiro nó correspondente — o que `of_add_child` não faz, tomando apenas uma etiqueta e um texto. O fragmento deve estar bem formado e declarar o espaço de nomes que usa
`of_remove (string as_xpath)` → `long`	Remove CADA nó correspondente (uma linha, um ramo obsoleto). Devolve quantos foram removidos (nunca negativo)

Espaços de nomes e XSLT #

Um XPath com prefixo (SOAP, uma API empresarial) não corresponde a nada sem um resolvedor: of_register_namespace liga o prefixo ao seu URI, of_clear_namespaces esquece-os todos. of_transform aplica uma folha XSLT — o motor tem XSLTProcessor, o PowerBuilder 10 não tem nada parecido.

Membro	Função
`of_register_namespace (string as_prefix, string as_uri)` → `long`	Liga um prefixo ao URI do seu espaço de nomes, para que um XPath com prefixo (`/s:Envelope`) se resolva. Devolve `0`, ou `-5` num prefixo vazio. As ligações duram até `of_clear_namespaces` ou `of_reset`
`of_clear_namespaces ( )` → `long`	Esquece todos os prefixos registados: um XPath com prefixo não corresponde a nada até que um prefixo seja ligado. Devolve `0`
`of_transform (string as_xslt)` → `string`	Transforma o documento carregado com uma folha XSLT e devolve o resultado como texto. Vazio se nada estiver carregado ou se a folha não for XML válido

// A SOAP response : bind the prefix, then query it
lnv_xml.of_load(ls_soap)
lnv_xml.of_register_namespace("s", "http://schemas.xmlsoap.org/soap/envelope/")
ls_ok = lnv_xml.of_get_value("//s:Body/result/status")

// Mutate, then read the result back
lnv_xml.of_set_value("/order/customer", "Grace")
lnv_xml.of_add_child("/order", "total", "690.50")
// Graft a whole fragment at once (of_add_child adds only one tag)
lnv_xml.of_add_xml("/order", "<lines><line sku=\"1\">A</line><line sku=\"2\">B</line></lines>")
ls_out = lnv_xml.of_xml()

A página oculta #

Membro	Função
`of_open ( )` → `long`	Cria a página oculta (lado leitura). Facultativo — a primeira leitura fá-lo. Devolve o handle (`> 0`) ou um código negativo
`of_is_open ( )` → `boolean`	Verdadeiro assim que a página oculta existe
`of_close ( )`	Liberta a página oculta. Construir continua sem ela. Feito por si na destruição
`of_reset ( )`	Regresso aos valores por omissão: o builder esvaziado, o estado de leitura limpo

Âmbito. O XML lê-se através do motor (DOMParser, XPath): n_pbt_xml abre uma página oculta na primeira leitura, ao contrário de json, que analisa em PowerScript puro. Para mostrar um XML como árvore recolhível, veja xmltree.