Merge pull request #236 from common-workflow-language/directory

Directory and file type schema

Author: mr-c

draft-3/examples/arguments.cwl

@@ -1,5 +1,6 @@
 cwlVersion: cwl:draft-3
 class: CommandLineTool
+label: Example trivial wrapper for Java 7 compiler
 baseCommand: javac
 hints:
   - class: DockerRequirement

draft-4/CommandLineTool.yml

@@ -79,30 +79,6 @@ $graph:
     - {$include: concepts.md}
     - {$include: invocation.md}
 
-- type: record
-  name: FileDef
-  doc: |
-    Define a file that must be placed in the designated output directory
-    prior to executing the command line tool.  May be the result of executing
-    an expression, such as building a configuration file from a template.
-  fields:
-    - name: "filename"
-      type: ["string", "#Expression"]
-      doc: "The name of the file to create in the output directory."
-    - name: "fileContent"
-      type: ["string", "#Expression"]
-      doc: |
-        If the value is a string literal or an expression which evaluates to a
-        string, a new file must be created with the string as the file contents.
-
-        If the value is an expression that evaluates to a File object, this
-        indicates the referenced file should be added to the designated output
-        directory prior to executing the tool.
-
-        Files added in this way may be read-only, and may be provided
-        by bind mounts or file system links to avoid
-        unnecessary copying of the input file.
-
 
 - type: record
   name: EnvironmentDef
@@ -248,17 +224,6 @@ $graph:
         the File objects must include up to the first 64 KiB of file contents
         in the `contents` field.
 
-- name: initialWorkDir
-  type: record
-  doc: |
-    Setup a working directory based on a number of input files (and/or directories)
-  fields:
-    - name: dirDef
-      type:
-        type: "array"
-        items: [ "#FileDef", "#File", "#Directory" ]
-      doc: list of files and/or directories
-
 
 - name: CommandInputRecordField
   type: record
@@ -499,7 +464,7 @@ $graph:
       type:
         - "null"
         - type: array
-          items: [string, "#CommandLineBinding"]
+          items: [string, "#Expression", "#CommandLineBinding"]
       jsonldPredicate:
         "_id": "cwl:arguments"
         "_container": "@list"
