Lisp Index Page

Richard P. Gabriel has a paper about Lisp-1 and Lisp-2. Basically Lisp-1 only have one universal namespace, while Lisp-2 has seperate namespace for functions and variables.

Scheme and clojure are lisp-1. Elisp and Common Lisp are Lisp-2.

As Peter Norvig put in Paradigms of Artificial Intelligence Programming

• adapt the language to your prolem
  • you can make DSL for your specific topic
  • support whatever programming style by just defining some macros
  • the basic and universal data structure: list
• developing lisp is fast
  • dynamic, define function during running
  • REPL

There is a myth that Lisp is "special-purpose" languages, while languages like Pascal and C are "general purpose". Actually, just the reverse is true.

David J. Cooper in Basic Lisp Techniques:

Many developers once hoped that the software development process of the future would be more automated through Computer-aided Software Engineering (CASE) tools. Such tools claim to enable programmers and non-programmers to diagram their applications visually and automatically generate code. While useful to a certain extent, traditional CASE tools cannot cover domain-specific details and support all possible kinds of customizations — so developers inevitably need to hand-code the rest of their applications, breaking the link between the CASE model and the code. CASE systems fall short of being a true “problem solving tool.”

The recursive nature of CL, and its natural ability to build applications in layers and build upon itself — in essence, code which writes code which writes code…, makes CL a much better software engineering solution. CL programs can generate other CL programs (usually at compile-time), allowing the developer to define all parts of the application in one unified high-level language. Using macros and functions, naturally supported by the CL syntax, the system can convert applications written in the high-level language automatically into “final” code. Thus, CL is both a programming language and a powerful CASE tool, and there is no need to break the connection.

In academic functional programming literature, folds are often called catamorphisms, unfolds are often called anamorphisms, and the combinations of the two are often called hylomorphisms. They're interesting because any for-each loop can be represented as a catamorphism. To convert from a loop to a foldl, package up all mutable variables in the loop into a data structure (records work well for this, but you can also use an algebraic data type or a list). The initial state becomes the accumulator; the loop body becomes a function with the loop variables as its first argument and the iteration variable as its second; and the list becomes, well, the list. The result of the fold function is the new state of all the mutable variables.

Similarly, every for-loop (without early exits) can be represented as a hylomorphism. The initialization, termination, and step conditions of a for-loop define an anamorphism that builds up a list of values for the iteration variable to take. Then, you can treat that as a for-each loop and use a catamorphism to break it down into whatever state you wish to modify.

The names CAR and CDR derive from the history of Lisp. The original Lisp implementation ran on an IBM 704 computer which divided words into two parts, called the “address” part and the “decrement”; CAR was an instruction to extract the contents of the address part of a register, and CDR an instruction to extract the contents of the decrement. By contrast, “cons cells” are named for the function ‘cons’ that creates them, which in turn was named for its purpose, the construction of cells.

These are two software design philosophies. The key different is:

• The right thing: interface should be simple
• Worse is better: implementation should be simple

The worse-is-better philosophy means that implementation simplicity has highest priority, which means Unix and C are easy to port on such machines.

Unix and C are the ultimate computer viruses.

The code will be portable because it is written on top of a virus.

The good news is that in 1995 we will have a good operating system and programming language; the bad news is that they will be Unix and C++.

Continuation is an abstract representation of the control state of a computer program. It can be used to implement exceptions, coroutines, loop break, return, yield, etc. It is the GOTO statement in functional programming.

The sandwich example by Luke Palmer (https://groups.google.com/forum/#!msg/perl.perl6.language/-KFNPaLL2yE/_RzO8Fenz7AJ):

Say you're in the kitchen in front of the refrigerator, thinking about a sandwich. You take a continuation right there and stick it in your pocket. Then you get some turkey and bread out of the refrigerator and make yourself a sandwich, which is now sitting on the counter. You invoke the continuation in your pocket, and you find yourself standing in front of the refrigerator again, thinking about a sandwich. But fortunately, there's a sandwich on the counter, and all the materials used to make it are gone. So you eat it. :-).

A continuation doesn't save data. It's just a closure that closes over the execution stack (and any lexicals associated with it; thus the "I want a sandwitch" thought). If things change between the taking and invoking of the continuation, those things remain changed after invoking.

References:

• wikipedia: https://en.wikipedia.org/wiki/Continuation
• sandwich example:
• a blog: https://medium.com/@steinuil/call-cc-and-other-fantastic-tales-a574cab554e3
• William Byrd: https://www.youtube.com/watch?v=2GfFlfToBCo&t=2087s

First, use the trace library:

(require racket/trace)

Tail call:

(define (foo n)
  (when (> n 0)
    (foo (sub1 n))))
(trace foo)
(foo 5)

Non-tail call:

(define (bar n)
  (when (> n 0)
    (identity (bar (sub1 n)))))
(trace bar)
(bar 5)

The call stack of foo is flat, the call stack of bar is triangular.

All REPL evaluation happens in a module, and the module of the REPL is typically different from that of a file.

In the REPL, the module name is shown in REPL right after @ sign. If you are not in the right module, you cannot access the bindings defined in it. You can switch the module by switch-to-geiser-module (C-c C-m), which is implemented as ,m, ,use, or ,enter, depending on the scheme implementation. You can also import the bindings of a module into the current namespace, using geiser-repl-import-module (C-c C-i).

In a file, the module is the current file. If you evaluate something, it will most likely output results in minibuffer, unless

1. an error happens, where you are dropped in the REPL in debugger mode with the module of the file, so that you can access all the bindings there. Just remember to ,q when you are done.
2. output images, which will be shown in the REPL, but no entry of debugger
3. a warning happens. The warning will be in a separate buffer, and will not drop you in debugger.

