
1. Foreword
===========

This directory contains the website specific scripts (rules) that quvi
uses to parse the video links. Should video link parsing ever break (and
they shall eventually), these are the scripts that one should take a look
at first.

These scripts are written in Lua. If you are new to Lua,
<http://www.lua.org/pil/> is a good place to start.


2. Structure of an quvi website script
======================================

Each script (rule) must contain the following functions:
  * ident
  * parse


2.1. function ident (page_url)
------------------------------

quvi calls this function to check if the script can handle
the user specified video page URL.

Parameters:
  * page_url (string)

Returns:
  * A table containing the following keys

    - domain (string)

      - This string is used to match page URL to domain

      - Returned to an application with quvi_next_supported_website

      - The string must cover any TLDs and additional domain names

      - e.g. "youtube.com", "video.google."

    - formats (string)

      - An "array" of the supported video format IDs that the website,
      each separated with '|', e.g. "default|best|hq|hd"

      - All scripts should at least define "default" in this string

      - Include "best" when/if possible/expected, e.g. multiple
      format IDs supported

    - will_handle (boolean)

      - If the script can handle the URL provided in the page_url
      variable, it should set "will_handle" to true, otherwise set
      it to false


2.2. function parse (video)
---------------------------

quvi calls this function to fetch and parse the user specified URL.
This function can vary greatly, see youtube.lua and buzzhumor.lua
scripts for a comparison of this.

The function is expected set the following video details.
  * host_id (string)
  * title (string)
  * id (string)
  * url (array of strings)

Each of these belong to the `video' table passed to the function
as a parameter. e.g. "video.host_id = 'youtube'"

Parameters:
  * video (table), contains the following keys
    - page_url (string)
    - requested_format (string)

Returns:
  * `video' table containing the updated details


3. Lua API
==========

All of the functions exposed to the lua scripts are in the "quvi" object,
e.g. "quvi.fetch(url)".


3.1. Function: string quvi.fetch (url, what)
--------------------------------------------

Fetches URL.

Parameters:
  * url (string) - URL to fetch
  * what (string) - "page", "config" or "playlist" (optional)

`what' will be translated to a QUVIstatusType defined in the
quvi.h header file. If what is undefined (nil), quvi will
default to "page".

Returns:
  * Fetched contents of the URL


3.2. Function: string quvi.unescape (string)
--------------------------------------------

Returns unescaped `string'.

Parameters:
  * string

Returns:
  * Unescaped string
