Channel Information Tag Syntax

The channel configuration file constitutes the entry point to a channel. This file contains a single channel_info tag that identifies the key locations of the channel’s resource files. Sherlock uses the attributes of this tag to identify the channel and to load its resources. This file can also act as a checkpoint for determining when the channel files have changed.

Table 1 describes the attributes of the channel_info tag.

For more information on using the channel_info tag, see Configuring Your Channel For Use.

Channels Tags Syntax

The following listing shows the format of the tags in a channel subscription file. The <channels> tag encloses one or more <channel> tags, each of which contains a URL to a channel configuration file. The <localized-strings> tag is optional and used primarily for the localization of the channel name itself.

<channels name="subscription_name" [check_point=<"true" | "false">] >

    [<channel url="channel_url" [version="min_version"]

                maxVersion="max_version"] />]+

    [<localized-strings>

        <localized-string language="2-letter_iso_code"

                key="key_name"

                string="value_for_key" />

    </localized-strings>]

</channels >

The following example shows a modified version of the channel subscription file provided by Apple for Sherlock development channels. In this example, the file includes a localized string for the subscription name. Sherlock displays the localized name for the subscription in the application preferences window. This example also includes two channels that support specific versions of Sherlock.

<channels name="Developer">

    <channel url="channels/xquery.xml" version="1.0" maxVersion="1.0" />

    <channel url="channels/javascript.xml"/>

    <channel url="channels/htmlview.xml" version="1.1" maxVersion="1.1" />

    <localized-strings>

        <localized-string language="en" key="Developer"

                string="Apple Developer Channels" />

    </localized-strings>

</channels >

Script Tag Syntax

The scripts and script tags let you modularize your channel’s source code and include additional web services. The scripts tag either loads a source file from server or encapsulates one or more script tags and makes the corresponding code available to your channel code. The script tag groups functions implemented using the same language into one location.

Table 2 describes the attributes of the script tag.

Table 3 describes the attributes of the scripts tag.

The following example shows the use of the scripts and script tag to declare a function. This declaration could be placed inline with the channel’s triggers or in a separate file.

<scripts>

    <script language="XQuery">

        define function HTMLToText($html)

        {

            $html/source(.)

        }

    </script>

</scripts>

If you were to place the preceding code in a separate file and include it, you would use another scripts tag to include it in the code file containing your triggers. The URL you specify can be either a full path to the server with the file, or a relative path if the file is on the same server.

<scripts src="http://www.mycompany.com/services/webservices.xml"/>

For more information on using the scripts and script tags, see Factoring Your Trigger Code.

Trigger Tag Syntax

Triggers are a combination of XML tags and script code that you include in your channel’s XML Triggers file. A trigger is identified by the <trigger> XML tag. The attributes of this tag identify information about the trigger, such as the path it responds to, the language of the enclosed script code, and any other execution options. The content of the tag is the script code to execute in the language given by the tag attributes. Sherlock triggers support script code written in the JavaScript and XQuery languages. The basic syntax of the trigger tag is as follows:

<trigger language="trigger_language" path="data_store_path"

            [additional_trigger_attributes]>

    [script_code]

</trigger>

The following example shows a trigger definition from the Yellow Pages channel. This trigger receives the value from a text field and stores it in the channel’s preferences file. The path attribute of the trigger tag identifies the data store path to which the trigger responds—a text field with the name CityStateZipField in this case. The inputs attribute is a way of initializing local script variables with values from the data store.

 <trigger language="JavaScript"

        path="YellowPages.CityStateZipField.objectValue"

        inputs="cityStateZip=YellowPages.CityStateZipField.objectValue">

    DataStore.Set("PERSISTENT.cityStateZip", cityStateZip);

    DataStore.Set("YellowPages.ClickAgaintext.stringValue", " ");

</trigger>

<trigger path="Stocks.action.symbols" language="XQuery"

            inputs="symbols= Stocks.action.symbols,

            table=Stocks.SymbolTable.dataValue"

            output="Stocks.SymbolTable.dataValue"

            notify="Stocks.action.updateQuotes"

            stream="true" append="true">

let $newSymbols := for $symbol in $symbols where

            empty($table/symbol[. = $symbol])

    return dictionary(("symbol", $symbol), ("id", string(unique-id())))

