# -*- coding: utf-8 -*-
# Author:   $Author: merkosh $
# Revision: $Rev: 40 $

Format
======

This describes how script are called by lmc and how they should
return their data.


Calling convention
------------------

Scripts are executed as child processes. Called from the command
line they should work just the same way.

Usually, when querying a movie database on the web for a title,
it yields a number of hits from which you then select the correct
one.
To support this behaviour a script has two tasks:
- get list of matching titles
- get detals on a specific hit

The synopsis is as follows:

  script <title>
  script <URL>


The URL is distinguished from the title by a leading 'http://'. If
your title contains this prefix, you're busted! ;)


Failure /Success
----------------

In case the script encounters an error, output any error messages to
STDERR and exit. The standard error output will be recorded by lmc
as error message and abort processing.

On success, the first line returned should contain either of:

status: failed
status: list
status: details

Return the first line if the query failed and lmc should abort
this process of searching. This is a "clean abort".
Return the second line if the return format is a list of alternatives
as described below.
The last line should be returned when returning details on on a
title.


Return format: list
-------------------

When given a title as parameter the script should gather a list of
matches from its source and return line orientated records of the 
form:

section: <section>
title: <title>
url: <url>
description: <description>

Empty lines are ignored. The order of (name, url, description) is
significant. There can be more than one, or zero description lines.

The section needs only to be specified once at the start and every
time the classification changes. The section describes a measure of
confidence how well the record fits the searched title, 
i.e. section: Exact Matches


Return format: details
----------------------

When the user makes a choice the script is called again with the URL
as parameter. It should then extract all available fields. Currently
recognised by lmc are:

originalTitle: <text>
year: <number>
picture: <url to image>
director: <text>
category: <text>
actors: <text>
rating: <integer>
url: <text>
length: <number>
country: <text>
languages: <text>
description: <text>
comments: <text>
translatedTitle: <text>
producer: <text>

The data is to be returned as line orientated records. Empty lines are
ignored. All fields may be specified multiple times. Its up to lmc to
concatenate multiple invocations apropriately or discard the last value.
It is your choice wether to i.e. list all actors individually or wether to
concatenate them to one line:

actors: Arnold Scharzenegger - Charlie
actors: Brad Pitt - David

or 

actors: Arnold Schwarzenegger - Charlie; Brad Pitt - David


If you cannot support a field, leave it out. 
See IMDB-en.pl for examples.

