mal/impls/chuck/notes.md

# Step 1

- What if I don't have an OOP language?
- types.qx could be more prominently mentioned...
- A table with all types and suggested object names would be hugely
  useful
- Same for a list of all errors and their messages
- Mention return types and argument types consistently
- More on int/float and their grammar (int is mentioned implicitly in
  the ASCII art, nothing on signs or bases or their lack of)
- Note that a string must be parsed for the `print_readably` thing to
  work and mention how one could do that (like, by using a `read` or
  `eval`-like thing or alternatively, chopping off the surrounding
  quotes and doing the inverse transformation of the printing)
- How is an atom printed?

# Step 2

- What if my language doesn't support lambdas, let alone passing
  around named functions? Ideally write something about
  implementing/using functors/delegates or replacing that namespace
  with a big switch as with VHDL.  Another problem is that if you
  choose a different solution in step 4, step 2 could end up no longer
  functional...
- What kind of error (read: what message?) is raised when no value can
  be looked up for the symbol?  Is it arbitrary?  Do I need to extend
  my error handling to allow for format strings?
- It would be worth a mention that you should extend the printer to
  handle "native" functions (or in oldtimey terms, subrs)

# Step 3

- You should modify both eval_ast *and* EVAL
- Suggest the trick with destructuring the AST into `a0`, `a1`,
  etc. variables for easier access.  Perhaps this can be used to clear
  up the general language used with AST manipulation (like, first
  parameter and second list element)?
- What does def! return?  Emacs Lisp for instance returns the symbol
  whereas the tests suggest the value should be returned instead...

# Step 4

- "Implement the strings functions"
- The "no closures" paragraph isn't quite clear.  Asides from that, do
  native functions don't really need to be wrapped the same way as the
  `fn*` objects, just introduce another type (like, a Subr and a Func
  type) and do a check before applying the arguments to it
- Why does the guide say that the first argument of `count` can be
  treated as list, yet there's a test performing `(count nil)` and
  expecting zero as result?
- Does it make sense to compare, say, atoms in `=`?

# Step 5

- "This is especially important in Lisp languages because they tend to
  prefer using recursion instead of iteration for control structures."
  <- I'd argue it's less of a lisp thing (see everything else related
  to CL) and more a thing functional programming proponents have
  considered more elegant than introducing iteration constructs (see
  haskell, ocaml, erlang)
- It's not really clear that the TCO change for `let*` involves the
  form you'd normally pass to `EVAL` to become the new `ast`.  I had to
  reread this a few more times to understand that the "second `ast`"
  is actually its third argument...
- Where did the check for `do` not being broken by TCO go?
- What's the deal with the `quux/tests/step5_tco.qx` file?

# Step 6

- "The closure calls the your EVAL function […]."
- I still don't have any closures.  How the heck do I implement
  `eval`?  What about `swap!`?
- It would be useful to mention that `swap!` sort of requires
  implementing `apply` first...

# Step 7

- Why the scare quotes for splicing?
- "Before implementing the quoting forms, you will need to implement
  some supporting functions in the core namespace:" should be one list
  item
- "this function takes a list as its second parameter and returns a
  new list that has the first argument prepended to it." reads backwards
- The quasiquote paragraph is hard to read
- It's rather confusing to refer to the argument of `ast` and to an
  `ast` parameter, perhaps name the latter a form?
- What could also help would be a visualization of the four
  conditionals:
  - \`42, \`()
  - \`~foo
  - \`(~@foo) and more
  - \`(42 ~@foo) and everything else
- Mal/mal is inconsistently capitalized
- "Expand the conditional with reader `read_form` function to add the
  following four cases" is again weird, better refer to the
  `read_form` function in reader.qx
- "concat should support concatenation of lists, vectors, or a mix or
  both." <- "or a mix or both" is redundant

# Step 8

- "In the previous step, quoting enabled some simple manipulation [of]
  data structures"
- The macroexpand function step refers to call/apply, it's unclear how
  to proceed if you don't have such a thing
- How should the exception for invalid `nth` access look like?  Also,
  why is it an exception and not an error like with the reader?
- How can `first` take a list (or vector), but work on `nil`?
- The description of `rest` is inconsistent with the tests
- "In the main program, use the rep function to define two new control
  structures macros."
- Why does the definition of `cond` use `throw` although it's only
  introduced in the next chapter?

# Step 9

- It's not really clear that you really just have a `try*` special
  form, with `catch*` merely existing inside it...
- Another thing to clarify is that the exception value is a string
  containing the message you'd see (unless you're using `throw`)
- Generally, it would be better to explain the general exception
  handling mechanism (with some examples), then showing how one
  implements it for both languages with and without exceptions
- Another way than using a global variable is introducing an error
  type next to the other MAL types and checking whether something a
  function returned is one, although the hint about returning one at
  each use of `EVAL` still stands...
- Shouldn't either trick be mentioned at the beginning, simply because
  you'll need it in a language without exceptions to do error handling?
- Why this bizarre treatment for `keyword`?  Why is there no test for
  it?
- Is there a test for whether hash maps deduplicate identical keys
  when using `hash-map` or `assoc`?
- What exactly are keys the specification for `dissoc`, `get` and
  `contains?` are speaking of?  Can I assume these are either strings
  or keywords?
- Why is it not documented that `get` may take `nil` instead of a map?
- Perhaps it's worth adding more tests involving symbols to ensure
  that functions using apply internally don't evaluate their args?

# Step A

- "Add meta-data support to mal functions." <- Shouldn't you mention
  that this involves implementing `with-meta` and `meta`?
- "TODO. Should be separate from the function macro flag." <- Why is
  this even related?
- It would be worth to mention that `with-meta` shall clone its
  argument to avoid one of the more sneaky test failure reasons
- "The value of this entry should be a mal string containing the name
  of the current implementation."
- "When the REPL starts up (as opposed to when it is called with a
  script and/or arguments), call the rep function with this string to
  print a startup header: `"(println (str \"Mal
  [\" *host-language* \"]\"))".`" <- proof that you better quote these
  because the asterisks just disappear...