2.7. 输出

2.7.1. 返回输出文件

某个工具的 outputs（输出）项是运行该工具后应返回的输出参数列表。 每个参数都有一个代表其名称的 id字段，以及描述其有效值类型的 type 字段。

When a tool runs under CWL, the starting working directory is the designated output directory. The underlying tool or script must record its results in the form of files created in the output directory. The output parameters returned by the CWL tool are either the output files themselves, or the result of examining the content of those files.

下例演示怎样返回从 tar 文件中提取的文件。

小技巧

将必要参数传递给 baseCommand

In previous examples, the baseCommand was just a string, with any arguments passed as CWL inputs. Instead of a single string, we can use an array of strings as the value of baseCommand. The first element of the array is the command to run, and any subsequent elements are mandatory command line arguments

tar.cwl

#!/usr/bin/env cwl-runner
cwlVersion: v1.2
class: CommandLineTool
baseCommand: [tar, --extract]
inputs:
  tarfile:
    type: File
    inputBinding:
      prefix: --file
outputs:
  example_out:
    type: File
    outputBinding:
      glob: hello.txt

tar-job.yml

tarfile:
  class: File
  path: hello.tar

接下来，新建一个 tar 文件供本示例使用。

$ touch hello.txt && tar -cvf hello.tar hello.txt
hello.txt

现在，在命令行上结合工具描述和输入对象运行 cwltool:

$ cwltool tar.cwl tar-job.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'tar.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/tar.cwl'
INFO [job tar.cwl] /tmp/i3s25t6t$ tar \
    --extract \
    --file \
    /tmp/rsk9c9gg/stg93a3deb9-7da1-46ad-bc6d-d91aec78451c/hello.tar
INFO [job tar.cwl] completed success
{
    "example_out": {
        "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/hello.txt",
        "basename": "hello.txt",
        "class": "File",
        "checksum": "sha1$da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "size": 0,
        "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/hello.txt"
    }
}INFO Final process status is success

The field outputBinding describes how to set the value of each output parameter.

outputs:
  example_out:
    type: File
    outputBinding:
      glob: hello.txt

The glob field consists of the pattern to match file names in the output directory. This can simply be the file's exact name. But if you don't know the name of the file in advance, you can use a wildcard pattern like glob: '*.txt'.

2.7.2. 捕获标准输出

To capture a tool's standard output stream, add the stdout field with the name of the file where the output stream should go. Then add type: stdout on the corresponding output parameter.

stdout.cwl

#!/usr/bin/env cwl-runner
cwlVersion: v1.2
class: CommandLineTool
baseCommand: echo
stdout: output.txt
inputs:
  message:
    type: string
    inputBinding:
      position: 1
outputs:
  example_out:
    type: stdout

echo-job.yml

message: Hello world!

现在，调用命令 cwltool 并为它提供工具描述和输入对象：

$ cwltool stdout.cwl echo-job.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'stdout.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/stdout.cwl'
INFO [job stdout.cwl] /tmp/d4uehejd$ echo \
    'Hello world!' > /tmp/d4uehejd/output.txt
INFO [job stdout.cwl] completed success
{
    "example_out": {
        "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/output.txt",
        "basename": "output.txt",
        "class": "File",
        "checksum": "sha1$47a013e660d408619d894b20806b1d5086aab03b",
        "size": 13,
        "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/output.txt"
    }
}INFO Final process status is success

2.7.3. 数组输出

您也可以用 glob 将多个输出文件捕获至一个文件数组。

array-outputs.cwl

#!/usr/bin/env cwl-runner
cwlVersion: v1.2
class: CommandLineTool
baseCommand: touch
inputs:
  touchfiles:
    type:
      type: array
      items: string
    inputBinding:
      position: 1
outputs:
  output:
    type:
      type: array
      items: File
    outputBinding:
      glob: "*.txt"

array-outputs-job.yml

touchfiles:
  - foo.txt
  - bar.dat
  - baz.txt

现在，调用命令 cwltool 并为它提供工具描述和输入对象：

$ cwltool array-outputs.cwl array-outputs-job.yml
INFO /opt/hostedtoolcache/Python/3.9.19/x64/bin/cwltool 3.1.20240508115724
INFO Resolved 'array-outputs.cwl' to 'file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/array-outputs.cwl'
INFO [job array-outputs.cwl] /tmp/fafuybud$ touch \
    foo.txt \
    bar.dat \
    baz.txt
INFO [job array-outputs.cwl] completed success
{
    "output": [
        {
            "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/baz.txt",
            "basename": "baz.txt",
            "class": "File",
            "checksum": "sha1$da39a3ee5e6b4b0d3255bfef95601890afd80709",
            "size": 0,
            "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/baz.txt"
        },
        {
            "location": "file:///home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/foo.txt",
            "basename": "foo.txt",
            "class": "File",
            "checksum": "sha1$da39a3ee5e6b4b0d3255bfef95601890afd80709",
            "size": 0,
            "path": "/home/runner/work/user_guide/user_guide/src/_includes/cwl/outputs/foo.txt"
        }
    ]
}INFO Final process status is success

如《YAML 指南》中所述，array-outputs-job.yml 文件中行首为 - 的成员代表数组元素，用以指明我们期待的各个输出。这种格式还可以用在 CWL 描述中表示数组成员。接下来若干章节中会演示这一用法。