(Re)generate: (find-show-conses-intro)
Source code:  (find-efunction 'find-show-conses-intro)
More intros:  (find-eev-quick-intro)
              (find-eev-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.


Prerequisites:
  (find-eev-quick-intro "2. Evaluating Lisp")
  (find-eev-quick-intro "3. Elisp hyperlinks")




. Introduction
This is a "cons diagram",

  (1 (2 "3") . 4)

  .__._______4
  |  |
  1  .__.    
     |  |
     2  "3"

that shows a sexp, (1 (2 "3") . 4), and how that sexp is represented
using conses. It uses a format that is much more compact than the
formats used by pair-tree.el - that is an Emacs package that is MELPA -
and by "Sdraw" from Racket. Compare:

  https://github.com/zainab-ali/pair-tree.el
  https://docs.racket-lang.org/sdraw/index.html

If you are reading this in Emacs then you have already loaded
"show-conses.el", that is able to display such diagrams. Try:

  (find-show-conses-2a '(1 (2 "3") . 4))

You will get a two-window setting like this,

   _________________________
  |         |               |
  |         |               |
  |  intro  | *show-conses* |
  |         |               |
  |_________|_______________|

and in the "*show-conses*" buffer some parts of the cons tree are
"highlighters". For example, if you go to the "." that corresponds
to the sub-sexp (2 "3") and type `C-c C-c' there it will highlight
the `(2 "3")' in the upper part. Try that now.

The highlighters are implemented using text properties, and the regions
that they highlight are implemented using a hash table that associates
names to markers. Try:


[TODO: rewrite everything below this point!!!]



  (find-epp (show-conses-propertize-h '(h "." "cadr")))

  (show-conses-delete-markers)
  (find-show-conses-lisp-3a '(1 (2 "3") . 4) :end)
  (show-conses-set-overlay-1 "car")
  (show-conses-set-overlay-1 "cr")
  (show-conses-delete-overlay)
  (find-2a nil '(find-ehashtable show-conses-markers))




. Intended audience
You can use sexps like

  (find-show-conses-lisp-2a '(1 (2 "3") . 4) :end)

to explain sexps and conses to your friends, but I consider that this
package is:

  "...more like a toy that is _slightly interesting_ if you play with
  it for a few seconds, and _much more interesting_ if you open it and
  take its pieces apart to see how everything works."

For more on that, see:

  http://anggtwu.net/2024-eev-for-5-year-olds.html#taking-apart




. Namespaces
The file "show-conses.el" is well-behaved: it only defines symbols
that start with "show-conses-" or "find-show-conses", plus a few
extensions to `M-e', that start with "ee-" and that, ahem, "invade
the eev namespace". Check:

  (find-eloadhistory-for 'show-conses-shorten)
  (find-eloadhistory-for 'ee-eval-last-sexp)

Remember that _most_ short and cryptic names, like `a' and `foo' - but
not `t', `car', and `pi' - are reserved for users. The function
`show-conses-export' (sort of) exports the symbols of show-conses.el
halfway towards this "user namespace", by creating shorter aliases in
which each "show-conses" is replaced by just "sc". You can inspect
what `show-conses-export' does by running this:

  (find-estring-elisp (show-conses-export0))

Run this to define these shorter symbols:

  ;; See: (find-efunction 'show-conses-export)
  (show-conses-export)

I will use the shorter symbols in most of the examples of this intro.



. The DSL