Merge pull request #265 from sogaiu/expose-example-filename-converter

Expose example filename creation via script

Author: bakpakin

README.md

@@ -42,15 +42,34 @@ documentation tool, but of course is written in and is a dialect of Janet. See
 
 ## Adding Examples
 
-Simply add a file with the name of the binding you are giving examples for to the examples
-directory, with the `.janet` suffix. If the binding includes the `/` character, replace it with
-an underscore - this works because no bindings in the core use an underscore. For example, the
-binding `array/new` has examples in the `examples/array_new.janet` file.
-
-If such a file already exists, you can simply append your example code the existing file.
-
-When building the site, the new examples will be included in the generated documentation. Make
-sure that your example has correct janet syntax, as syntax errors will cause the entire site
-to not build. If the example has valid syntax (has a 0 exit code when loaded with
-        `janet -k example/my-fn.janet`), there may be a bug in the mendoza janet syntax
-highlighter and you open a bug in mendoza.
+Simply add a file with the name of the binding you are giving examples
+for to the `examples` directory, with the `.janet` suffix.
+
+To cope with some of Janet's symbols having names with characters that
+are not-so-friendly to certain filesystem and/or operating system
+combinations, an escaping scheme is used.
+
+For a given symbol, use the `content/api/examples.janet` script to
+generate an appropriate filename.  For example, for `array/new`,
+invoking:
+
+```
+$ janet content/api/examples.janet array/new
+```
+
+should give the output:
+
+```
+array_47new.janet
+```
+
+If such a file already exists, you can simply append your example code
+to the existing file.
+
+When building the site, the new examples will be included in the
+generated documentation. Make sure that your example has correct janet
+syntax, as syntax errors will cause the entire site to not build. If
+the example has valid syntax (has a 0 exit code when loaded with
+`janet -k example/my-fn.janet`), there may be a bug in the mendoza
+janet syntax highlighter in which case please open a bug in mendoza.
+

content/api/examples.janet

@@ -0,0 +1,20 @@
+(def replacer
+  (peg/compile
+    ~(% (any (+ (/ '(set "%*/:<>?")
+                   ,|(string "_" (0 $))) '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"))
+
+(defn main
+  [& args]
+  (def symbol-name (get args 1))
+  (assert symbol-name "please specify a symbol name")
+  (print (string/slice (sym-to-filename symbol-name)
+                       (length "examples/"))))
+

content/api/gen-docs.janet

@@ -1,6 +1,7 @@
 # Generate documentation
 
 (import mendoza/markup-env :as mdz)
+(import ./examples :as ex)
 
 (defn- remove-extra-spaces
   "Many docstrings have extra spaces that don't look
@@ -11,17 +12,11 @@
     (set ret (string/replace "  " " " ret)))
   ret)
 
-(def- replacer (peg/compile ~(% (any (+ (/ '(set "%*/:<>?") ,|(string "_" (0 $))) '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"))
-
 (defn- check-example
   "Check if a binding has related examples. If so, load them
   and get their content."
   [sym]
-  (def path (sym-to-filename sym))
+  (def path (ex/sym-to-filename sym))
   (when (= :file (os/stat path :mode))
     (def src (slurp path))
     src))