Erssical : Queries

A query is described in an XML document of the following form ↴

<?xml version="1.0"?>
<query>
  <sources> ... </sources>
  <target> ... </target>
  <filter> ...  </filter>
</query>

You can have a look at this example.

<query>

This is the top element of the query. The optional attribute type can be used to specify the type of document returned as result of the query. The following types are handled:

application/rss+xml: the query will return a new RSS document,
text/calendar: the query will return calendar data in Ical format,
application/xml: the query will return an XML tree based on a template.

For any other value or if this attribute is not present, the type application/rss+xml is assumed.

The <query> element can contain <sources>, <target>, <filter> and <template> elements.

This element contains the various source RSS channels, each one is defined by a <source> sub-element. A source RSS channel can be embedded or referenced by its URL.

Referenced source

Most of the time, a source is referenced by a URL given in the href attribute. For example:

<source href="http://www.good-eris.net/stog/index.rss"/>

For referenced sources, it is possible to give default event information, which will be merged with the event information of the items when the channel is fetched. To do so, just add event elements in the <source> element. The prefix of these elements can be omitted when placed here. For example, the following code defines a new referenced source, and all its items will be added the "ocaml" keyword when the source is fetched:

<source href="http://planet.ocamlcore.org/rss20.xml">
  <keywords><item>ocaml</item></keywords>
</source>

Embedded source

A whole RSS channel can be embedded in a <source> element, when no href attribute is present. To do so, just put channel elements in the <source> element, for example:

<source>
  <title>My favorite RSS channel</title>
  <link>http://my.favorite-channel.mine</link>
  <description>bla bla bla</description>
  <item> ... </item>
  <item> ... </item>
</source>

An optional <target> element can be used to specify information for the final RSS channel. Most of the time, the channel information will be embedded in the <target> element, in the same way as for source channel, but the target channel can also be referenced by a URL like a referenced source.

Example of embedded target:

<target>
  <title>Merged channel</title>
  <link>http://mysite.net/foo.rss</link>
  <description>Merged channel from various sources</description>
  ...
</target>

When no target channel is provided, the channel information of the first source channel is used to build the new channel.

The <filter> element is used to keep only items matching some criteria. A filter is composed of basic filters and filter combinators.

It is not possible yet to filter on all event information, as some event information is not yet fully specified (type, level, ...).

The <keywords> element filters RSS items containing some keywords. Each keyword is specified in an <item> element. In an <item> element, the attribute regexp="true" means that the string contained in the element must be handled as a regular expression to match RSS item keywords.

More than one <item> element can be present under a <keywords> element. By default, the RSS item must match all the specified <item> criteria. If the <keywords> element has attribute connector="or", then the RSS item must match at least one of the <item> criteria.

For example, the following filter will keep only RSS items having keywords matching the string "api" or the regular expression "o?caml":

<filter>
  <keywords connector="or">
    <item>api</item>
    <item regexp="true">o?caml</item>
  </keywords>
</filter>

This filter works the same way as <keywords> but for the "organizers" information of the RSS items.

This filter works the same way as <keywords> but for the "speakers" information of the RSS items.

The <startDate> element is used to filter RSS items according to their start date, or their date if no start date is specified. Two attributes, after and before, can be used as date and time constraints.

For example, the following filter will keep only RSS items whose (start) date is between the 1^st of May 2013 at 12h:00 and the 31^st of the same month at 16:00:

<filter>
  <startDate
    after="1 May 2013 12:00:00 +0100"
    before="31 May 2013 16:00:00 +0100"/>
</filter>

Of course, one can specify only the attribute after or before.

The <endDate> element is used to filter on the RSS item end date, if present. If a RSS item has no such date, then the RSS item is considered as matching the criteria.

<or>

The <or> element contains other filters. A RSS item matches this filter if it matches at least one of the filters defined in the <or> element. For example, the following filter will keep only RSS items matching the <keywords> filter or the <startDate> filter:

<filter>
  <or>
    <keywords><item>api</item></keywords>
    <startDate after="1 May 2012 12:00:00 +0100"/>
  </or>
</filter>

<and>

The <and> element is like the <or> filter but RSS items must match all the sub-filters to be kept.

<not>

The <not> element also contains sub-filters. A RSS item will be kept if it does not match at least one sub-filter: The intersection of RSS items matching the sub-filters is computed, then only the complement of this intersection is kept. For example, the following filter will keep only RSS items which don't have the "api" keyword and start after the 1^st of May 2012 at 12:00:

<filter>
  <not>
    <keywords><item>api</item></keywords>
    <startDate after="1 May 2012 12:00:00 +0100"/>
  </not>
</filter>

This is equivalent to the following filter:

<filter>
  <not>
    <and>
      <keywords><item>api</item></keywords>
      <startDate after="1 May 2012 12:00:00 +0100"/>
    </and>
  </not>
</filter>

This element contains the XML template used when querying a XML result. Here is an example of such a template element:

<query type="application/xml">
  <template tag="div" class="rss-items">
    <div class="rss-item">
      <span class="rss-date"><item-pub-year/>-<item-pub-month/>-<item-pub-mday/></span
      ><span class="rss-item-title"><a href="&lt;item-url/&gt;"><item-title/></a></span>
      <span class="rss-source">[<item-source-name/>]</span>
    </div>
  </template>
</query>

The tag="div" means that the root element of the result tree will be a "div". The additional attributes of the <template> are added to this root node.

The elements under the <template> are used as template: for each item in the final channel (i.e. after merging and filtering), rewrite rules are applied and the result is added to the root node of the result. Rewrite rules consist in replacing some XML nodes by information about the current item.

The following nodes are replaced:

<item-title>: title of the item,
<item-description>: description of the item,
<item-url>: link of the item,
<item-pubdate>: publication date of the item,
<item-pub-year>: year of the publication date of the item; you can also use <item-pub-month>, <item-pub-mday>, <item-pub-hour>, <item-pub-minute>, and <item-pub-second> elements,
<item-author>: author of the item,
<item-source-url>: url of the source channel,
<item-source-name>: name of the source channel.