Skip to content
This repository was archived by the owner on Jun 9, 2020. It is now read-only.

Commit 2f458ef

Browse files
khillionkhillion
committed
update user guide
1 parent 5f44d8d commit 2f458ef

File tree

7 files changed

+237
-95
lines changed

7 files changed

+237
-95
lines changed

‎doc/source/user_guide.rst

+101-5
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,14 @@
66
User Guide
77
**********
88

9-
This user guide aims to help you through the different steps to build your CWL tool with
9+
This user guide assumes you have at least some basic knowledge about CWL.
10+
11+
.. Note::
12+
Here is a `CWL user guide`_ for an introduction to tool and workflows wrappers.
13+
14+
.. _`CWL user guide`: https://www.commonwl.org/user_guide/
15+
16+
The aim is to help you through the different steps to build your CWL tool with
1017
python-cwlgen.
1118

1219
.. Note::
@@ -16,15 +23,104 @@ python-cwlgen.
1623

1724
Basic example
1825
-------------
19-
Through this little tutorial, we will go step by step through the example you can `find on Github`_.
26+
Through this little tutorial, we will go step by step through the example you can `find on Github`_. It aims to wrap the `grep` command.
2027

2128
.. _`find on Github`: https://github.com/common-workflow-language/python-cwlgen/blob/master/examples/example.py
2229

2330
Initialize your tool
2431
""""""""""""""""""""
2532

26-
Add an input
27-
""""""""""""
33+
You need to initialize a `CommandLineTool` object
34+
35+
.. code-block:: python
36+
37+
import cwlgen
38+
cwl_tool = cwlgen.CommandLineTool(tool_id='grep',
39+
label='print lines matching a pattern',
40+
base_command='grep')
41+
42+
Now that you have your object, you can attach the different elements of a tool description.
43+
44+
Add Inputs
45+
""""""""""
46+
47+
Now we need to add inputs to our tool. We are going to only wrap a simple version of the `grep` command with a input file and a pattern.
48+
49+
First the input file:
50+
51+
.. code-block:: python
52+
53+
file_binding = cwlgen.CommandLineBinding(position=2)
54+
input_file = cwlgen.CommandInputParameter('input_file',
55+
param_type='File',
56+
input_binding=file_binding,
57+
doc='input file from which you want to look for the pattern')
58+
cwl_tool.inputs.append(input_file)
59+
60+
And finally the pattern:
61+
62+
.. code-block:: python
63+
64+
pattern_binding = cwlgen.CommandLineBinding(position=1)
65+
pattern = cwlgen.CommandInputParameter('pattern',
66+
param_type='string',
67+
input_binding=pattern_binding,
68+
doc='pattern to find in the input file')
69+
cwl_tool.inputs.append(pattern)
70+
71+
.. Note::
72+
You can specify more information concerning your inputs: `Input documentation`_
73+
74+
.. _`Input documentation`: http://python-cwlgen.readthedocs.io/en/latest/classes.html#input-and-outputs
75+
76+
This is it for the inputs, now let's add some outputs and the description will be ready to be tested.
2877

29-
Add an output
78+
Add an Output
3079
"""""""""""""
80+
81+
The only output which is retrieved in our example is a File with the line containing the pattern. Here is how to add this output:
82+
83+
.. code-block:: python
84+
85+
output = cwlgen.CommandOutputParameter('output',
86+
param_type='stdout',
87+
doc='lines found with the pattern')
88+
cwl_tool.outputs.append(output)
89+
# Now specify a name for your output file
90+
cwl_tool.stdout = "grep.txt"
91+
92+
Add Documentation and Metadata
93+
""""""""""""""""""""""""""""""
94+
95+
You can ask bunch of information and metadata concerning your tool.
96+
For instance you can add some documentation:
97+
98+
.. code-block:: python
99+
100+
cwl_tool.doc = "grep searches for a pattern in a file."
101+
102+
For the metadata:
103+
104+
.. code-block:: python
105+
106+
metadata = {'name': 'grep',
107+
'about' : 'grep searches for a pattern in a file.'}
108+
cwl_tool.metadata = cwlgen.Metadata(**metadata)
109+
110+
Write your tool
111+
"""""""""""""""
112+
113+
Finally, you can export your tool description with the `export()` method.
114+
115+
.. code-block:: python
116+
117+
cwl_tool.export() # On STDOUT
118+
cwl_tool.export(outfile="grep.cwl") # As a file (grep.cwl)
119+
120+
You can then try your tool description (using `cwltool`_ for instance):
121+
122+
.. _`cwltool`: https://github.com/common-workflow-language/cwltool/
123+
124+
.. code-block:: bash
125+
126+
cwltool grep.cwl --input_file underdog_lyrics.txt --pattern lost

‎examples/example.cwl

-35
This file was deleted.

‎examples/example.py

-55
This file was deleted.

