From 7e01ee1fa96360b902043a35a0c22c729a95b2b4 Mon Sep 17 00:00:00 2001
From: Nicola Soranzo <nicola.soranzo@earlham.ac.uk>
Date: Thu, 8 Jun 2017 19:48:02 +0100
Subject: [PATCH] Sync galaxy.xsd with latest Galaxy updates

---
 planemo/xml/xsd/tool/galaxy.xsd | 139 +++++++++++++++++++++++++++-----
 1 file changed, 119 insertions(+), 20 deletions(-)

diff --git a/planemo/xml/xsd/tool/galaxy.xsd b/planemo/xml/xsd/tool/galaxy.xsd
index 3ced93719..3d7bc3ef7 100644
--- a/planemo/xml/xsd/tool/galaxy.xsd
+++ b/planemo/xml/xsd/tool/galaxy.xsd
@@ -166,8 +166,8 @@ graphical tool form by setting this to ``false``.</xs:documentation>
           <xs:documentation xml:lang="en">Allows for certain framework
 functionality to be performed on certain types of tools. Normal tools that execute
 typical command-line jobs do not need to specify this, special kinds of tools such
-as [Data Source](https://wiki.galaxyproject.org/Admin/Internals/DataSources) and
-[Data Manager](https://wiki.galaxyproject.org/Admin/Tools/DataManagers) tools should
+as [Data Source](https://galaxyproject.org/admin/internals/data-sources/) and
+[Data Manager](https://galaxyproject.org/admin/tools/data-managers/) tools should
 set this to have values such as ``data_source`` or ``manage_data``.</xs:documentation>
         </xs:annotation>
       </xs:attribute>
@@ -237,7 +237,7 @@ programs or modules that the tool depends upon are included in this tag set.
 When a tool runs, Galaxy attempts to *resolve* these requirements (also called
 dependencies). ``requirement``s are meant to be abstract and resolvable by
 multiple different systems (e.g. [conda](http://conda.pydata.org/docs/), the
-[Galaxy Tool Shed dependency management system](https://wiki.galaxyproject.org/ToolShedToolFeatures#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories),
+[Galaxy Tool Shed dependency management system](https://galaxyproject.org/toolshed/tool-features/#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories),
 or [environment modules](http://modules.sourceforge.net/)).
 
 Read more about dependency resolvers in Galaxy on
@@ -251,7 +251,7 @@ discussed in greater detail
 This example shows a tool that requires the samtools 0.0.18 package.
 
 This package is available via the Tool Shed (see
-[Tool Shed dependency management](https://wiki.galaxyproject.org/ToolShedToolFeatures#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories)
+[Tool Shed dependency management](https://galaxyproject.org/toolshed/tool-features/#Automatic_third-party_tool_dependency_installation_and_compilation_with_installed_repositories)
 ) as well as [Conda](https://docs.galaxyproject.org/en/master/admin/conda_faq.html)
 and can be configured locally to adapt to any other package management system.
 
@@ -296,12 +296,12 @@ resolver.
       <xs:documentation xml:lang="en"><![CDATA[
 
 This tag set is contained within the 'requirements' tag set. Galaxy can be
-configured to run tools within Docker (https://www.docker.com/) containers -
+configured to run tools within [Docker](https://www.docker.com/) containers -
 this tag allows the tool to suggest possible valid Docker containers for this
 tool.
 
 Read more about configuring Galaxy to run Docker jobs
-[here](https://wiki.galaxyproject.org/Admin/Tools/Docker).
+[here](https://galaxyproject.org/admin/tools/docker/).
 
 ]]></xs:documentation>
     </xs:annotation>
@@ -309,7 +309,7 @@ Read more about configuring Galaxy to run Docker jobs
       <xs:extension base="xs:string">
         <xs:attribute name="type" type="ContainerType" use="required">
           <xs:annotation>
-            <xs:documentation xml:lang="en"> This value describes the type of container that the tool may be executed in and currently must be 'docker'. </xs:documentation>
+            <xs:documentation xml:lang="en"> This value describes the type of container that the tool may be executed in and currently must be ``docker``. </xs:documentation>
           </xs:annotation>
         </xs:attribute>
       </xs:extension>
@@ -354,12 +354,16 @@ Read more about configuring Galaxy to run Docker jobs
   <xs:complexType name="Code">
     <xs:annotation>
       <xs:documentation xml:lang="en"><![CDATA[
-**Deprecated** do not use this unless absolutely necessary.
+**Deprecated** Do not use this unless absolutely necessary.
+
+The extensions described here can cause problems using your tool with certain components
+of Galaxy (like the workflow system). It is highly recommended to avoid these constructs
+unless absolutely necessary.
 
 This tag set provides detailed control of the way the tool is executed. This
 (optional) code can be deployed in a separate file in the same directory as the
 tool's config file. These hooks are being replaced by new tool config features
-and methods in the ~/lib/galaxy/tools/__init__.py code file.
+and methods in the [/lib/galaxy/tools/\__init__.py](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/tools/__init__.py) code file.
 
 ### Examples
 
@@ -444,12 +448,95 @@ def get_field_components_options( dataset, field_name ):
     return options
 ```
 
+#### Parameter Validation
+
+This function is called before the tool is executed. If it raises any exceptions the tool execution will be aborted and the exception's value will be displayed in an error message box. Here is an example:
+
+```python
+def validate(incoming):
+    """Validator for the plotting program"""
+    
+    
+    bins = incoming.get("bins","")
+    col = incoming.get("col","")
+
+
+    if not bins or not col:
+        raise Exception, "You need to specify a number for bins and columns"
+
+
+    try:
+        bins = int(bins)
+        col = int(col)
+    except:
+        raise Exception, "Parameters are not integers, columns:%s, bins:%s" % (col, bins)
+
+
+    if not 1<bins<100:
+        raise Exception, "The number of bins %s must be a number between 1 and 100" % bins
+```
+
+This code will intercept a number of parameter errors and return corresponding error messages. The parameter ``incoming`` contains a dictionary with all the parameters that were sent through the web.
+
+#### Pre-job and pre-process code
+
+The signature of both of these is the same:
+
+```python
+def exec_before_job(inp_data, out_data, param_dict, tool):
+def exec_before_process(inp_data, out_data, param_dict, tool):
+```
+
+The ``param_dict`` is a dictionary that contains all the values in the ``incoming`` parameter above plus a number of keys and values generated internally by galaxy. The ``inp_data`` and the ``out_data`` are dictionaries keyed by parameter name containing the classes that represent the data.
+
+Example:
+
+```python
+def exec_before_process(inp_data, out_data, param_dict, tool):
+    for name, data in out_data.items():
+        data.name = 'New name'
+```
+
+This custom code will change the name of the data that was created for this tool to **New name**. The difference between these two functions is that the ``exec_before_job`` executes before the page returns and the user will see the new name right away. If one were to use ``exec_before_process`` the new name would be set only once the job starts to execute.
+
+#### Post-process code
+
+This code executes after the background process running the tool finishes its run. The example below is more advanced one that replaces the type of the output data depending on the parameter named ``extension``:
+
+```python
+from galaxy import datatypes
+def exec_after_process(app, inp_data, out_data, param_dict, tool, stdout, stderr):
+    ext = param_dict.get('extension', 'text')
+    items = out_data.items()   
+    for name, data in items: 
+        newdata = datatypes.factory(ext)(id=data.id)
+        for key, value in data. __dict__.items():
+            setattr(newdata, key, value)
+        newdata.ext = ext
+        out_data[name] = newdata
+```
+
+The content of ``stdout`` and ``stderr`` are strings containing the output of the process.
+
 ]]></xs:documentation>
 
     </xs:annotation>
+    <xs:sequence>
+      <xs:element name="hook" type="CodeHook" minOccurs="0" maxOccurs="unbounded"/>
+    </xs:sequence>
     <xs:attribute name="file" type="xs:string" use="required">
       <xs:annotation>
-        <xs:documentation xml:lang="en">This value is the name of the executable code file, and is called in the exec_before_process(), exec_before_job(), exec_after_process() and exec_after_job()( methods.</xs:documentation>
+        <xs:documentation xml:lang="en">This value is the name of the executable code file, and is called in the ``exec_before_process()``, ``exec_before_job()``, ``exec_after_process()`` and ``exec_after_job()`` methods.</xs:documentation>
+      </xs:annotation>
+    </xs:attribute>
+  </xs:complexType>
+  <xs:complexType name="CodeHook">
+    <xs:annotation>
+      <xs:documentation xml:lang="en">**Deprecated** Map a hook to a function defined in the code file.</xs:documentation>
+    </xs:annotation>
+    <xs:attribute name="exec_after_process" type="xs:string">
+      <xs:annotation>
+        <xs:documentation xml:lang="en">Function defined in the code file to which the ``exec_after_process`` hook should be mapped</xs:documentation>
       </xs:annotation>
     </xs:attribute>
   </xs:complexType>
@@ -519,7 +606,7 @@ The documentation contained here is mostly reference documentation, for
 tutorials on writing tool tests please check out Planemo's
 [Test-Driven Development](https://planemo.readthedocs.io/en/latest/writing_advanced.html#test-driven-development)
 documentation or the much older wiki content for
-[WritingTests](https://wiki.galaxyproject.org/Admin/Tools/WritingTests).
+[WritingTests](https://galaxyproject.org/admin/tools/writing-tests/).
 
 ]]></xs:documentation>
     </xs:annotation>
@@ -1095,7 +1182,7 @@ it may be inconvenient to upload the entiry file and this can be used instead.
       <xs:annotation>
         <xs:documentation xml:lang="en"><![CDATA[
 
-If ``compare`` is set to ``diff``, attempt to decompress both produced output and expected output files if needed before performing the diff. This is useful for testing gzipped outputs that are non-deterministic despite having deterministic decompressed contents. This is available in Galaxy 17.05+ and was introduced in ``Pull Request #3550 <https://github.com/galaxyproject/galaxy/pull/3550>`__.
+If ``compare`` is set to ``diff``, attempt to decompress both produced output and expected output files if needed before performing the diff. This flag is useful for testing gzipped outputs that are non-deterministic despite having deterministic decompressed contents. This is available in Galaxy 17.05+ and was introduced in [pull request #3550](https://github.com/galaxyproject/galaxy/pull/3550).
 
 ]]></xs:documentation>
       </xs:annotation>
@@ -1643,7 +1730,7 @@ conditionally reference ``${input_type.process_obs_metadata}`` with a Cheetah
 
 A common use of the conditional wrapper is to select between reference data
 managed by the Galaxy admins (for instance via
-[data managers](https://wiki.galaxyproject.org/Admin/Tools/DataManagers)
+[data managers](https://galaxyproject.org/admin/tools/data-managers/)
 ) and
 history files. A good example tool that demonstrates this is
 the [Bowtie 2](https://github.com/galaxyproject/tools-devteam/blob/master/tools/bowtie2/bowtie2_wrapper.xml) wrapper.
@@ -1882,7 +1969,7 @@ variable:
 --color $adv.plot_color
 ```
 
-Further examples can be found in the [test case](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/section.xml) from [PR #35](https://github.com/galaxyproject/galaxy/pull/35)
+Further examples can be found in the [test case](https://github.com/galaxyproject/galaxy/blob/master/test/functional/tools/section.xml) from [pull request #35](https://github.com/galaxyproject/galaxy/pull/35).
 ]]></xs:documentation>
     </xs:annotation>
     <xs:sequence>
@@ -2572,7 +2659,7 @@ For newer tools with ``profile>=16.04``, the default behavior is ``exit_code``.
 Legacy tools default to ``default`` behavior described above (erroring if the tool
 produces any standard error output).
 
-See [PR 117](https://github.com/galaxyproject/galaxy/pull/117) for more implementation
+See [pull request 117](https://github.com/galaxyproject/galaxy/pull/117) for more implementation
 information and discussion on the ``detect_errors`` attribute.
 
 #### ``strict``
@@ -3029,7 +3116,7 @@ specified by the ``skip`` attribute.</xs:documentation>
             <xs:documentation xml:lang="en">Tool data table name to check against
 if ``type`` is ``dataset_metadata_in_tool_data``. See the documentation for
 [tool data tables](https://wiki.galaxyproject.org/Admin/Tools/Data%20Tables)
-and [data managers](https://wiki.galaxyproject.org/Admin/Tools/DataManagers) for
+and [data managers](https://galaxyproject.org/admin/tools/data-managers/) for
 more information.</xs:documentation>
           </xs:annotation>
         </xs:attribute>
@@ -4888,16 +4975,17 @@ for more examples.
 ]]></xs:documentation>
     </xs:annotation>
     <xs:sequence/>
-    <xs:attribute name="input" type="xs:string" use="required">
+    <xs:attribute name="input" type="xs:string">
       <xs:annotation>
-        <xs:documentation xml:lang="en">This value must be the attribute name of
+        <xs:documentation xml:lang="en">This attribute should be the name of
 the desired input parameter (e.g. ``input="out_format"`` above).</xs:documentation>
       </xs:annotation>
     </xs:attribute>
     <xs:attribute name="value" type="xs:string" use="required">
       <xs:annotation>
-        <xs:documentation xml:lang="en">This value must also be an attribute
-name of an input parameter (e.g. ``value="interval"`` above).</xs:documentation>
+        <xs:documentation xml:lang="en">This must be a possible value of the ``input``
+parameter (e.g. ``value="interval"`` above), or of the deprecated ``input_dataset``'s
+attribute.</xs:documentation>
       </xs:annotation>
     </xs:attribute>
     <xs:attribute name="format" type="xs:string" use="required">
@@ -4908,6 +4996,16 @@ name of an input parameter (e.g. ``value="interval"`` above).</xs:documentation>
 for a list of supported formats.</xs:documentation>
       </xs:annotation>
     </xs:attribute>
+    <xs:attribute name="input_dataset" type="xs:string" gxdocs:deprecated="true">
+      <xs:annotation>
+        <xs:documentation xml:lang="en">Deprecated.</xs:documentation>
+      </xs:annotation>
+    </xs:attribute>
+    <xs:attribute name="attribute" type="xs:string" gxdocs:deprecated="true">
+      <xs:annotation>
+        <xs:documentation xml:lang="en">Deprecated.</xs:documentation>
+      </xs:annotation>
+    </xs:attribute>
   </xs:complexType>
 
   <xs:complexType name="Citations">
@@ -5068,6 +5166,7 @@ and ``bibtex`` are the only supported options.</xs:documentation>
     </xs:annotation>
     <xs:restriction base="xs:string">
       <xs:enumeration value="empty_dataset"/>
+      <xs:enumeration value="empty_extra_files_path"/>
       <xs:enumeration value="expression"/>
       <xs:enumeration value="regex"/>
       <xs:enumeration value="in_range"/>