xml — `n_pbt_xml` #

← Référence des composants · Sommaire du guide

Écrire un XML élément par élément — ouvertures, attributs, texte, fermetures — avec l'échappement fait pour vous, puis en relire un avec du vrai XPath : of_load, of_get_value, of_get_attr, of_count. PowerBuilder 10 n'a aucun analyseur XML ; celui-ci s'appuie sur le DOMParser et document.evaluate du moteur WebView2, appelés synchronement.

▶ Le voir en vrai — Application de démonstration, tuile XML : les résultats, le code qui les produit et cette page, côte à côte.

En bref #

Le build est du PowerScript pur (assembler une chaîne ne demande aucun moteur). La lecture ouvre une page cachée à la première requête. Le XPath est la version 1.0, telle que le navigateur l'évalue.

Démarrage rapide #

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>

Propriétés #

Membre	Rôle
`string is_last_error`	Pourquoi la dernière lecture a rendu vide ou un code négatif : document mal formé, XPath sans correspondance, plafond démo. Vide après un succès

Construire un document #

Membre	Rôle
`of_start_element (string as_name)`	Ouvre un élément (les éléments s'imbriquent : un tag ouvert est fermé d'abord)
`of_element_attr (string as_name, string as_value)`	Ajoute un attribut à l'élément ouvert, valeur échappée (avant tout enfant ou texte)
`of_element_text (string as_text)`	Le contenu texte de l'élément courant, échappé
`of_end_element ( )`	Ferme l'élément courant (vide, il est auto-fermant `<name/>`)
`of_leaf (string as_name, string as_text)`	Un élément feuille en un appel — `<name>texte</name>`, échappé
`of_clear ( )` → `long`	Vide le builder pour commencer un autre document. Rend `0`
`of_xml ( )` → `string`	Le document tel quel : ce que vous avez bâti ou chargé (`of_load`), après toute modification — la sortie unique, à envoyer, stocker ou réécrire. Un document bâti n'a pas besoin de page (tout élément resté ouvert y est fermé) ; un document chargé est sérialisé par le moteur. `of_pretty` en donne la forme indentée

Lire un document (XPath) #

Membre	Rôle
`of_load (string as_xml)` → `long`	Charge un texte XML (analysé par le DOMParser du moteur). Rend `0` si bien formé, `-5` si vide, `-4` si XML invalide, `-2` si la page cachée échoue
`of_is_valid ( )` → `boolean`	Vrai quand le dernier `of_load` a réussi et qu'un document est chargé
`of_exists (string as_xpath)` → `boolean`	Vrai quand l'XPath correspond à au moins un nœud
`of_get_value (string as_xpath)` → `string`	Le contenu texte du PREMIER nœud correspondant. Vide si aucun
`of_get_attr (string as_xpath, string as_name)` → `string`	La valeur de l'attribut `as_name` du premier nœud correspondant. Vide si absent
`of_count (string as_xpath)` → `long`	Combien de nœuds l'XPath sélectionne. `0` si aucun (un compte XPath n'est jamais négatif)
`of_name (string as_xpath)` → `string`	Le nom de balise du premier nœud correspondant. Vide si aucun
`of_pretty ( )` → `string`	Le document tel quel — bâti ou chargé, ce que rend `of_xml` — ré-indenté pour la lecture. Vide s'il n'y a rien, ou si un document bâti n'est pas bien formé

Plusieurs nœuds, et le document #

Membre	Rôle
`of_get_values (string as_xpath, ref string as_values[])` → `long`	Le contenu texte de CHAQUE nœud correspondant, dans `as_values` ; rend le compte. Là où `of_get_value` ne rend que le premier
`of_get_attrs (string as_xpath, string as_name, ref string as_values[])` → `long`	La valeur de l'attribut `as_name` sur CHAQUE nœud correspondant (l'id de chaque ligne) ; rend le compte
`of_get_attr_names (string as_xpath, ref string as_names[])` → `long`	Les noms de tous les attributs du premier nœud correspondant (énumération) ; rend le compte

Modifier un document #

Le côté écriture change l'arbre chargé sur place ; of_xml en rend le résultat. Chacune vise le PREMIER nœud correspondant (sauf of_remove, qui les prend tous), rend 0 au succès, -4 si rien ne correspond, -5 sur un argument vide.

Membre	Rôle
`of_set_value (string as_xpath, string as_text)` → `long`	Fixe le texte du premier nœud correspondant (ses enfants sont remplacés)
`of_set_attr (string as_xpath, string as_name, string as_value)` → `long`	Fixe (ou ajoute) un attribut sur le premier nœud correspondant
`of_remove_attr (string as_xpath, string as_name)` → `long`	Retire un attribut du premier nœud correspondant
`of_add_child (string as_xpath, string as_tag, string as_text)` → `long`	Ajoute un élément enfant `<as_tag>as_text</as_tag>` sous le premier nœud correspondant (l'enfant hérite de l'espace de noms du parent)
`of_add_xml (string as_xpath, string as_fragment)` → `long`	Greffe un fragment XML déjà formé (un ou plusieurs éléments frères) sous le premier nœud correspondant — ce que `of_add_child` ne fait pas, ne prenant qu'une balise et un texte. Le fragment doit être bien formé et déclarer l'espace de noms qu'il utilise
`of_remove (string as_xpath)` → `long`	Retire TOUS les nœuds correspondants (une ligne, une branche périmée). Rend combien ont été retirés (jamais négatif)

Espaces de noms et XSLT #

Un XPath préfixé (SOAP, une API d'entreprise) ne correspond à rien sans résolveur : of_register_namespace lie le préfixe à son URI, of_clear_namespaces les oublie tous. of_transform applique une feuille XSLT — le moteur a XSLTProcessor, PowerBuilder 10 n'a rien de tel.

Membre	Rôle
`of_register_namespace (string as_prefix, string as_uri)` → `long`	Lie un préfixe à l'URI de son espace de noms, pour qu'un XPath préfixé (`/s:Envelope`) résolve. Rend `0`, ou `-5` sur un préfixe vide. Les liaisons durent jusqu'à `of_clear_namespaces` ou `of_reset`
`of_clear_namespaces ( )` → `long`	Oublie tous les préfixes enregistrés : un XPath préfixé ne correspond plus à rien tant qu'un préfixe n'est pas relié. Rend `0`
`of_transform (string as_xslt)` → `string`	Transforme le document chargé avec une feuille XSLT et rend le résultat en texte. Vide si rien n'est chargé ou si la feuille n'est pas du XML valide

// 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()

La page cachée #

Membre	Rôle
`of_open ( )` → `long`	Crée la page cachée (côté lecture). Facultatif — la première lecture le fait. Rend le handle (`> 0`) ou un code négatif
`of_is_open ( )` → `boolean`	Vrai dès que la page cachée existe
`of_close ( )`	Libère la page cachée. Le build continue sans elle. Fait pour vous à la destruction
`of_reset ( )`	Retour aux valeurs par défaut : le builder est vidé, l'état de lecture effacé

Portée. Le XML se lit par le moteur (DOMParser, XPath) : n_pbt_xml ouvre une page cachée à la première lecture, contrairement à json, qui s'analyse en PowerScript pur. Pour afficher un XML en arbre repliable, voyez xmltree.