Satimage
Dictionary of XMLLib
Home The dictionaries Dictionary of XMLLib  
Satimage XML DOM
XML XPath, XSLT
XML Documents
XML Validation
Satimage PropertyList Additions
Satimage Pool Additions
XNF Additions
Satimage XML DOM
An AppleScript implementation of the DOM. Uses the Libxml2 open source project.

XMLRef n : an opaque reference to an XML node. Initial XMLRefs must be created with XMLOpen.


namespace n : the AppleScript format of an XML namespace.

properties

nsprefix string : the prefix of the namespace.

nsurl string : the uri of the namespace.

NodeInfo n : type returned by XMLNodeInfo.

properties

kind string : XML class of the element : ELEMENT_NODE, TEXT_NODE, ATTRIBUTE_NODE, DOCUMENT_NODE...

name string : tag of the element for element node.

attribute list of string : a list of attribute name, attribute value.

namespace namespace : optional. namespace of the element.

SystemID string : the system ID of the DTD (document node only).

ExternalID string : the external ID of the DTD (document node only).



XMLOpen v : open an XML file and parse it. Must be balanced with a XMLClose at the end of the job. Alternatively, use to "from string" parameter to provide the xml data as a string

XMLOpen [alias] : a file containing xml data or an url

[from string text] : a string containing xml data

[keep blanks boolean] : default false

[load external DTD boolean] : default false

[substitute entities boolean] : default false

