diff options
| -rw-r--r-- | cppawk-cons.1 | 229 |
1 files changed, 114 insertions, 115 deletions
diff --git a/cppawk-cons.1 b/cppawk-cons.1 index 23302e0..be48a3f 100644 --- a/cppawk-cons.1 +++ b/cppawk-cons.1 @@ -38,99 +38,98 @@ cons \- Lisp-like data representation and control flow macros .ft B #include <cons.h> - // Basic control-flow macros + \fI// Basic control-flow macros\fP - progn(...) // eval multiple expressions, yield last - prog(...) // eval multiple expressions, yield 1 - and(...) // short circuit and; yields nil or last expr - or(...) // short-circuit or: yields first true expr + progn(...) \fI// eval multiple expressions, yield last\fP + prog(...) \fI// eval multiple expressions, yield 1\fP + and(...) \fI// short circuit and; yields nil or last expr\fP + or(...) \fI// short-circuit or: yields first true expr\fP - // Lisp-like data structuring + \fI// Lisp-like data structuring\fP - nil // empty list; Boolean false. - consp(x) // is x a cons cell? - atom(x) // is x an atom? - null(x) // is x the nil object? - endp(x) // true if x is cons, false if nil, else error + nil \fI// empty list; Boolean false.\fP + consp(\fIx\fP) \fI// is x a cons cell?\fP + atom(\fIx\fP) \fI// is x an atom?\fP + null(\fIx\fP) \fI// is x the nil object?\fP + endp(\fIx\fP) \fI// true if x is cons, false if nil, else error\fP - numberp(x) // true if x is a number - stringp(x) // true if x is a boxed string - symbolp(x) // true if x is a boxed string + numberp(\fIx\fP) \fI// true if x is a number\fP + stringp(\fIx\fP) \fI// true if x is a boxed string\fP + symbolp(\fIx\fP) \fI// true if x is a boxed string\fP - box(av) // convert Awk number or string Lisp value. - unbox(lv) // convert Lisp value to Awk number or string. - box_str(av) // create Lisp boxed string from Awk value av - box_sym(av) // create Lisp symbol named av + box(\fIav\fP) \fI// convert Awk number or string Lisp value.\fP + unbox(\fIlv\fP) \fI// convert Lisp value to Awk number or string.\fP + box_str(\fIav\fP) \fI// create Lisp boxed string from Awk value av\fP + box_sym(\fIav\fP) \fI// create Lisp symbol named av\fP - cons(a, d) // create cons cell with car = a and cdr = d. - car(x) // retrieve car of cons cell x. - cdr(x) // retrieve cdr of cons cell x. + cons(\fIa\fP, \fId\fP) \fI// create cons cell with car = a and cdr = d.\fP + car(\fIx\fP) \fI// retrieve car of cons cell x.\fP + cdr(\fIx\fP) \fI// retrieve cdr of cons cell x.\fP - sexp(x) // convert Lisp value to S-expression string + sexp(\fIx\fP) \fI// convert Lisp value to S-expression string\fP - equal(x, y) // test whether two Lisp values are equal - equalize(x) // convert object to canonical representation + equal(\fIx\fP, \fIy\fP) \fI// test whether two Lisp values are equal\fP + equalize(\fIx\fP) \fI// convert object to canonical representation\fP - list(...) // return argument values as a Lisp list - append(...) // append list arguments; last may be atom - li(...) // inline macro version of list - listar(...) // Lisp's list*, implemented as a macro + list(...) \fI// return argument values as a Lisp list\fP + append(...) \fI// append list arguments; last may be atom\fP + li(...) \fI// inline macro version of list\fP + listar(...) \fI// Lisp's list*, implemented as a macro\fP - member(y, x) // first suffix of list x starting with y + member(\fIy\fP, \fIx\fP) \fI// first suffix of list x starting with y\fP - position(y, x) // zero-based position of y in list x + position(\fIy\fP, \fIx\fP) \fI// zero-based position of y in list x\fP - nth(i, x) // zero-based i-th item from list x + nth(\fIi\fP, \fIx\fP) \fI// zero-based i-th item from list x\fP - nthcdr(i, x) // suffix of x starting at i-th item + nthcdr(\fIi\fP, \fIx\fP) \fI// suffix of x starting at i-th item\fP - ldiff(x, y) // prefix of x omitting suffix y. - last(x, [n]) // suffix of x of length n, defaulting to 1. - butlast(x, [n]) // prefix of x omitting last n, defaulting to 1. + ldiff(\fIx\fP, \fIy\fP) \fI// prefix of x omitting suffix y.\fP + last(\fIx\fP, [\fIn\fP]) \fI// suffix of x of length n, defaulting to 1.\fP + butlast(\fIx\fP, [\fIn\fP]) \fI// prefix of x omitting last n, defaulting to 1.\fP - reverse(x) // reverse list x + reverse(\fIx\fP) \fI// reverse list x\fP - iota(x, y[, d]) // numbers from x to y, incrementing by + iota(\fIx\fP, \fIy\fP[, \fId\fP]) \fI// numbers from x to y, incrementing by\fP - uniq(x) // list x deduplicated + uniq(\fIx\fP) \fI// list x deduplicated\fP - mapcar(f, x) // map list through function f + mapcar(\fIf\fP, \fIx\fP) \fI// map list through function f\fP - mappend(f, x) // map list through f, append results + mappend(\fIf\fP, \fIx\fP) \fI// map list through f, append results\fP - // array -> list conversion + \fI// array -> list conversion\fP - atol(x) // convert values of Awk array a to list - keys(x) // return list of keys of Awk array x + atol(\fIx\fP) \fI// convert values of Awk array a to list\fP + keys(\fIx\fP) \fI// return list of keys of Awk array x\fP - // field <-> list conversion + \fI// field <-> list conversion\fP - ftol(x) // convert Awk positional fields to list - ltof(x) // set Awk positional fields from list x + ftol(\fIx\fP) \fI// convert Awk positional fields to list\fP + ltof(\fIx\fP) \fI// set Awk positional fields from list x\fP - // list iteration + \fI// list iteration\fP - dolist(item, list) - statement + dolist(\fIitem\fP, \fIlist\fP) + \fIstatement\fP - dolisti(item, index, list) - statement + dolisti(\fIitem\fP, \fIindex\fP, \fIlist\fP) + \fIstatement\fP - // push and pop + \fI// stack-like list manipulation\fP - push(y, x) // push item y onto x, updating location x - pop(x) // pop item from list x, updating x + push(\fIy\fP, \fIx\fP) \fI// push item y onto x, updating location x\fP + pop(\fIx\fP) \fI// pop item from list x, updating x\fP - // procedural list construction + \fI// procedural list construction\fP - bag = list_create() - bag = list_add(bag, item1) - bag = list_add(bag, item2) - list = list_end(bag) + \fIbag\fP = list_create() + \fIbag\fP = list_add(\fIbag\fP, \fIitem\fP) + \fIlist\fP = list_end(\fIbag\fP) - // bags macro: collect into multiple bags that become lists + \fI// bags macro: collect into multiple bags that become lists\fP - bags (b1, b2, ...) { bag(b1, value) ... } + bags (\fIb1\fP, \fIb2\fP, ...) { bag(\fIb1\fP, \fIvalue\fP) ... } .ft R .SH OVERVIEW @@ -361,8 +360,8 @@ macros found in some Lisp dialects. .B Syntax: .ft B - prog(expr1, expr2, ...) - progn(expr1, expr2, ...) + prog(\fIexpr1\fB, \fIexpr2\fB, ...) + progn(\fIexpr1\fB, \fIexpr2\fB, ...) .ft R .B Description: @@ -390,19 +389,19 @@ macro evaluates one or more expressions .B Example: .ft B - // simulate missing comma operator in Awk + \fI// simulate missing comma operator in Awk\fP - for (prog(i = 0, j = 0); - i < N; - prog(i++, j += i)) + for (prog(\fIi\fP = 0, \fIj\fP = 0); + \fIi\fP < N; + prog(\fIi\fP++, \fIj\fP += \fIi\fP)) { } - // Write a macro swap() that can be used anywhere - // where an expression can be used, and returns the - // prior value of a. + \fI// Write a macro swap() that can be used anywhere\fP + \fI// where an expression can be used, and returns the\fP + \fI// prior value of a.\fP - #define swap(a, b, temp) (progn(temp = a, a = b, b = temp)) + #define swap(\fIa\fP, \fIb\fP, \fItemp\fP) (progn(\fItemp\fP = \fIa\fP, \fIa\fP = \fIb\fP, \fIb\fP = \fItemp\fP)) .ft R .SS Macros \fIand\fP and \fIor\fP @@ -410,8 +409,8 @@ macro evaluates one or more expressions .B Syntax: .ft B - and(expr1, expr2, ...) - or(expr1, expr2, ...) + and(\fIexpr1\fP, \fIexpr2\fP, ...) + or(\fIexpr1\fP, \fIexpr2\fP, ...) .ft R .B Description: @@ -516,8 +515,8 @@ false, along with zero. .B Syntax: .ft B - consp(x) - atom(x) + consp(\fIx\fP) + atom(\fIx\fP) .ft R .B Description: @@ -539,8 +538,8 @@ Any object that is not a cons is classified as an atom. .B Syntax: .ft B - null(x) - endp(x) + null(\fIx\fP) + endp(\fIx\fP) .ft R .B Description: @@ -581,9 +580,9 @@ other than the empty list .B Syntax: .ft B - numberp(x) - stringp(x) - symbolp(x) + numberp(\fIx\fP) + stringp(\fIx\fP) + symbolp(\fIx\fP) .ft R .B Description: @@ -612,16 +611,16 @@ to distinguish numbers from non-numbers. numberp("abc") -> 0 numberp(cons(1, 2)) -> 0 - stringp("") -> 0 // "" is the object nil - stringp("abc") -> 0 // not a boxed string + stringp("") -> 0 \fI// "" is the object nil\fP + stringp("abc") -> 0 \fI// not a boxed string\fP stringp(box("abc")) -> 1 - stringp("Tabc")) -> 1 // manually boxed "abc" + stringp("Tabc")) -> 1 \fI// manually boxed "abc"\fP - symbolp(nil) -> 1 // nil is a symbol - symbolp("") -> 1 // indistinguishable from nil - symbolp(3) -> 0 // numbers are not symbols - symbolp("abc") -> 0 // not a symbol - symbolp("Sabc") -> 1 // manually produced symbol abc + symbolp(nil) -> 1 \fI// nil is a symbol\fP + symbolp("") -> 1 \fI// indistinguishable from nil\fP + symbolp(3) -> 0 \fI// numbers are not symbols\fP + symbolp("abc") -> 0 \fI// not a symbol\fP + symbolp("Sabc") -> 1 \fI// manually produced symbol abc\fP .ft R .SS Functions \fIbox\fP, \fIunbox\fP, \fIbox_str\fP and \fIbox_sym\fP @@ -629,10 +628,10 @@ to distinguish numbers from non-numbers. .B Syntax: .ft B - box(av) - unbox(lv) - box_str(av) - box_sym(av) + box(\fIav\fP) + unbox(\fIlv\fP) + box_str(\fIav\fP) + box_sym(\fIav\fP) .ft R .B Description: @@ -708,17 +707,17 @@ symbol, and not as \f"B"Snil"\fP. box("abc") => "Tabc" box(undef) => "U" - unbox(nil) => "nil" // name of symbol nil is "nil" + unbox(nil) => "nil" \fI// name of symbol nil is "nil"\fP unbox(box("abc")) => "abc" unbox(3.14) -> 3.14 unbox(symbol("abc")) => "abc" unbox("xyz") => ;; error - unbox("Txyz") => "xyz" // T type code indicates boxed string + unbox("Txyz") => "xyz" \fI// T type code indicates boxed string\fP - box_sym("") => "S" // symbol with empty string name - box_sym(3.14) => "S3.14" // the symbol 3.14 (not a number) - box_sym("abc") => "Sabc" // the symbol abc - box_sym("nil") => "" -> nil // "nil" is the symbol nil + box_sym("") => "S" \fI// symbol with empty string name\fP + box_sym(3.14) => "S3.14" \fI// the symbol 3.14 (not a number)\fP + box_sym("abc") => "Sabc" \fI// the symbol abc\fP + box_sym("nil") => "" -> nil \fI// "nil" is the symbol nil\fP .ft R .SS Functions \fIcons\fP, \fIcar\fP and \fIcdr\fP @@ -726,9 +725,9 @@ symbol, and not as \f"B"Snil"\fP. .B Syntax: .ft B - cons(a, d) - car(c) - cdr(c) + cons(\fIa\fP, \fId\fP) + car(\fIc\fP) + cdr(\fIc\fP) .ft R .B Description @@ -776,12 +775,12 @@ symbol as an argument instead of a cons, in which case they return car(cons(1, 2)) -> 1 cdr(cons(1, "abc")) => "abc" - // Without boxing, undefined gets treated as nil. + \fI// Without boxing, undefined gets treated as nil.\fP cons(undef1, undef2) => "C0,0:" -> (nil . nil) car(cons(undef1, undef2)) => "" -> nil - // Boxing passes through and recovers Awk undefined value + \fI// Boxing passes through and recovers Awk undefined value\fP cons(box(undef1), box(undef2)) => "C1,1:UU" -> (#U . #U) car(cons(box(undef1), box(undef1))) => ;; Awk undefined value @@ -792,7 +791,7 @@ symbol as an argument instead of a cons, in which case they return .B Syntax: .ft B - sexp(x) + sexp(\fIx\fP) .ft R .B Description @@ -904,8 +903,8 @@ function favors the last of these. .B Syntax: .ft B - equal(x, y) - equalize(x) + equal(\fIx\fP, \fIy\fP) + equalize(\fIx\fP) .ft R .B Description @@ -1185,15 +1184,15 @@ may be understood in terms of equivalent applications of the function: .ft B - append(X) <--> X + append(\fIX\fP) <--> \fIX\fP - append(list(1), X) <--> cons(1, X) + append(list(1), \fIX\fP) <--> cons(1, \fIX\fP) - append(list(1, 2), X) <--> cons(1, cons(2, X)) + append(list(1, 2), \fIX\fP) <--> cons(1, cons(2, \fIX\fP)) - append(list(1, 2), <--> cons(1, cons(2, cons(3, cons(4, X)))) + append(list(1, 2), <--> cons(1, cons(2, cons(3, cons(4, \fIX\fP)))) list(3, 4), - X) + \fIX\fP) .ft R From these equivalences, it is clear that the last argument X, @@ -1208,7 +1207,7 @@ operation, proceeding from right to left. append(nil) -> nil append(3) -> 3 append("abc") -> "abc" - append(3, 4) -> // error! + append(3, 4) -> \fI// error!\fP append(list(1, 2, 3), list(4, 5)) -> (1 2 3 4 5) append(list(1, 2, 3), list(4, 5), cons(6, 7)) -> (1 2 3 4 5 6 . 7) .ft R @@ -1218,8 +1217,8 @@ operation, proceeding from right to left. .B Syntax: .ftB - li(...) // inline macro version of list - listar(...) // Lisp's list*, implemented as a macro + li(...) \fI// inline macro version of list\fP + listar(...) \fI// Lisp's list*, implemented as a macro\fP .ft R .B Description @@ -1297,7 +1296,7 @@ and so forth. .B Syntax: .ftB - member(y, x) + member(\fIy\fP, \fIx\fP) .ft R .B Description |