Clarify parameter reference: null and array length (#64)

* Address ambiguity on null and inputs.somearray.length in parameter reference
* Clarify that the length field can sometimes apply to a non-array input

Author: pvanheus

concepts.md

@@ -510,17 +510,23 @@ or more repeats, and all other characters are literal values.
 Use the following algorithm to resolve a parameter reference:
 
   1. Match the leading symbol as the key
-  2. Look up the key in the parameter context (described below) to get the current value.
+  2. If the key is the special value 'null' then the
+     value of the parameter reference is 'null'. If the key is 'null' it must be the only symbol in the parameter reference.
+  3. Look up the key in the parameter context (described below) to get the current value.
      It is an error if the key is not found in the parameter context.
-  3. If there are no subsequent segments, terminate and return current value
-  4. Else, match the next segment
-  5. Extract the symbol, string, or index from the segment as the key
-  6. Look up the key in current value and assign as new current value.  If
-     the key is a symbol or string, the current value must be an object.
-     If the key is an index, the current value must be an array or string.
-     It is an error if the key does not match the required type, or the key is not found or out
-     of range.
-  7. Repeat steps 3-6
+  4. If there are no subsequent segments, terminate and return current value
+  5. Else, match the next segment
+  6. Extract the symbol, string, or index from the segment as the key
+  7. Look up the key in current value and assign as new current value.
+     1. If the key is a symbol or string, the current value must be an object.
+     2. If the key is an index, the current value must be an array or string.
+     3. If the next key is the last key and it has the special value 'length' and
+         the current value is an array, the value of the parameter reference is the
+         length of the array. If the value 'length' is encountered in other contexts, normal
+         evaluation rules apply.
+     4. It is an error if the key does not match the required type, or the key is not found or out
+        of range.
+  8. Repeat steps 3-8
 
 The root namespace is the parameter context.  The following parameters must
 be provided:

conformance_tests.yaml

@@ -3399,3 +3399,25 @@
 - $import: tests/mixed-versions/test-index.yaml
 - $import: tests/loadContents/test-index.yaml
 - $import: tests/iwd/test-index.yaml
+
+- job: tests/empty.json
+  tool: tests/params_broken_null.cwl
+  label: params_broken_null
+  doc: Test parameter reference that refers to null.something
+  should_fail: true
+  tags: [ required, command_line_tool ]
+
+- job: tests/empty.json
+  tool: tests/params_broken_length_of_non_list.cwl
+  doc: Test paramer reference that refers to length of non-array input
+  should_fail: true
+  tags: [ required, command_line_tool ]
+
+- job: tests/length_non_array_input.yml
+  tool: tests/params_input_length_non_array.cwl
+  doc: Test 'length' in parameter reference where it does not refer to length of an array input
+  tags: [ required, command_line_tool ]
+  output:
+    output1: 1
+    output2: 2
+    output3: 3

tests/length_non_array_input.yml

@@ -0,0 +1,5 @@
+bar:
+  length: 2
+baz:
+  length:
+    bap: 3

tests/params_broken_length_of_non_list.cwl

@@ -0,0 +1,14 @@
+class: CommandLineTool
+cwlVersion: v1.2
+inputs:
+  bar:
+    type: Any
+    default: 0
+
+outputs:
+  output1:
+    type: Any
+    outputBinding:
+      outputEval: $(inputs.bar.length)
+
+baseCommand: "true"

tests/params_broken_null.cwl

@@ -0,0 +1,14 @@
+class: CommandLineTool
+cwlVersion: v1.2
+inputs:
+  bar:
+    type: Any
+    default: "something"
+
+outputs:
+  output1:
+    type: "null"
+    outputBinding:
+      outputEval: $(null.something)
+
+baseCommand: "true"

tests/params_input_length_non_array.cwl

@@ -0,0 +1,40 @@
+class: CommandLineTool
+cwlVersion: v1.2
+inputs:
+  length:
+    type: int
+    default: 1
+  bar:
+    type:
+      type: record
+      name: bar_record
+      fields:
+        length:
+          type: int
+  baz:
+    type:
+      type: record
+      name: baz_record
+      fields:
+        length:
+          type:
+            type: record
+            name: length_record
+            fields:
+              bap:
+                type: int
+
+outputs:
+  output1:
+    type: int
+    outputBinding:
+      outputEval: $(inputs.length)
+  output2:
+    type: int
+    outputBinding:
+      outputEval: $(inputs.bar.length)
+  output3:
+    type: int
+    outputBinding:
+      outputEval: $(inputs.baz.length.bap)
+baseCommand: "true"