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

書式(EBNF形式)
----------------

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>'

補足
----
  about 'soptions':
    nodown      : ダウンロードしない
    nocookie    : Cookieを送信しない
    deletecookie: Cookieを削除する
    noresume    : レジュームしない
    getkeylink  : ファイルからkeylinkを含む用いてhyperlinkを取得する。
　　　　　　　　　これはwebサーバーがcontent-lengthを返さなかった時のみ行う。
    getkeylinkf : webサーバーがcontent-lengthを返した時もkeylinkを含むhyper-
                 linkの取得をする。
    readconfig  : 現在のホストネームでServer Templateを再度検索する。

  abount 'macros':
    アイテムのURLがhttp://www.hoge.com/foo/bar.htmlの場合、
     $(url) : http://www.hoge.com/foo/bar.html
     $(protocol): http:
     $(host): www.hoge.com
     $(dir) : /foo
     $(file): /bar.html
     $(query):
    $(retrieved_***)はoptionに'getkeylink'または'getkeylinkf'を指定したとき，
    またはHTTPヘッダーのlocationフィールドを読み込んだ時に設定される。
    $(previous_***)は一つ前のセッションでGETしたURLです．

   $(dir, i, j, k, l)はi番目からj番目までのディレクトリを指す(0番目から数える)
   。
   k,l はオプションで、指定すると、$(dir, i, j)で得られた文字列の最初から
   k文字、後ろからl文字削ります。
   jが-1ならi番目から最後までのディレクトリとなる。
   例:
      $(dir)が/usr/local/share/localeの場合:
       $(dir, 1, 2) is /local/share
       $(dir, 0, 0) is /usr
       $(dir, 1, -1) is /local/share/locale
       $(dir, 5, -1) is <空白>
       $(dir, 0, 0, 1, 0) is usr
   $(host, i, j, k, l), $(retrieved_dir, i, j, k, l),
   $(retrieved_host, i, j, k, l)も使用できる。
   
  about 'sessions':
     sessionは複数指定した場合，上から順に実行する。例えば、

     <session>
        <get> $(url) </get>
        <option> getkeylink </option>
        <keylink> foobar </keylink>
     </session>
     <session>
        <get> $(retrieved_url) </get>
        <referer> $(previous_url) </referer>
     </session>

     の場合、まず、$(url)をリクエストし、その結果取得したファイルから
     文字列"foobar"を含むハイパーリンクを抽出する。このハイパーリンクは
     $(retrieved_url)で参照できる。
     そして$(retrieved_url)のGET要求をrefererを$(previous_url)にして
     送信する. この例では$(previous_url)は$(url)である.

     CGIによる偽ダウンロードページを処理するにはsessionを複数指定する
     必要があるだろう.

Template
--------
<server>
  <name> [テンプレートの名前] </name>
  <comment> [テンプレートの説明] </comment>
  <target-servers> [テンプレートを適用するサーバー(ドメイン)] </target-servers>
  <ignore-servers> [テンプレートを適用したくないサーバー(ドメイン)] </ignore-servers>
  <ignore-extensions> [テンプレートを適用しない拡張子を指定] </ignore-extensions>
  <sequence>
    <session>
      <get> [リクエストするURL] </get>
      <referer> [リファラー] </referer>
      <option> [オプション(soptionをみてください)] </option>
      <keylink> [keylink文字列] </keylink>
      <post-offset-size> [オフセットサイズ] </post-offset-size>
      <post-offset-string> [オフセット文字列] </post-offset-string>
    </session>
  </sequence>
</server>