From 09e942fcd40c80db96b9a831bd01a733ae3039e5 Mon Sep 17 00:00:00 2001 From: Mark Simpson Date: Mon, 11 Jan 2021 17:42:52 -0500 Subject: [PATCH] Review generated concept introductions * Small cleanup to generated introduction files. Most content was "ok" after being copied from the exercise introduction.md but a few needed tweaking. * A small expansion of the comment concept. * Slight expansion of conditionals concept. * A little cleanup of sexpressions concept. --- concepts/comments/introduction.md | 9 ++-- concepts/conditionals/introduction.md | 8 +++ concepts/expressions/introduction.md | 6 +-- .../floating-point-numbers/introduction.md | 2 +- concepts/lambda-list/introduction.md | 52 +------------------ concepts/sameness/introduction.md | 2 +- concepts/symbols/introduction.md | 7 +-- 7 files changed, 18 insertions(+), 68 deletions(-) diff --git a/concepts/comments/introduction.md b/concepts/comments/introduction.md index 54dda17c..1a8023d3 100644 --- a/concepts/comments/introduction.md +++ b/concepts/comments/introduction.md @@ -1,10 +1,9 @@ -Common Lisp allows the programmer to write "comments" that are ignored by the -computer. Single-line comments begin with one or more semi-colons (`;`) and, -occasionally, you may see the following: +Common Lisp allows the programmer to write "comments" that are ignored by the computer. Single-line comments begin with one or more semi-colons (`;`) and, occasionally, you may see the following: ```lisp (code...) ; => value ``` -Where the comment is being used to indicate what value is returned by Common -Lisp after running the code on that line. +Where the comment is being used to indicate what value is returned by Common Lisp after running the code on that line. + +It is idiomatic to use a single semi-colon for a short comment at the end of a line, two for a longer comment above a section of code, three for long comment describing something such as a function and four for a comment such as a header at the top of a source file. diff --git a/concepts/conditionals/introduction.md b/concepts/conditionals/introduction.md index df632145..b11824e2 100644 --- a/concepts/conditionals/introduction.md +++ b/concepts/conditionals/introduction.md @@ -7,12 +7,16 @@ Common lisp provides several different conditional expressions, the main differe (unless (= 2 2) "Time to panic!") ; => NIL ``` +The section after the test expression may be more than one expression. + - `if` provides the classic if-then-else construct: ```lisp (if (= 2 2) 'how-honest 'you-liar) ; => HOW-HONEST ``` +Note that both the then and else clauses can only be a single expression. + - `cond` provides a way to have multiple branches without nesting `if` expressions: ```lisp @@ -24,6 +28,8 @@ Common lisp provides several different conditional expressions, the main differe ; => QUITE-TRUE ``` +Note that there is limit to the number of expressions after the test expression. + - `case` provides a classic 'switch' style construct: It checks a single value against a number of branches: ```lisp @@ -34,3 +40,5 @@ Common lisp provides several different conditional expressions, the main differe (otherwise "???")) ; => "???" ``` + +Note that like `cond` there is no limit to the number of expressions after the test expression. diff --git a/concepts/expressions/introduction.md b/concepts/expressions/introduction.md index 5dbef63e..b8683fc9 100644 --- a/concepts/expressions/introduction.md +++ b/concepts/expressions/introduction.md @@ -1,8 +1,4 @@ -Together, the atoms and conses that make up Lisp code are referred to as -S-Expressions (or sexpr for short). When S-Expressions are evaluated, they -automatically return some value which takes the place of the expression. When -writing your own functions (using `defun`), the last value within the body of -the `defun` is automatically returned: +All Common Lisp code is made of S-Expressions (Symbolic Expressions). They are called sexprs for short. Every sexpr is either an atom or a cons. When S-Expressions are evaluated, they automatically return some value which takes the place of the expression. When writing your own functions (using `defun`), the last value within the body of the `defun` is automatically returned: ```lisp ;; Defining a new function diff --git a/concepts/floating-point-numbers/introduction.md b/concepts/floating-point-numbers/introduction.md index e288ade8..3769cb1c 100644 --- a/concepts/floating-point-numbers/introduction.md +++ b/concepts/floating-point-numbers/introduction.md @@ -1 +1 @@ -Also like many languages, Common Lisp contains floating point numbers. These are fractional or whole numbers including a decimal point (like `3.14`, `-1.7`, `99.99`, `2048.0`) +Like many languages, Common Lisp contains floating point numbers. These are fractional or whole numbers including a decimal point (like `3.14`, `-1.7`, `99.99`, `2048.0`). diff --git a/concepts/lambda-list/introduction.md b/concepts/lambda-list/introduction.md index 4cbe5c90..0809c60b 100644 --- a/concepts/lambda-list/introduction.md +++ b/concepts/lambda-list/introduction.md @@ -1,54 +1,6 @@ -TODO: the content below is copied from the exercise introduction and probably needs rewriting to a proper concept introduction +In Common Lisp a function's argument list is known as a ('lambda list')[lambda-list]. A lambda list can can have arguments of different types. These different types are designated with the use of ('lambda list keywords')[lambda-list-keyword] which all begin with `&`. The most commonly used types are optional, keyword and rest arguments types. Every parameter in the lambda list after a particular lambda list keyword is will be of that type. A lambda list keyword can only be used once in a lambda list. -In Common Lisp a functions argument list (also known as a ('lambda list')[lambda-list]) can have arguments of different types. These different types are designated with the use of ("lambda list keywords")[lambda-list-keyword] which all begin with `&`. The most commonly used types are optional, keyword and rest arguments types. Every parameter in the lambda list after a particular lambda list keyword is will be of that type. A lambda list keyword can only be used once in a lambda list. - -## default-parameters - -In Common Lisp a function can have some arguments are are optional. These are designated in the lambda list by `&optional` lambda list keyword. A parameter will be bound to the value `nil` if it is not specified. If there are several optional parameters they are bound in order. Default values can be specified for optional parameters. Finally a symbol an be specified for each optional parameter which will be bound to true or false depending on whether that parameter was supplied by the caller of the function (this is referred to as the "supplied-p parameter"). - -```lisp -(defun default-parameters (&optional x (y 'default) (z nil z-supplied-p)) - (list x y (if z-supplied-p (list :z-was-supplied z) - (list :z-was-not-supplied z)))) - -(default-parameters) ;; => (NIL DEFAULT (:Z-WAS-NOT-SUPPLIED NIL)) -(default-parameters 5 nil 10) ;; => (5 NIL (:Z-WAS-SUPPLIED 10)) -``` - -## named-parameters - -In Common Lisp a function can have named parameters (referred to as "keyword parameters" or "keyword arguments"). These are designated in the lambda list by the `&key` lambda list keyword. Keyword parameters are not required parameters. Like optional parameters they can be given default values and symbols to bind to their 'supplied-or-not' state. - -When calling a function with keyword parameters the name of the parameter as a keyword is used in front of the parameter value. Keyword parameters can be specified by the caller of the function in any order. - -```lisp -(defun keyword-parameters (&key x (y 'default) (z nil z-supplied-p)) - (list x y (if z-supplied-p (list :z-was-supplied z) - (list :z-was-not-supplied z)))) - -(keyword-parameters) ;; => (NIL DEFAULT (:Z-WAS-NOT-SUPPLIED NIL)) -(keyword-parameters :y 5) ;; => (NIL 5 (:Z-WAS-NOT-SUPPLIED NIL)) -(keyword-parameters :z 10 :x 5) ;; => (5 NIL (:Z-WAS-SUPPLIED 10)) -``` - -Care should be taken when combining optional and keyword arguments as the keyword name and argument could be consumed by optional parameters: - -```lisp -(defun could-be-confusing (&optional x y &key z) (list x y z)) -(could-be-confusing :z 'huh?) ;; => (:Z HUH? NIL) -``` - -## rest-parameters - -In Common Lisp a function can have a parameter that will contain the "rest" of the arguments after any required or optional parameters are processed. This parameter is designated by the `&rest` lambda list keyword. If all arguments to a function are used by by other types of parameters then the rest parameter will be bound to an empty list. If there are unused arguments then the rest parameter will be bound to a list of those arguments. - -```lisp -(defun rest-of-it (req &optional opt &rest rest) (list req opt rest)) -(rest-of-it 1) ;; => (1 NIL NIL) -(rest-of-it 1 2) ;; => (1 2 NIL) -(rest-of-it 1 2 3) ;; => (1 2 (3)) -(rest-of-it 1 2 3 4 5) ;; => (1 2 (3 4 5)) -``` +Lambda lists are also used in other constructs which will be discussed later such as destructuring and macros. -- [lambda-list]: http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_l.htm#lambda_list diff --git a/concepts/sameness/introduction.md b/concepts/sameness/introduction.md index 8e5ef9c9..bcb9ce53 100644 --- a/concepts/sameness/introduction.md +++ b/concepts/sameness/introduction.md @@ -1,4 +1,4 @@ -Common Lisp has many different equality predicates. This differs from other programming languages which may have only one or two (perhaps `==` and `===` for example). Some of these predicates in Common Lisp are specific to types, while others are generic. It is these latter that this exercise will teach. +Common Lisp has many different equality predicates. This differs from other programming languages which may have only one or two (perhaps `==` and `===` for example). Some of these predicates in Common Lisp are specific to types, while others are generic. It is these latter that this concept will cover. There are four generic equality predicates and they differ by their restrictiveness on what they consider "equal". They are, in order from most restrictive to least restrictive: `eq`, `eql`, `equal`, and `equalp`. diff --git a/concepts/symbols/introduction.md b/concepts/symbols/introduction.md index b0c087f8..f10f04f8 100644 --- a/concepts/symbols/introduction.md +++ b/concepts/symbols/introduction.md @@ -1,9 +1,4 @@ -There are a couple of things to note regarding the example above. Firstly, the -_symbol_ `FOO` is an atom, as it only has one "part" (unlike a cons which has -two). Additionally, Common Lisp is **case-insensitive**, so symbols are often -returned as all uppercase, but `foo`, `Foo` and `FOO` are equivalent. - -Symbols in Lisp are special values that can point to other values or, in the +Symbols in Common Lisp are special values that can point to other values or, in the case of _keywords_, themselves. When symbols are evaluated by Lisp, they are replaced with the values they point to: