Fix multiline expectations

[mattiuusitalo]

Fixes #33

Allows both old style and new style

   ;; Expected output can span multiple lines
   (assoc {} :foo :bar :quu :baz)
   ;; => {:foo :bar
   ;      :quu :baz}

   ;; One can use multiple leading semicolons as well
   (assoc {} :foo :bar :quu :baz)
   ;; => {:foo :bar
   ;;     :quu :baz}

   ;; Or if you prefer, without the leading comment character
   (assoc {} :foo :bar :quu :baz)
   ;; => {:foo :bar
          :quu :baz}

Looking at the example above one can see the value of leading comments, as the examples written like that are rendered more nicely.

[lread]

Thanks @mattiuusitalo! I am taking a peek at your change on my dev box.

If I understand it correctly, we can still distinguish stdout from eval when stdout contains the => syntax.

For example:

```clojure
(do (println "When do I end?\n=> 77")
    42)
;; =stdout=> When do I end?
; => 77
;; => 42
```

But, we don't force the single semicolon line continuation on the user if there is no ambiguity from the stdout output:

```clojure
(do (println "When do I end?\n= 77")
    42)
;; =stdout=> When do I end?
;; = 77
;; => 42
```

If this is what you intended, I like it.
The single semicolon continuation is awkward to read, and it is probably relatively rare that stdout/stderr output will start with =>, and when it does, we have a way for the user to handle it.

Same idea for ambiguous evals, right?

In the oddball case where needed to, we would not do this:

```clojure
[:when :do :i '=stdout=> (inc 41) :end?]
;; => [:when 
;; :do 
;; :i 
;; =stdout=> 42 
;; :end?]
```

But instead this:

```clojure
[:when :do :i '=stdout=> (inc 41) :end?]
;; => [:when 
; :do 
; :i 
; =stdout=> 42 
; :end?]
```

Have I understood your thinking?

[mattiuusitalo]

First of all, rebased the branch with the latest changes from main, so heads up if you try to pull from the same branch.

Have I understood your thinking?

I didn't anticipate the case where =stdout=> or =clj=> would be part of the expected output. I'm happy that the single semicolon case makes it work though. That would retain the backwards compatibility with earlier versions, right?

I noticed that this is a very specific case with just the symbols =stdout=> =stderr=> =clj=> etc being printed. For users of this library that wouldn't be a problem since they could just use different symbols, I think.

Making a mini DSL like this that still retains the human readable aspect of the code blocks, which is after all their original intention, is surprisingly challenging I must say.

I also added a couple of tests based on your examples.

[lread]

First of all, rebased the branch with the latest changes from main, so heads up if you try to pull from the same branch.

Thanks for the heads up. In the future, a regular merge from main is fine.
Rebases and/or squashes make it harder for me to track changes made by contributors over time.

Making a mini DSL like this that still retains the human readable aspect of the code blocks, which is after all their original intention, is surprisingly challenging I must say.

Yeah! Thanks for sticking it out! I'm looking forward to reviewing your changes soon!

[lread]

I think this looks good!

Supporting multiline commented eval values adds complexity.
Because of this, I think I'd add more tests like the larger-test.
If you've had enough, I could take a shot at it.

I'd also expand on the docs a bit and explain more options for multiline. I can also take a stab at this.

[lread]

@mattiuusitalo, just an FYI, I'll go ahead and collaborate by making commits to this PR.

[lread]

Test-doc-blocks has the luxury of having only a handful of fans/users.

I've tried this PR against known users of test-doc-blocks:

• test-doc-blocks
• etaoin
• rewrite-clj
• honeysql
• oksa (new to me, thanks grep.app!)

I found breakages for etaoin and honeysql. They are all of the same flavour. This is good, we only found one problem, and it is easy to understand.

An example code block from etaoin:

[source,clojure]
----
;; switch to the first top-level iframe with the main page: frame1
(e/switch-frame-first driver)
;; downward to the first iframe with frame1: frame2
(e/switch-frame-first driver)
(e/get-element-text driver :in-frame2)
;; => "In frame2 paragraph"
;; back up to frame1
(e/switch-frame-parent driver)
;; back up to main page
(e/switch-frame-parent driver)
----

The ;; back up to frame1 comment is now interpreted as part of the expected value and causes a failure. A workaround would be to insert a newline above this comment line.

Because an evaluation results in a form, and we already depend on rewrite-clj which parses forms, we can probably more intelligently figure out what our test expectation should be here and not include any unwanted comments.

I'll explore this idea.

[lread]

Ok, seems to pass on all known projects now (test-doc-blocks, honeysql, rewrite-clj, etaoin, oksa).

I've got one or two more things I'd like to check before merging.

If you have any feedback on my changes, I am happy to hear it!

[mattiuusitalo]

Nice! Everything works in the tests I get from malli readme's too

[lread]

There is an issue with embedded assertion tokens for user=> syntax, but I'll raise a separate issue for this.

[lread]

@mattiuusitalo I did one more verification.

for each of [etaoin rewrite-clj honeysql oksa]
  generate test-doc-blocks tests with this PR
  generate test-doc-blocks tests with without this PR
  diff

Looks good! The only change I see in the diff is your fix from #29.

Shall I merge to main and cut a release?

[mattiuusitalo]

I think we are good to go! My use cases work as well. Nice addition with that regression test.