Server Template file for aria
-----------------------------
$Id$

Syntax(EBNF form)
----------------

Quick guide to EBNF

       EBNF is a concise and exact way of describing the grammar
       of a language.  Each EBNF definition is made up of
       production rules.  Eg.

        symbol ::= definition | alternate1 | alternate2 ...

       Each production rule references others and thus makes up a
       grammar for the language.  EBNF also contains the
       following operators, which many readers will recognize
       from regular expressions.  Do not, however, confuse them
       with "wildcard" characters, which have different meanings.

       ?       Means that the preceding symbol (or group of
               symbols) is optional.  That is, it may appear once
               or not at all.

       *       Means that the preceding symbol (or group of
               symbols) may appear zero or more times.

       +       Means that the preceding symbol (or group of
               symbols) may appear one or more times.

       Parentheses may be used to group symbols together.  For
       clarity, we will use single quotes ('') to designate what
       is a verbatim character string (as opposed to a symbol
       name).
                                        (FROM MANPAGE OF sudoers)


macros := '$(url)' | '$(host)' | '$(dir)' | '$(file)' | '$(query)' |
         '$(protocol)' |
         '$(dir,' unsigned (',' signed)? (',' signed)? (',' signed)?')' |
         '$(host,' unsigned (',' signed)? (',' signed)? (',' signed)?')' |
         '$(retrieved_url)' | '$(retrieved_host)' | '$(retrieved_dir)' |
         '$(retrieved_file)' | '$(retrieved_query)' |
         '$(retrieved_protocol)' |
         '$(retrieved_dir,' unsigned (',' signed)? (',' signed)? (',' signed)? ')' |
         '$(retrieved_host,' unsigned (',' signed)? (',' signed)? (',' signed)? ')'
         '$(previous_url)' | '$(previous_host)' | '$(previous_dir)' |
         '$(previous_file)' | '$(previous_query)' |
         '$(previous_protocol)' |
         '$(previous_dir,' unsigned (',' signed)? (',' signed)? (',' signed)? ')' |
         '$(previous_host,' unsigned (',' signed)? (',' signed)? (',' signed)? ')'

string := [a-zA-Z/_-.0-9]([a-zA-Z/_-.0-9?])*

string_macro := '"' (string | macro) '"' | (string | macro) 

url := http://(string_macros)+ | $(protocol)//(string_macros)+

number := [0-9]([0-9])*

signed := ('-')? number

unsigned := number

server_config_list := ('<server>' 'server_entry '</server>')*

server_entry := template_name
                comment
                server_name_list
                (ignore_server_name_list)?
                (ignore_extension_list)?
                sequence

template_name: = '<identifier>' string '</identifier>'

comment := '<comment>' (string|' ')* '</comment>'

server_name_list := '<target-servers>' string (' ' string)* '</identifier>'

ignore_server_name_list := '<ignore-servers>' string (' ' string)* '</ignore-servers>'

ignore_extension_name_list := '<ignore-extensions>' string (' ' string)* '</ignore-extensions>'

sequence := '<sequence>' session_list '</sequence>'

session_list := ('<session>' session_entry '</session>')*

session_enry := (get)? (referer)? (keylink)? (soption)? (postoffsetsize)? (postoffsetstring)?

get := '<get>' url '</get>'

referer := '<referer>' url '</referer>'

keylink := '<keylink>' string_macro (' ' string_macro)* '</keylink>'

soption := '<option>' ('nodown' | 'getkeylink' | 'getkeylinkf' | 'nocookie' | 'noresume')* '</option>'

postoffsetsize := '<post-offset-size>' unsigned '</post-offset-size>'

postoffsetstring := '<post-offset-string>' string '</post-offset-string>'


Supplement
----------
  *about 'soptions':
    nodown      : do not download
    nocookie    : do not send cookie
    noresume    : do not resume
    deletecookie: delete cookie
    getkeylink  : get hyperlink containing key-link(specified in %keylink line)
                  in downloaded file if server does not return content-length.
                  Retrieved url can be accessed by '$(retrieved_url)' macro.
    getkeylinkf : get hyperlink even if server returns content-length.
    readconfg   : re-search Server Template by hostname.

  *abount 'macros':
    if target URL is http://www.hoge.com/foo/bar.html, then:
     $(url) : http://www.hoge.com/foo/bar.html
     $(protocol): http:
     $(host): www.hoge.com
     $(dir) : /foo
     $(file): /bar.html
     $(query):
    $(retrieved_***) is set by executing 'get keylink'(see "abount 'soptions':")
    or by reading location field in HTTP header
    $(previous_***) is pointed to URL of the previous session.

    $(dir, i, j, k, l) represents directory between ith and jth(assuming '1st'
    dir is 0th).
    k, l are optional. If k and l are specified, delete first k chacracters and
    last l characters in $(dir, i, j)
    If j is negative number, the j is set to the end of string
    example:
      if $(dir) is /usr/local/share/locale, then:
       $(dir, 1, 2) is /local/share
       $(dir, 0, 0) is /usr
       $(dir, 1, -1) is /local/share/locale
       $(dir, 5, -1) is <blank>
       $(dir, 0, 0, 1, 0) is usr
    $(host, i, j, k, l), $(retrieved_dir, i, j, k, l) and
    $(retrieved_host, i, j, k, l) are also available
   
  *about 'sessions':
    If multiple sessions are specified, they are executed from top to buttom.
    For example, the sessions are
     <session>
        <get> $(url) </get>
        <keylink> foobar </keylink>
        <option> getkeylink </option>
     </session>
     <session>
        <get> $(retrieved_url) </get>
        <referer> $(previous_url) </get>
     </session>
    then, firstly get $(url) and parse it, then retrieve URL containing
    keyword "foobar" (for example, http://www.abc/dir/foobar.zip).
    Secondly, send a request to get retrieved URL with referer $(previous_url)
    ($(retrieved_url) is http://www.abc/dir/foobar.zip, and
     $(previous_url) is $(url) in this example).


Template
--------
<server>
  <identifier>[write the name of template here]</identifier>
  <comment> [write comment] </comment>
  <target-servers>[write the list of names of servers you want to apply this template]</target-servers>
  <ignore-servers>[write the list of names of servers you do not want to apply this template]</ignore-servers>
  <ignore-extensions>[write the list of extensions you want to ignore]</ignore-extensions>
  <sequence>
    <session>
      <get> [write the url to get] </get>
      <referer> [write the referer] </referer>
      <option> [write the options] </options>
      <keylink> [write the keylinks] </keylink>
      <post-offset-size> [write the size of gabage header] </post-offset-size>
      <post-offset-string> [write the gabage header string] </post-offset-string>
    </session>
  </sequence>
</server>

#you can write multiple sessions.