readmoi.core — com.sagevisuals/readmoi 3

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. Default values are sourced from the defaults file.

Dynamic vars that govern output formatting:

• *wrap-at*
• *separator*

Dynamic vars that may be referred for creating content (e.g., Setup section):

• *project-group*
• *project-name*
• *project-version*

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

html-tidy-defaults clj

A vector of strings to be supplied to tidy-html as if on the command line. The most notable defaults are:

• -i indent
• --quiet limits output report
• --wrap wrap lines at column 160
• --write-back over-write original file

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."

readmoi-defaults clj

A hash-map residing in readmoi_defaults.clj that supplies the default values for the following options keys:

• :clojars-badge
• :license-hiccup
• :sections-directory
• :project-group
• :project-name
• :project-version
• :readme-html-directory
• :readme-html-filename
• :readme-markdown-directory
• :readme-markdown-filename
• :tidy-html?

Override default values by associating new values into the ReadMoi options hash-map. See generate-all.

short-date clj

(short-date)

Short-form date, named month.

Example:

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

tidy-html-body clj

(tidy-html-body f)

(tidy-html-body f options)

Given html body (or substantially html-like markdown), contained in file pathname string f, use tidy-html to wrap and indent the html. Tidy-ing settings may be supplied by options vector, which completely replaces html-tidy-defaults.

Useful for tidy-ing only an html body for supplying to GitHub's markdown processor.

Requires local installation of html-tidy.

See also tidy-html-document for a similar utility that operates on a full html document.

tidy-html-document clj

(tidy-html-document f)

(tidy-html-document f options)

For html document (or substantially html-like markdown), contained in file pathname string f, use tidy-html to wrap and indent the html. Tidy-ing settings may be supplied by options vector, which completely replaces html-tidy-defaults.

Requires local installation of html-tidy.

Note: This utility delegates the tidy-ing task to tidy-html, which insists on adding a missing html head, title, etc. To tidy a fragment, i.e., an html body, use tidy-html-body.

Note: When tidy-ing, in-line [:code ...] blocks et. al., may be broken over lines at an undesirable space. Use a Unicode non-breaking space, U+00A0, to maintain a coherent block. An html non-breaking space entity,   renders literally, and thus not suitable for this purpose.