return $newSymbols

</trigger>

Nib File Installation

Sherlock defines several trigger paths for determining when a channel’s interface is displayed or removed from the Sherlock window. Table 7 lists the paths along with a description of when the path is triggered.

Persistent Storage Paths

Sherlock uses the PERSISTENT path to manage data in the Sherlock preferences file for the current user. You can use this path to get or set channel-specific data you want to retain between Sherlock sessions. You can also use it to access data shared by multiple channels.

To store channel-specific data, specify the PERSISTENT base path followed by a unique path name to identify the stored data. For example, to save the postal code of the current user to the preferences file, you could use the following JavaScript code:

userPostalCode = 95014;

DataStore.Set("PERSISTENT.postalCode", userPostalCode);

Inside the preferences file, Sherlock creates a dictionary for each channel’s individual preferences. Any data a channel writes to the PERSISTENT path are placed inside that channel’s dictionary and are accessible only by that channel.

If you want to share persistent data with other channels, you must do so using the PERSISTENT.SHARED base path. This path defines an area of the preferences file where channels may share data they find useful. To store shared data, you must add your channel identifier and the path name for the data to the PERSISTENT.SHARED path name. For example, to store a value at the path MyData in the channel whose identifier is com.apple.MyChannel, you would use the following path:

PERSISTENT.SHARED.com.apple.MyChannel.MyData

All channels use the same path to access your channel’s shared data. However, paths you create in the persistent storage space are accessible for reading and writing by your channel but are read-only to all other channels.

Printing Paths

Sherlock provides several specific paths to implement printing support for channels. The use of these paths is discussed in detail in the article Printing Your Channel’s Content.

URL Paths

Sherlock supports the automatic loading and execution of a channel using a browser URL. Sherlock defines a URL base path for accessing the query attributes of a URL. If a URL attribute has a value, Sherlock stores the value in the URL path under the name of the attribute. Attributes without values generate notifications instead.

For example, the following code shows a potential URL that can be sent to Sherlock:

sherlock://com.apple.yellowPages?query=sushi&zip=95120&search

When this URL is received, Sherlock writes each query attribute to the URL path. Query attributes are written in the same order as they appear in the query string. After all of the parameters are written, Sherlock sends a notification to the path URL.complete to signal the end of the parameter list. So, from the preceding example, Sherlock would perform the following equivalent operations (shown here as if they were part of a JavaScript trigger) to store the data:

DataStore.Set("URL.query", "sushi");

DataStore.Set("URL.zip", "95120");

DataStore.Notify("URL.search");

DataStore.Notify("URL.complete");

For each data value it sets, Sherlock also generates a notification to any triggers monitoring that path. If your channel defined a trigger that monitored the URL.query path, that trigger would be called prior to any triggers for the URL.zip or URL.search paths.

HTMLView

HTMLView objects contain properties for rendering HTML content. HTMLView inherits properties from NSControl and NSView. Table 9 lists the path properties for HTMLView.

This control is supported only on Mac OS X version 10.3 and later.

NSBrowser

NSBrowser objects contain properties for accessing the column data of a browser (column view) control. NSBrowser inherits properties from NSControl and NSView. Table 9 lists the path properties for NSBrowser.

Although you can store hierarchical data using text and numbers in the data array of a browser, an easier way is to use dictionaries. When you specify a dictionary of items for a row, you can include a key called IS_LEAF to indicate that Sherlock should treat the dictionary as hierarchical data. When the key is set to true, Sherlock displays a right-arrow icon next to the row entry indicating there is more data.

NSButton

NSButton objects contain properties for getting and setting the display characteristics of the button. NSButton inherits properties from NSControl and NSView. You can use the action property inherited from NSControl to respond to button clicks. Table 11 lists the path properties for NSButton.

NSComboBox

NSComboBox objects contain properties for getting and setting the items and text-completion characteristics of the combo box. NSComboBox inherits properties from NSTextField, NSControl, and NSView. Table 11 lists the path properties for NSComboBox.

NSControl

NSControl defines common properties for the NSBrowser, NSButton, NSImageView, NSMatrix, NSSlider, NSTableView, NSStepper, and NSTextField controls. NSControl also inherits properties from NSView. Table 13 lists the path properties for NSControl.

NSDrawer

