Types
XMLRef n : an opaque reference to an XML node. Initial XMLRefs must be created with XMLOpen.
| Satimage XML DOM |
| An AppleScript implementation of the DOM. Uses the Libxml2 open source project. |
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).
anything n : any class or reference
dictionary n, pl dictionaries
alias n, pl aliases
file specification n
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
XMLClose v : release memory, associated XMLRefs are no longer valid.
XMLClose XMLRef
XMLRoot v : get the root of the XML document.
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
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.
XMLElement v : equivalent to XMLChild without all nodes.
XMLParent v : return the parent of an object.
XMLNextSibling v : return the next sibling of an object.
XMLNextElement v : equivalent to XMLNextSibling without all nodes.
XMLPrevSibling v : return the previous sibling of an object.
XMLPrevElement v : equivalent to XMLPrevSibling without all nodes.
XMLGetAttribute v : return the contents of an attribute.
XMLSetAttribute v : set (or create) an attribute.
XMLRemoveAttribute v : remove an attribute.
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
[nsclean boolean] : remove the redundant namespaces. Default: true.
→ XMLRef : a reference to the newly created object
Example
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
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
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
[nsclean boolean] : append the implicit namespaces. 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
XMLGetText v : return the textual contents of a node.
XMLGetText XMLRef : an XML object containing a simple text node.
→ string
Example
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
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
XMLGetNameSpace v : return the namespace of a given element.
XMLGetNameSpaces v : search all the namespaces in the scope of a given node.
XMLGetNameSpaceFromPrefix v : return the URL associated to a given prefix in the scope of a given node.
XMLAddNamespace v : add a namespace declaration in 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
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.
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 :
Example
- 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).
ExampleXMLGetByID 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')".
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
XMLGetNodePath v : return a valid xpath for an object.
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
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
The saxon extensions expression(), eval(), evaluate() and line-number() are also available in the namespace "http://icl.com/saxon".
ExampleXMLCompile v : compile an XML document into a XSLT stylesheet for faster transformations. The resulting stylesheet is stored within the document and will be used in future XMLTransform calls
XMLCompile XMLRef : the XML document
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: "".
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
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
XMLIndexDocument v : index or re-index a document. May be useful to speed up XMLTransform or XMLXPath when some expressions involve node ordering.
XMLIndexDocument XMLRef : the XML document to index
XMLStrings v
XMLStrings XMLRef : or a list
→ text
XMLLocalize v
| 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
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)
XMLXInclude v : XInclude processing
XMLXInclude XMLRef : a document
→ integer : the number of includes processed
Example
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
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
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
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
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
[nodelist list of XMLRef] : the set of nodes to output. Default all nodes.
[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.
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
| XML Validation |
| Validation of documents and DTDs |
XMLValidate v : validate a document with respect to its DTD or a given dtd.
XMLSchema v : validate a schema or a document with respect to a schema
XMLRelaxNG v : validate a relaxNG schema or a document with respect to a relaxNG schema
XMLCheckDTD v : check the syntax of a given DTD.
XMLCheckDTD anything : the DTD's URL or alias, or the text of the DTD
XMLDu v : sum up the structure of a node
XMLDu XMLRef
→ string : a textual representation of the tree
XMLGetID v
XMLGetID CFRef : a reference to an element of the XML document
→ integer : the ID of the XML document
XMLFromID v
XMLFromID integer : the ID of the XML document
→ CFRef : a reference to an element of the XML document
| 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.
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.
PlistClose v : release memory, associated CFRefs are no more valid.
PlistClose CFRef
PlistRetain v
PlistRetain 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.
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.
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.
PlistExist v : match a value in an array.
PlistMatch v : return a list of dictionaries containing a given key or a given (key, value) pair.
PlistURL v : get the path to the plist document.
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")
PlistToJavaScript v : transform a plist into a JavaScript string syn plisttojson
PlistToJavaScript CFRef
→ string
Example
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
PlistGetID v
PlistGetID CFRef : a reference to the property list
→ integer : the ID of the property list
PlistFromID v
PlistFromID integer : the ID of the property list
→ CFRef : a reference to the property list
| 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
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
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')"
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