Some of the useful commands:

• C-c C-z: jump to repl, start if not started.
• C-c C-d d: read document for symbol
• C-c C-d i: read the manual (more comprehensive) for symbol
• C-c C-d m: read the list of exported bindings in a module (enter)
• C-x C-e: evaluate last sexp
• C-x C-b: evaluate buffer
• C-x C-r: evaluate region
• C-M-x: eval top level
• C-c \ runs the command geiser-insert-lambda, inserts a lambda. As a comparison, the racket-mode has racket-unicode-input-method-enable, implemented an input method for all latin letters.

http://www.greghendershott.com/2015/07/keyword-structs-revisited.html

  (begin-for-syntax
    (define syntax->keyword (compose1
                             string->keyword
                             symbol->string
                             syntax->datum)))

The syntax:

  (match val-expr clause ...)

  clause = [pat [#:when cond-expr] body ...+]

cond-expr is in teh scope of pat (to have the bind or not??).

The clauses are checked one-by-one, and the body of first match will be in the tail position.

Pattern can be

• _ to match anything and abandon it.
• a single id which matches anything and bind to it. An ID can appear more than once, in which case the pattern is considered matching only if all of the bindings of ID are same.
  • e.g. (list a b a) will not match '(1 2 3), but will match '(1 2 1)
• a list which binds to the destruction.
• The quote can not be used to construct list of symbols, it will match verbatically instead. For that, use quasiquote, which supports the evaluation and splice-eval.
  • e.g. `(1 ,a ,b) will match '(1 2 3) with a and b bound.
• hash-table can be used to match the key and values, Using ... in it means collect into a list.
  • e.g. (hash-table ("key1" a) ("key2" b)).
  • e.g. (hash-table (key val) ...) will match #hash(("a" . 1) ("b" . 2)), and key will be '("b" "a")
• cons can be used to match pairs
• struct-id can be used to match fields by position. Use (struct struct-id _) to match an instance of structure itself. E.g.
  • for structure (struct tree (val left right))
  • pattern (tree a (tree b _ _) _) will match
  • (tree 0 (tree 1 #f #f) #f)
  • with a bound to 0, b bound to 1
• (and pat ...) is used to combine a list of patterns. The typical usage is (and id pat) where you can bind id and still check the pat against the entire value. or is also available but not that useful.
• (? expr pat ...): combine a predicate and the and pattern. I.e. first, apply expr on the value to match, if #t, the additional pat are matched using the above and pattern.

There are some syntax sugar for matching:

• (match-lambda clause ...): equivalent to (lambda (id) (match id clause ...))

Matthias Felleisen boils down macros into three main categories:

1. Binding form
2. Change order of evaluation
3. Make DSLs

Different from common lisp where you have compile time and runtime, racket has the concept called level. The level 0 is roughly runtime, and level 1 is compile time. But there're also level -1 and level 2, 3, …, thus it is more general. But typically the first two levels are used.

When using racket syntax, you typically need to require the base library for it, by (require (for-syntax racket/base)).

Everything boils down to define-syntax and syntax-case. define-syntax is nothing fancy. It just define a binding, same as define, but the binding is in effect at level 1. Thus actually we typically still define it as a lambda expression, thus it has the shorthand to write argument (stx) in the same line. syntax-rules itself is a lambda expression surounding syntax-case. Thus second form does not use syntax-rules, but use syntax-case directly.

  (define-syntax foo
    (syntax-rules ()
      ((_ a ...) (printf "~a\n" (list a ...)))))
  ;; <=>
  (define-syntax (foo stx)
    (syntax-case stx ()
      (_ a ...)
      #'(printf "~a\n" (list a ...))))

syntax-case match a given syntax object against patterns, and return another syntax object. It is doing the transformation. You can actually do the transformation yourself, using sytax->datum, operates on it, and use datum->syntax to convert it back. So syntax-case just provides an easier way to do that, in the sense that you don't need to convert explicitly. Instead, you specify by position the argument, to match the datum, and construct a syntax object as a result.

  (syntax-case stx-expr (literal-id ...)
    [pattern result-expr] ...)

Note the result is result-expr, that means the expr is going to be executed, and the return value should be a syntax object.

  (define-syntax (foo stx)
    (syntax-case stx ()
      [(_ a b c)
       #'(if a b c)]))

See, stx is matched against the pattern (_ a b c), and destructed. a b c can then be used to construct the returned syntax object. Note, the return must be a syntax object, it replaces the (foo xxx) and be evaluated. The first is _ because we don't care about the leading identifier #'foo.

syntax-rules is a lambda expression, that calls syntax-case to return a syntax object. It is used to define multiple patterns and templates at one time. Note that the result is a "template" instead of "expr", meaning it is restricted: cannot run any code, merely return the template as if quoted. Thus when using syntax-rules, the result need not be quoted by syntax.

  (syntax-rules (literal-id ...)
    [(id . pattern) template] ...)
  ;; <=>
  (lambda (stx)
    (syntax-case stx (literal-id ...)
      [(generated-id . pattern) (syntax-protect #'template)] ...))

define-syntax-rule is shorthand for define-syntax and syntax-rules. The pattern is a list, the first is an identifier, the following are pattern variables that matches anything. The template is the constructed form to replace the old form. It is not quoted, because it uses syntax-rules to construct. All pattern variables will be replaced by the actual form.

  (define-syntax-rule (id . pattern) template)
  ;; <=>
  (define-syntax id
    (syntax-rules ()
      [(id . pattern) template]))

This is so constrained. The following is equivalent to the above:

  (define-syntax-rule (foo a b c)
    (if a b c))

with-syntax is often used to nest syntax. It is like let but is able to bind pattern variables.

(syntax-case <syntax> () [<pattern> <body>] ...)
(syntax-case (list stx-expr ...) () [(pattern ...) (let () body ...+)])
;; <=>
(with-syntax ([<pattern> <stx-expr>] ...) <body> ...+)

Since racket has the test module concept, there needs no unit test framework. However, it seems that rackunit provides some predicate functions.

In racket, each file is a module with the file name as the module name. You can define a submodule using module* and module+. The former can only appear exactly once for each module, while the latter can appear multiple times, all of them concatenated into a single module as if using module*.

Thus, folks typically use module* to define a main module, which will be run by racket after the enclosing module by racket. module+ is used to define test modules, and will be executed by raco test command.

rackunit provides check APIs and also organize tests into cases and suites. A check is a simple check, like equality. A test case is a group of checks. If one of them fails, the following will not be executed, and the test case fails. A suite is a group of test cases, and has a name.

Check APIs (all of them accepts an optional message at the end):

• check-eq?
• check-not-eq?
• check-equal?
• check-not-equal?
• check-pred pred v: check if apply pred on v will produce other than #f
• check-= v1 v2 epsilon: |v1-v2| <= epsilon
• check-true v: #t
• check-false v: #f
• check-not-flase v: not #f
• check op v1 v2: generic form, op is (-> any any any)
• fail: fail unconditionally, useful when developing to mark some tests

The following does not accept message, because they are straightforward:

• check-match v pattern: check if v match pattern

test-begin expr ... is used to group exprs, while test-case name body ...+ accept a name for them, and get reported if test fails.

Test suites are not going to run by default. This allows you to specify which tests to run. There're text (run-tests in rackunit/text-ui) and gui (test/gui in rackunit/gui) interfaces to select tests. Create a suite using (test-suite name-expr test ...). The tests can be single check or a test case.

• /: provide the fraction if given two numbers, not to round it.
• quotient n m: (truncate (/ n m))
• remainder n m: seems that the result has the same sign with n
• modulo n m: seems that the result has the same sign with m
• add1
• sub1
• abs
• max
• min
• gcd
• lcm: least common multiple
• round
• floor
• ceiling
• truncate: towards 0
• numerator
• denominator

Computation

• sqrt
• expt e p: e to the power of p
• exp z
• log z [b (exp 1)]

Random

• random k: [0,k)
• random min max: [min,max)
• random-seed k

With racket/random:

• random-sample seq n

The define keyword can be used to bind a id to a variable, but most likely you are binding a procedure. So the syntax for arguments matters.

  (define (head args) body ...+)
  args = arg ... | arg ... . rest-id
  arg = arg-id
      | [arg-id default-expr]
      | keyword arg-id
      | keyword [arg-id default-expr]

Note how the rest-id are used to implement the ... by using one dot.

The context matters. In an internal-definition context, a define binds a local binding. At top level, it introduces top-level binding.

In application of procedures, apply will apply the procedure with content of the list as argument, thus the procedure must accept as many parameters as the length of list. The list is actually more flexible, i.e. collected using list*.

compose accepts one or more procedures, and composes them by applying one by one, and fold result into parameter to the next. The last procedure is applied first. There're two versions, compose allow arbitrary number of values to be passed between procedure calls, as long as the number of results and parameters match. compose1 restricts this to exactly one value.

• if
• (cond [test-expr then-body ...+] ...)

  (cond cond-clause ...)
  cond-clause = [test-expr then-body ...+]
              | [else then-body ...+]
              | [test-expr => proc-expr]
              | [test-expr]

• and: A typically trick: (and (some expr) #t) to return a boolean value
  • if no expr, return #t
  • one expr, return its value in tail position.
  • Multiple exprs
    • if first eval to #f, return #f
    • otherwise recursive call with the rest of exprs in tail position.
• test-expr => proc-expr: proc-expr must produce a procedure that accept exactly one argument, the result of test-expr is that argument. The value is returned.
• test-expr without a body will return the result of test-expr. Not in tail position.
• (case val-expr [(datum ...) then-body ...+] ...): if val-expr matches one of datum, execute the body
• when
• unless
• (for ([id seq-expr] #:when guard-expr #:unless guard-expr) body)
• for/list, for/vector, for/hash
• for/and, for/or
• for/sum, for/product
• for/first, for/last
• for/fold
• for*: like for, but with implicit #:when #t between each pair. Thus all clauses are nested. for* also has the form of different return values.

The reading syntax of characters starts with #\, with following forms

As a side note, windows use \r\n, Unix use \n, Mac OS use \r

APIs

• make-string k [char]
• string-length
• string-ref
• substring str start [end]
• string-copy
• string-append
• string->list
• list->string
• string=?, string<?, ..
• string-ci=?, …
• string-upcase, string-downcase, string-titlecase, string-foldcase (normalize for different locale)

With racket/string:

• string-join
• string-replace
• string-split
• string-trim
• string-contains? s contained
• string-prefix? s prefix
• string-suffix? s suffix

With racket/format:

• ~a: accept a value, using display. It accepts several keyword arguments:
  • #:separator "": the function actually accepts multiple values, each of them is connected with separator
  • #:width
  • #:max-width
  • #:min-width
  • #:limit-marker "": if the string is longer than the width, use this as indication of "more".
  • #:align: (or/c 'left 'center 'right) = 'left
  • #:pad-string " ": when width is less than the specified width, this is used to pad
• ~v: use print instead of display. Default separator is " ", default limit-marker is "…"
• ~s: use write. Default separator is " ", default limit-marker is "…"

Byte string

• make-bytes k [b]
• bytes-length
• bytes-ref
• subbytes bstr start [end]
• bytes-copy
• bytes-append
• bytes->list
• list->bytes
• bytes=?, …
• bytes->string/utf-8
• bytes->string/locale
• bytes->string/latin-1
• string->bytes/utf-8
• string->bytes/locale
• string->bytes/latin-1

• #rx"xxx": regular expression
• #px"xxx": perl regular expression

Functions:

• regexp-quote: generate a regular expression string that match the string literally
• regexp-match pattern input [start-pos end-pos]: find the pattern in the input. and return a list containing the result (only one). If no match, return #f. If has capture group, return the match and all captured group.
• regexp-match*: match multiple times, return list of results. #:match-select accepts a procedure (defaults to car). Examples: values (all), cadr
• regexp-match-position: like regexp-match, but return list of number pairs, each is a range of [start, end).
• regexp-match?: return #t or #f
• regexp-match-exact?: return #t only if entire content matches.
• regexp-split pattern input: complement of regexp-match*
• regexp-replace pattern input insert: replace the first match. Match can be referenced by using & (whole match), \0 (whole match), \n captured.
• regexp-replace*: replace all
• regexp-replaces input ([pat rep] ...): do regexp-replace* for each replacement in order, chained. Which means latter can operate on former.
• regexp-replace-quote: produce string suitable to use as replacement (unquoting \ and &)

Input port specific:

• regexp-try-match: like regexp-match, but if the input is a port, don't read the input on failure.
• regexp-match-peek: do not read input ports on both failure and success
• regexp-match-peek-positions: return positions
• regexp-match-peek-immediate: non-blocking on input port

(regexp-match #rx"x(.)" "12x4x6")
;; '("x4" "4")
(regexp-match* #rx"x(.)" "12x4x6" #:match-select var) ; default
;; '("x4" "x6")
(regexp-match* #rx"x(.)" "12x4x6" #:match-select values) ; all
;; '(("x4" "4") ("x6" "6"))
(regexp-match* #rx"x(.)" "12x4x6" #:match-select cadr)
;; '("4" "6")

The variants tradition:

• v: use eqv?
• q: use eq?
• f: accept and use a procedure

The APIs:

• length
• list-ref
• list-tail
• append
• reverse
• map, andmap, ormap
• for-each
• foldl, foldr
• filter pred lst: return list with items that makes pred #t.
• remove
• sort
• member, memf (using function): if found, return the tail list starting from the match
• findf: like memf, but return just the matched element.
• assoc v lst: the first element of lst whose car equal to v. E.g. (assoc 1 '((1 2) (3 4))) returns '(1 2). variants: assv, assq, assf

from racket/list

• empty?
• first
• rest
• second
• last
• list-update lst pos updater: the pos index is updated with (updater (list-ref lst pos))
• list-set lst pos value
• index-of lst v: return the index of the first v
• index-where lst proc: use function
• indexes-of, indexes-where: return all matches
• take lst pos: take only the first pos elements
• drop lst pos: same as list-tail
• split-at lst pos: same as (values (take lst pos) (drop lst pos))
• takef, dropf, splitf-at: take all the elements satisfying the function.
• take-right, drop-right, split-at-right, and their f-version
• list-prefix? l r: whether l is prefix of r
• take-common-prefix l r
• drop-common-prefix l r
• split-common-prefix l r
• flatten v
• check-duplicates lst
• remove-duplicates lst
• partition prod lst: return two lists, with items that prod evaluates to #t and #f respectively. It is the same as

  (values (filter pred lst)
          (filter (negate pred) lst))

• range end: [0,end)
• range start end [step=1]
• shuffle lst
• combinations lst [size]: if size is given, return only combination of length size.
• permutations lst
• argmin proc lst: return the first elemnt in lst that minimize (proc elem)
• argmax

Vectors

• vector-length
• vector-ref
• vector-set!: it makes sense to set a vector, because it takes constant time to access and update
• vector->list
• list->vector
• vector-fill! vec v
• vector-copy! dst dst-start src [src-start] [src-end]

A box is like a single-element vector, typically used as minimal mutable storage.

• box: create a box
• box?
• unbox: return the content
• set-box! box v: return #<void>
• box-cas! box old new: atomically update content from old to new, return #t. If does not contain old, nothing changed, and return #f.

From racket/vector:

• vector-map
• vector-append
• vector-take, vector-drop
• vector-take-right, vector-drop-right
• vector-split-at, vector-split-at-right
• vector-copy
• vector-filter
• vector-filter-not
• vector-count proc vec
• vector-argmin, vector-argmax
• vector-member
• vector-sort
• vector-sort!

• (hash key val ... ...)
• hash-set hash key v
• hash-ref hash key
• hash-has-key?
• hash-update
• hash-remove
• hash-clear
• hash-keys
• hash-values
• hash->list
• hash-keys-subset? hash1 hash2: hash1 is a subset of hash2?
• hash-count hash
• hash-empty?
• hash-union: require racket/hash

Sequence is designed to be used with for. Not only list and vectors are sequence, hash table is also sequence. Dictionary and set are also sequences. List can also be dictionary type.

• sequence?

Constructing sequences

• in-range
• in-naturals
• in-list
• in-vector
• in-string
• in-lines [in=(current-input-port)]
• in-hash
• in-hash-keys, in-hash-values, in-hash-pairs
• in-directory [dir use-dir?]: It is depth first. The path are built, not individual components. If dir is not given, use current dir. If use-dir? with signature (path? . -> any/c) is given, it acts like as a filter of the results

• set v ...: construct a hash set
• list->set lst: construct from list
• for/set
• set-member?
• set-add
• set-remove
• set-empty?
• set-count
• set-first
• set-rest
• set-copy
• set-clear
• set-union
• set-intersect
• set-subtract
• set=?
• subset? st1 st2: st1 is subset of st2?
• proper-subset? st1 st2: strict subset
• set->list
• in-set

struct id maybe-super (field ...) struct-option ...
field = field-id | [field-id field-option ...]

The struct form creates a structure type (unless #:prefab is specified), and some names (along with others). Now we use myid as the provided id:

• struct:myid: the structure type descriptor, can be used in #:super option
• myid: constructor, unless #:constructor-name option is specified
• myid?: predicate procedure
• myid-myfield: accessor procedure for each field

values produce multiple values value, to consume that, typically use let-values, let*-values, define-values. Also, binding forms that can destruct values can also be used.

For now, I only care about how to handle exceptions. To do that:

• call-with-exception-handler f thunk: (f ex)
• with-handlers ([pred-expr handler-expr] …) body …+

  (with-handlers ([exn:fail:syntax?
                   (λ (e) (displayln "got a syntax error"))]
                  [exn:fail?
                   (λ (e) (displayln "fallback clause"))])
    (raise-syntax-error #f "a syntax error"))

Here's the hierarchy of built-in exceptions

• exn
  • exn:fail
    • exn:fail:contract
    • exn:fail:syntax
    • exn:fail:read
    • exn:fail:filesystem
    • exn:fail:network
    • exn:fail:out-of-memory
    • exn:fail:unsupported
    • exn:fail:user
  • exn:break

To raise an exception, you can use:

• raise: too general, don't use for now
• error: raise exn:fail
• raise-user-error
• raise-syntax-error

Comparison

• Thread: all the threads are running parallel, but they run on the same processor.
• Future: can utilize multiple processors

Thread

• thread thunk: create a thread to run, and return immediately with thread descriptor. When thunk terminates, the thread terminates. Threads are managed in current custodian.
• thread?
• current-thread
• thread-suspend
• thread-resume
• kill-thread
• break-thread
• sleep [secs=0]: cause the current thread to sleep. 0 simply hint other threads to execute (useful??).
• thread-running?
• thread-dead?
• thread-wait thd: block until thd terminates
• thread-send thd v
• thread-receive: block until a v is ready
• thread-try-receive: non-block version

Parameters are procedures, which optionally accepts one argument. If no argument, get the value. Given the arguement, set the value. This is like a global variable, thus suitable for a command line option storage. The parameters are local to thread, and sub thread inherit parent ones, but not shared. This means setting the parameter will not affect the parameter in other thead (including parent thread).

To make a parameter, simply:

(define aaa (make-parameter #f))
(aaa) ; => #f
(aaa 3)
(aaa) ; => 3

Parameters are often used by parameterize it in some content, instead of set directly.

(parameterize ([param value-expr] ...)
  body ...+)

Future (racket/future)

• future thunk: return the future. It will not run, until touch it.
• touch f: blockingly run the future f, and return the result. After touch returns, the results are still hold in the future. You can touch it again and retrieve the same result. Then, how to run in parallel? Create a thread to touch it??
• current-future
• future-enabled?
• future?
• processor-count
• for/async (for-clause ...) body ...+

Places can also use multiple cores. Place enables greater parallelism than future, because it creates a new racket VM, and include separate garbage collection. Thus the setup and communication cost is higher. Places can only communicate through place channels.

• (getenv name)
• (putenv name value)

In racket/os

• gethostname
• getpid

The function cons builds lists. If second argument is a list, it adds the first one onto the list. This is called "consing onto the list". cons returns a newly allocated cons. Thus allocating memory from the heap is sometimes generally known as consing. list can also be used to create a list. append connect several list to become one. A proper list is either nil, or a cons whose cdr is a proper list. This definition is recursive. Improper list is shown in dotted notation, and is called a dotted list. The predicate null is specifically test empty list.

A family of functions is used to access elements of the list. The car of a list is the first element, the cdr is everything after the first. Common lisp also provides caar, cdddr, all the combinations up to 4-level. List has some special function to handle. nth and nthcdr is used to access element. first, second, …, tenth can retrieve corresponding element. last, butlast, and rest are also intuitive. nbutlast is the destructive version of butlast.

There are also some functions to access list properties. list-length returns the length. endp is a predicate to check the end of a list

List can be used to represent different data structures.

1. It can simulate a stack. push and pop are macros, and are defined using setf. pushnew is a variant of push that uses adjoin instead of cons.
2. List can form a tree. When using cons, the pointers are constructed in the list, thus lists might share components. Sometimes you have to make a copy of a list to avoid chaning other lists.
   • There are two functions to make copies: copy-list and copy-tree. copy-list recursive calls on the cdr of the list, thus it is not deep copy. On the contrary, copy-tree recurs on both car and cdr, thus copy entire list. Similarly, tree-equal can be used to test the equality of the whole tree.
   • To modify the structure of a list, substitute replace elements in a sequence, it does not go into deeper tree. The function subst will replaces elements in tree, deeply. Such form that recursing down both car and cdr is said to be doubly recursive. subst-if and subst-if-not provides the conditional substitution. Their destructive versions are available for efficiency nsubst, nsubst-if, nsubst-if-not.
3. List can also simulate a set. You can add an item to a set (a list) by adjoin. It will cons the item onto the list if it is not in the set. You can tell the member via member, member-if, member-if-not. Set operations include adjoin, union, intersection, set-difference, set-exclusive-or and their destructive counterparts nunion, nintersection, nset-difference, nset-exclusive-or. You can predict subset with subsetp and tail with tailp.
4. Finally, Association Lists are maps. This is often called assoc-list or alist, representing mapping. It is only used for small maps, because it is not efficient. The alist is just list of cons cells whose car is key, cdr is value. Apart from build the list of cons cells, parilis can be used to create a alist from lists of keys and values. Add new key value pairs onto the alist with acons. Use assoc to retrieve the first cons cell with the key, and nil if not found. Use setf with assoc to set the value. The condition version of assoc are assoc-if and assoc-if-not. Lisp allows not only map from car to cdr, but also cdr to car with rassoc, rassoc-if, rassoc-if-not. Use copy-alist to copy the alist.
5. The Property list (plist for short) is similar to alist, but structured differently. It is a flat list, with keys and values intersect each other. E.g. (A 1 B 2). It is less flexible than the alist, and you can only use getf with a key to get the value. getf and setf can be used together to set the value. Use remf to remove a key value pair from the plist. You can also retrieve multiple key-values by get-properties.
   • The special thing about plist is that, each symbol has a plist. It can be retrieved by symbol-plist, but this is rarely used because the whole plist is not often the focus. What you need is get that directly get the key of the plist of the symbol. In other words, (get 'symbol 'key) equals to (getf (symbol-plist 'symbol) 'key). remprop is a similar function to remf.

Mapping is very powerful. The most frequently used is mapcar. It takes a function and some lists. Each time, it takes one element from the lists out as arguments to the function, until some list runs out, and finally return the results in a list. maplist takes the same arguments and does the same thing, but everytime apply function on the cdrs of the lists. Other map functions include mapcan, mapcon, mapc, mapl.

One last trick, the destructuring-bind can be used to bind variables. It cna be used to bind into tree structures.

(destructuring-bind (x y z) (list 1 2 3))
(destructuring-bind (x y z) (list 1 (list 2 20) 3)) ; y = (2 20)
(destructuring-bind (x (y1 y2) z) (list 1 (list 2 20) 3)) ; y1=2

Sequence contains both lists and vectors. To tell what kind of sequence it is, one can use consp, listp, bit-vector-p, vectorp, simple-vector-p, simple-bit-vector-p, arrayp. You can use length to get the length of a list.

Accessing the element of a sequence with elt. subseq get the subsequence in [begin,end) with index starting from 0.

In modifying a list, reverse and nreverse reverses the list. remove, remove-if, remove-if-not remove from a sequence while the destructive version named delete delete-if delete-if-not. remove-duplicates and delete-duplicates make sure no same element in the sequence. substitute, substitute-if, substitute-if-not replace within the sequence, does not go deeper. nsubstitute nsubstitute-if nsubstitute-if-not are destructive. There are sort and stable-sort, but they are destrictuve, so if in doubt, pass a copy. concatenate (reqiures type) is used for concatenate many sequences into one. merge (requires type) destructively merge two sequence. If both of them are sorted, the result is also sorted.

It is possible to search inside a sequence. find and position returns the element and index of the first match, respectively. Their predicate versions are find-if, find-if-not and position-if, position-if-not. count, count-if, count-if-not returns the count. One can also search a sequence in another.

map (requires return type) maps a function to a sequence. The map also needs a type as first argument. nil means no return, then map will return nil. map-into does not require a type, but the first argument is a sequence that will be destructed. Kind of a mapping, but every, notany and some, notevery are predicates to test on a sequence. reduce differs from map in that it always utilize the previous result in the next computation.

A string is a specialized vector (one-dimensional array) whose elements are characters. A character object can be notated by writing #\c where c is any standard character.

To access the characters, instead of aref, you can use char which is faster.

In comparision, while numeric value uses =, /= and <, characters have case sensitive (char=, char/=, char<) and insensitive versions (char-equal, char-not-equal, char-lessp). Strings also have case sensitive (string=, string/=, string<) and insensitive versions (string-equal, string-not-equal, string-lessp). This is actually a family of functions: string-greaterp, string-not-greaterp, string-not-lessp.

You can construct a string by make-string with size, or convert from another type to string via string. Trimming a string is handled by string-trim, string-left-trim, string-right-trim. Case conversion can be done by string-upcase, string-downcase, string-capitalize and their destructive versions nstring-upcase, nstring-downcase, nstring-capitalize.

Array can be general array, holding arbitrary object types; it can also be a specialized array that hold a given type, which increase the efficiency. One dimentional arrays are called vectors. Vectors holding arbitrary objects are general vectors.

There are two kinds of array: fixed and resizable. An array can be created by make-array. Since vector is more often used, you can simply use vector to create a one-dimension array. When you make an array, you specify the size, making a fixed size array. For resizable, there're two ways. First, you can give a :fill-pointer when making the array. For example (make-array 5 :fill-pointer 0) makes an empty array of capacity 5. This array can be used in vector-push and vector-pop who operates on the :fill-pointer. However, this seems resizable, but the capacity is at most 5. The second way to make the real resizable array is to give :adjustable t option wehn making it. Instead of using vector-push, you use vector-push-extend to operate on it so that it can take care of the capacity. The arrays are all general array that can hold different data types, you can create an array suitable for one type by giving :element-type option.

aref is used to access the element of an array. To replace elements, we use setf with aref. For vector, you might want to use svref, where sv means "simple vector", to access elements faster.

Array holding type bit are called bit-vectors. Bit operations are supported via bit, sbit, bit-and, bit-ior, bit-xor, bit-eqv, bit-nand, bit-nor, bit-andc1, bit-andc2, bit-orc1, bit-orc2, bit-not

Macro (defstruct point x y) will also define make-point, point-p, copy-point, point-x, point-y. The read format is #S.

This is a map. make-hash-table creates a hash-table. The test predicate :test for keys can be one of eq eql equal equalp with eql as default.

gethash retrieve from the table. It returns multiple values, with first be the value of the key or nil if no such key. The second value present whether the key is present. Use setf together with gethash can set the hash.

To remove an object from hash table, use remhash. You can also clear the table by clrhash. To iterate through a hash table, use maphash.

Lisp is case-insensitive. The program will be converted to upper case when stored in computer. Symbol names can be, in addition to letters and numbers, the following characters can also be considered to be alphabet: + - * / @ $ % ^ & _ = < > ~ . Conventionaly we write +global-constant+ and *global-variable*.

A symbol has a Property List. It can be retrieved by symbol-plist.

Global variable can be defined by defvar and defparameter. Naming convention is put * surrounds it. The difference (Prefer defvar):

• defparameter will always assign the initial value
• defvar will do so only if the variable is not defined; defvar can also be used without initial value, the variable will be unbound.

defconstant is used to declare constant. Use + surrounds it. It is possible to redefine the constant using defconstant again, but the behavior is undefined. E.g. the code refer to it might need to be reevaluated to see the update. So, do NOT redefine a constant, otherwise it is not a constant, use defparameter instead.

Local variables have lexical binding, global variables have dynamic binding. Under lexical scope, a symbol refers to the variable where the symbol appears. With dynamic scope, a variable is looked up where the function is called, not where it is defined. To cause a local variable to have dynamic scope, we declare it to be special ((declare (special x))).

Assigning a value to a binding is:

1. change the binding only, do not change other hidden bindings for this symbol
2. do not change the value object the binding refers to

The symbol is a reference of the object. Assigning to the symbol will create another reference to another object. But, if the object is mutable, then assign to the reference will change the object. Function parameters are reference. So if the object is mutable, then assigning to the parameter will change the referenced object.

The general assignment operator is setf (place value)+. When assigning a binding, it will call setq (but don't call setq directly!), and returns the newly assigned value. In the document, a SEFTable thing is suitable to be a setf place. Always use setf instead of setq. This is more general. This includes variables, array locations, list elements, hash table entries, structure fields, and object slots.

To make the code more concise, some "f-family" are invented.

(incf x)

(setf x (+ x 1))

(decf x)

(incf x 10)

here incf and decf modifies the argument, so they are called modify macros. Other modify macros:

• push, pop, pushnew
• rotatef, shiftf
  • (roratef a b) is equal to (let ((tmp a)) (setf a b b tmp) nil)
  • (shiftf a b 10) shifts all the values left, equals to (let ((tmp a)) (setf a b b 10) tmp)

There are two types of destructive functions:

• for-side-effect: typically use setf
• recycling operation

The recycling operations are typically those with n as prefix. 80 percent of the use cases are PUSH/NREVERSE and SETF/DELETE.

 (defun upto (max)
   (let ((result nil))
     (dotimes (i max)
       (push i result))
     (nreverse result)))

 (setf foo (delete nil foo))

sort is also destructive, so use it on a copy of the list. Be sure to assign it back to the variable.

 (defparameter *list* (list 4 3 2 1))
 (sort *list* #'<) ;; (1 2 3 4)
 *list* ;; (4)
 ;; so shoud use:
 (setf *list* (sort *list* #'<))

Common Lisp is strong typed, but the type is associated with objects, not variables. This approach is called manifest typing. Though type declarations are completely optional, you might want to do this for efficiency.

nil is false, everything else is true nil is both an atom and a list. () is exactly the same as nil

In Common Lisp, the types form a hierarchy. An object always has more than one type. The type t is the super type of all types, so everything is of type t. For example, a number 13 is of type fixnum, integer, rational, real, number, atom, t.

Function typep ((typep obj type)) tests whether an object is of a type. (subtypep type1 type2) tests the type hierarchy.

Type conversion functions are those I found used most but hardly remember, documenting here.

• parse-integer: string to integer

Numbers can use read form, e.g. #b010101, #xaf08. Predicates such as numberp, integerp, rationalp, floatp, realp, complexp can test the type of an object. For numbers, zerop, plusp, minusp, oddp, evenp can tests the property.

Number comparison can be <, >, <=, >=, =. These are same as using the operator sequencially on the operands. /= works pairwise. max and min get the maximum and minimum one.

(1+ x) same as (+ x 1). incf and decf are destructive. gcd greatest common divisor, lcm least common multiple.

Scientific computations are supported. exp computes exponential with \(e\) while expt computes general exponential. log computes log to \(e\) if the second parameter is omitted. sqrt is a special case of expt with 1/2 as the power.

The function of type name is used to do convertion, including float, rational. Some types of number have two parts. For ratio, numerator and denominator get the two parts. Break number into two parts can be done by several pairs of functions: signum and abs (sign and value), mod and rem, realpart and imagpart for complex.

Rounding can be done with floor (toward negative infinity), ceiling (toward positive infinity), truncate (toward 0), and round (to nearest integer). Float version is also available: ffloor, fceiling, ftruncate, fround.

Logical operations are available as well. logior, logxor, logand, logeqv, lognand, lognor, logandc1, logandc2, logorc1, logorc2, lognot Besides, boole seems to be a more general function that accept many operations that cover all above.

random create random numbers.

The predicate fboundp tells whether there's a function with a given symbol name. symbol-function can retrieve the function object with the symbol. The document of a globally defined function can be retrieved by calling documentation. The function's read format is called sharp-quote, the special form function takes a function name and return the function object. The function object can be obtained by #'.

Macro is designed to abstract away common syntactic patterns.

macroexpand-1 can be used to check the expension in one level.

When designing macros, there are three kinds of leaks of implementation details that you need avoid.

• multiple evaluation of parameters
  • You must evaluate each param once, because that is the intuition of user of the macro.
  • to fix it, evaluate it ones and bind to a variable
• order of evaluating parameters
  • you need to make sure the order of evaluation of parameters is from left to right. Again this to follow the intuition of user.
• variable scope
  • use GENSYM to create name to use. For example the code below, the name is generated at expanding time, and ,name is used whenever you want to use the variable.

  (defmacro mymac (param)
    (let ((name (gensym)))
      `(let ((,name ,param))
         ,name)))

