Adding examples to Janet api documentation.

[erichaney]

Added an example for ++, --, and ->. Let me know if the filenames are not what they ought to be.

[bakpakin]

Thanks Eric, I appreciate the code examples!

Looks like the example file for -> should just be examples/->.janet, no need for the escape. To check, run make; make run and verify that examples pop up in the generated docs.

[erichaney]

I hesitated to name the file ->.janet since > and < are not permitted in file names for windows.

But I can see that what I did isn't getting picked up in the generated docs. No biggie. Feel free to close this and I can resubmit with the unescaped file name.

[CFiggers]

@erichaney You can just change it in place and the PR will update automatically. 🙂

[sogaiu]

I hesitated to name the file ->.janet since > and < are not permitted in file names for windows.

I also thought this when examining the file naming scheme for examples before.

Some of the printable characters that looked potentially problematic to me for Windows included:

• /
• <
• >
• *
• %
• :
• ?

(", \, or | are not listed because AFAIK, these cannot be in legal Janet identifiers)

FWIW, I think some of the code that handles symbol to file name conversion currently is here.

My translation of that is:

(def- replacer
  (peg/compile
    ~(accumulate
       (any
         (choice (replace (capture (set "/*%"))
                          ,|(string "_" (0 $))) 
                 (capture 1))))))

(defn- sym-to-filename
  "Convert a symbol to a filename. Certain filenames are not allowed on various operating systems."
  [fname]
  (string "examples/" ((peg/match replacer fname) 0) ".janet"))

May be it makes sense to also handle the following specially?

• <
• >
• :
• ?

For comparison, this is the scheme I settled on for janet-ref. Some use can be see here.

[erichaney]

I removed the escape from the file name. I'll focus on contributing examples that don't use any special characters for now. 👍

[sogaiu]

I think the evaluation result for this line (line 4 of -.janet) is off:

(- 1.4 -4.5) # -> -5.9

What I get here is:

$ janet
Janet 1.37.1-60d9f977 linux/x64/gcc - '(doc)' for help
repl:1:> (- 1.4 -4.5)
5.9

[sogaiu]

For this line (line 4 of accumulate2.janet):

(reduce2 + []) # -> 0

what I get here is:

$ janet
Janet 1.37.1-60d9f977 linux/x64/gcc - '(doc)' for help
repl:1:> (reduce2 + [])
nil

[sogaiu]

Not sure how much we should be concerned with the following sort of thing, but FWIW, I noticed in some lines that there is no space between the # and the -> (i.e. I see #-> instead of # ->). For the most part, I think elsewhere in the examples (also outside of this PR) there has been use of a space.

For reference, the following have examples of the aforementioned:

• accumulate.janet (line 1)
• accumulate2.janet (line 1)
• all.janet (lines 1 and 2)

(Unfortunately, you may need to scroll to see the relevant bits via the links.)

[erichaney]

Thanks for pointing out the issues.

I think I will close this PR and resubmit one file at a time so it is easier to review and track changes.