Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding more text for exclusive vs inclusive parameters and added diagram #384

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Adding more text for exclusive vs inclusive parameters and added diagram #384

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added src/_static/images/diagrams/inclusive_v_exclusive.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
26 changes: 18 additions & 8 deletions src/topics/inputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,21 @@ You can specify arrays of arrays, arrays of records, and other complex types.

## Inclusive and Exclusive Inputs

Sometimes an underlying tool has several arguments that must be provided
together (they are dependent) or several arguments that cannot be provided
together (they are exclusive). You can use records and type unions to group
Sometimes an underlying tool has several arguments that must all be provided
together (they are inclusive/dependent) or several arguments that cannot be provided
together, only one of the arguments can be provided (they are exclusive). You can use records and type unions to group
parameters together to describe these two conditions.

```{image} /_static/images/diagrams/inclusive_v_exclusive.png
:name: inclusive_v_exclusive-diagram
:width: 600px
:align: center
```


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the extra blank lines are not necessary. This is not really important, but we tried to remove unnecessary blank lines before, so probably better if we can avoid adding extra lines that are not necessary.

With cwltool, if not all inclusive arguments are provided, an error is thrown.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other pages & paragraphs cwltool appears formatted as cwltool (the command). We should probably use that here too for consistency (although I noticed there are some places where it's written without the formatting).

If multiple exclusive arguments are provided, the first one is used and the rest are ignored.

```{literalinclude} /_includes/cwl/inputs/record.cwl
:language: cwl
:caption: "`record.cwl`"
Expand All @@ -212,7 +222,7 @@ parameters together to describe these two conditions.
:emphasize-lines: 6-7
```

In the first example, you can't provide `itemA` without also providing `itemB`.
In the first example, you can't provide `itemA` without also providing `itemB`, or an error is thrown. This is because they are inclusive (dependent) parameters. If you provide one, you must provide the other.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably better to break this line to make it shorter like the other ones (regardless of 80 or 120 limits).

This is useful to visualize diffs with git or GitHub UI: https://sembr.org/


```{literalinclude} /_includes/cwl/inputs/record-job2.yml
:language: yaml
Expand All @@ -230,8 +240,8 @@ $ cat output.txt
-A one -B two -C three
```

In the second example, `itemC` and `itemD` are exclusive, so only the first
matching item (`itemC`) is added to the command line and remaining item (`itemD`) is ignored.
In the second example, `itemC` and `itemD` are exclusive, but `record-job2.yml` provides both arguments, so only the first
matching item provided (`itemC`) is added to the command line and remaining item (`itemD`) is ignored.

```{literalinclude} /_includes/cwl/inputs/record-job3.yml
:language: yaml
Expand All @@ -249,8 +259,8 @@ $ cat output.txt
-A one -B two -D four
```

In the third example, only `itemD` is provided, so it appears on the
command line.
In the third example, `record-job3.yml` only provides `itemD`, so `itemD` is what appears on the
command line.

### Exclusive Input Parameters with Expressions

Expand Down