• eval form: evaluate form in the current dynamic environment and a null lexical environment
• evalhook
• applyhook

The quote operator is a special operator, meaning that it has a distinct evaluation rule of its own: do nothing. (quote (+ 3 5)) is same as '(+ 3 5). It is a way of pretecting expressions from evaluation.

Integers and strings both evaluate to themselves. nil evaluates to itself as well. Empty list () is exactly nil, thus is also self-evaluated.

There are 25 special operators

• block
• catch
• compiler-let
• declare
• eval-when
• flet
• function
• go
• if
• labels
• let
• let*
• macrolet
• multiple-value-call
• multiple-value-prog1
• progn
• progv
• quote
• return-from
• setq
• tagbody
• the
• throw
• unwind-protect

When compile a file, it evaluates all top level forms in the file. If the top level is eval-when, things can be controled. eval-when accepts three different situations, namely :compile-toplevel, :load-toplevel, :execute. You can specify multiple of them, thus can make the top level evaluates at compile time, load time, or both.

There's probably only one eval-when is useful, that is use ALL of them:

(EVAL-WHEN
 (:COMPILE-TOPLEVEL :LOAD-TOPLEVEL :EXECUTE)
 ...)

should wrap things that need be available in the compilation environment as well as the target environment. E.g. a defined function that is used in defmacro.

