Clojure macros continue to surprise me

I really enjoyed reading this, and I don't know Clojure at all. This is a problem I've encountered several times while building design systems/component libraries. It's a very universal documentation problem, regardless of what platform it's targeting.

I have done the same with React - but it gets messy. Something nice like in the post would be great for that.

Too often I see very poor Storybook sites in the wild (a web based design system visual explorer, somewhat like the screenshot in the post) where no thought was given to this exact problem.

Instead of something meaningful like in the post, I see:

    () => <TextInputStorybook />

As the only avaliable code. The point of the code blocks is so people can copy paste. When I see that, I know I'm in for a rough ride because the code quality inevitably isn't any good either.

For reference, this is easily the best design system I know of: https://seek-oss.github.io/braid-design-system/components/Te... I use this as a reference when I work on my own.

In elixir you can run docs as (init) tests too. The doctest macro is generating the tests from the docs within the module. Maybe this might be interesting together with this article.

The fifth time this has been posted in just over a week... it must be a REALLY good article! :)

> What if our macro read the source file?

> Like, actually went to the file system, opened a file, and read its content? We already have the file name conveniently stored in file, and luckily Clojure keeps sources around.

> So this is what I ended up with:

> (defn slurp-source [file key]

Looks like a function to me (which is good).

The real trick here is dodging ASTs, which, after trying to use in so many parse-the-code projects, really aren’t needed all the time but are put pretty highly on the pedestal

  sometimes a vector is just a vector, but sometimes it’s a UI component and shows the structure of the UI.

Easily the worst aspect of Clojure. Everything is an untyped map or an untyped vector. Your editor can't tell the difference between a vector of keywords and some DSL for a macro. Things like this make Clojure a nightmare to refactor and scale poorly relative to languages like TypeScript.

Just wait for using full blown CL macros then.

TXR Lisp:

  $ cat slurp-source.tl
  (defun slurp-source (path key)
    (let* ((lines (file-get-lines path))
           (match (member-if (op contains key) lines))
           (tail (rest match))
           (indent (find-min-key tail : (op match-regex @1 #/\s*/)))
           (dedent (mapcar (op drop indent) tail)))
      `@{dedent "\n"}\n`))
  $ txr -i slurp-source.tl
  1> (put-string (slurp-source "slurp-source.tl" "let*"))
       (match (member-if (op contains key) lines))
       (tail (rest match))
       (indent (find-min-key tail : (op match-regex @1 #/\s*/)))
       (dedent (mapcar (op drop indent) tail)))
  `@{dedent "\n"}\n`))
  t