2.1. YAMLガイド#
YAMLは、コンピュータと人間の両方が読むことができるように設計されたファイル形式です。本ガイドでは、CWL定義や入力パラメータファイルを書く際に関連するYAMLの機能を紹介します。
注釈
すでにYAMLに慣れている方は、このセクションを読み飛ばしてもかまいません。
2.1.1. 目次#
2.1.2. キーバリューペア#
基本的に、YAML で書かれたファイルは_キーと値のペア_ のセットで構成されています。各ペアはkey: value として記述され、: の後に空白が必要です。CWLファイルのキー名には、空白を含めるべきではありません。camelCase は、CWL仕様で特別な意味を持つ複数語のキー名、それ以外はアンダースコアのキー名として使用します。例えば：
first_name: Bilbo
last_name: Baggins
age_years: 111
home: Bag End, Hobbiton
上記のYAMLは4つのキー -first_name,last_name,age_years, home - 及びそれぞれの値を定義しています。値は、文字列、数値（整数、浮動小数点、科学的表現）、ブール値（true またはfalse ）、またはより複雑な入れ子型（下記参照）にできます。
値は引用符で括ることができますが、意味が変わってきます。例えば、"1234" は文字列として扱われ、1234 は整数値として扱われます。CWLでは、baseCommand のすべての部分が文字列でなければならないので、コマンドに固定した数値を指定する場合は、その数値を引用符で囲むようにしてください：[echo, "42"]`.
2.1.4. マップ#
CWLでツールやワークフローを定義する場合、通常、より複雑で入れ子構造の表現を構築する必要があります。maps と呼ばれるこれらの階層構造は、キーの値として追加のキーと値のペアを提供することによりYAMLで記述されます。これらのペア（「子」と呼ばれることもあります）は、属するキー（「親」）の下の新しい行に書かれ、2つのスペースでインデントされます（⇥タブ文字は許可されていません）。例えば、次のようになります：
cwlVersion: v1.0
class: CommandLineTool
baseCommand: echo
inputs: # this key has an object value
example_flag: # so does this one
type: boolean
inputBinding: # and this one too
position: 1
prefix: -f
上記のYAMLは、複雑なネストされたオブジェクトの記述を比較的素早く構築する方法を示しています。inputs マップはキーexample_flag だけを含み、それ自体が2つのキー、type とinputBinding を含み、これらの子の1つ、inputBinding はさらに2つのキーと値のペア (position とprefix) を含みます。1つのキーに対して複数の値/キーバリューペアを提供することについての詳細は、以下の配列のセクションを参照してください。上記のYAMLの例と比較するために、inputs オブジェクトを図式化したものを示します。
2.1.5. 配列#
ある状況下では、1つのキーに対して複数の値やオブジェクトを提供する必要があります。上記のMapsのセクションですでに見たように、1つのキーに複数のキーと値のペアをマッピングできます。しかし、各値にユニークなキーを用意しなくても、キーに対して複数の値を定義することも可能です。この場合、array を用いて、各値を独自の行で定義し、その前に- を置くことで実現できます。例えば、次のようになります：
touchfiles:
- foo.txt
- bar.dat
- baz.txt
と、マップと配列を組み合わせたより複雑な例です：
exclusive_parameters:
type:
- type: record
name: itemC
fields:
itemC:
type: string
inputBinding:
prefix: -C
- type: record
name: itemD
fields:
itemD:
type: string
inputBinding:
prefix: -D
2.1.6. JSON形式#
YAMLはJavaScript Object Notation (JSON)に基づいています。マップと配列は、JSON構文を使ってYAMLで定義することもできます。例えば:
touchfiles: [foo.txt, bar.dat, baz.txt] # equivalent to first Arrays example
と：
# equivalent to the `inputs` example in "Maps" above
inputs: {example_flag: {type: boolean, inputBinding: {position: 1, prefix: -f}}}
ネイティブ JSON は、フィールドが意図的に空のままになっている場所 (空の配列を表す[] など) や、値が同じ行にあることがより理にかなっている場所 (たとえば、シェルコマンドでオプションフラグとその値を提供する場合) を示すのに便利なことがあります。しかし、上の2番目の例が示すように、YAMLファイルの可読性に深刻な影響を与える可能性があるので、控えめに使用する必要があります。
2.1.7. リファレンス#
Learn YAML in Y Minutes リファレンスは、CWLでは有効でない機能もカバーしていますが、このガイドを書く間、私たちにとって非常に役に立ちました。
2.1.3. コメント#
#を使うと、CWL定義や入力パラメータファイルにコメントを追加できます。#の右側にある文字は、YAML を解釈するプログラムによって無視されます。たとえば、次のようになります：同じ行の中でコメントの前に何かある場合は、必ず
#の前に少なくとも1つのスペースを追加してください！