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

This directory contains the website scripts quvi uses to parse the video
links. Should video link parsing ever break (and they will 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 website script 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, e.g. "default|best|hq|hd"
      - All scripts should at least define "default" in this string
      - Should include "best" if there are more than just "default" ID

    - handles (boolean)
      - Used to check whether the script can handle the user specified URL


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

quvi calls this function to fetch and parse the user specified URL.
This function looks typically very different for each website. Compare
buzzhumor.lua and youtube.lua for an example of this.

The "parse" function is expected set/update the following video details:
  * host_id (string)
  * title (string)
  * id (string)
  * url (array of strings)
  * redirect (string) [see notes below]

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

Parameters:
  * quvi sets the following table keys before it runs the script
    - page_url (string)         -- user specified URL
    - requested_format (string) -- user requested video format ID

Returns:
  * The updated `video' table

Notes:
  * "redirect", special field, if set (default:empty):
    - Drop user specified URL and follow to the redirect URL instead
    - This replaces the original user defined URL (set by quvi_parse)
    - See academicearth.lua script for an example


3. Exposed C functions
======================

quvi exposes the following C functions to the website scripts. Each of
these are in the "quvi" object, e.g. quvi.fetch.


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

Fetches data from the specified URL.

Parameters:
  * url (string)                - URL to fetch
  * options (table)             - Additional options* [optional]

options:
  * fetch_type       (string)   ("page"|"config"|"playlist") =page
  * arbitrary_cookie (string)   e.g. "foo=1;bar=2"
  * user_agent       (string)   e.g. "foo/0.1"

arbitrary_cookie value is passed (as it is) to libcurl, see:
  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE

Returns:
  * Fetched data


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

Returns an unescaped `string'.

Parameters:
  * string

Returns:
  * Unescaped string
