Commits

patrickl  committed 4790f66

[svn r532] doc

  • Participants
  • Parent commits 342c442

Comments (0)

Files changed (1)

 .B \-\^l
 When the 
 .B -l 
-options is used, an implementation of the Haskell \fIlet\fP keyword is provided,
-allowing for short (one line) bash functions to be defined in a style similar to Haskell.
+options is used, \fBbashkell\fP defines a \fIlet\fP functionn that is an alias for \fIdefine\fP (see below
+for more about \fIdefine\fP). This allows function definition in a style more similar to Haskell.
 
 Note: As a side effect of defining a \fIlet\fP function, the bash \fIlet\fP keyword 
 will be masked. Do not use this option if you intend to use the bash \fIlet\fP
 
 
 .SH INPUT
-Most \fBbashkell\fP functions (with the exception of \fIshow\fP) operate on a list of strings ([String])
+Most \fBbashkell\fP functions (with the exception of \fIshow\fP) operate on a list
 as input. By default, a function's input is assumed to be provided via stdin. However, it is also
 possible to provide the function's input on the command line, by using a \fI$\fP followed by the actual
 input supplied as parameters. For example, the 2 following ways of implementing the identity function 
-using \fImap\fP are equivalent:
+over a list using \fImap\fP are equivalent:
 
-  echo -e "1\\n2\\n3" | map echo
-  map echo $ 1 2 3
+  $ echo -e "1\\n2\\n3" | map echo
+  1
+  2
+  3
+
+  $ map echo $ 1 2 3
+  1 
+  2
+  3
 
 
 .SH OUTPUT
+The output for all \fBbashkell\fP functions is stdout. If a function returns a list, the output will
+be (possibly) multiple lines to stdout. If a function returns a scalar value, the output will be one line to 
+stdout.
+
+
+.SH LAMBDA EXPRESSIONS
+\fBbashkell\fP has support for Haskell-style lambda expressions. These can be used with the higher-order 
+\fBbashkell\fP function or with the \fIdefine/let\fP function. The syntax is really similar to Haskell:
+
+  \\ARG1 ... ARGN -> BASH_EXPRESSION
+
+For example, you could rewrite the identity function from the above example as such:
+
+  $ map '\\x -> echo $x' $ 1 2 3
+  1
+  2
+  3
+
+You could also have given a name to your lambda expression using \fIdefine\fP:
+
+  $ define id = '\\x -> echo $x'
+  $ map id $ 1 2 3
+  1
+  2
+  3
 
 
 .SH HIGHER-ORDER FUNCTIONS
 
-  type INPUT = [String]
-  type OUTPUT = [String]
-  type EXPRESSION = (String ->)* String
+.SS map [-r] EXPRESSION [$ INPUT...]
+Maps \fIEXPRESSION \fP over the input. \fIEXPRESSION\fP can be either a normal bash expression or a lambda expression.
+In the case of a normal bash expression, the argument will be appended to the end of the expression. 
 
-  map :: EXPRESSION -> INPUT -> OUTPUT
-  
-  
+For example, to get the basename of a list of files, each of the following example would work:
 
+  $ map basename $ /tmp/file1 /tmp/file2 /tmp/file3
+  file1
+  file2
+  file3
 
-.SH LAMBDA EXPRESSIONS
-All 
-.B bashkell
-functions that accept a 
+  $ map '\\f -> basename $f' $ /tmp/file1 /tmp/file2 /tmp/file3
+  file1
+  file2
+  file3
+
+  $ echo /tmp/file1 > /tmp/files
+  $ echo /tmp/file2 > /tmp/files
+  $ echo /tmp/file3 > /tmp/files
+  $ map basename </tmp/files
+  file1
+  file2
+  file3
+
+.SS filter EXPRESSION [$ INPUT...]
+Returns elements of \fIINPUT\fP for which \fIEXPRESSION\fP is true. Note that here it is the return code
+of \fIEXPRESSION\fP that is used to determine truth, all output is discarded.
+
+For example, to verify which files exist from a list of file:
+
+  $ filter 'test -e' $ /etc/passwd /etc/foo /etc/bar
+  /etc/passwd
+
+  $ filter '\\f -> [[ -e "$f" ]]' $ /etc/passwd /etc/foo /etc/bar
+  /etc/passwd
+
+Select even numbers from a list:
+
+  $ filter '\\n -> !((n % 2))' $ 1 2 3 4
+  2
+  4
+
+.SS foldl [-r] EXPRESSION ACC [$ INPUT...]
+Performs a left fold on the input, using \fIEXPRESSION\fP and \fIACC\fP as the starting value. 
+
+For example, you can sum a list of integers using the following left fold:
+
+  $ foldl '\\acc x -> echo $(($x + $acc))' 0 $ 1 2 3 4 5
+  15
+
+.SS foldr [-r] EXPRESSION ACC [$ INPUT...]
+Performs a right fold on the input, using \fIEXPRESSION\fP and \fIACC\fP as the starting value. 
+
+.SS all EXPRESSION [$ INPUT...]
+
+.SS any EXPRESSION [$ INPUT...]
+
+.SS OPTIONS
+
+
+
+
 
 
 .I COMMAND