TinderToolBox is an application designed to manipulate Tinderbox files using custom commands, extended XPaths, and XSL stylesheets.
Please note that this is unsupported experimental software, and not an official product. Neither the author of TinderToolBox (Marc-Antoine Parent) nor the publishers of Tinderbox (Eastgate) can be held responsible for any loss of data due the to misuse of this software.
TinderToolBox should keep evolving, and you should check for updates on my site.
This software requires Python 2.3 or later, libxml2/libxslt from gnome, and the python bindings to those libraries. All those come with Panther and Tiger except for the Python bindings, which I package in the application.
So on Tiger it should just work. On Panther... It seems to work, but the python bindings were recompiled against the Tiger versions of the libraries, so there just may be issues. (Please tell me if there are...)
I used to provide an installer for libxml and the bindings here for Panther, but it is now somewhat obsolete: This file contains (prebound) libxml 2.6.10, libxslt 1.1.7, libexslt 0.8.5 (installed in /usr/local) and the Python extensions. They were compiled on Mac OS X 10.3.4 Panther and will definitely not work on Jaguar or Puma. (and are useless on Tiger... )
See here.
To apply TinderToolBox to a Tinderbox file, simply drag this tinderbox file on the TinderTool application. Active commands will be executed.
An other way to achieve the same result is to type, in a terminal window:
open -a TinderToolBox TinderToolExamples
Important: Though the program now prompts for a save location, the original Tinderbox file will be replaced by the result of the transformation by default. Warning: It is easy to lose your data. No warranty, etc. The original file will be renamed with successively numbered ".bak" suffixes. If you want to study these examples more than once each, I recommend you work on a copy of this file.
You can also drag a XSLT stylesheet with a Tinderbox document. In that case, the XSLT will be applied to the Tinderbox document, and the result saved (with a '.xml' suffix) in a location of your choice.
You will be prompted for the value of each xsl:param element of the XSLT stylesheet.
Caveat: Values given must be a literal, not a XPath expression, even if the xsl:param's default is given by an expression in the 'select' attribute; but if you are prompted and do not change an expression from a 'select', it will still be used. If this sentence makes no sense to you, you probably should not use this feature!
A more advanced CLI interface exists: look in TinderToolBox.app/Contents/Resources/TinderToolBox.py. But it may need some tweaking with python library paths to work well from within the application. For python programmers only.
The TinderToolExamples document demonstrates most of the various Tinderbox file alteration commands that are available using the TinderToolBox application.
Each node in the "Examples (Disabled)" explains and demonstrates a different command.
Examples are disabled initially. To enable an example, drag the example note into the "Enable an example" note.
Here are some general principles about the commands:
A Tinderbox note is a command by virtue of containing a valid command in the xmlCommand attribute.
The commands are enabled or disabled according to the xmlActivation boolean attribute.
The commands are executed recursively in document order. If a command is inactive, or if a command fails, commands under it will not be executed.
All other command arguments are given as XPaths. Note that literals must be 'single-quoted'. There are a number of xpath extension functions to help manipulate Tinderbox constructs, which are associated with the "tb:" prefix in the "http://eastgate.com/Tinderbox" URI, and explained in the "XPath functions" node.
Many commands act on a value, which may be a set of notes, and put the value somewhere. The 'somewhere' is specified by a XPath in the xmlTarget attribute. The value is specified by a XPath in the xmlValue attribute. If appropriate, the xmlValue XPath is computed relative to each target.
In this document, the xmlTarget is set to "." by default, computed relative to the command node, which means that the arguments will be put there.
Many commands act on named objects, esp. creation commands or commands relative to links. The name is specified by a XPath in the xmlName attribute. An empty name allows to specify links irrespective of link type.
In the case of link creation, a link in the reverse direction may be specified by prefixing the link name with "-"
Some commands that create objects allow to specify a "xmlUniqueItemSignature". This XPath will be used relative to the newly created item to compute a signature for this item. If another item exists with the same signature in the target location, the new item will not be added to the document.
The result of the command will be a XPath which evaluates to the set of notes affected; this XPath will be put in the xmlResult attribute in the form of a note-by-id XPath command (which allows it to be re-used as input in another command.)
Other attributes are explained in the corresponding notes.
Look at the examples in the TinderToolExample.tbx file to see how to use the Tinderbox commands.
Here is a list of XPath extensions and XSLT extensions for use in stylesheets.
Of course, this is a by-product of Tinderbox.
Kudos to Mark Bernstein.
Second, this tool depends on the great work of the gnome libxml2 project.
Thanks to Kimbro Stakken (Syncato) for providing inspiration to use XPaths in Python.
For wrapping my script, I used to use Sveinbjorn Thordarson's nifty Platypus tool, but I switched to Bob Ippolito's py2app and aeve. Thanks to both.
When I started to glimpse that xml-rpc was the way to go, I tried horrible ways to pass arguments, until I found this clear scheme description from Mark A. Hershberger.
The python implementation of this scheme is my own.
Oh, and I should never forget the Python team... It is always a joy to use that language.
This work is licensed under a Creative Commons License (Attribution-Share Alike).
Last modified on 03/02/06. Created by Marc-Antoine Parent with Tinderbox 3.6.2.