readmoi.core — com.sagevisuals/readmoi 0-SNAPSHOT2

Functions for generating ReadMoi webpages.

File resources/readmoi_options.edn contains a map with the following key-vals.

Required keys:

• :sections, and within each section:
  • :section-name
  • :section-href
  • :section-skip-load?

Optional keys:

• :clojars-badge?
• :copyright-holder
• :fn-map-additions
• :license-hiccup
• :project-description
• :project-name-formatted
• :readme-UUID
• :readme-html-directory
• :readme-html-filename
• :readme-markdown-directory
• :readme-markdown-filename
• :sections-directory
• :separator
• :wrap-at

See project's documentation for details.

*fn-map-additions* clj

Additional directives to pass to zprint governing formatting specific function invocations. Default {}.

*project-group* clj

Project group as observed in Leiningen project.clj. Defaults to "" (i.e., empty string). Intended to be referenced within hiccup/html section files.

*project-name* clj

Project name as observed in Leiningen project.clj. Defaults to "" (i.e., empty string). Intended to be referenced within hiccup/html section files.

*project-version* clj

Project version as observed in Leiningen project.clj. Defaults to nil. Intended to be referenced within hiccup/html section files.

*separator* clj

Characters that separate the string representation of the form to be evaluated and the string representation of the result. Default =>.

*wrap-at* clj

Base-case column wrap, override-able by supplying extra args to the function that would otherwise consult this value, e.g., print-form-then-eval. Default 80.

copyright clj

(copyright person)

Formatted copyright with updated year.

generate-all clj

(generate-all project-metadata opt)

Given project-metadata and ReadMoi options opt, write-to-file html and markdown ReadMe.

See project documentation for details on the structure of the options map.

Dynamic vars that govern output:

• *wrap-at*
• *separator*
• *fn-map-additions*

Example:

(generate-all (read-string (slurp "project.clj"))
              (load-file "resources/readmoi_options.edn"))

;; writes "readme.html" to "doc\" directory and writes "README.md" to
;; project's root directory

long-date clj

(long-date)

Long-form date+time, with time zone removed.

Example:

(long-date) ;; => "2024-11-16 07:26:53"

prettyfy clj

(prettyfy s & width)

Apply zprint formatting to string s. Optional integer width over-rides dynamic var *wrap-at*.

Provide zprint alternative function classifications by re-binding *fn-map-additions*.

Examples:

(prettyfy (str (eval (read-string "(repeat 3 (repeat 3 [77 88 99]))"))))
;; => "(([77 88 99] [77 88 99] [77 88 99])\n  ([77 88 99] [77 88 99] [77 88 99])\n  ([77 88 99] [77 88 99] [77 88 99]))"

…which would render to…

(([77 88 99] [77 88 99] [77 88 99])
 ([77 88 99] [77 88 99] [77 88 99])
 ([77 88 99] [77 88 99] [77 88 99]))

print-form-then-eval clj

(print-form-then-eval str-form)

(print-form-then-eval str-form width-fn width-output)

Returns a hiccup [:code] block wrapping a Clojure stringified form str-form, separator sep (default ' => '), and evaluated value. def, defn, s/def/, defmacro, defpred, and require expressions are only evaled; their output is not captured.

The two optional width args supersede *wrap-at*.

• width-fn governs the max-width of the rendered str-form. Default *wrap-at*.
• width-output governs the max-width of the rendered evaluation of str-form. Default (/ *wrap-at* 2).

Re-bind *wrap-at* to change base-case column-wrap width. The two optional width args, width-fn and width-output, supersede this value.

Re-bind *separator* to change the evaluation arrow.

Re-bind *fn-map-additions* to include additional zprint :fn-map directives.

See also prettyfy.

Note: Evaluated output can not contain an anonymous function of either (fn [x] ...) nor #(...) because zprint requires an internal reference to attempt a backtrack. Since the rendering of an anonymous function changes from one invocation to the next, there is no stable reference.

1. Basic example:

   (print-form-then-eval "(+ 1 2)")
   ;; => [:code "(+ 1 2) ;; => 3"]
   

   After hiccup processing, renders as…

   (+ 1 2) ;; => 3
   

2. Another example:

   (print-form-then-eval "(map inc (range 1 6))")
   ;; => [:code "(map inc (range 1 6)) ;; => (2 3 4 5 6)"]
   

   Renders as…

   (map inc (range 1 6)) ;; => (2 3 4 5 6)
   

3. Example with supplied widths:

   (print-form-then-eval "(map inc (range 1 6))" 10 5)
   ;; => [:code "(map inc\n  (range\n    1\n    6))\n;; => (2\n;;     3\n;;     4\n;;     5\n;;     6)"]
   

   Renders as…

   (map inc
   (range
     1
     6))
   ;; => (2
   ;;     3
   ;;     4
   ;;     5
   ;;     6)
   

4. Example with alternative arrow:

   (binding [*separator* " --->> "]
     (print-form-then-eval "(inc 1)"))
   ;; => [:code "(inc 1) ;; --->> 2"]
   

   Renders as…

   (inc 1) ;; --->> 2
   

random-paragraph clj

(random-paragraph)

Generate a random alpha-numeric paragraph.

For similar example, see random-sentence.

random-sentence clj

(random-sentence)

Generates a random alpha-numeric sentence.

Example:

(random-sentence) ;; => "2g  0j45do 2xq n1nwrm 2a41nk g0x47ov v4bbix jo3687i2oh ofrg1o bi 2fc68 15pn1 o82hp3hu49l5d6xhx hk1bgdo2xex2c133bo."

short-date clj

(short-date)

Short-form date, named month.

Example:

(short-date) ;; => "2024 November 16"