*
*  builder.py: Simple PDB file cooker for WM3D
*

About:
  Flash viewer WM3D does not read PDB files, it understands only its own
  XML data instead. This python program, builder.py, is a pdb2xml
  converter for wm3d.

  This program can be used either in interactive or non-interactive mode.
  The interactive mode uses stdin input by user and works like a shell,
  although available command are not so many. Non-interactive mode uses
  only command line arguments given to the program.

  XML data are outputted to stdout in both of two modes.

  This program is also used in VMD plugin.

Basic Idea:
  A simple way to use this program is summarized as following.

  1. Load PDB data.
  2. Register querys.
  3. Select atoms according to the registered querys.
  4. Output XML (or PDB) data to stdout.

  Users must tell the PDB file name to the programfirst. Next you may
  register your query(s) such as residue index or atom names to the
  program. Then, you tell the program to search ATOMs which match with
  your query(s). It is to be noted that you should call "select" with empty
  qureys if you want to choose all the atoms. Finally you tell it to write
  data of selected atoms.

  For example, imagine you have PDB file "p.pdb" and you want XML data of
  GLY residues in it. This request is accomplished by the following ways.
  (Output xml file is tentatively named "p.xml".)

  Interactive-mode:
    (lines begin with "%" are shell prompt,
                 with ">>" are output from program )

    % ./builder.py > p.xml
    >> entering command line mode.
    >> type "exit" or press Ctrl+D to exit.
    >> type "help" to show list of commands.
    load p.pdb
    >> read xxx atoms from the pdb file
    res GLY
    >> add residue query to the selection.
    select
    >> select yyy atoms
    genatom
    >> finished to generate atoms.

  Non-interactive-mode:
    % ./builder.py -p p.pdb -r GLY -s -x > p.xml

  Note that "p.xml" file is not a valid XML data for WM3D now. You should
  manually add the <WMXML> and </WMXML> tags at the begining and end of the
  file.

Sample Usage:

  1. Select GLY, ALA, PHE residues from PDB file:
    ###### sample input ###########
    load p.pdb
    res GLY ALA PHE
    select
    genatoms
    ################################

    "res" command accepts multiple arguments. They are dealed with "OR"
    fashion.

  2. Select alpha carbons (CA) of MET:
    ###### sample input ###########
    load p.pdb
    res MET
    select
    atom CA
    select
    genatoms
    ################################

    Atoms can be selected by "atom" command like "res" command.
    If you want to select atoms in "AND" fashion, you should call "select"
    command multiple times. In this case, all the atoms in MET residues are
    selected first. "CA" atoms in the MET residues is then selected.

  3. Select atoms of name "CG*" in residue 1-100:
    ###### sample input ###########
    load p.pdb
    res 1-100
    select
    atom CG*
    select
    genatoms
    ################################

    "atom" and "res" command accepts the value range and regular
    expressions. 100-109 is valid, but 10? is not valid, since the regular
    expressions are available only for atom/residue-names, not for
    atom/residue index.

    valid:     res 100 101 102 103 104 105 106 107 108 109
    valid:     res 100-109
    NOT valid: res 10?

Command List:

   Action                |     command line     |     interactive
   -----------------------------------------------------------------------
   load pdb file         |  --load [file]       |  load [file]
                         |  --pdb [file]        |  pdb [file]
                         |  -l [file]           |  l [file]
                         |  -p [file]           |  p [file]
   -----------------------------------------------------------------------
   clear selection       |  --clear             |  clear
                         |  -c                  |  c
   -----------------------------------------------------------------------
   clear pdb data        |  --allclear          |  allclear
                         |  -C                  |  ac
   -----------------------------------------------------------------------
   register atom query   |  --atom [query]      |  selectatom [query]
                         |  -a [query]          |  atom [query]
                         |                      |  a [query]
   -----------------------------------------------------------------------
   register res query    |  --residue [query]   |  selectresidue [query]
                         |  -r [query]          |  selectresid [query]
                         |                      |  selectres [query]
                         |                      |  residue [query]
                         |                      |  resid [query]
                         |                      |  res [query]
                         |                      |  r [query]
   -----------------------------------------------------------------------
   register mol query    |  --molecule [query]  |  selectmolecule [query]
   (not meaningful now)  |  -m [query]          |  selectmol [query]
                         |                      |  molecule [query]
                         |                      |  mol [query]
                         |                      |  m [query]
   -----------------------------------------------------------------------
   select atoms          |  --select            |  select
   (querys are cleared   |  -s                  |  sel
    after the selection) |                      |  s
   -----------------------------------------------------------------------
   generate ATOMs        |  --gatom             |  genatoms [options]
   (<ATOM> in wm3d XML)  |  -x                  |  genatom [options]
               *1        |  -X [options]        |  ga [options]
   -----------------------------------------------------------------------
   generate BONDs        |  --gbond             |  genbonds [options]
   (<BOND> in wm3d XML)  |  -y                  |  genbond [options]
               *1        |  -Y [options]        |  gb [options]
   -----------------------------------------------------------------------
   generate RIBBON/COIL  |  --gribbon           |  genchains
   (<CHAIN> in wm3d XML) |  -z                  |  genchain
               *2        |                      |  gc
   -----------------------------------------------------------------------
   generate COILs        |  --gcoil             |  gencoils
   (<CHAIN> in wm3d XML) |  -Z                  |  gencoil
                         |                      |  gco
   -----------------------------------------------------------------------
   write PDB data        |  --write             |  writepdb
                         |  -w                  |  write
                         |                      |  w
   -----------------------------------------------------------------------
   exit program          |                      |  exit
                         |                      |  quit
                         |                      |  q
                         |                      |  ^D

   *1 atoms must be predefined in file "DEFAULTS" (in this directory)
   *2 stride is to be used for secondary structure assignment.
      you should set the correct path of it in "system.py"