A catch expression takes a tag, which can be any kind of object, followed by a body of expressions. A throw with the corresponding tag will cause catch to return immediately. If there's no pending catch with the right tag, the throw causes an error.

Calling error interrupt the execution, and transfer the control to the lisp error handler.

Loop keywords are not true common lisp keywords. They are symbols recognized only by Loop Facility. If you do not use any loop keywords, the loop simply runs forever.

loop is a macro, and expansion produces an implicit block named nil, and it accepts three basic part in its tagbody:

• loop prologue: execute before iteration begin
• loop body: execute during each iteration
• loop epilogue: execute after iteration termination

All variables are initialized in the loop prologue.

These input/output operations perform on streams. Streams are lisp objects representing sources and destinations of characters.

By default, input is read from the stream *standard-input*, output is written to *standard-output*. Conventionally the suffix -input and -output means the input and output stream respectively, while -io represents streams with bidirectional stream. Similar variables include *error-output*, *query-io*, *debug-io*, *terminal-io*, *trace-output*.

read is a complete lisp parser. When inputing a number, it parses and returns the number, instead of a string. read reads up to an expression. read-line read until a newline. read-from-string read an expression from a string. All of these are defined on the primitive read-char which reads a single character. peek-char read the character without removing it from the stream. You can also unread a char by unread-char. parse-integer is often used if you want to get the integer.

