<!--
  ~ The MIT License (MIT)
  ~
  ~ Copyright (c) 2007-2015 Broad Institute
  ~
  ~ Permission is hereby granted, free of charge, to any person obtaining a copy
  ~ of this software and associated documentation files (the "Software"), to deal
  ~ in the Software without restriction, including without limitation the rights
  ~ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  ~ copies of the Software, and to permit persons to whom the Software is
  ~ furnished to do so, subject to the following conditions:
  ~
  ~ The above copyright notice and this permission notice shall be included in
  ~ all copies or substantial portions of the Software.
  ~
  ~
  ~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  ~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  ~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  ~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  ~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  ~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  ~ THE SOFTWARE.
  -->

<!--

cli_plugin.dtd

An XML DTD specifying a command line interface plugin for IGV which accepts
some number of inputs from the user (which may be data loaded into IGV at runtime),
and feeds those inputs to a command line program to create a new track.

2012-Aug-21

Version Alpha
-->

<!--
cli_plugin, the root element under which all elements are contained
api_version
	The API version of IGV this plugin targets. Current
name
	A human readable name of this plugin (presented to users)
id
	A unique ID for this plugin
plugin_version
  	Your version string. The version of the plugin itself
plugin_url
    URL where the user can go for help / installation instructions.
 -->
<!ELEMENT cli_plugin (tool+)>
<!ATTLIST cli_plugin api_version (alpha) #REQUIRED
    name CDATA #REQUIRED
    id CDATA #REQUIRED
    plugin_url CDATA #IMPLIED
    plugin_version CDATA #IMPLIED>

<!-- tool element
Each plugin can have multiple tools. These are parsed separately
by IGV, just combined into 1 file for convenience of distribution.
Each tool represents a command line executable.
Attributes
name
    The name of the tool as it appears to the user
defaultPath
    Default path to the executable. This can be an absolute path, if it
    is a relative path the users PATH environment variable
    is checked for the relevant tool. The developer is reminded
    that the PATH environment variable can vary depending on how
    IGV is launched.  This value is overridden if the user
    changes it in settings

description:
    Human readable description of the tool

visible
    Whether the tool should show up in the tools menu.
    Default is "true", because if "false" there's no way
    for the user to access it. Intended to be used by developers
toolUrl:
    url where the user can go for help on this command line tool.
forbidEmptyOutput:
    If the tool requires at least 1 feature, mark this true.
    A dummy feature will be written out
-->
<!ELEMENT tool (default_arg?, default_output?, msg*, command+)>
<!ATTLIST tool name CDATA #REQUIRED
    defaultPath CDATA #IMPLIED
    description CDATA #IMPLIED
    visible (true|false) "true"
    toolUrl CDATA #IMPLIED
    helpUrl CDATA #IMPLIED
    forbidEmptyOutput (true|false) "false">

<!--
msg
    Commands used to launch the tool. For instance,
    if it's a jar file, "java -jar".
    -->
<!ELEMENT msg (#PCDATA)>

<!-- default_arg element
Default properties for each command.
If no arguments are provided, the defaults are used.
If ANY arguments are provided, no other defaults are used.-->
<!ELEMENT default_arg (arg+)>

<!-- default_output element
Default properties for each command.
If outputs are provided, the defaults are used.
If ANY outputs are provided, no other defaults are used.-->
<!ELEMENT default_output (output+)>

<!-- command element
Different commands available to the provided executable.
Attributes
 name
    Human readable name
 cmd
    The exact text passed to the command line for this command-->
<!ELEMENT command (arg*, output*)>
<!ATTLIST command name CDATA #REQUIRED
    cmd CDATA "">

<!-- output element
A plugin can return multiple things.
Right now we only accept outputs of type "track"
-->
<!ELEMENT output (parser?)>
<!ATTLIST output name CDATA "Output Track"
    type (FeatureTrack|DataSourceTrack|VariantTrack) #IMPLIED
    defaultValue CDATA #IMPLIED>


<!-- parser element
Consists of instructions for telling IGV how to parse the output
returned from the tool.
Attributes
strict
    If true (default), throw an error if we hit a line
    that cannot be parsed. If false, just skip that line.
format
    The format returned. Must be a file extension readable by
    IGV.
source
    The file from which to read output, or "stdout" if
    the tool returns data in the standard output stream (default)
decodingCodec
    Class used for decoding the output.
    Takes precedence over format if both provided
-->
<!ELEMENT parser (libs*)>
<!ATTLIST parser
    strict (true|false) "true"
    format CDATA "bed"
    source CDATA "stdout"
    decodingCodec CDATA #IMPLIED>

<!--
libs
    Location (relative to the directory in which the xml file is located)
    to look for the decoding_codec. Can be URLs, absolute, or
    paths relative to the location of the XML spec file
-->
<!ELEMENT libs (#PCDATA)>


<!-- arg element
Represents arguments to the command line interface which require user input
Attributes

name
    Name shown to user

cmd_arg
    If supplied, will be placed before the
    input argument on the command line. In the case of tracks,
    which are saved to a temporary file, it will be placed before
    the name of the file

type
    What type of input the user is expected to provide,
    whether text, a track, etc. Data from tracks uses
    encoding_codec to be written to file

defaultValue
    When the argument is first displayed to the user, the default value.

id
    Unique identifier for this argument. Can be used by later
    arguments to refer to this value

output
    optional, default true
    If true this argument is written to the command line
    If false it isn't. This is so we can feed inputs to a different command

visible
    optional, default true
    Whether the argument is visible to the user.
    Useful if we just want to pass an argument on the command line always

encodingCodec
    Optional; default is BED format
    Fully qualified class name to use for encoding features to strings.
    Only applies to data arguments. Must implement FeatureEncoder interface.

    -->
<!ELEMENT arg (libs*)>
<!ATTLIST arg
    name CDATA #REQUIRED
    cmd_arg CDATA ""
    type (BOOL|TEXT|LONGTEXT|FEATURE_TRACK|MULTI_FEATURE_TRACK|ALIGNMENT_TRACK|VARIANT_TRACK|LOCUS) #REQUIRED
    defaultValue CDATA #IMPLIED
    id ID #IMPLIED
    output (true|false|TRUE|FALSE) "true"
    visible (true|false) "true"
    encodingCodec CDATA #IMPLIED
    remembered CDATA #IMPLIED>

