Recent changes to Common-lisp-tutorial

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Mon, 04 Sep 2017 00:31:10 -0000

--- v115
+++ v116
@@ -444,7 +444,8 @@

 But what if you actually want to refer to "\\\\"?  No problem, just use the expression "{\\\\}".  Common Lisp, and some other lisps, supports "slashification" (e.g., if "\" followed by any character means that character is part of a symbol).  But this symbol \\\\ is chosen so that it can be written in any Lisp.  If that Lisp doesn't use slashification, \\\\ means the symbol with a two-character name \\\\.  If it uses slashification, \\\\ means the symbol with the one-character name \\.  The good news is that you can use the marker \\\\ on practically any Lisp system, so you don't need to constantly change notation if you use different ones.

-The readable-lisp implementation also supports a special line continuation extension.  If there's at least one expression on the line, and the line ends with "\\\\", then this is consier a line continuation - the line continues as if the newline never occurred.  This is similar to how many other languages handle "\\" at the end of a line.  The following line has to have the same indentation as the previous line with the "\\\\" at the end.  You can keep doing this for as many lines as you'd like.  This extension is technically not part of the sweet-expression specification, it's simply a permitted extension, but in Common Lisp this extension can be useful.
+The readable-lisp implementation also supports a special line continuation extension.  If there's at least one expression on the line, and the line ends with "\\\\", then the "\\\\" is considered a line continuation.  That is, the line continues as if the newline never occurred.  This is similar to how many other languages handle "\\" at the end of a line.  The following line has to have the same indentation as the previous line (the line with the "\\\\" at the end).  You can keep doing this for as many lines as you'd like.  This extension is not part of the sweet-expression specification in SRFI-110, it's simply a permitted extension, but in Common Lisp this extension can be useful.  It has been added to the Scheme implementation for consistency with the Common Lisp implementation.
+

 Sublist
 -------

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Mon, 04 Sep 2017 00:23:27 -0000

--- v114
+++ v115
@@ -444,6 +444,8 @@

 But what if you actually want to refer to "\\\\"?  No problem, just use the expression "{\\\\}".  Common Lisp, and some other lisps, supports "slashification" (e.g., if "\" followed by any character means that character is part of a symbol).  But this symbol \\\\ is chosen so that it can be written in any Lisp.  If that Lisp doesn't use slashification, \\\\ means the symbol with a two-character name \\\\.  If it uses slashification, \\\\ means the symbol with the one-character name \\.  The good news is that you can use the marker \\\\ on practically any Lisp system, so you don't need to constantly change notation if you use different ones.

+The readable-lisp implementation also supports a special line continuation extension.  If there's at least one expression on the line, and the line ends with "\\\\", then this is consier a line continuation - the line continues as if the newline never occurred.  This is similar to how many other languages handle "\\" at the end of a line.  The following line has to have the same indentation as the previous line with the "\\\\" at the end.  You can keep doing this for as many lines as you'd like.  This extension is technically not part of the sweet-expression specification, it's simply a permitted extension, but in Common Lisp this extension can be useful.
+
 Sublist
 -------

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Tue, 26 May 2015 03:30:00 -0000

--- v113
+++ v114
@@ -119,7 +119,7 @@
 Using basic curly-infix-expressions (c-expressions)
 =============================================

-Let's first try out "curly-infix-expressions" (c-expressions).  We'll assume you've installed things, and that you've successfully loaded the "readable" library using either *(asdf:load-system :readable)* or *(ql:quickload "readable")*.
+Let's first try out "curly-infix-expressions" (c-expressions).  We'll assume you've installed things, started up your favorite Common Lisp implementation, and that you've successfully loaded the "readable" library using either *(asdf:load-system :readable)* or *(ql:quickload "readable")*.

 To enable basic c-expressions, run this command (which will modify our existing readtable to add these capabilities):

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Tue, 26 May 2015 03:26:53 -0000

--- v112
+++ v113
@@ -12,9 +12,11 @@
 Starting Common Lisp implementation and loading the readable library
 ====================================================================

-You need to run your implementation of Common Lisp and then load the "readable" library.  Any Common Lisp implementation should work, as it only depends on standard Common Lisp mechanisms. The sbcl implementation is especially well-tested and known to work well.  Unfortunately, clisp has a number of annoying limitations and problems, so we would recommend another implementation (such as sbcl).  That said, the readable notation does *work* on clisp if you want to use it, and we do include information below on how to work around clisp's problems.
-
-You can load the "readable" library by using QuickLisp, or by invoking ASDF directly. Here is how to do it in each case.
+You need to run your implementation of Common Lisp and then load the "readable" library.  Any Common Lisp implementation should work, as it only depends on standard Common Lisp mechanisms. The sbcl implementation is especially well-tested and known to work well.
+
+Unfortunately, the clisp implementation of Common Lisp has a number of annoying limitations and problems, so we would recommend another implementation (such as sbcl).  That said, the readable notation does *work* on clisp if you want to use it, and we do include information below on how to work around clisp's problems.  As of May 2015 it is still a live project, but the last release of clisp was in 2010; as a result, the clisp-provided ASDF system is absurdly old.  We provide some work-arounds for various broken behaviors of clisp, but they are less than optimal.  If you want an especially portable implementation of Common Lisp, you might consider CCL (which is effectively very portable) or ECL (which is written completely in C).
+
+You can load the "readable" library by using QuickLisp, or by invoking ASDF directly. QuickLisp is by far the easiest way, though using it doesn't install a few tools you might want.  Here is how to do it in each case.

 Loading the "readable" library via QuickLisp
 --------------------------------------------
@@ -100,6 +102,8 @@
     (setf (readtable-case *readtable*) :invert)

 "Readtable-case" is a general capability of Common Lisp, not specific to the "readable" notations, but all readable notations work with it.  It's best to do this *before* enabling a readable notation. From here on, we'll assume you did this, though it is not required.
+
+I think that using readtable-case :invert makes interacting with Common Lisp more pleasant.  The one issue is that when debugging some actoins will reveal that the symbols are actually (still) being stored as upper case for compatibility's sake.  I think that's a small price to pay.

 A few other notes

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Wed, 19 Nov 2014 02:20:30 -0000

--- v111
+++ v112
@@ -253,16 +253,6 @@
     f{{x + 2} * {y - 3}} <==> (f (* (+ x 2) (- y 3)))

-Wrapping up neoteric-expressions
---------------------------------
-
-Neoteric-expressions are a nice step forward.  But we still have to do all that parentheses-balancing, which hinders readability. Sweet-expressions, our next stop, address this.
-
-To end this part of the demo, disable our changed notation:
-
-    (readable:disable-readable)
-
-

 Another clisp limitation: ugly vertical bars in symbols
 =======================================================
@@ -287,7 +277,7 @@
 Using sweet-expressions (t-expressions) 
 =======================================

-Sweet-expressions take neoteric-expressions and infers parentheses from indentation.  You can enable neoteric-expressions by running:
+Sweet-expressions start with neoteric-expressions and in addition infers parentheses from indentation.  You can enable neoteric-expressions by running:

     (readable:enable-sweet)

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Wed, 19 Nov 2014 02:17:00 -0000

--- v110
+++ v111
@@ -279,7 +279,7 @@

 The "sweet-clisp" script may help.  It uses both of these mechanisms (print-escape nil and special printing routines), and also works around some other clisp bugs, to prevent all those ugly vertical bars.

-We hope that this will not happen in a future version of clisp.  The problem is in clisp's write procedure.  More specifically, the problem is in clisp source file "src/io.d" function "pr_symbol_part", which implements this weird behavior yet provides no mechanism to turn it off.   On 2013-05-06 David A. Wheeler raised the issue of adding such flexibility to clisp.  If clisp were more flexible, then the readable library could use that flexibility to inhibit these extraneous vertical bars.  At the time of this writing the clisp developers have refused to fix this.
+We hope that this will not happen in a future version of clisp.  The problem is in clisp's write function.  More specifically, the problem is in clisp source file "src/io.d" function "pr_symbol_part", which implements this weird behavior yet provides no mechanism to turn it off.   On 2013-05-06 David A. Wheeler raised the issue of adding such flexibility to clisp.  If clisp were more flexible, then the readable library could use that flexibility to inhibit these extraneous vertical bars.  At the time of this writing the clisp developers have refused to fix this.

 A completely different solution, if you hate how the symbols look, is to switch to another Common Lisp implementation like sbcl.  This will also enable auto-loading of rc files as discussed above (a problem in clisp that impacts QuickLisp).

@@ -298,7 +298,7 @@
 - Lines with *only* a ;-comment, and nothing else, are completely ignored - even their indentation is irrelevant.
 - Whitespace-only lines at the beginning of a new expression are ignored, but a whitespace-only line (including a zero-length line) ends an expression.

-Here's a notional example, with a sweet-expression on the left and its equivalent traditional s-expression on the right (this won't *run* if you type it in, since we have no procedure called "a"):
+Here's a notional example, with a sweet-expression on the left and its equivalent traditional s-expression on the right (this won't *run* if you type it in, since we have no function called "a"):

     a b c d        =>   (a b c d
       e f g                (e f g)
@@ -372,7 +372,7 @@
          1
          {n * factorial{n - 1}}

-Note that infix is easily expressed with {...}.  You can call a procedure using an infix expression with f{...}, a common circumstance.  Naturally, this is simply a cleaner representation of:
+Note that infix is easily expressed with {...}.  You can call a function using an infix expression with f{...}, a common circumstance.  Naturally, this is simply a cleaner representation of:

     (defun factorial (n)
       (if (<= n 1)
@@ -533,10 +533,10 @@

 The "readable" library comes with some other functions you can call.

-Reading procedures
+Reading functions
 ------------------

-Various procedures let you read using a specific notation:
+Various functions let you read using a specific notation:

 *   curly-infix-read: Read a curly-infix-expression datum.
 *   neoteric-read: Read a neoteric-expression datum.
@@ -546,9 +546,9 @@
 Writing readable expressions
 ----------------------------

-Version 1.0.5 adds additional procedures in Common Lisp to print expressions using these readable notations.  That way, you can easily print these notations as well as read them.  Their interfaces are intentionally similar to the standard Common Lisp procedures, so they should be easy to use.
-
-Procedure "write-readable" writes out its first parameter in a readable notation, similar to the standard procedure write.  It takes all the optional parameters of write (such as :stream), plus the optional ":notation" parameter for controlling the output notation.  By default, the output notation is the same as the input notation.  The ":notation" parameter can be 'basic-curly-infix, 'full-curly-infix, 'neoteric, or 'sweet.  "Write-readable" will always use at least basic-curly-infix notation.  Circularity detection is available; use ":circle t" to enable it.  It also includes similar procedures print1-readable, princ-readable, and print-readable.  You can write to strings instead of the current output with write-to-string-readable, prin1-to-string-readable, and princ-to-string-readable.
+Version 1.0.5 adds additional functions in Common Lisp to print expressions using these readable notations.  That way, you can easily print these notations as well as read them.  Their interfaces are intentionally similar to the standard Common Lisp functions, so they should be easy to use.
+
+Function "write-readable" writes out its first parameter in a readable notation, similar to the standard function write.  It takes all the optional parameters of write (such as :stream), plus the optional ":notation" parameter for controlling the output notation.  By default, the output notation is the same as the input notation.  The ":notation" parameter can be 'basic-curly-infix, 'full-curly-infix, 'neoteric, or 'sweet.  "Write-readable" will always use at least basic-curly-infix notation.  Circularity detection is available; use ":circle t" to enable it.  It also includes similar functions print1-readable, princ-readable, and print-readable.  You can write to strings instead of the current output with write-to-string-readable, prin1-to-string-readable, and princ-to-string-readable.

 The current implementation directly supports circularity detection in cons cells.  The implementation directly supports the following Common Lisp types: cons, symbol, number, character, pathname, string, and bit-vector.  Note that the "cons" is fully supported, which means that proper lists, dotted lists, and circular lists are all supported. Other types are currently partly supported by calling the underlying "write" implementation; this includes the types array (including vector), hash-table, function, readtable, package, stream, random-state, condition, and restart, as well as those created by defstruct, define-condition, or defclass.  In most cases this partial support is more than enough, but you should be aware of its limitations.   First, the contents of partially-supported types will be presented in traditional Lisp notation instead of a more readable notation (though it will still be a valid format).  Also, if you use circularity detection, the circularity detection in any partially-supported types will be separate and will not synchronize with the detection in fully-supported types. There are merely limitations of the current implementation, not of the fundamental concept.  Patches are welcome!

@@ -563,7 +563,7 @@
 As noted earlier, the clisp implementation of "write" normally displays symbols in a really ugly way when the readtable includes letters (as it does when neoteric or sweet-expression reading is active).  The "write-readable" and related routines work around this problem as well.

-Syntax for basic writing procedures
+Syntax for basic writing functions
 -----------------------------------

 **write-readable** object &key array base case circle escape gensym length level lines miser-width pprint-dispatch pretty radix readably right-margin stream notation => object
@@ -584,7 +584,7 @@

 print-readable is just like prin1-readable except that the printed representation of object is preceded by a newline and followed by a space.

-Syntax for string writing procedures
+Syntax for string writing functions
 -----------------------------------

 **write-to-string-readable** object &key array base case circle escape gensym length level lines miser-width pprint-dispatch pretty radix readably right-margin => string

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Wed, 19 Nov 2014 02:15:08 -0000

--- v109
+++ v110
@@ -298,7 +298,7 @@
 - Lines with *only* a ;-comment, and nothing else, are completely ignored - even their indentation is irrelevant.
 - Whitespace-only lines at the beginning of a new expression are ignored, but a whitespace-only line (including a zero-length line) ends an expression.

-Here's a notional example, with a sweet-expression on the left and its equivalent traditional s-expression on the right (this won't actually *run* if you type it in, of course):
+Here's a notional example, with a sweet-expression on the left and its equivalent traditional s-expression on the right (this won't *run* if you type it in, since we have no procedure called "a"):

     a b c d        =>   (a b c d
       e f g                (e f g)

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Tue, 18 Nov 2014 22:27:49 -0000

--- v108
+++ v109
@@ -99,7 +99,7 @@

     (setf (readtable-case *readtable*) :invert)

-"Readtable-case" is a general capability of Common Lisp, not specific to the "readable" notations, but all readable notations work with it.  From here on, we'll assume you did this, though it is not required.
+"Readtable-case" is a general capability of Common Lisp, not specific to the "readable" notations, but all readable notations work with it.  It's best to do this *before* enabling a readable notation. From here on, we'll assume you did this, though it is not required.

 A few other notes

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Tue, 18 Nov 2014 22:25:33 -0000

--- v107
+++ v108
@@ -95,11 +95,11 @@
 Lowercase symbols (readtable-case)
 ------------------------------------------------------

-[Common Lisp is actually case-sensitive](http://www.cliki.net/case%20sensitivity); by default it converts all symbols into upper case and then displays them in upper case.  Many people prefer to enter and see normal symbols in lowercase.  If you're one of those people (David A. Wheeler is), and you're using something other than clisp, just use Common Lisp's built-in "readtable-case" capability.  You probably want to set it to ":invert" early on (before setting any readable notation):
+[Common Lisp is actually case-sensitive](http://www.cliki.net/case%20sensitivity); by default it converts all symbols into upper case and then displays them in upper case.  If you prefer to enter and see normal symbols in lowercase, just set Common Lisp's built-in "readtable-case" capability to ":invert" by doing this:

     (setf (readtable-case *readtable*) :invert)

-"Readtable-case" is a general capability of Common Lisp, not specific to the "readable" notations, but all readable notations work with it.
+"Readtable-case" is a general capability of Common Lisp, not specific to the "readable" notations, but all readable notations work with it.  From here on, we'll assume you did this, though it is not required.

 A few other notes
@@ -389,8 +389,8 @@
     ' foo bar1 bar2
         spam eggs1 eggs2

-Will produce:
-(FOO BAR1 BAR2 (SPAM EGGS1 EGGS2))
+Will produce this (if readtable-case is :invert):
+(foo bar1 bar2 (spam eggs1 eggs2))

 This works with the other standard abbreviations (backquote, comma, and comma-at): use them at the beginning of a line and follow them with space, and they apply to the entire sweet-expression that follows.  Otherwise, they only apply to the next neoteric expression.

@@ -560,7 +560,7 @@
     write-readable '(log 10 100)  ; Writes log(10 100)
     write-readable '(cos (* 2 x)) ; Writes cos{2 * x}

-The clisp implementation of "write" displays symbols in a really ugly way when the readtable includes letters (as it does when neoteric or sweet-expression reading is active).  The "write-readable" and related routines work around this problem as well.
+As noted earlier, the clisp implementation of "write" normally displays symbols in a really ugly way when the readtable includes letters (as it does when neoteric or sweet-expression reading is active).  The "write-readable" and related routines work around this problem as well.

 Syntax for basic writing procedures
@@ -625,7 +625,9 @@

     (readable:disable-readable)

-You would typically load other modules before actually enabling a notation, to prevent the unlikely case that they'd be interpreted differently.
+You would typically load other modules before actually enabling a notation, to prevent the unlikely case that they'd be interpreted differently.  You might also set the readtable-case to :invert before enabling a notation, so normal symbols are displayed in lower case; you can do this using:
+
+    (setf (readtable-case *readtable*) :invert)

 The programs sweet-clisp and sweet-sbcl set up sweet-expression readers for those two implementations of Common Lisp, for your convenience.

Common-lisp-tutorial modified by David A. Wheeler

David A. Wheeler — Tue, 18 Nov 2014 22:17:26 -0000

--- v106
+++ v107
@@ -298,14 +298,14 @@
 - Lines with *only* a ;-comment, and nothing else, are completely ignored - even their indentation is irrelevant.
 - Whitespace-only lines at the beginning of a new expression are ignored, but a whitespace-only line (including a zero-length line) ends an expression.

-Here's a notional example (this won't actually *run* if you type it in, of course):
+Here's a notional example, with a sweet-expression on the left and its equivalent traditional s-expression on the right (this won't actually *run* if you type it in, of course):

     a b c d        =>   (a b c d
       e f g                (e f g)
       h i                  (h i)
       j k                  (j k
         l m                   (l m)
-        n o                   (n o)
+        n o                   (n o))
       p                    p
       q r s                (q r s))