prin1 generates output for programs (with double quotes), while princ generates for human. terpri prints a newline. pprint prints with indention. format output the control-string except that a tilde introduces a directive. Most directives use one or more elements of arguments. If no more arguments, signal an error. But it is ok is more arguments are provided and unprocessed. If the destination is nil, a string is created as the output and get returned. Otherwise format returns nil.

A format directive is determined by one single character. It can take optional prefix. The prefix can be separated using : or @ or both. Parameters are separated by comma, and they can be ommited to take the default value. What kind of parameters are accepted is determined by the directive character. The most commonly used directive is ~A which is a place holder for a value printed by princ. ~% outputs a newline. ~F outputs a float number.

A pathname is a portable way to specifying a file. A pathname has 6 components: host, device, directory, name, type, and version.

Open a file as stream by open. It has some keyword arguments to modify its behavior. :direction keywords takes :input, :output or :io. :if-exists takes :supersede. We typically use setf to store the stream returned by open. The steam is closed by close. with-open-file is often more convenient, we don't need to remember to close.

In case you only have a string, it is convenient to use with-input-from-string and with-output-to-string.

This is used to solve name conflict.

• *package*
• make-package
• in-package
• find-package
• package-name
• package-nicknames
• rename-package
• package-use-list
• package-used-by-list
• package-shadowing-symbols
• list-all-packages
• delete-package
• intern
• find-symbol
• unintern
• export
• unexport
• import
• shadowing-import
• shadow
• use-package
• unuse-package
• defpackage
• find-all-symbols
• do-symbols
• do-external-symbols
• do-all-symbols
• with-package-iterator

https://common-lisp.net/project/asdf/asdf.html

A module is identified by a list of one or more symbols indicating the hierarchy, e.g. (ice-9 popen). When creating a module, you typically supplies what modules to depend on, and what symbols are exported as its public interface:

(define-module (ice-9 popen)
  #:use-module (ice-9 popen)
  #:use-module (ice-9 pclose)
  #:export (my list-of names))

When using a module, the use-modules accesses this public interface.

(use-modules (ice-9 popen))
(use-modules ((ice-9 popen)
              #:select ((open-pipe . pipe-open) close-pipe)
              #:renamer (symbol-prefix-proc 'unixy:)))
(use-modules ((ice-9 popen)
              #:select ((open-pipe . pipe-open) close-pipe)
              #:prefix unixy:))

Another way to access a module is through @ syntax:

(define unixy:pipe-open (@ (ice-9 popen) open-pipe))
(define unixy:close-pipe (@ (ice-9 popen) close-pipe))

The @@ syntax does the same thing, but is able to access private bindings.

Both method will try to find the module in %load-path, and if not loaded, will load it.