NSDrawer objects contain properties to which you can send open and close notifications. Table 14 lists the path properties for NSDrawer.

NSImageView

NSImageView objects contain properties for accessing the image data and URL. NSImageView inherits properties from NSControl and NSView. Table 15 lists the path properties for NSImageView.

NSMatrix

NSMatrix objects contain the currently selected cells in the matrix. NSMatrix inherits properties from NSControl and NSView. Table 16 lists the path properties for NSMatrix.

NSMovieView

NSMovieView objects contain properties for loading and playing a movie. NSMovieView inherits properties from NSView. Table 17 lists the path properties for NSMovieView.

NSPopUpButton

NSPopUpButton objects contain properties identifying the items of the pop-up menu. NSPopUpButton inherits properties from NSButton, NSControl, and NSView. Table 18 lists the path properties for NSPopUpButton.

To insert a menu-item separator in the pop-up menu, add the string “SherlockMenuItemSeparator” to the array of strings in items. If you use an array of dictionaries to specify your menu items, put the “SherlockMenuItemSeparator” string in the title key and omit the representedObject key.

NSProgressIndicator

NSProgressIndicator objects contain properties for controlling the appearance of the progress bar. NSProgressIndicator inherits properties from NSView. Table 19 lists the path properties for NSProgressIndicator.

NSSlider

NSSlider has no accessible properties of its own, but it does inherit properties from NSControl and NSView. To set the minimum and maximum values of the slider, you must do so from Interface Builder.

NSSplitView

NSSplitView objects contain a property defining the minimum size of a split-view pane. NSSplitView inherits properties from NSView. Table 20 lists the path properties for NSSplitView.

NSStepper

NSStepper has no accessible properties of its own, but it does inherit properties from NSControl and NSView. To set the minimum and maximum values of the stepper, you must do so from Interface Builder.

NSTableView

NSTableView objects contain properties identifying the appearance of the table’s columns and rows, as well as the contents of the table. NSTableView inherits properties from NSControl and NSView. Table 21 lists the path properties for NSTableView.

To specify pasteboard types, you associate an appropriate path name with the pasteboard type key. When the data is copied, Sherlock copies the data at the specified path to the pasteboard. For example, the following JavaScript code sets two different pasteboard types for a row. The first line sets the string version of the URL to the string object of the row. The second line sets the URL pasteboard data to the double-click URL for the row.

DataStore.Set(

        "Internet.SearchResultsTable.pasteboardTypes.NSStringPboardType",

        "description.URL.objectValue");DataStore.Set("Internet.SearchResultsTable.pasteboardTypes.NSURLPboardType",

        "doubleClickURL");

Note that you should not specify the path to the row itself in the paths you specify. Sherlock assumes that you are copying from the current row automatically.

NSTabView

NSTabView objects contain a property identifying the currently selected tab. NSTabView inherits properties from NSView. Table 22 lists the path properties for NSTabView.

NSTextField

NSTextField objects contain properties for the control contents as well as for receiving notifications. NSTextField inherits properties from NSControl and NSView.

Table 23 lists the path properties for NSTextField.

NSTextView

NSTextView objects contain properties identifying their enclosed text. NSTextView inherits properties from NSView. Table 24 lists the path properties for NSTextView.

NSView

NSView objects define common properties for many controls and views. Table 25 lists the path properties for NSView.

NSWindow

NSWindow objects define properties for displaying and manipulating windows. Table 26 lists the path properties for NSWindow.

You typically use NSWindow objects defined in your nib files as sheets for your main channel window. To display a sheet, you send a beginSheet notification to the target window. For example, to display a sheet named MySheet when the user clicked a button, you would use the following code:

<trigger path="MyChannel.DisplaySheetBtn.action" language="JavaScript">

    DataStore.Notify("MySheet.beginSheet");

</trigger>

To respond to events in the sheet, you would define additional triggers to handle the sheet’s controls, just as you do for your channel controls. For example, to respond to an OK button on the sheet, you would use code similar to the following:

<trigger path="MySheet.OKButton.action" language="JavaScript">

    DataStore.Notify("MySheet.endSheet");

</trigger>

SherlockAddressComboBox