‎examples/grep.cwl

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
#!/usr/bin/env cwl-runner
2+
3+
$namespaces: {s: http://schema.org/}
4+
arguments: []
5+
baseCommand: grep
6+
class: CommandLineTool
7+
cwlVersion: v1.0
8+
doc: |-
9+
grep searches for a pattern in a file.
10+
id: grep
11+
inputs:
12+
input_file:
13+
doc: input file from which you want to look for the pattern
14+
inputBinding: {loadContents: false, position: 2, separate: true, shellQuote: true}
15+
type: File
16+
pattern:
17+
doc: pattern to find in the input file
18+
inputBinding: {loadContents: false, position: 1, separate: true, shellQuote: true}
19+
type: string
20+
label: print lines matching a pattern
21+
outputs:
22+
output: {doc: lines found with the pattern, type: stdout}
23+
s:about: grep searches for a pattern in a file.
24+
s:name: grep
25+
stdout: grep.txt

‎examples/grep.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Feels like I'm lost in a moment
2+
It feels like I'm lost in a moment

‎examples/grep_example.py

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
#!/usr/bin/env python
2+
3+
## Author(s): Kenzo-Hugo Hillion
4+
## Contact(s): [email protected]
5+
## Python version: 3.6.0
6+
## Creation : 12-30-2016
7+
8+
'''
9+
Example of usage of the cwlgen library
10+
'''
11+
12+
########### Import ###########
13+
14+
import cwlgen
15+
16+
if __name__ == "__main__":
17+
18+
# Create a tool
19+
cwl_tool = cwlgen.CommandLineTool(tool_id='grep',
20+
label='print lines matching a pattern',
21+
base_command='grep')
22+
23+
# Add 2 inputs (input file and pattern)
24+
file_binding = cwlgen.CommandLineBinding(position=2)
25+
input_file = cwlgen.CommandInputParameter('input_file',
26+
param_type='File',
27+
input_binding=file_binding,
28+
doc='input file from which you want to look for the pattern')
29+
cwl_tool.inputs.append(input_file)
30+
pattern_binding = cwlgen.CommandLineBinding(position=1)
31+
pattern = cwlgen.CommandInputParameter('pattern',
32+
param_type='string',
33+
input_binding=pattern_binding,
34+
doc='pattern to find in the input file')
35+
cwl_tool.inputs.append(pattern)
36+
37+
# Add 1 output
38+
output = cwlgen.CommandOutputParameter('output',
39+
param_type='stdout',
40+
doc='lines found with the pattern')
41+
cwl_tool.outputs.append(output)
42+
cwl_tool.stdout = "grep.txt"
43+
44+
# Add documentation
45+
cwl_tool.doc = "grep searches for a pattern in a file."
46+
47+
# Add Metadata
48+
metadata = {'name': 'grep',
49+
'about' : 'grep searches for a pattern in a file.'}
50+
cwl_tool.metadata = cwlgen.Metadata(**metadata)
51+
cwl_tool.metadata = cwlgen.Metadata(**metadata)
52+
53+
# Write in an output file
54+
#cwl_tool.export()
55+
cwl_tool.export("grep.cwl")

‎examples/underdog_lyrics.txt

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
Kill me if you dare
2+
Hold my head up everywhere
3+
Keep myself riding down this train
4+
I'm the underdog
5+
Live my life like a lullaby
6+
I keep myself riding on this train
7+
I keep myself riding on this train
8+
Love in technicolor, sprayed out on walls
9+
Well I've been pounding at the pavement
10+
'Til there's nothing at all
11+
I got my cloak and dagger
12+
In a bar room brawl
13+
See the local loves a fighter
14+
Loves a winner to fall
15+
Feels like I'm lost in a moment
16+
But I'm always losing to win
17+
And I can't get away from the moment
18+
Seems like it's time to begin
19+
Kill me if you dare
20+
Hold my head up everywhere
21+
Keep myself riding on this train
22+
I'm the underdog
23+
Live my life on a lullaby
24+
I keep myself riding on this train
25+
I keep myself riding on this train
26+
It don't matter
27+
I won't do what you say
28+
No money and no power
29+
I won't go your way
30+
I can't take for the people
31+
They don't matter at all
32+
Well I've been waiting in the fuckin' shadows
33+
'Til the day that you fall
34+
It feels like I'm lost in a moment
35+
But I'm always losing to win
36+
Can't get away from the moment
37+
Seems like it's time to begin
38+
Kill me if you dare
39+
Hold my head up everywhere
40+
Keep myself riding on this train
41+
But I'm the underdog
42+
Live my life on a lullaby
43+
I keep myself riding on this train
44+
So tell me if you're down
45+
Throw your weapons to the ground
46+
I keep myself riding on this train
47+
Paper on the wire
48+
Sold your soul for another one
49+
I keep myself riding on this train
50+
(Okay Leicester)
51+
I keep myself riding on this train
52+
53+
Songwriters: Sergio Pizzorno
54+
Underdog lyrics © Sony/ATV Music Publishing LLC

0 commit comments

Comments
 (0)