@@ -665,20 +630,72 @@ $graph:
         IRI such as an [RRID](http://www.identifiers.org/rrid/SCR_001156).
         Example: `http://identifiers.org/rrid/RRID:SCR_001156`
 
-- name: CreateFileRequirement
+- name: DirentExt
   type: record
-  extends: "#ProcessRequirement"
   doc: |
-    Define a list of files that must be created by the workflow
-    platform in the designated output directory prior to executing the command
-    line tool.  See `FileDef` for details.
+    Define a file or subdirectory that must be placed in the designated output
+    directory prior to executing the command line tool.  May be the result of
+    executing an expression, such as building a configuration file from a
+    template.
   fields:
-    - name: fileDef
+    - name: entryname
+      type: [string, Expression]
+      jsonldPredicate:
+        _id: cwl:entryname
+      doc: |
+        The name of the file or subdirectory to create in the output directory.
+    - name: entry
+      type: [string, Expression]
+      jsonldPredicate:
+        _id: cwl:entry
+      doc: |
+        If the value is a string literal or an expression which evaluates to a
+        string, a new file must be created with the string as the file contents.
+
+        If the value is an expression that evaluates to a `File` object, this
+        indicates the referenced file should be added to the designated output
+        directory prior to executing the tool.
+
+        If the value is an expression that evaluates to a `Dirent` object, this
+        indicates that the File or Directory in `entry` should be added to the
+        designated output directory with the name in `entryname`.
+
+        If `writable` is false, the file may be made available using a bind
+        mount or file system link to avoid unnecessary copying of the input
+        file.
+    - name: writable
+      type: boolean?
+      doc: |
+        If true, the file or directory must be writable by the tool.  Changes
+        to the file or directory must be isolated and not visible by any other
+        CommandLineTool process.  This may be implemented by making a copy of
+        the original file or directory.  Default false (files and directories
+        read-only by default).
+
+- name: InitialWorkDirRequirement
+  type: record
+  extends: ProcessRequirement
+  doc:
+    Define a list of files and subdirectories that must be created by the
+    workflow platform in the designated output directory prior to executing the
+    command line tool.
+  fields:
+    - name: listing
       type:
-        type: "array"
-        items: "#FileDef"
-      doc: The list of files.
+        - type: array
+          items: [File, DirentExt]
+        - string
+        - Expression
+      jsonldPredicate:
+        _id: "cwl:listing"
+        mapSubject: entryname
+        mapPredicate: entry
+      doc: |
+        The list of files or subdirectories that must be placed in the
+        designated output directory prior to executing the command line tool.
 
+        May be an expression.  If so, the expression return value must validate
+        as `{type: array, items: [File, Dirent]}`.
 
 - name: EnvVarRequirement
   type: record

draft-4/Process.yml

@@ -33,15 +33,18 @@ $graph:
     - cwl:draft-3
     - cwl:draft-4.dev1
     - cwl:draft-4.dev2
+    - cwl:draft-4.dev3
 
 - name: CWLType
   type: enum
   extends: "sld:PrimitiveType"
   symbols:
     - cwl:File
+    - cwl:Directory
   doc:
     - "Extends primitive types with the concept of a file as a first class type."
     - "File: A File object"
+    - "Directory: A Directory object"
 
 - name: File
   type: record
@@ -58,28 +61,95 @@ $graph:
         symbols:
           - cwl:File
       jsonldPredicate:
-        "_id": "@type"
-        "_type": "@vocab"
+        _id: "@type"
+        _type: "@vocab"
       doc: Must be `File` to indicate this object describes a file.
-    - name: path
+    - name: location
       type: string
-      doc: The path to the file.
+      doc: |
+        A URI that identifies the file resource.  This may be a relative
+        reference, in which case it must be resolved using the base URI of the
+        document.  The location may refer to a local or remote resource; the
+        implementation must use the URI to retrieve file content.  If an
+        implementation is unable to retrieve the file content stored at a
+        remote resource (due to unsupported protocol, access denied, or other
+        issue) it must signal an error.
+
+        If the `path` field is provided but the `location` field is not, an
+        implementation may assign the value of the `path` field to `location`,
+        then follow the rules above.
+      jsonldPredicate:
+        _id: "@id"
+        _type: "@id"
+    - name: path
+      type: string?
+      doc: |
+        The local path where the File is made available prior to executing a
+        CommandLineTool.  This must be set by the implementation.  This field
+        must not be used in any other context.  The command line tool being
+        executed must be able to to access the file at `path` using the POSIX
+        `open(2)` syscall.
       jsonldPredicate:
         "_id": "cwl:path"
         "_type": "@id"
+    - name: basename
+      type: string?
+      doc: |
+        The base name of the file, that is, the path component following the
+        final slash in the path.
+
+        The implementation must set this field based on the value of `path`
+        prior to evaluating parameter references or expressions in a
+        CommandLineTool document.  This field must not be used in any other
+        context.
+    - name: dirname
+      type: string?
+      doc: |
+        The name of the directory containing file, that is, the path leading up
+        to the final slash in the path such that `dirname + '/' + basename =
+        path`.
+
+        The implementation must set this field based on the value of `path`
+        prior to evaluating parameter references or expressions in a
+        CommandLineTool document.  This field must not be used in any other
+        context.
+    - name: nameroot
+      type: string?
+      doc: |
+        The basename root such that `nameroot + nameext == basename`, and
+        `nameext` is empty or begins with a period and contains at most one
+        period.  Leading periods on the basename are ignored; a basename of
+        `.cshrc` will have a nameroot of `.cshrc`.
+
+        The implementation must set this field based on the value of `path`
+        prior to evaluating parameter references or expressions in a
+        CommandLineTool document.  This field must not be used in any other
+        context.
+    - name: nameext
+      type: string?
+      doc: |
+        The basename extension such that `nameroot + nameext == basename`, and
+        `nameext` is empty or begins with a period and contains at most one
+        period.  Leading periods on the basename are ignored; a basename of
+        `.cshrc` will have an empty `nameext`.
+
+        The implementation must set this field based on the value of `path`
+        prior to evaluating parameter references or expressions in a
+        CommandLineTool document.  This field must not be used in any other
+        context.
     - name: checksum
       type: ["null", string]
       doc: |
         Optional hash code for validating file integrity.  Currently must be in the form
-        "sha1$ + hexidecimal string" using the SHA-1 algorithm.
+        "sha1$ + hexadecimal string" using the SHA-1 algorithm.
     - name: size
       type: ["null", long]
       doc: Optional file size.
     - name: "secondaryFiles"
       type:
         - "null"
         - type: array
-          items: "#File"
+          items: [File, Dirent]
       jsonldPredicate: "cwl:secondaryFiles"
       doc: |
         A list of additional files that are associated with the primary file
@@ -111,12 +181,24 @@ $graph:
         runtime may perform exact file format matches.
 
 
+- name: Dirent
+  type: record
+  fields:
+    - name: entryname
+      type: string
+      jsonldPredicate:
+        "_id": cwl:entryname
+    - name: entry
+      type: [File, Directory]
+      jsonldPredicate:
+        "_id": cwl:entry
+
 - name: Directory
   type: record
   docParent: "#CWLType"
   doc: |
     Represents a directory to present to a command line tool. This could be a virtual
-    directory, made of files assembled from a number of concrete directories.
+    directory, made of files assembled from multiple locations.
   fields:
     - name: class
       type:
@@ -125,18 +207,48 @@ $graph:
         symbols:
           - cwl:Directory
       jsonldPredicate:
-        "_id": "@type"
-        "_type": "@vocab"
+        _id: "@type"
+        _type: "@vocab"
       doc: Must be `Directory` to indicate this object describes a Directory.
-    - name: path
+    - name: location
       type: string
-      doc: The path to the directory.
+      doc: |
+        A URI that identifies the directory resource.  This may be a relative
+        reference, in which case it must be resolved using the base URI of the
+        document.  The location may refer to a local or remote resource.  If
+        the `listing` field is not set, the implementation must use the
+        location URI to retrieve directory listing.  If an implementation is
+        unable to retrieve the directory listing stored at a remote resource (due to
+        unsupported protocol, access denied, or other issue) it must signal an
+        error.
+
+        If the `path` field is provided but the `location` field is not, an
+        implementation may assign the value of the `path` field to `location`,
+        then follow the rules above.
       jsonldPredicate:
-        "_id": "cwl:path"
-        "_type": "@id"
-    # - name: size
-    #   type: ["null", long]
-    #   doc: Optional directory size.
+        _id: "@id"
+        _type: "@id"
+    - name: path
+      type: string?
+      doc: |
+        The local path where the Directory is made available prior to executing a
+        CommandLineTool.  This must be set by the implementation.  This field
+        must not be used in any other context.  The command line tool being
+        executed must be able to to access the directory at `path` using the POSIX
+        `opendir(2)` syscall.
+      jsonldPredicate:
+        _id: "cwl:path"
+        _type: "@id"
+    - name: listing
+      type:
+        - "null"
+        - type: array
+          items: [File, Dirent]
+      doc: List of files or subdirectories contained in this directory
+      jsonldPredicate:
+        _id: "cwl:listing"
+        mapSubject: entryname
+        mapPredicate: entry
 
 - name: SchemaBase
   type: record