SherlockAddressComboBox objects contain properties for displaying address information from the user’s Address Book database. This control displays an NSComboBox control that can be used to enter or select address information. The control keeps a list of the 10 most recently used addresses for auto-completion purposes. SherlockAddressComboBox inherits properties from NSControl and NSView. Table 27 lists the path properties for SherlockAddressComboBox.

This control is supported only on Mac OS X version 10.3 and later.

AddressBook Object

The AddressBook object provides access to the local Address Book database. You can use this object to add new addresses to the database and search for existing addresses. Table 28 lists the methods defined by the AddressBook object.

DataStore Object

The DataStore object provides access to the channel’s field data and coordinates the transmission and receipt of notifications. You use this object in your script code to get or set data store values. You can also use it to generate explicit notifications from your script code. Table 31 lists the methods defined by the DataStore object.

For example, to get the value at the path MyPath.MyTextField.objectValue, you would use the following JavaScript code:

value = DataStore.Get("MyPath.MyTextField.objectValue");

System Object

The System object provides some useful utilities, which are listed in Table 32.

XMLQuery Object

The XMLQuery object provides an interface for calling XQuery functions from JavaScript. This object provides access to all of the built-in XQuery functions as well as to the Apple-specific additions. Each XQuery function is implemented as a method of the XMLQuery object. For example, to call the url function, you would use the following syntax:

urlObject = XMLQuery.url("http://www.apple.com");

Due to JavaScript naming conventions, when you call an XQuery function whose name contains a hyphen (-) character, you must replace the character with an underscore (_) instead. For example, to call the convert-entities function from JavaScript, you would use the following syntax:

outString = XMLQuery.convert_entities("&");

base-url

The base-url function returns a URL to the directory containing the file that called this method. The syntax for this function is as follows:

url base-url()

This function returns the location of the code file that called this method.

base64-decode

The base64-decode function decodes a base-64 encoded block of data into a string. The syntax for this function is as follows:

data base64-decode(source)

Base-64 encoding packs three 8-bit bytes into four 7-bit ASCII characters. If the number of bytes in the original data is not divisible by three, “=” characters are used to pad the encoded data. This function reverses the process to yield the original string.

base64-encode

The base64-encode function encodes the source data using base-64 encoding. The syntax for this function is as follows:

data base64-encode(source)

Base-64 encoding packs three 8-bit bytes into four 7-bit ASCII characters. If the number of bytes in the original data is not divisible by three, “=” characters are used to pad the encoded data.

For example, the following function call would yield an encoded value of “MQ==“:

base64-encode("1")/string()

channel-version

The channel-version function returns a CFNumberRef with the current channel implementation version. The syntax for this function is as follows:

number channel-version()

charset-encoding

The charset-encoding function returns the encoding index for the specified IANA character set name. The syntax for this function is as follows:

number charset-encoding(encoding)

The encoding parameter contains the character set name.

charset-name

The charset-name function returns the IANA character set name corresponding to the specified index. The syntax for this function is as follows:

string charset-name(encoding)

The encoding parameter is an integer specifying the string encoding.

convert-entities

The convert-entities function converts HTML entity characters in a string to their equivalent display characters. The syntax of this function is as follows:

string convert-entities(source)

The source parameter contains a text string. Any characters of the form &<code>; where <code> is an entity name are converted to display characters. For example, the string & is converted to the ampersand character “&”. This function returns a new string with the converted characters.

convert-html

The convert-html function converts HTML entity characters to displayable text and normalizes the spaces in the string. The syntax of this function is as follows:

string convert-html(source)

The source parameter contains a string with HTML text. This function converts entity characters to their displayable forms and normalizes whitespace characters. This function returns a new string with the displayable text.

In the following example, the call to convert-html returns the string “&<a href=x.gif>picture</a>“.

convert-html(" &amp;<a href=x.gif>picture</a>     ")

curl

The curl function performs an HTTP GET request using curl to initiate the request. The syntax for this function is as follows:

data curl(source)

The source parameter contains the URL to request.

data

The data function builds and returns an object of type CFDataRef. The syntax of this function is as follows:

data data(theData)

data-length

The data function returns the number of bytes in a data block. The syntax of this function is as follows:

number data-length(theObject)

data-match

The data-match function searches a data block for the specified starting and ending patterns and returns the first match it finds. The syntax for this function is as follows;

data data-match(source, matchStart, matchEnd, includeStart, includeEnd)