[validate boolean] : validate with respect to its dtd; default false. Support XML Catalogs (http://www.oasis-open.org/committees/entity/spec-2001-08-06.html) at "/etc/xml/catalog" or "/Library/DTDs/catalog"

[html4 boolean] : require the HTML4 lax parsing. Default: false

[xmlscript boolean] : parse the script tags even if HTML4 is true. Produce faithful xml when scripts are escaped with CDATA sections. Default: false

[verbose boolean] : default false

[failure level integer] : a number between 1 and 3. 3: fail only on fatal errors, 2: fail on xml recoverable errors, 1: fail on warnings. The default is provided by the XMLErrorLevel command.

[in pool string] : the name of the group where the new document is created. Default: the current pool. At launch the current pool is "".

[bypassing namespace boolean] : default false. Bypass the default namespaces.

XMLRef : a reference to the XML parsed document, required by all the other XML commands

Example
For the examples in this page we shall use the periodic chart of the chemical elements at "http://www.satimage.fr/software/samples/allelements.xml".
You can open the file in a new Unicode window with the Open URL... menu item (Open...+shift) and enter the URL.
Or execute: open "http://www.satimage.fr/software/samples/allelements.xml".
The following lines load "allelements.xml" into XMLLib.
Don't forget to balance XMLOpen with a XMLClose to release the opened XML document.
set the_URL to "http://www.satimage.fr/software/samples/allelements.xml" set the_doc to XMLOpen the_URL --  «data XMLR0000000100000000» set the_root to XMLRoot the_doc -- «data XMLR0000000104739D80»
XMLOpen lets you create a new xml document from a string
set doc2 to XMLOpen from string "<?xml version='1.0' encoding='UTF-8'?><a/>" --  «data XMLR0000000200000000» XMLDisplayxml doc2 -- "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <a/>" XMLClose doc2

XMLClose v : release memory, associated XMLRefs are no longer valid.

XMLClose XMLRef

XMLRoot v : get the root of the XML document.

XMLRoot XMLRef : the document

XMLRef : the root element

XMLCount v : count children in the given XML object.

XMLCount XMLRef : an XML object

[all nodes boolean] : if false XMLCount omits non-element nodes. Default true.

→ integer : the number of children

Example
Please make sure you have run the XMLOpen example first.
XMLCount the_root -- 112 -- the table contains 112 atoms

XMLCountElement v : count elements in the given XML object. Equivalent to XMLCount without all nodes

XMLCountElement XMLRef : an XML object

→ integer : the number of children

XMLChild v : provide access to children of a given XML object.

XMLChild XMLRef : the parent

index integer : 1..XMLCount, index of the requested child

[all nodes boolean] : if false XMLChild omits non-element nodes. Default true.

XMLRef : the child

Example
Please make sure you have run the XMLOpen example first.
set the_child to XMLChild the_root index 1 -- «data XMLR0000000104739DC0» -- the_child is an opaque reference -- the atom itself has children: set the_child_2 to XMLChild the_child index 1 -- to know what kind of thing it is you can use XMLNodeInfo or XMLDisplayXML XMLDisplayXML the_child_2

XMLElement v : equivalent to XMLChild without all nodes.

XMLElement XMLRef : the parent

index integer : 1..XMLCountElement, index of the requested child

XMLRef : the child

XMLParent v : return the parent of an object.

XMLParent XMLRef or list of XMLRef

XMLRef : the parent(s)

XMLNextSibling v : return the next sibling of an object.

XMLNextSibling XMLRef

[all nodes boolean] : if false XMLNextSibling omits non-element nodes. Default true.

XMLRef : the next sibling

XMLNextElement v : equivalent to XMLNextSibling without all nodes.

XMLNextElement XMLRef

XMLRef : the next sibling element

XMLPrevSibling v : return the previous sibling of an object.

XMLPrevSibling XMLRef

[all nodes boolean] : if false XMLPrevSibling omits non-element nodes. Default true.

XMLRef : the previous sibling

XMLPrevElement v : equivalent to XMLPrevSibling without all nodes.

XMLPrevElement XMLRef

XMLRef : the previous sibling element

XMLTagName v : return the name of the element.

XMLTagName XMLRef or list of XMLRef

→ string

Example
set doc2 to XMLOpen from string "<glass><water/></glass>" XMLTagName (XMLRoot doc2) -- "glass" XMLClose doc2

XMLGetAttribute v : return the contents of an attribute.

XMLGetAttribute XMLRef or list of XMLRef

name string : the name of the attribute

[namespace string] : the namespace URL. For instance, to retrieve an xml:lang attribute this parameter must be "http://www.w3.org/XML/1998/namespace" and the name parameter must be "lang"

→ string

XMLSetAttribute v : set (or create) an attribute.

XMLSetAttribute XMLRef or list of XMLRef

name string or list of string : the name of the attribute

to string or list of string : the contents of the attribute.

[namespace string] : the namespace URL

Example
set doc2 to XMLOpen from string "<a>Satimage</a>" set r to (XMLRoot doc2) XMLSetAttribute r name "href" to "http://www.satimage-software.com" XMLDisplayXML r -- "<a href=\"http://www.satimage-software.com\">Satimage</a>" XMLClose doc2

XMLRemoveAttribute v : remove an attribute.

XMLRemoveAttribute XMLRef or list of XMLRef

name string or list of string : the name of the attribute

[namespace string] : the namespace URL

XMLRemove v : delete an object. The reference to this object (or to any contained object) is no more valid.

XMLRemove XMLRef : the object to delete

XMLRemoveChildren v : delete all children.

XMLRemoveChildren XMLRef

XMLExists v : Test if an XMLRef is valid.

XMLExists XMLRef : the object to test

→ boolean

XMLNewChild v : create a new child in a given object.

XMLNewChild string, XMLRef, or list of XMLRef : the XML string describing the new child or the XMLRef(s) to clone

[keep blanks boolean] : default false

at XMLRef : the parent

XMLRef : a reference to the newly created object

Example
set doc2 to XMLOpen from string "<agents/>" set r to (XMLRoot doc2) set a to XMLNewChild "<agent/>" at r XMLNewChild "<name>James Bond</name>" at a XMLNewChild "<number>007</number>" at a XMLDisplayXML r -- "<agents> <agent> <name>James Bond</name> <number>007</number> </agent> </agents>" XMLClose doc2

XMLNewSibling v : create a new object beside a given object.

XMLNewSibling string, XMLRef, or list of XMLRef : the XML string describing the new object or the XMLRef(s) to clone

[keep blanks boolean] : default false

[after XMLRef] : insert new object after this one

[before XMLRef] : insert new object before this one

XMLRef : a reference to the newly created object

Example
set doc2 to XMLOpen from string "<lang><english/><german/><spanish/></lang>" set r to (XMLRoot doc2) set {g} to XMLXPath r with "/lang/*[compare(name(),'french')>0]" XMLNewSibling "<french/>" before g XMLDisplayXML r -- "<lang> <english/> <french/> <german/> <spanish/> </lang>" XMLClose doc2

XMLNodeInfo v : return node information. syn XMLDisplay

XMLNodeInfo XMLRef, alias, or string : the XML object to display. If the direct parameter is an alias (or a string), XMLNodeInfo attempts to retrieve the root node or the DOCTYPE node of the file (XMLNodeInfo does not check the whole file)

NodeInfo : a record containing the name, the kind and the dictionary (attributes) of the object

Example
Also helpful for development and debugging with its companions XMLDisplayXML and XMLGetText.
Please make sure you have run the XMLOpen example first.
set the_child to XMLChild the_root index 1 XMLNodeInfo the_child -- {kind:"ELEMENT_NODE", name:"ATOM"} -- the atom itself has children: set the_child_2 to XMLChild the_child index 1 XMLNodeInfo the_child_2 -- {kind:"ELEMENT_NODE", name:"NAME"} -- the 1st atom's 1st child is the atom's name -- And now an example with attributes set {hydrogen} to XMLXPath the_root with "ATOM[SYMBOL='H']/BOILING_POINT" XMLNodeInfo hydrogen -- {kind:"ELEMENT_NODE", name:"BOILING_POINT", attribute:{"UNITS", "Kelvin"}} XMLDisplayXML hydrogen -- "<BOILING_POINT UNITS="Kelvin">20.28</BOILING_POINT>" XMLGetText hydrogen -- "20.28" set {units} to XMLXPath the_root with "ATOM[SYMBOL='H']/BOILING_POINT/@UNITS" -- an atribute node XMLNodeInfo units -- {kind:"ATTRIBUTE_NODE", name:"UNITS"} XMLDisplayXML units -- " UNITS=\"Kelvin\"" XMLGetText units -- "Kelvin"

XMLDisplayXML v : return an XML object as a string.

XMLDisplayXML XMLRef or list of XMLRef : the XML object to display

[formatting boolean] : add returns and tabs for legibility. Default: true.

[xml declaration boolean] : require the xml declaration (relevant only if the direct parameter is a document). Default: true

[html4 boolean] : require compatible HTML4 output (relevant only if the direct parameter is a document). Default: false

→ string or list of string

XMLSetXML v : set the contents of an element or text node.

XMLSetXML XMLRef : an XML object.

to string : the text description for the new contents of the node (or for the new nodes if the direct parameter is a text node).

Example
set doc2 to XMLOpen from string "<div/>" set r to XMLRoot doc2 XMLSetText r to "Hello<br/>World" -- create one text node XMLDisplayXML r -- "<div>Hello&lt;br/&gt;World</div>" XMLSetXML r to "Hello<br/>World" -- create 2 text nodes and a "br" empty node XMLDisplayXML r -- "<div>Hello<br/>World</div>" XMLClose doc2

XMLGetText v : return the textual contents of a node.

XMLGetText XMLRef : an XML object containing a simple text node.

→ string

Example
Please make sure you have run the XMLOpen example first.
Let us first select a node with a single text node:
set {h} to (XMLXPath the_root with "ATOM[SYMBOL='H']/NAME") XMLGetText h -- "Hydrogen"
But with a more complex element, the result is the concatenation of all the text nodes:
set {h} to (XMLXPath the_root with "ATOM[SYMBOL='H']") XMLGetText h -- "Hydrogen1.007941120.2813.81H 0.0899 1s1 0.322.12.08 0.4581 14.1 0.0585 13.598 14.304 0.1815 "

XMLSetText v : set the textual contents of an element or text node.

XMLSetText XMLRef : if it is an element node, its content will be replaced by a unique text node

to string : copied as is ; in particular the entities are not interpreted.

Example
Please make sure you have run the XMLOpen example first.
Let us first select a node with a single text node:
set {h} to (XMLXPath the_root with "ATOM[SYMBOL='H']/NAME") XMLSetText h to "Hydrogenium" XMLGetText h -- "Hydrogenium"
But with a more complex element, the result is a single the text node; other children are deleted:
set {h} to (XMLXPath the_root with "ATOM[SYMBOL='H']") XMLSetText h to "Hydrogenium" XMLDisplayXML h -- "<ATOM STATE="GAS">Hydrogenium</ATOM>"

XMLAppendText v : append text to an element or text node.

XMLAppendText string : the string to append

at XMLRef : if necessary, a new text node wil be appended at the end of this node

Example
Please make sure you have run the XMLOpen example first.
set doc to XMLOpen from string "<div>Hello<br/>World</div>" set root to XMLRoot doc XMLDisplayXML root -- "<div>Hello<br/>World</div>" XMLAppendText " !" at root -- append the text to the last text node XMLDisplayXML root -- "<div>Hello<br/>World !</div>" XMLSetXML root to "Hello<br/>" -- create 1 text node and a "br" empty node XMLDisplayXML root -- "<div>Hello<br/></div>" XMLAppendText " !" at root -- create a new text node XMLDisplayXML root -- "<div>Hello<br/> !</div>"

XMLGetNameSpace v : return the namespace of a given element.

XMLGetNameSpace XMLRef : an XML element or attribute

namespace

XMLGetNameSpaces v : search all the namespaces in the scope of a given node.

XMLGetNameSpaces XMLRef : an XML node

→ list of namespace

XMLGetNameSpaceFromPrefix v : return the URL associated to a given prefix in the scope of a given node.

XMLGetNameSpaceFromPrefix XMLRef : an XML node

prefix text

→ text

XMLAddNamespace v : add a namespace declaration in an XML element.

XMLAddNamespace namespace

at XMLRef : an XML element

XMLFind v : select a child (or children) satisfying a simple criterion: the name of the XML element and/or the key and value of an attribute. XMLFind is a poor man's XMLXPath suitable (and fast) for simple queries and is not aware of the namespace specifiers

XMLFind XMLRef : the parent where the search occurs

[name string] : the name of the element

[key string] : the key of the attribute

[value string] : the value of the attribute

[all occurrences boolean] : returns a list of all occurrences. Default : false

XMLRef : or a list of XMLRefs with all occurrences

XMLFindText v : find a string in text nodes

XMLFindText string : the string to find

in XMLRef or list of XMLRef : the tree node where the search begins

[all occurrences boolean] : returns a list of all occurrences. Default: false

XMLRef : the text node found or a list if "all occurrences" is true. Use XMLParent to retrieve the element node.

XMLRegexp v : find text nodes conforming (or not conforming) to a given regular expression pattern

XMLRegexp string : the pattern

in XMLRef or list of XMLRef : the tree node where the search begins

[all occurrences boolean] : returns a list of all occurrences. Default: false

[conforming boolean] : if false returns the text nodes not conforming to the pattern. Default: true

XMLRef : the text node found or a list if "all occurrences" is true. Use XMLParent to retrieve the element node.

Example
Please make sure you have run the XMLOpen example first.
XMLGetText (XMLRegexp "B.*ium" in the_doc with all occurrences) -- {"Barium", "Beryllium", "Bohrium", "Berkelium"}

XMLBase v : get the base URL of a node.

XMLBase XMLRef : a node

[as type] : string, alias...

→ string : the effective base of the node, not the xml:base attribute.

XMLSetBase v : set the xml:base attribute of a node.

XMLSetBase XMLRef : a node

to string : or alias. Passing "" remove the xml:base attribute of the node

XMLAbsoluteURL v : resolve a relative URL using a node base (or an absolute URL).

XMLAbsoluteURL string : a (possibly) relative URL

from XMLRef : the node providing the base URL (or an absolute URL)

[as type] : string, alias...

→ string : an absolute URL

XMLRelativeURL v : translate an URL into the most suitable relative URL with respect to a given base.

XMLRelativeURL string or alias : an absolute URL

from XMLRef : the node providing the base URL (or an absolute URL)

→ string : a relative or absolute URL

XMLError v : the full text of the last error occurred (debugging)

XMLError

→ string

XML XPath, XSLT
An AppleScript implementation of XPath, and XSLT.

XPathRef n : A record defining a list of XMLRef by providing a node and an xpath string. Such a record may be used instead of a list of XMLRef.

properties

XMLRef XMLRef : the starting node

xpath pattern string : an xpath expression defining a node set.

namespace list of namespace : (optional) definition of the prefixes used in the xpath expression.

xpath variables list of any or record : (optional) an even list {varname1,value1,…}. varname1 is a string and value1 should be a string, a number, a boolean or a (list of ) CFRef . The XPath expression may refer to such a variable by $varname1. Alternatively, xpath variables may be a record {var1:value1,...}


XMLXPath v : select an object (or objects) satisfying an xpath request.

XMLXPath XMLRef : the starting point for the path

with string : the xpath expression

[namespace namespace or list of namespace] : {nsprefix:theName, nsurl:thehref} or a list of records. Or use XMLSetContext.

[xpath variables list] : an even list {varname1,value1,…}. The XPath expression may refer to such a variable by $varname1. Alternatively, xpath variables may be a record {var1:value1,...}

→ list of XMLRef : the selected objects

XMLXpath conforms to XPath1.0 and adds :
  • the XPath2.0 functions compare, upper-case, lower-case, ends-with and base-uri in the namespace "http://www.w3.org/2005/xpath-functions"
  • the folowing exslt extensions:
    • align, concat, decode-uri, encode-uri, padding and replace in the namespace "http://exslt.org/strings"
    • abs, acos, asin, atan, constant, cos, exp, highest, log, lowest, max, min, power, random, sin, sqrt and tan in the namespace "http://exslt.org/math"
    • add, add-duration, date, date-time, day-abbreviation, day-in-month, day-in-week, day-in-year, day-name, day-of-week-in-month, difference, duration, hour-in-day, leap-year, minute-in-hour, month-abbreviation, month-in-year, month-name, second-in-minute, seconds, sum, time, week-in-month, week-in-year and year in the namespace "http://exslt.org/dates-and-times"
    • difference, distinct, has-same-node, intersection, leading and trailing in the namespace "http://exslt.org/sets"
  • parent-uri and relative-uri in the namespace "http://www.satimage-software.com/xpath-functions". The function parent-uri(uri) returns the "parent" of uri and the function relative-uri(uri1,uri2) returns uri1 as a relative url with respect to uri2 (uri, uri1, uri2 must be of type string or nodeset).
  • any AppleScript handler thru the namespace "http://www.satimage-software.com/xpath-functions-applescript" (see the example below).
Example
Please make sure you have run the XMLOpen example first.
Here we suppose we would like to retrieve the atomic weight of Oxygen.
set {the_weight} to XMLXpath the_root with "ATOM[NAME='Oxygen']/ATOMIC_WEIGHT" XMLGetText the_weight -- "15.9994"
Or shorter
XMLXpath the_root with "string(ATOM[NAME='Oxygen']/ATOMIC_WEIGHT)" -- "15.9994"
Or using xpath variables (very useful to avoid problems with characters like "'<>&)
XMLXPath the_root with "string(ATOM[NAME=$s]/ATOMIC_WEIGHT)" xpath variables {s:"Oxygen"} -- "15.9994"
Another example with a test on an attribute:
XMLGetText (XMLXPath the_root with "*[@STATE='GAS']/NAME") -- {"Argon", "Hydrogen", "Helium", "Xenon"}
Suppose you discover an unknown atom, and you name it Smilium.The most urgent thing would be to find a symbol for it.
XMLXpath the_root with "ATOM[SYMBOL='Sm']" -- {«data XMLR000000010718F430»}
The symbol "Sm" is already in use, let us try "Sl":
XMLXpath the_root with "ATOM[SYMBOL='Sl']" -- {}
The symbol "Sl" is available. We now find the element just before Smilium in alphabetic order:
set x to item -1 of (XMLXPath the_root with "ATOM[compare(NAME,'Smilium')<0]") XMLGetText (XMLFind x name "NAME") -- "Samarium"
And create the Smilium:
set the_data to "<ATOM> <NAME>Smilium</NAME> <SYMBOL>Sl</SYMBOL></ATOM>" set the_smilium to XMLNewSibling the_data after x -- «data XMLR00000001095D9720»
Now we can enter more information about Smilium:
XMLNewChild "<ATOMIC_NUMBER>144</ATOMIC_NUMBER>" at the_smilium XMLNewChild "<ATOMIC_WEIGHT>321</ATOMIC_WEIGHT>" at the_smilium XMLNewChild "<ATOMIC_RADIUS>3.14</ATOMIC_RADIUS>" at the_smilium
... and finally display our element:
XMLDisplayXML the_smilium -- "<ATOM> <NAME>Smilium</NAME> <SYMBOL>Sl</SYMBOL> <ATOMIC_NUMBER>144</ATOMIC_NUMBER> <ATOMIC_WEIGHT>321</ATOMIC_WEIGHT> <ATOMIC_RADIUS>3.14</ATOMIC_RADIUS> </ATOM>"
Assuming that the following handler exists in your AppleScript context:
on myregexp(pattern, s) try find text pattern in s with regexp and string result return true end return false end myregexp
You can now use regexp expressions in the following way:
XMLSetContext the_doc namespace {nsprefix:"AS", nsurl:"http://www.satimage-software.com/xpath-functions-applescript"} set x to XMLXPath the_root with "ATOM/NAME[AS:myregexp('Se.*um', string(.))]" XMLDisplayXML x -- {"<NAME>Selenium</NAME>", "<NAME>Seaborgium</NAME>"}

XMLGetByID v : retrieve an element by ID. i.e. this element has an attribute xml:id or an attribute declared as an ID is the DTD of the document. In this later case, the document must have been opened with validate. XMLGetByID x xmlid "aa" is a shortcut for XMLPath x with "id('aa')".

XMLGetByID XMLRef : a valid XMLRef

xmlid string : id of the element

XMLRef : or a list if the xmlid parameter is a list

XMLSetContext v : set the default context for future xpath requests.

XMLSetContext XMLRef : an XML document

[namespace list of namespace] : a list of {nsprefix:theName, nsurl:thehref}. If nsurl is "" the pair is removed. Further calls to XMLXPath may omit the "namespace" parameter

[xpath variables list of string or record] : a list {varname1 ,value1,…}. Further XMLXPath expressions may refer to such a variable by $varname1. If value1 is "missing value" the variable "varname1" becomes undefined. Alternatively, "xpath variables" may be a record {var1:value1,...}

Example
Here we deal with "allelementsns.xml", a clone of "allelements.xml" with a default namespace in the root element. Suppose we would like to retrieve the atomic weight of Oxygen.
set the_URLns to "http://www.satimage.fr/software/samples/allelementsns.xml" set the_docns to XMLOpen the_URLns --  «data XMLR0000000200000000» set the_rootns to XMLRoot the_docns set {the_atom} to XMLXpath the_rootns with "ATOM[NAME='Oxygen']" -- {}
Indeed the ATOM element belongs to the namespace "http://www.satimage.fr/software/samples/periodictable"
XMLXpath the_rootns with "pt:ATOM[pt:NAME='Oxygen']" namespace {nsprefix:"pt", nsurl:"http://www.satimage.fr/software/samples/periodictable"} -- {«data XMLR0000001208209A80»}
XMLSetContext may simplify the scripting
XMLSetContext the_docns namespace {nsprefix:"pt", nsurl:"http://www.satimage.fr/software/samples/periodictable"} XMLXpath the_rootns with "pt:ATOM[pt:NAME='Oxygen']" -- {«data XMLR0000001208209A80»}

XMLGetNodePath v : return a valid xpath for an object.

XMLGetNodePath XMLRef : the node

from XMLRef : starting point for the path

→ string : the path

Example
Please make sure you have run the XMLOpen example first.
For debugging purposes, the returned XPath expression is exactly the path to the object
set {the_weight} to XMLXpath the_root with "ATOM[NAME='Oxygen']/ATOMIC_WEIGHT" XMLGetNodePath the_weight -- "/PERIODIC_TABLE/ATOM[67]/ATOMIC_WEIGHT"

XMLXPointer v : resolve a reference to a XML fragment. "XMLXPointer" can open the targeted XML file only if the "read permission" parameter is not false.

XMLXPointer string : the link: "[absoluteOrRelativeUrl]#anID" (the file must have been opened with "XMLOpen" using the validate option) or "[absoluteOrRelativeUrl]#xpointer(xpathExpression)"

[baseURL string] : the base URL in order to resolve a relative URL. Alternatively may be provided by the "from" parameter

[from XMLRef] : for non-local links and relative URLs, define the base URL for the link. For local links (starting with #) and relative xpathExpression: the element where the search begins

[in pool string] : the name of the group where the open document can be found. By default XMLXPointer use the pool of the "from" parameter or the current pool

[namespace namespace or list of namespace] : {nsprefix:theName, nsurl:thehref} or a list of records to resolve the xpath expression

[read permission boolean] : default true. Open a new document if necessary. If true (or missing) the following parameters may be useful.

[keep blanks boolean] : default false

[substitute entities boolean] : default false

[validate boolean] : validate with respect to its dtd; default false

[failure level integer] : a number between 1 and 3. 3: fail only on fatal errors, 2: fail on xml recoverable errors, 1: fail on warnings. The default is provided by the XMLErrorLevel command.

→ list of XMLRef : the objects linked

Example
Please make sure you have run the XMLOpen example first.
An example with a local pointer
set the_pointer to "#xpointer(/PERIODIC_TABLE/ATOM[NAME='Oxygen'])" set {the_atom} to XMLXPointer the_pointer from the_doc -- {«data XMLR0000001208209A80»}
An example with an absolute URL
set the_pointer to "http://www.satimage.fr/software/samples/allelements.xml#xpointer(/PERIODIC_TABLE/ATOM[NAME='Oxygen'])" set {the_atom} to XMLXPointer the_pointer -- {«data XMLR0000001208209A80»}
An example with a relative URL and explicit namespace.
This kind of reference frequently occurs when you refer to an xml element of another document (usually in a href attribute).
This example uses the pool parameter to allocate the (possible) new document in a new pool which can be deleted after use.
set the_URLns to "allelementsns.xml" set the_pointer to "xpointer(/pt:PERIODIC_TABLE/pt:ATOM[pt:NAME='Oxygen']/pt:ATOMIC_WEIGHT)" set ns to "http://www.satimage.fr/software/samples/periodictable" set fullURL to (escapeURL the_URLns) & "#" & the_pointer set {the_weight} to XMLXPointer fullURL from the_atom namespace {nsprefix:"pt", nsurl:ns} in pool "trash" -- or equivalent set fullURL to (escapeURL the_URLns) & "#xmlns(pt=" & ns & ")" & the_pointer set {the_weight} to XMLXPointer fullURL from the_atom in pool "trash" XMLGetText the_weight -- "15.9994" DeletePool "trash"

XMLTransform v : transform an XML document (or a node) according to a given XSLT stylesheet.

XMLTransform XMLRef : the XML document to transform (or a node)

[with string] : (or an XMLRef) the stylesheet. If this parameter is missing, XMLTransform will attempt to find in the direct parameter a processing instruction providing a stylesheet: <?xml-stylesheet type='…' href='... '?>. The type attribute must be 'text/xsl' or 'application/xml' or 'text/xml'

[xsl params record or list of string] : a list {varname1 ,value1,…}. Set the values of the global xsl:param elements of the stylesheet or create new xsl global variables. The values are strings interpreted as xpath expressions. Thus a raw string parameter must be quoted like in {s:"'hello'"}. As there is no escaping in xsl, raw string parameters can more simply be provided with the "xsl string params" parameter. Alternatively, "xsl params" may be a record {var1 ,value1,…}

[xsl string params list] : like xsl params, but the string values are automatically quoted

[in file specification] : a file path for the result

[as type] : XMLRef or string or CFRef. Default: XMLRef

[in pool string] : the name of the group where the new document must be created. Default: the current pool. At launch the current pool is "".

XMLRef, string, or CFRef : or no result if the "in" parameter is present. A reference to the newly created document (resp. string) if the "as" parameter is XMLRef (resp. string) or a property list if the "as" parameter is CFRef (and the resulting data are actually valid XML data for a property list)

XMLTransform conforms to XSLT-1.0. Most of the exslt extensions are available. Namely the whole common, math, sets and strings modules, the functions evaluate() and map() of the dynamic module, the date module except parse-date() and format-date(), the functions module except the element script.
The saxon extensions expression(), eval(), evaluate() and line-number() are also available in the namespace "http://icl.com/saxon".
Example
In Smile, if you have opened a document containing a processing instruction providing a stylesheet: <?xml-stylesheet type='application/xml' href='... '?>, you can display in a web window the result of its transformation by hitting the enter key with the command key pressed in its Unicode window.
Extract the 20 first ATOM , sort the first elements of ATOM for better display, add an ID attribute to ATOM elements and a css stylesheet
set the_doc to XMLOpen "http://www.satimage.fr/software/samples/allelements.xml" set f to ((path to desktop from user domain) as string) & "firstelements.xml" XMLTransform the_doc with "http://www.satimage.fr/software/samples/extract.xsl" in file f open file f
In Smile, you can now display these elements by hitting the enter key with the option (alt) key pressed in the "firstelements.xml" window.
The stylesheet can be opened with the Open URL menu or by executing: open "http://www.satimage.fr/software/samples/extract.xsl".
Notice that "firstelements.xml" now declares a dtd. In Smile, you can check the validity of the document by hitting the enter key with the command key pressed in the "firstelements.xml" window.
Now ATOM nodes can be retrieved with their symbol like in:
set theurl to "file://localhost" & POSIX path of file f set {hydrogen} to XMLXPointer (theurl & "#H") with validate
or by rank with the atomic number:
set {hydrogen} to XMLXPointer (theurl & "#xpointer(PERIODIC_TABLE/ATOM[1])") -- or with the abbreviated syntax: set {hydrogen} to XMLXPointer (theurl & "#/1/2") -- element 1 of PERIODIC_TABLE is HEADER !

XMLNewIndex v : create an index for XMLLookup. XMLNewIndex returns an error if its evaluation results in an empty index

XMLNewIndex string : the name of the index

match string : an XPath expression for the selected items

use string : an XPath expression for the identifier of the items in the index

at XMLRef : the document or the node to apply the match

[namespace namespace or list of namespace] : {nsprefix:theName, nsurl:thehref} or a list of records. Or use XMLSetContext.

[xpath variables list] : a list {varname1 ,value1,…}. The XPath expression may refer to such a variable by $varname1. Alternatively, "xpath variables" may be a record {var1 :value1,…}

The goal is to optimize XPath requests by evaluating once and for all an xpath request and putting the results in an index.
The references of the index are the nodes matched by the "match" pattern. The entries are the string value of the "use" pattern apllied to each reference of the index. An index works as an "xsl:key" element in an xslt stylesheet.

Be aware that if after calling XMLNewIndex you add nodes to the document, the index may be no longer correct.
In this case rebuild the index with XMLNewIndex or delete it by passing XMLNewIndex an empty match: "".

XMLLookup v : retrieve a list of nodes associated to an index and a key

XMLLookup string : the entry to find in the index

using string : the name of the index. XMLLookup returns an error if there is no index with the given name

at XMLRef : the document (or a node of the document) holding the index

→ list of XMLRef : an empty list if there is no entry in the index corresponding to the direct parameter

Example
A basic example:
set doc to XMLOpen from string "<a><b name='x'/><b name='y'/></a>" XMLNewIndex "test key" match "//b" use "@name" at doc set {x} to XMLLookup "x" using "test key" at doc XMLDisplayXML x -- "<b name=\"x\"/>"
The following example opens a plist as an XML document. Then build an index to map the "keys" of the plist dictionary onto their contents.
set doc to XMLOpen "/Applications/Safari.app/Contents/Info.plist" XMLNewIndex "dict" match "/plist/dict/*[name()!='key']" use "preceding-sibling::key[1]" at doc set {x} to XMLLookup "CFBundleIdentifier" using "dict" at doc XMLGetText x -- "com.apple.Safari"

XMLEntries v : return the list of the keys in an index created with XMLNewIndex

XMLEntries string : the name of the index

at XMLRef : the document containing the index

→ list of string

XML Documents
Commands to handle XML documents and global settings.

XMLURL v : get the path to the XML document.

XMLURL XMLRef : the document

[as type] : string, alias...

[parent boolean] : return the parent folder. Default: false

file specification

XMLSetURL v

XMLSetURL XMLRef : a node

to alias

XMLDocument v : get the opened XML document from the file URL.

XMLDocument file specification

[in pool string] : Default: the current pool. At launch the current pool is "".

XMLRef : the document

XMLCloneDocument v : create a clone of the direct parameter (except for the url)

XMLCloneDocument XMLRef : a document

[in pool string] : Default: the current pool.

XMLRef : the newly created document

XMLXInclude v : XInclude processing

XMLXInclude XMLRef : a document

→ integer : the number of includes processed

Example
set doc to XMLOpen from string "<a> <include xmlns='http://www.w3.org/2001/XInclude' href='http://www.satimage.fr/software/samples/allelements.xml' xpointer=\"xpointer(/PERIODIC_TABLE/ATOM[NAME='Argon'])\"/> </a>" XMLXInclude doc XMLDisplayXML doc -- "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <a> <ATOM STATE=\"GAS\" xml:base=\"http://www.satimage.fr/software/samples/allelements.xml\"> <NAME>Argon</NAME> <ATOMIC_WEIGHT>39.948</ATOMIC_WEIGHT> <ATOMIC_NUMBER>18</ATOMIC_NUMBER> ... <THERMAL_CONDUCTIVITY UNITS=\"Watts/meter/degree Kelvin\"><!-- At 300K --> 0.0177 </THERMAL_CONDUCTIVITY> </ATOM> </a>"

XMLGetEncoding v : return the encoding of the XML document.

XMLGetEncoding XMLRef : the document

→ string

XMLSetEncoding v : set the encoding of the XML document. The encoding will be used by XMLSave.

XMLSetEncoding XMLRef : the document

to string : "UTF-8", "UTF-16", "ISO-8859-1"... "ISO-8859-9", "ISO-2022-JP", "SHIFT_JIS" or "EUC-JP".

Example
An example with a local pointer
set doc2 to XMLOpen from string "<a>Français</a>" XMLGetEncoding doc2 -- "" XMLClose doc2
Default is ASCII, and the file will be saved as <?xml version="1.0"?> <a>Fran&#xE7;ais</a>.
XMLSetEncoding doc to "UTF-8"
Now the file will be saved as <?xml version="1.0" encoding="UTF-8"?> <a>Français</a>.
You may also proceed as in
set doc2 to XMLOpen from string "<?xml version='1.0' encoding='UTF-8'?><a>Français</a>" XMLGetEncoding doc2 -- "UTF-8" XMLClose doc2

XMLSetIndentString v : set the default indent string. The indent string is used by XMLSave and XMLDisplayXML.

XMLSetIndentString string : a string containing spaces or tabs

→ string : the previous indent string

XMLSave v : save an XML document.

XMLSave XMLRef : the XML object to save

[in file specification] : the file path

[formatting boolean] : add returns and tabs for legibility. Default: true.

[html4 boolean] : require compatible HTML4 output. Default: false

[xml declaration boolean] : require the xml declaration. Default: true

[encoding string]

Example
Please make sure you have run the XMLOpen example first.
XMLSave doc in file ("" & (path to desktop) & "allelements.xml")

XMLErrorLevel v

XMLErrorLevel [integer] : the requested error level. 1 fails on warnings. 2 fails on XML recoverable errors. 3 fails on fatal errors. Set to 2 at the beginning

→ integer : the previous setting

XMLExtendedChar v : toggle between the 1.0 and the 1.1 XML recommendation for character definition.

XMLExtendedChar [boolean] : if true the extended character set (including all positive characters smaller than 32) of the 1.1 XML recommendation is in use.

→ boolean : the previous setting

XMLListDocuments v

XMLListDocuments [string] : the pool. Default: the current pool.

[as anything] : XMLListDocuments as string returns the url of the xmldocuments instead of their references

→ list of XMLRef : the opened xmldocuments

XMLSetDocID v : set an identifier to an existing document. Avoid many problems with the AppleScript's global variables

XMLSetDocID XMLRef : the XML document

to string

XMLGetDocByID v : retrieve a document by identifier

XMLGetDocByID string : the identifier

[in pool string] : Default: the current pool.

XMLRef

XMLc14n v : Canonicalization of an XML document

XMLc14n XMLRef : the XML document or a list of XMLRef or an XPathRef

[in alias] : the destination file

[comments boolean] : include comments. Default true

[exclusive boolean] : exclusive canonicalization. Default false

[inclusive prefixes list of string] : list of inclusive prefixes (relevant if exclusive is true).

[digest string] : "SHA1" or "MD5". If this parameter is provided, returns a digest using the specified algorithm. The result is base64-encoded if the "in" parameter is not provided.

→ string : if the "in" parameter is not provided.

If the direct parameter is an XMLRef, XMLc14n processes the entire document containing that reference.
If the direct parameter is a list, XMLc14n processes the subset according to xml-c14n11.
Consequently, in order to process the element myElem as a whole, you may use the XPathRef: {XMLRef:myElem, xpath pattern:"descendant-or-self::node()|.//@*"} as direct parameter.

XMLSetExtras v : associate any AppleScript contents with a document. This utility command is at the scripter's convenience and has no effect on the XML part of the document

XMLSetExtras XMLRef : the XML document

to anything

XMLGetExtras v : retrieve the extras of a document

XMLGetExtras XMLRef : the XML document

anything

XML Validation
Validation of documents and DTDs

XMLValidate v : validate a document with respect to its DTD or a given dtd.

XMLValidate XMLRef : the document or the element to validate

[against alias] : a dtd

[verbose boolean] : default false

[failure level integer] : a number between 1 and 2. 2: fail on recoverable xml errors, 1: fail on warnings. Default: 2

Example
In Smile, you can check the syntax of a document by hitting the enter key in its Unicode window, and you can check the validity of a document by hitting the enter key with the command key pressed in its Unicode window.

XMLSchema v : validate a schema or a document with respect to a schema

XMLSchema [XMLRef] : the document. If this parameter is missing, XMLSchema attempts to validate the schema provided in the "with respect to" parameter

with respect to alias : the url of the schema. May be also provided as text or XMLRef.

XMLRelaxNG v : validate a relaxNG schema or a document with respect to a relaxNG schema

XMLRelaxNG [XMLRef] : the document. If this parameter is missing, XMLRelaxNG attempts to validate the relaxNG schema provided in the "with respect to" parameter

with respect to alias : the url of the relaxNG schema. May be also provided as text or XMLRef.

XMLCheckDTD v : check the syntax of a given DTD.

XMLCheckDTD anything : the DTD's URL or alias, or the text of the DTD

Satimage PropertyList Additions
An AppleScript interface to property lists.

Presentation

Property lists are widely used in MacOSX. They are stored as files with the "plist" extension.

Property lists (plists in short) can contain simple types (numbers, strings, dates, booleans and raw data) and collections: dictionaries and arrays:

  • dictionaries contain elements that you reference by key (string).
  • arrays contain ordered elements that you reference by index.

This suite lets you edit property lists.

Creating a plist

The CRef type is used to refer to any element in a plist or to the plist itself.
Plists are created with PlistNew:
set myPlist to PlistNew {"a", "b", "c"}
or with PlistOpen:
set myPlist to PlistNew someFile.

Browsing a plist

Walking through a plist is quite simple with the PlistChild command:
  • use the parameter key to access a dictionary's child,
  • use the parameter index to access an array's item.
Retrieve the contents of an element with PlistGet.

Changing a plist

Modifying a plist may be more difficult since some elements are not changeable and thus can only be replaced inside their container. The modifiable elements are dictionary, arrays and strings.

Thus, while
PlistGet someReference
always works,
PlistSet someReference to something
may fail.
And you must use
PlistSet someDict key aKey to something
or
PlistSet someArray index i to something
except in some rare cases where either you need to keep some references intact (see warnings) or you set the root itself.
Examples:
set p to PlistNew {"a", "b", 1} set pp to PlistChild p index 2 PlistGet pp -- returns "b" PlistSet pp to "d" -- ok PlistGet pp -- returns "d" PlistSet pp to {} -- error: pp is not an array PlistSet p index 2 to {} -- ok, but pp is no more valid set pp to PlistChild p index 3 PlistGet pp -- returns 1 PlistGet p index 3-- returns 1 PlistSet pp to 2 -- error: pp is not mutable PlistSet p index 3 to 2 -- ok, but pp is no more valid PlistGet p -- returns {"a", {}, 2}

Saving and closing a plist

When you are done with a plist you can save it with PlistSave and close it with PlistClose to release the memory.

Warnings

This suite handles real pointers for the sake of speed. Thus you cannot reuse references to an object that has been replaced or removed:
set pp to PlistChild p key "name" PlistSet p key "name" to "a" -- or PlistRemoveChild p key "name" PlistGet pp --crashes the current application
while:
set pp to PlistChild p key "name" PlistSet pp to "a" -- here we assume that pp already refers to a string PlistGet pp --returns "a"
But referring to an element of a plist closed with PlistClose does not crash - it will just throw an error.
set pp to PlistChild p key "name" PlistClose p try PlistGet pp --error can't get «data...» on error log "Damnation, the plist does not exist!" end

CFRef n : an opaque reference to a property list element. Initial CFRefs must be created with PlistNew or PlistOpen.


PlistNew v : create a new PropertyList with the contents of the direct parameter. Must be balanced with a PlistClose at the end of the job.

PlistNew [anything] : any AppleScript type, usually, a record or a list. Default: an empty record.

[typed boolean] : if false, write as raw base64 data. Default: true. Use false when storing complex types (such as alias) to allow other software to use the p-list (for instance, when changing a Preference p-list). If false, specify the type with 'as' when using PlistGet.

[in pool string] : the name of the group where the plist document is created. Default: the current pool. At launch the current pool is "".

CFRef : a reference to the property list, required by the other PropertyList commands

PlistOpen v : open a property list file and parse it. Must be balanced with a PlistClose at the end of the job.

PlistOpen alias : or a string containing xml data

[in pool string] : the name of the group where the plist document is created. Default: the current pool. At launch the current pool is "".

CFRef : a reference to the parsed property list, required by the other PropertyList commands

PlistClose v : release memory, associated CFRefs are no more valid.

PlistClose CFRef

PlistSave v : save a Plist.

PlistSave CFRef : the Plist to save

[in file specification] : the file path

[binary boolean] : default: false

PlistBinaryFormat v : is the plist in a binary file format?

PlistBinaryFormat CFRef : the Plist

→ boolean

PlistCount v : count children in the given CFRef.

PlistCount CFRef or list of CFRef : an CFRef

→ integer or list of integer : the number of children

PlistChild v : provide access to children of a given CFRef. Similar to PlistGet, but return a CFRef. Provide either a "index", or a "key", or a "using" parameter. Only the direct parameter or "key", or "index" may be a list. If there is no specifier, PlistChild returns all the children.

PlistChild CFRef : the parent: an array or a dictionary

[index integer] : 1..PlistCount, index of the requested child

[key string] : relevant only if the direct parameter is a dictionary

[using string] : a selecting path. A valid path contains sequences of keys (for dictionaries) separated with slashes, and indices (for arrays) inside brackets. Example: "key1/key2[4]/key3[2]"

CFRef : the child or a list if one parameter is a list

PlistType v : return the type of a CFRef (the tag's name).

PlistType CFRef : the CFobject to display

→ string

PlistGet v : Similar to PlistChild, but return actual contents. Can be used with direct parameter alone to retrieve the contents of a CFRef. Only one of the parameters "key", "index" or "using" can be specified. Only the direct parameter or "key", or "index" may be a list.

PlistGet CFRef : the CFRef to display

[as string] : for base64 data stored 'without typed', the AppleScript type.

[index integer] : 1..PlistCount, index of the requested child

[key string]

[using string] : a path. See the PlistChild command.

anything : or a list if one parameter is a list

PlistGetXML v : return the contents of a CFRef as xml data.

PlistGetXML CFRef : the CFRef to display

→ string

PlistGetKeys v : return the list of keys in a dictionary.

PlistGetKeys CFRef : the dictionary

→ list of string

PlistSet v : equivalent to PlistNewChild on dictionaries. Use PlistSet to modify an existing element in an array.

PlistSet CFRef : the parent: an array or a dictionary

[index integer] : 1..PlistCount, index of the requested child

[key string]

[using string] : a path. See the PlistChild command.

to anything : any AppleScript content or a CFRef. Be aware of self-references when you use CFRef

[typed boolean] : irrelevant with CFRefs. Default: true. If false, write as raw base64 data. Use false to store complex types (eg alias) for use by other software (eg, when editing a Preference file). If false, specify the type with 'as' when using PlistGet.

PlistNewChild v : create a new child in a given object (array or dictionary). You must use PlistSet to modify an existing element of an array.

PlistNewChild [anything] : any AppleScript content or a CFRef. Be aware of self-references when you use CFRef. Default: an empty record.

at CFRef : the container: an array or a dictionary

[index integer] : 1..(PlistCount+1), index of the new child

[key string] : requested if CFRef is a dictionary

[using string] : a path. See the PlistChild command.

[typed boolean] : see the PlistSet command.

CFRef : the child

PlistRemoveChild v : delete an object. The reference to this object (or to any object it may contain) is no longer valid. Future use of this reference may crash XMLLib.

PlistRemoveChild CFRef : the container: an array or a dictionary

[index integer] : 1..PlistCount, index of the requested child

[key string or list of string] : the key of the requested child

[using string] : a path. See the PlistChild command.

PlistEqual v : compare the contents of two plist. Return true if equal.

PlistEqual CFRef

to CFRef

→ boolean

PlistExist v : match a value in an array.

PlistExist any : a value

in CFRef : an array

→ list of integer : the available indices (1 based)

PlistMatch v : return a list of dictionaries containing a given key or a given (key, value) pair.

PlistMatch CFRef : an array containing dictionaries

key string : the key to match. For a more complex request, omit this parameter and provide the "using" parameter

[using string] : a selecting path (see PlistChild)

[value string, real, or boolean] : the requested value of the key

→ list of CFRef

PlistURL v : get the path to the plist document.

PlistURL CFRef : the document

[as type]

[parent boolean] : return the parent folder. Default: false

file specification

PlistDocument v : retrieve the already opened plist from the file URL.

PlistDocument file specification

[in pool string] : Default: the current pool. At launch the current pool is "".

CFRef : the plist

PlistListDocuments v : List the opened plist documents

PlistListDocuments [string] : the pool. Default: the current pool

→ list of CFRef : the property lists opened in the specified pool.

PlistAdd v : concatenate arrays or dictionaries. "PlistAdd x after y" (resp. "PlistAdd x before y") works like the Applescript statement "set y to y & x" (resp. "set y to x & y")

PlistAdd CFRef : of the same type as the "after" or "before" parameter. May alternatively be a list or a record

[after CFRef] : the array or the dictionary to modify

[before CFRef] : the array or the dictionary to modify

PlistToJavaScript v : transform a plist into a JavaScript string syn plisttojson

PlistToJavaScript CFRef

→ string

Example
set p to PlistNew PlistNewChild 3 at p key "any key" PlistNewChild {"a", "list"} at p key "b" PlistToJavaScript p -- "{\"b\":[\"a\", \"list\"], \"any key\":3}" PlistClose p

PlistSetDocID v : set an identifier to an existing plist

PlistSetDocID CFRef : the XML document

to string

PlistGetDocByID v : retrieve a plist by identifier. Avoid many problems with the AppleScript's global variables

PlistGetDocByID string : the identifier

[in pool string] : Default: the current pool.

CFRef

Satimage Pool Additions
Pool management. Optional features that you can use to manage groups of XML documents or PList's, protect their privacy, and dispose of them when suitable.

SetPool v : Set the new default pool. Further "XMLOpen", "XMLListDocuments", "PlistOpen", "PlistNew" and "PlistListDocuments" will occur in this pool

SetPool string : name of the new default pool

→ string : the previous default pool.

DeletePool v : release all documents in the specified pool.

DeletePool [string] : name of the pool. Default: the default pool.

GetPool v : return the name of the pool containing the document

GetPool anything : an XML document (XMLRef) or a plist document (CFRef)

→ string : the name of the pool.

XNF Additions

Overview

Extensible Numerical File Format, abbreviated XNF, describes a public format for storing numerical data.

An XNF file is a bundle, a special kind of folder which looks like a file (and that Finder names a "package"). Double-clicking an XNF file opens a user interface in Smile to browse, view, extract, and plot the data that it contains. For example, run this script in Smile:

open "http://www.satimage.fr/software/xnf/sample.xnf/"

The bundle contains two items at the root level: a folder named Contents, which stores the data files, and the index.xml XML file, describing the contents of the files. The metadata in the XML file can be handled using the XML commands above. The XNF Additions Suite provides commands to retrieve or write the binary data.

Documentation about the xnf format can be found at http://www.satimage.fr/software/en/sl_xnfv2.html

XNFOpen v : open an xnf bundle or create a new xnf bundle if the file does not exist. Must be balanced with a XMLClose (or DeletePool) at the end of the job. XNFOpen equivalent to XMLOpen but expects a bundle path instead of a file path.

XNFOpen file : usually with a file name ending with".xnf"

[in pool string] : the name of the group where the new document is created. Default: the current pool. At launch the current pool is "".

XMLRef : a reference to the table of contents. Call XMLClose to release the memory

Example
set doc to XNFOpen "http://www.satimage.fr/software/xnf/sample.xnf/" set ds1 to XNFGetDataSet doc xmlid "test1D" set x to XNFGetArray ds1 index 1 set y to XNFGetArray ds1 index 3 QuickCurve(x, y, 0) -- SmileLab only set ds2 to XNFGetDataSet doc xmlid "test2D" set z to XNFGetArray ds2 index 1 as record QuickScalarMap(0, 0, z, 0) -- SmileLab only set ds3 to XNFGetDataSet doc xmlid "test3D" set {nx, ny} to XNFGetDimensions ds3 set z to XNFGetArray ds3 index 1 as record start {1, 1, 4} length {nx, ny, 1} QuickScalarMap(0, 0, z, 0) -- SmileLab only XMLClose doc

XNFSaveBundle v : save the TOC of the XNF bundle (like XMLSave does) and update the modification date of the bundle

XNFSaveBundle XMLRef : an XMLRef returned by XNFOpen

Example
set x to creatematrix "x" ncols 10 nrows 11 set f to POSIX path of (path to desktop) & "sample.xnf" set doc to XNFOpen f set ds to XNFNewDataSet "test" dimensions {10, 11} at doc XNFNewArray x at ds XNFSetScaleRange 1 at ds to {-1, 2 / 9} XNFSetScaleRange 2 at ds to {-1, 2 / 10} XNFSaveBundle doc XMLClose doc open f -- SmileLab only

XNFNewDataSet v : create a new dataset with a given id and given dimensions

XNFNewDataSet string : id of the new dataset

dimensions list of integer : a list {dim1, ... dimn} of integers

[scale list of array of real] : a list of scale

at XMLRef : usually the XML document returned by XNFOpen

XMLRef : the resulting node

The direct parameter must be a valid XML id, i.e. a NCName; roughly speaking, it begins with a letter or an underscore and must contain only letters, digits, underscores, periods and hyphens.

XNFGetDataSet v : retrieve an reference to a dataset by id. XNFGetDataSet thexnf xmlid "aa" is a shortcut for XMLPath thexnf with "id('aa')"

XNFGetDataSet XMLRef : an XMLRef returned by XNFOpen

xmlid string : id of the dataset

XMLRef : a dataset

XNFGetDimensions v : retrieve the dimensions of a dataset.

XNFGetDimensions XMLRef : a dataset

→ any : the list of the dimensions {n1,...}

XNFNewArray v : add an array to a dataset

XNFNewArray array of real

at XMLRef : a dataset returned by XNFNewDataSet or XNFGetDataSet

[as string] : the requested format for the data in the file: "real32" | "real64" | "uint8" | "uint16" | "uint32" | "sint8" | "sint16" | "sint32" | "complex64" | "complex32". Default: "real64"

[big endian boolean] : the requested byteorder. Default: system byte order.

XMLRef : the resulting node

XNFNewFileData v : add an array already stored in a binary file to a dataset

XNFNewFileData any : an alias or a string for an absolute or relative URL

at XMLRef : a node returned by XNFNewDataSet or XNFGetDataSet

[starting at integer] : offset of the data in bytes. Default 0

as string : the format of the data in the file: "real32" | "real64" | "uint8" | "uint16" | "uint32" | "sint8" | "sint16" | "sint32" | "complex64" | "complex32"

[big endian boolean] : is the file encoded as big endian or little endian? Default: system byte order.

XMLRef : the resulting node

XNFGetArray v : retrieve an array or a sub-array. If "start" and "length" are present XNFGetArray returns a sub-array of possibly lower dimensionality if some length is 1.

XNFGetArray XMLRef : a dataset

[index integer] : index of the array inside the dataset. Default 1

[start list of integer] : for each dimension of the dataset, the first element to read. 1-based

[length list of integer] : for each dimension of the dataset, number of elements to read

[part string] : for complex arrays, choose a string in the set "r" (real part), "i" (imaginary part), "m" (modulus) or "p" (phase)

[as type] : pass 'record' to get the result as a record {dimensions:{...}, array of real: ...}

→ array of real : or record

XNFSetScale v : set the scale of the specified axis to a list of real

XNFSetScale integer : index of the axis in the dataset

at XMLRef : a node returned by XNFNewDataSet or XNFGetDataSet

to array of real

[as string] : the requested format for the data in the file: "real32" | "real64" | "uint8" | "uint16" | "uint32" | "sint8" | "sint16" | "sint32". Default: "real64"

[big endian boolean] : the requested byteorder. Default: system byte order.

XNFSetScaleReference v : set the scale of the specified axis to a reference of some 1-D dataset

XNFSetScaleReference integer : index of the axis in the dataset

at XMLRef : a node returned by XNFNewDataSet or XNFGetDataSet

to string : the id of an existing dataset

XNFSetScaleRange v : set the scale of the specified axis to a range

XNFSetScaleRange integer : index of the axis in the dataset

at XMLRef : a node returned by XNFNewDataSet or XNFGetDataSet

to list of real : a list {start,step}

XNFGetScales v : retrieve the scales of dataset. If "start" and "length" are present XNFGetScales returns the scales corresponding to the sub-array returned by XNFGetArray

XNFGetScales XMLRef : a dataset

[start list of integer] : for each dimension of the dataset, the first element to read. 1-based

[length list of integer] : for each dimension of the dataset, number of elements to read

→ list of array of real

XNFGetArray3D v : see Numerics.osax about Array3DRef

XNFGetArray3D XMLRef : a 3-D dataset

[index integer] : index of the array inside the dataset. Default 1

[name string] : the name of the new Array3DRef

[part string] : for complex arrays, choose a string in the set "r" (real part), "i" (imaginary part), "m" (modulus) or "p" (phase)

→ Array3DRef