aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorArun Isaac2024-04-12 23:34:10 +0100
committerArun Isaac2024-04-12 23:34:10 +0100
commit19aac5603966d04ff6a728c7a832fc7a389dbbeb (patch)
tree6ffc9d5823d884f3c88cceeee7abb92d874010c9 /doc
parent213729d512924a088ea46adeb97ae2003acff399 (diff)
downloadccwl-19aac5603966d04ff6a728c7a832fc7a389dbbeb.tar.gz
ccwl-19aac5603966d04ff6a728c7a832fc7a389dbbeb.tar.lz
ccwl-19aac5603966d04ff6a728c7a832fc7a389dbbeb.zip
doc: Write guide to the source code.
* doc/ccwl.skb (Guide to the source code): New chapter. (Contributing): Demote to section inside "Guide to the source code".
Diffstat (limited to 'doc')
-rw-r--r--doc/ccwl.skb70
1 files changed, 66 insertions, 4 deletions
diff --git a/doc/ccwl.skb b/doc/ccwl.skb
index a0dc3ae..31ed0cc 100644
--- a/doc/ccwl.skb
+++ b/doc/ccwl.skb
@@ -400,10 +400,72 @@ construct may be invoked from within workflows just like ,(code
,(code "n-1").]
(scheme-source "doc/js-expression-iota.scm"))))
- (chapter :title [Contributing]
- :ident "chapter-contributing"
- (p [ccwl is developed on GitHub at ,(ref
+ (chapter :title [Guide to the source code]
+ :ident "chapter-guide-to-the-source-code"
+ (p [This chapter is a guide to reading, understanding and hacking
+on the ccwl source code. You do not need to read this chapter to
+merely use ccwl to write your workflows. You only need to read this if
+you wish to understand and maybe improve the implementation of ccwl.])
+ (section :title [Important objects and functions]
+ :ident "section-important-objects-and-functions"
+ (p [As described in the ,(ref :ident "section-important-concepts"
+:text [Important Concepts]) section, ccwl is a statically typed
+expression oriented language in which functions take one or more
+arguments (either positional or named) and return one or more
+outputs. There are different kinds of functions—namely commands,
+javascript expressions, workflows and external CWL workflows. These
+are represented by ,(source-ref "ccwl/ccwl.scm"
+"\\(define-immutable-record-type <command>" (code [<command>])),
+,(source-ref "ccwl/ccwl.scm" "\\(define-immutable-record-type <js-expression>"
+(code [<js-expression>])), ,(source-ref "ccwl/ccwl.scm"
+"\\(define-immutable-record-type <workflow>" (code [<workflow>])) and
+,(source-ref "ccwl/ccwl.scm" "\\(define-immutable-record-type <cwl-workflow>"
+(code [<cwl-workflow>])) objects respectively. Inputs and outputs of
+these functions are represented by ,(source-ref "ccwl/ccwl.scm"
+"\\(define-immutable-record-type <input>" (code [<input>]))
+and ,(source-ref "ccwl/ccwl.scm" "\\(define-immutable-record-type <output>"
+(code [<output>])) objects respectively. Special macros—
+,(source-ref "ccwl/ccwl.scm" "\\(define-syntax command" (code [command])),
+,(source-ref "ccwl/ccwl.scm" "\\(define-syntax js-expression" (code [js-expression])),
+,(source-ref "ccwl/ccwl.scm" "\\(define-syntax workflow" (code [workflow]))
+and ,(source-ref "ccwl/ccwl.scm" "\\(define-syntax cwl-workflow" (code [cwl-workflow]))
+are provided to define ,(code [<command>]), ,(code [<js-expression>]),
+,(code [<workflow>]) and ,(code [<cwl-workflow>]) objects
+respectively. These macros provide syntax validation and present a
+more concise interface to users. ,(code [<input>]) and ,(code
+[<output>]) objects are never defined on their own by the user, but
+rather are inferred by the aforementioned macros.])
+ (p [ccwl introduces the notion of a ,(source-ref "ccwl/ccwl.scm"
+"\\(define-immutable-record-type <key>" (code [<key>])) that is a
+generalization of ,(code [<input>]) and ,(code [<output>])
+objects. Keys flow through workflow steps and string them
+together. Keys in the ccwl DSL are analogous to variable names in a
+regular programming language. The ,(source-ref "ccwl/ccwl.scm"
+"\\(define \\(collect-steps" (code [collect-steps])) function
+traverses workflow expression trees and produces a list of CWL
+steps. ccwl constructs such as ,(code [pipe]), ,(code [tee]), ,(code
+[identity]), ,(code [rename]), ,(code [scatter]), etc. are implemented
+in the collect-steps function.]))
+ (section :title [Source tree organization]
+ :ident "section-source-tree-organization"
+ (p [Here’s a short summary of what some important files in the
+source tree contain.]
+ (description
+ (item :key (file "ccwl/ccwl.scm")
+ [Core functionality—the functions, keys, input/output
+objects, etc.— of the ccwl DSL])
+ (item :key [,(file "ccwl/cwl.scm") and ,(file "ccwl/graphviz.scm")]
+ [Serialization concerns to CWL and dot respectively])
+ (item :key (file "ccwl/yaml.scm")
+ [Library to serialize scheme trees to YAML in the manner of
+guile-json to JSON])
+ (item :key (file "ccwl/ui.scm")
+ [Command-line reporting of errors in the context of the
+user’s workflow description]))))
+ (section :title [Contributing]
+ :ident "section-contributing"
+ (p [ccwl is developed on GitHub at ,(ref
:url "https://github.com/arunisaac/ccwl"). Feedback, suggestions,
feature requests, bug reports and pull requests are all
welcome. Unclear and unspecific error messages are considered a
-bug. Do report them!])))
+bug. Do report them!]))))