The source parameter contains the data block you want to search. The matchStart parameter contains the initial match data. Once found, the match continues until the data in the matchEnd parameter is found. This function returns a data object with the matched contents.

The includeStart and includeEnd parameters tell this function whether to include the starting and ending match data in the returned string. These parameters are set to false by default and may be omitted.

The following example returns the data “0x3334”, which represents the last two bytes of the data block. Only the last two bytes are returned because false is specified for the includeStart parameter.

data-match("1234","2","4",false(),true())

data-match-all

The data-match-all function searches a data block for the specified starting and ending patterns and returns a list of matches. The syntax for this function is as follows:

seq data-match-all(source, matchStart, matchEnd, includeStart,

        includeEnd)

The source parameter contains the data block you want to search. The matchStart parameter contains the initial match data. Once found, the function accumulates data until the matchEnd parameter is found. This function returns a data object with the matched contents.

The includeStart and includeEnd parameters tell this function whether to include the starting and ending match data in the returned string. These parameters are set to false by default and may be omitted.

The following example returns the data “0x3334, 0x3534”, which matches the two patterns within the data block. Only the last two bytes of each match are returned because false is specified for the includeStart parameter.

data-match("1234 1254","2","4",false(),true())

data-match-ignore-case

The data-match function searches a data block for the specified starting and ending patterns and returns the first match it finds. The syntax for this function is as follows:

data data-match-ignore-case(source, matchStart, matchEnd, includeStart,

        includeEnd)

The source parameter contains the data block you want to search. The matchStart parameter contains the initial match data. Once found, the function accumulates data until the matchEnd parameter is found. Matches do not take case into account. This function returns a data object with the matched contents.

The includeStart and includeEnd parameters tell this function whether to include the starting and ending match data in the returned string. These parameters are set to false by default and may be omitted.

data-match-ignore-case-all

The data-match-ignore-case-all function searches a data block for the specified starting and ending patterns and returns a list of matches. The syntax for this function is as follows:

seq data-match-ignore-case-all(source, matchStart, matchEnd,

        includeStart, includeEnd)

The source parameter contains the data block you want to search. The matchStart parameter contains the initial match data. Once found, the function accumulates data until the matchEnd parameter is found. Matches do not take case into account. This function returns a data object with the matched contents.

The includeStart and includeEnd parameters tell this function whether to include the starting and ending match data in the returned string. These parameters are set to false by default and may be omitted.

dictionary

The dictionary function builds and returns a dictionary object from the specified parameters. The syntax of this function is as follows:

dictionary dictionary (...)

Use this function to build a dictionary of key/value pairs in an XQuery function.

dictionary-get

The dictionary-get function returns the value for the specified key in a dictionary. The syntax of this function is as follows:

node dictionary-get(source, key)

The source parameter contains the dictionary. The key parameter contains the key to search for in the dictionary.

encoded-data-to-string

The encoded-data-to-string function converts a data object to a string. The syntax for this function is as follows:

string encoded-data-to-string(source, charset)

The source parameter contains the data object to convert. The charset parameter contains the name of the IANA registry character set to use for the conversion.

eval

The eval function evaluates the specified XQuery string and returns the result. The syntax for this function is as follows:

type eval(string)

The string parameter contains an XQuery statement to be evaluated.

The eval function optionally takes a second argument. In this case, string can contain variables that are defined in the second argument, which is a dictionary of key-value pairs. For example:

eval("concat('eval may take ',$number, ' argument',$plural)", dictionary(("number", 2),("plural","s")))

This call returns the string “eval may take 2 arguments”.

http-get

The http-get function initiates an HTTP GET request for the given URL and returns the results. The syntax for this function is as follows:

dictionary http-get(source, headers)

The source parameter contains the URL string to request. The headers parameter is an optional dictionary you can use to specify HTTP request header information. On return, this function returns a dictionary with the keys listed in Table 33.

http-head

The http-head function initiates an HTTP HEAD request and returns only the header portion. The syntax for this function is as follows:

dictionary http-head(source, headers)

The source parameter contains the URL string to request. The headers parameter is an optional dictionary you can use to specify HTTP request header information. On return, this function returns a dictionary with the keys listed in Table 33.

http-post

The http-post function initiates an HTTP POST request for the given URL and returns the results. The syntax for this function is as follows:

