Last updated at 3:27 am UTC on 7 June 2008
Pastell is an add-on to YAXO that makes navigation of an XML DOM tree much easier.
This text documents how Pastell works. It can't and won't be guarenteed that it will be up-to-date with the actual code; please refer to the test suite and the code in order to be sure how this stuff is supposed to work.
#child: & #/
Let's suppose that we have this XML fragment:
</html>and that we have an XMLElement instance for the 'body' tag. By sending it a #child: message with a symbol as argument, we can get all the tags under body whose name is equal to the argument of the #child: send. Thus,
body child: #pwill return a collection (instance of PastellCollection) whose elements are those XMLElements instance whose name is 'p'. Instead of using #child: (the "full" form), we can also send #/ ("shorthand" form):
body / #por even omit the selector and just send a #p message ("direct" form):
body pThe difference between the full and shorthand forms and the direct form is that the former always return a collection (in case, just an empty one), while the latter raise a MessageNotUnderstood exception if there aren't any tags with that name. This means that
body / #frobnicatewill return an empty PastellCollection, while
body frobnicatewill raise a MessageNotUnderstood exception.
While #child: may return only a part of the child nodes of an XML element, or even none, #children always returns a collection with all the child nodes of the element. So
html childrenwill return a collection whose first element corresponds to the 'head' tag, and whose second element corresponds to the 'body' tag.
#descendant: & #//
Similar to #child:, #descendant: returns all the XMLElement instances that are descendant of the receiver, including if necessary the receiver itself. So, if we have an XMLElement instance for the 'html' tag, we could send ("full" form)
html descendant: #por ("shorthand" form)
html // #pin order to get a collection with the 'p' XMLElement instances.
Will return the parent root of an XML element, that is the node that contains the element. So
body parentwill return an XMLElement for the 'html' tag.
Will return the XMLElement ancestor of the recevier whose name is equal to the symbol sent as an argument of #ancestor. For example,
title ancestor: #htmlwill return the XMLElement for the 'html' tag.
#at: and #@
An XMLElement instance also understands two new attributes-related messages. Both the messages are sent with a symbol as argument, and return the value of the corresponding attribute, or nil if no attribute is found. So,
p at: #idis the "full" form and
p @ #idis the "shorthand" form. Both forms will return the string 'squeak' when sent to the second 'p' element.
An XMLDocument instance understands the #child:, and #descendant: messages, and their shortcut forms. It also understands the "direct" form of #child:. Other messages understood by XMLDocument are #root and #ancestor:.
This message returns the root node of the document. Please note that, in the above sample, the following relationship is true:
(document root) == ((document child: #html) first)
Sending #ancestor: to an XMLDocument instance will always result in a nil return value, regardless of the argument of the message send.
PastellCollection is the specialized collection used by the Pastell extensions. it behaves like a sequenceable collection, but also understands some Pastell messages like #child: and #descendant: .
#child: and #descendant:
Sending #child: or #descendant: to a PastellCollection instance will result in a new PastelCollection whose contents are the result of sending #child:/#descendant: to the single elements of the receiver.
PastellCollection also understands the shorthand form of #child: and :descendant: and the direct form of #child:.
If we have a PastellCollection whose elements have a textual content, that content may be retrieved by sending #contentString to the collection. This will return a collection whose elements are the contents we were looking for.