Sherlock Scripting Language Support

Sherlock provides you with two different languages—JavaScript and XQuery—for writing your channel’s script code. These languages provide you with both the power and flexibility to process data and manipulate your channel’s contents dynamically. This article provides a brief introduction to each language and provides information about Apple’s implementation.

Introduction to JavaScript

The JavaScript language was originally developed by Netscape as a way to implement dynamic HTML pages in a client’s web browser. JavaScript is an interpreted language whose syntax resembles those of C in some aspects, but which also includes a mechanism for declaring and using objects. JavaScript is also known by the name ECMAScript and is typically used for writing short subroutines to manipulate browser data or respond to user interactions within web pages.

Sherlock supports JavaScript as one of the primary languages for writing triggers. Sherlock’s uses a standard implementation of the JavaScript engine to interpret and execute script code in the Sherlock application environment. The JavaScript syntax is documented in numerous third-party books and is not covered in this article. However, developers familiar with the C and Java languages will find some familiar programming constructs.

Apple provides several predefined objects for JavaScript code to use. These objects are specific to the Sherlock channel environment and are described in more detail in JavaScript Extensions.

Introduction to XQuery

XQuery is a part of the XML Query specification currently being defined by the World Wide Web Consortium. The goal of XML Query is to provide a convenient way to extract data from real and virtual documents on the web. The medium for achieving this goal is XML and the script language used to manipulate the data is called XQuery.

A complete discussion of the XQuery language is beyond the scope of this article. For the latest information about XML Query, visit the World Wide Web Consortium website (http://www.w3c.org/XML/Query). This site includes information about the XQuery language and other current developments.

Apple provides several additions to the XQuery language that allow you to manage Sherlock resources. Apple’s additions are documented in XQuery Extensions.

For new and experienced XQuery programmers, the following sections include some tips and techniques for using XQuery in your Sherlock channels.

Accessing the Data Store

Because XQuery triggers do not have access to the data store, you must use the inputs and output attributes of the trigger to get and set data store values. These parameters are described further in the section Trigger Tag Syntax.

An alternative to using the output attribute to return values is to return a dictionary of key/value pairs instead. When you return a dictionary of values from an XQuery trigger, the data store interprets the keys of the dictionary as paths. The data store then assigns the value for each key back to the corresponding path.

Commenting Out Text

Comments in XQuery begin with an open curly brace followed by two hyphens. To close the comment, use two hyphens followed by a close curly brace, as shown in the following example:

{-- Comments go here. --}

Support for Additional Data Types

Apple defines additional data types to supplement those provided by the XQuery language. Among the data types are the data, dictionary, and url types, which correspond to the Core Foundation types CFDataRef, CFDictionaryRef, and CFURLRef respectively.

The dictionary type is especially useful when writing XQuery-based triggers. To create a dictionary, you use the dictionary function provided by Apple and defined in XQuery Extensions. When you return a dictionary from an XQuery trigger, Sherlock interprets the dictionary keys as data store paths and proceeds to update the corresponding values with the dictionary data.

Accessing the Web

Apple provides several additions to the XQuery language that make it easy to access web-based resources. The additions are built on top of Apple’s Web Foundation Framework and provide access to the web using the HTTP protocol.

To request a URL, you can use any of the following functions:

  • http-get

  • http-head

  • http-post

  • http-request

These functions take the requested URL and any parameters and use them to generate an HTTP request. They return a dictionary of keys identifying the returned data and status information.

Deciding Which Language To Use

When it comes time to write your trigger code, you need to choose which language to use. Most tasks can be performed using either JavaScript or XQuery; however, some tasks are better performed in one language than the other. Knowing which language to use for a given trigger can simplify the channel development process.

Common uses for the JavaScript language include executing conditional code, putting values in the data store, and opening URLs based on user actions.

Advantages of using the JavaScript language to develop triggers and services include:

Disadvantages include:

Common uses for the XQuery language include retrieving data from a URL and parsing XML/HTML to create a list of results.

Advantages of using the XQuery language to develop triggers and services include:

Disadvantages include:

Supported XQuery Functions

Sherlock supports a subset of the XQuery functions defined at http://www.w3.org/TR/2002/WD-xquery-operators-20020816/ . The supported functions are listed here in functional groups.

Date, Time, and Duration

current-dateTime, dateTime, date, time, duration

Numbers

number, ceiling, floor, round, sum

Strings

string, string-length, normalize-space, concat, contains, starts-with, ends-with, substring, substring-after, substring-before, translate, compare, lower-case, upper-case, replace, string-pad, match, matches, string-join, codepoints-to-string, string-to-codepoints

Other

document, count, local-name, boolean, false, true, not, empty, exists, distinct-values, distinct-nodes, insert, remove, sublist, min, max, to, item-at, index-of, deep-equal

Deprecated XQuery Constructs in Mac OS X 10.3

In Mac OS X 10.3, Table 1 list identifies the XQuery constructs that are being deprecated. You should update your channel code to eliminate calls these functions.

Table 1  Deprecated XQuery constructs

Construct

Notes

sortby function

This function is being replaced by the “order by” expressions instead.

== and !== operators

Use the is and isnot operators instead.

XML constructs with non-quoted attributes

An example of this construct is <a href={$link} />. You must now include quotes around the attribute value, so that the above construct would now be <a href="{$link}" />.

Using uninitialized variables

If you use a variable that has not been defined or initialized with a value, you will get an error.

Comments

Using a close curly brace character } inside a comment now generates an error.