dictionary http-post(source, postdata, headers)

The source parameter contains the URL string to request. The headers parameter is an optional dictionary you can use to specify HTTP request header information. On return, this function returns a dictionary with the keys listed in Table 33.

http-request

The http-request function initiates a generic HTTP request for the given URL and returns the results. The syntax for this function is as follows:

dictionary http-request(url, additionalInfo)

You can use this function to initiate a request of any type: GET, POST, HEAD. The url parameter contains the URL string to request. The additionalInfo parameter contains a dictionary with information to add to the request. This dictionary contains the keys shown in Table 36.

On return, this function returns a dictionary with keys appropriate to the type of request. The possible keys are listed in Table 33.

load-service

The load-service function loads the services from the specified URL and makes them available to your script code. The syntax for this function is as follows:

boolean load-service(url)

The url parameter contains the URL of the file containing the service. The function returns a boolean value indicating whether the services were successfully loaded.

localized-resource

The localized-resource function returns a localized resource based on the user’s current language settings. The syntax for this function is as follows:

type localized-resource(key, baseURL, fileName)

The key parameter identifies a key in the LocalizedResources.plist file of the language folder matching the user’s current settings. The value associated with this key should be the name of the resource file you want to locate.

The baseURL and fileName parameters are optional. Use the baseURL parameter to override the default location for localized resources, which is specified in the channel configuration file. Use the fileName parameter to specify a property-list file other than LocalizedResources.plist in which to look up the desired key.

localized-url

The localized-url function returns the location of the localized resource file based on the user’s current language settings. The syntax for this function is as follows:

type localized-url(fileName, baseURL)

The fileName parameter specifies the name of a localized resource file. Localized copies of the file must be located in the channel’s language folders. The baseURL parameter is optional and is used to override the default base folder to use when searching for localized resources.

msg

The msg function prints a message to stderr. The syntax for this function is as follows:

type msg(debug_msg)

This function returns the message that was printed. Debugging must be enabled before you can view the output messages. To enable debugging, open a Terminal window on your system and define the environment variable SHERLOCK_DEBUG_CHANNELS with a value of 1. Once this variable is defined, launch Sherlock from the command line to begin your debugging session.

null

The null function returns the null object. The syntax for this function is as follows:

null null()

You can use the returned value to determine if an XQuery object is valid.

property-list-decode

The property-list-decode function converts an XML property list into a property-list data object. The syntax for this function is as follows:

data property-list-decode(source)

The source parameter contains the raw bytes from the XML property-list file. If a parsing error occurs, this function returns an empty object.

property-list-encode

The property-list-encode function converts a source object into a data object whose contents are an XML property list. The syntax for this function is as follows:

data property-list-encode(source)

The source parameter contains the property-list data you want to encode as XML. The resulting data is appropriate for writing out to an XML file, but is returned as a data object instead of a string.

reg-exp

The reg function performs a pattern match on the specified string and returns the matching text. The syntax of this function is as follows:

seq reg-exp(source, reg-exp)

The source parameter contains the string to search. The reg-exp parameter contains the regular expression to apply to the string. This function returns a sequence of strings, each of which contains the text from a specific match.

The syntax for regular expressions is identical to those for the matches function defined in XQuery. For a complete specification of the expression syntax, see http://www.w3.org/TR/xmlschema-2/#regexs.

sherlock-function

The sherlock-function function calls a Sherlock Web Service to perform a specific task. The syntax for this function is as follows:

type sherlock-function(sourceURL, functionName, ...)

The sourceURL parameter specifies the URL for the file containing the web services code you want to access. The functionName parameter contains the name of a specific function you want to access. If the web-service function takes any parameters of its own, you can pass those in as extra arguments to sherlock-function.

source

The source function returns an XML string representing the specified node. The syntax for this function is as follows:

string source(node)

string-combine

The string-combine function concatenates a sequence of strings together using a designated separator string. The syntax of this function is as follows:

string string-combine(strings, separator)

The strings parameter contains the sequence of strings to be concatenated. The separator parameter contains the separator string. The function returns the resulting string.

string-separate

The string-separate function splits a string based on the specified separator string. The syntax of this function is as follows:

seq string-separate(source, separator)

