Class CommandLine

                object --+        
                         |        
 argparse._AttributeHolder --+    
                             |    
                object --+   |    
                         |   |    
argparse._ActionsContainer --+    
                             |    
       argparse.ArgumentParser --+
                                 |
                                CommandLine

Use this class to define common command line arguments such input cms
file, input trajectory, output file base name, trajectory slicing option,
and so on.

After calling L{parse_args} method, you will have those arguments parsed
properly, and you will get the L{cms.Cms} object, the L{msys.System} object,
and the trajectory object (sliced properly), automatically.

You can use the C{spec} argument to custom your command line interface.
Examples:

  1:
  spec = REQUIRE_MSYS_CMS + REQUIRE_TRJ + REQUIRE_OUT + SLICE_TRJ
  # This will give you the following:
  #   cms  - First positional argument for cms input, and when it's parsed,
  #          you will get both msys and cms models.
  #   trj  - Second positional argument for trajectory input
  #   out  - Third positional argument for output base name
  #   -slice-trj
  #        - Option for slicing trajectory

  2:
  spec = REQUIRE_CMS_ONLY + REQUIRE_TRJ + REQUIRE_OUT + SLICE_TRJ
  # Similar to the first example, but parsing the cms input file will return
  # only the cms model.

  3:
  spec = REQUIRE_CMS_ONLY + OPTIONAL_TRJ + REQUIRE_OUT + SLICE_TRJ
  # This will give you the following:
  #   cms  - First positional argument for cms input, and when it's parsed,
  #          you will get the cms models.
  #   out  - Second positional argument for output base name
  #   -trj - Option for trajectory input
  #   -slice-trj
  #        - Option for slicing trajectory

Other standard options:
  -ref-mae  Reference geometry from given .mae or .cms file. After parsing,
            the .ref_mae attribute will provide
            C{(structure.Structure, str)}, where the first element is the
            C{Structure} object of the file and the second the file's name.
            If this option is unspecified, the attribute' value will be
            C{None}.
            spec: REF_MAE
  -ref-frame
            Reference geometry from a trajectory frame. After parsing, the
            .ref_frame attribute will provide C{(traj.Frame, int)}, where
            the first element is the specified frame and the second the
            index of the frame. If this option is overridden by -ref-mae, or
            if the trajectory is not provided, the attribute's value will
            be C{None}.
            spec: REF_FRAME

Usage example:

In the python script:

   def _get_cml():
       cml = cui.CommandLine(spec=(cui.REQUIRE_MSYS_CMS + cui.REQUIRE_TRJ +
                                   cui.SLICE_TRJ + cui.REQUIRE_OUT + cui.JC),
                             description="my script")
       cml.add_argument(...)
       # Other application-specific options.

       return cml

   def get_job_spec_from_args(argv):
       return _get_cml().get_job_spec(argv)[0]

The standard in-/output file options will be automatically registered for
jobcontrol to transfer. If you have non-standard in-/output files, you can
register them by yourself, for example:

   def get_job_spec_from_args(argv):
       _, builder = _get_cml().get_job_spec(argv)
       cui.jc_reg_input(builder, "auxiliary_file")
       cui.jc_reg_input(builder, "data/auxiliary_file_in_a_dir")
       cui.jc_reg_output(builder, "another_output.dat")
       return builder.getJobSpec()

@rtype: (L{launchapi.JobSpecification},
         L{launchapi.JobSpecificationArgsBuilder})