The source parameter contains the string you want to split. The separator parameter contains the separator string. The function returns the resulting sequence of strings. This function does not include the separator string in the strings of the returned sequence.

string-to-encoded-data

The string-to-encoded-data function converts a string to a data object. The syntax for this function is as follows:

data string-to-encoded-data(source, charset)

The source parameter contains the string to convert. The charset parameter contains the name of the IANA registry character set to use for the conversion.

For example, the following function call would yield a data object with the contents 0xffef0031:

string-to-encoded-data("1", "UTF-16")

unique-id

The unique-id function returns a unique number for the current channel. The syntax for this function is as follows:

number unique-id()

url

The url function returns a CFURLRef object for the specified source. The syntax for this function is as follows:

url url(source)

The source parameter contains a string with the URL text.

url-decode

The url-decode function decodes a string with encoded characters, returning a regular text string. The syntax for this function is as follows:

string url-decode(urlSource, charactersToLeaveEscaped)

The urlSource parameter contains the string you want to decode. The charactersToLeaveEscaped parameter contain specific characters to leave untouched. The encoding parameter specifies the encoding format for the returned string.

The following example decodes the colon and forward-slash encoded characters in the string. The string returned by this function call is “http://”:

url-decode("http%3A%2F%2F", "")

url-encode

The url-encode function encodes the characters of a URL string. The syntax for this function is as follows:

string url-encode(urlSource, charactersToLeaveUnescaped,

        legalURLCharactersToBeEscaped, encoding)

The urlSource parameter contains the URL string you want to encode. The charactersToLeaveUnescaped and legalURLCharactersToBeEscaped parameters contain specific characters to modify or leave untouched. The encoding parameter specifies the encoding format for the returned string.

The following example encodes the colon and forward-slash characters in the given string. The string returned by this function call is “http%3A%2F%2F”:

url-encode("http://", "", ":/", "UTF-8")

url-host

The url-host function returns the hostname information from a URL string. The syntax for this function is as follows:

string url-host(urlSource)

The urlSource parameter contains the URL path whose hostname you want to obtain. The return value omits any scheme and pathname information. For example, the following function call returns the string “www.apple.com”:

url-host("http://www.apple.com/index.html")

url-last-path-component

The url-last-path-component function returns the last path component of a URL string. The syntax for this function is as follows:

string url-last-path-component(urlSource)

The urlSource parameter contains the URL whose path information you want to obtain. The return value omits any scheme, hostname, and leading path information. For example, the following function call returns the string “index.html”:

url-last-path-component("http://www.apple.com/test/index.html")

url-path

The url-path function returns the relative path information from a URL string. The syntax for this function is as follows:

string url-path(urlSource)

The urlSource parameter contains the URL whose path information you want to obtain. The return value omits any scheme and hostname information. For example, the following function call returns the string “/test/index.html”:

url-path("http://www.apple.com/test/index.html")

url-query

The url-query function returns the query attributes of a URL string. The syntax for this function is as follows:

string url-query(urlSource)

The urlSource parameter contains the URL whose attribute information you want to obtain. The return value omits any scheme, hostname, and leading path information. For example, the following function call returns the string “action=search”:

url-query("http://www.apple.com/index.html?action=search")

url-query-value

The url-query-value function extracts the value of an attribute from a URL string. The syntax for this function is as follows:

string url-query-value(urlSource, key)

The urlSource parameter contains the URL whose attribute information you want to obtain. The key parameter contains the name of the attribute to return. The return value omits any scheme, hostname, and leading path information. For example, the following function call returns the string “search”:

url-query-value("http://www.apple.com/index.html?action=search", "action")

url-scheme

The url-scheme function returns the scheme type of a URL string. The syntax for this function is as follows:

string url-scheme(urlSource)

The urlSource parameter contains the URL path whose scheme you want to obtain. The return value omits any host and pathname information. For example, the following function call returns the string “http”:

url-scheme("http://www.apple.com/index.html")

url-with-base

The url-with-base function returns a CFURLRef object built from the specified base and relative paths. The syntax for this function is as follows:

url url-with-base(urlSource, base)

The urlSource parameter contains a relative pathname to append to the URL path in the base parameter.

version

The version function returns a CFNumberRef with the version of the XQuery implementation currently in use. The syntax for this function is as follows:

number version()