1 ; Copyright 2022 Frank Duncan (frank@consxy.com) under AGPL3. See distributed LICENSE.txt.
2 (in-package #:sheep-var)
6 (defun peek () (car *doc*))
7 (defun next () (setf *prev-line* (pop *doc*)))
8 (defun more () (not (not *doc*)))
9 (defun prev-line () *prev-line*)
13 (defun add-keyword (type)
14 (setf *keywords* (remove-duplicates (cons type *keywords*) :test #'string=)))
16 (defun fire-error (msg) (error (make-instance 'sheep:validation-failure :msg msg)))
18 (defun expect-blank-line ()
21 (when (string/= "" (next)) (fire-error (format nil "Expected blank line after: ~A" prev)))))
23 (defun verify-next-line (&key optional)
25 ((and optional (not (more))) t)
26 ((cl-ppcre:scan " $" (peek)) (fire-error (format nil "Can't end line with a space: ~A" (peek))))
27 ((< 120 (length (peek))) (fire-error (format nil "Longer than 120 chars: ~A" (peek))))))
29 (defun freeform->paragraphs (next next-optional)
30 (verify-next-line :optional t)
34 ((and next-optional (not next-line)) (list ""))
35 ((and (string= "" next-line) (not (more))) (fire-error "Can't end with empty line"))
36 ((cl-ppcre:scan "^ [^ ]+" next-line)
38 ((rest-of-freeform (freeform->paragraphs next next-optional)))
41 (subseq next-line 2 (length next-line))
42 (if (string/= "" (car rest-of-freeform)) " " "")
43 (car rest-of-freeform))
44 (cdr rest-of-freeform))))
45 ((string= "" next-line)
46 (if (string= next (peek))
48 (cons "" (freeform->paragraphs next next-optional))))
49 (t (fire-error (format nil "Got unexpected line, requires blank lines or start with two spaces: ~S" next-line))))))
51 (defun parse-freeform (start section next next-optional)
52 (when (string/= start (next)) (fire-error (format nil "Expected ~A instead of: ~A" start (prev-line))))
55 ((paragraphs (freeform->paragraphs next next-optional)))
56 (list section (mapcar #'handle-text paragraphs))))
58 (defun process-examples ()
60 (verify-next-line :optional t)
63 ((example-scanner (cl-ppcre:create-scanner "^ ([^ ].+) => (.+)$"))
65 (if (not (cl-ppcre:scan example-scanner next-line))
66 (fire-error (format nil "Example line does not match \" example => result\": ~A" next-line))
67 (cl-ppcre:register-groups-bind (example result) (example-scanner next-line)
68 (list example result))))
71 (defun parse-examples ()
72 ; This shouldn't fire, unless there's a bug in our processing
73 (when (string/= "EXAMPLES:" (next)) (fire-error (format nil "Expected EXAMPLES: instead of: ~A" (prev-line))))
75 (list :examples (process-examples)))
77 ; For formatting of things like types in there
78 (defun handle-text (text)
80 ((inject-keywords (text remaining-keywords)
82 (not remaining-keywords)
89 ((not (cl-ppcre:scan (cl-ppcre:quote-meta-chars (car remaining-keywords)) text-item)) (list text-item))
92 ((split-text (cl-ppcre:split (cl-ppcre:quote-meta-chars (car remaining-keywords)) text-item :limit 1000)))
94 (list (car split-text))
95 (mapcar (lambda (ti) (list (list :keyword (car remaining-keywords)) ti)) (cdr split-text)))))))
96 (inject-keywords text (cdr remaining-keywords)))))))
97 (list :text (inject-keywords text *keywords*))))
99 (defun parse-header (var)
102 ((var-name (symbol-name var)))
103 (when (not (string= var-name (peek)))
104 (fire-error (format nil "First line of ~A did not match: ~A, ~A" var var-name (peek))))
105 (add-keyword var-name)
108 (list :variable var-name)))
110 (defun internal-doc->ast (var doc)
112 ((*doc* (cl-ppcre:split "\\n" doc :limit 1000))
115 (cons (parse-header var)
118 (parse-freeform "VALUE TYPE:" :value-type "INITIAL VALUE:" nil)
119 (parse-freeform "INITIAL VALUE:" :initial-value "DESCRIPTION:" nil)
120 (parse-freeform "DESCRIPTION:" :description "EXAMPLES:" t))
121 (when (more) (list (parse-examples)))))))
123 (defun doc->ast (var) (internal-doc->ast var (documentation var 'variable)))
125 (defun format-text (text)
130 ((stringp text) text)
131 ((and (listp text) (eql :keyword (car text))) (format nil "_~(~A~)_" (cadr text)))
132 ; This should never fire, unless there's a bug in our processor
133 (t (fire-error (format nil "Don't know how to convert text: ~S" text)))))
136 (defun format-header (header)
137 (format nil "## Variable ~A
140 (cl-ppcre:quote-meta-chars (second header))))
142 (defun format-freeform (heading text)
143 (format nil "#### ~A:~%~%~{~A~%~^~%~}" heading (mapcar #'format-text (cadr text))))
145 (defun format-examples (examples)
148 (format nil "~%#### Examples:~%~%~{~A~%~}"
150 (lambda (example) (format nil "```~A``` => ```~A``` " (car example) (cadr example)))
155 ((get-section (name) (find name ast :key #'car)))
156 (format nil "~A~A~%~A~%~A~A"
157 (format-header (get-section :variable))
158 (format-freeform "Value Type" (get-section :value-type))
159 (format-freeform "Initial Value" (get-section :initial-value))
160 (format-freeform "Description" (get-section :description))
161 (format-examples (get-section :examples)))))
163 (defun ast->category-name (ast)
164 (declare (ignore ast))
167 (defun ast->short-name (ast)
168 (format nil "~(~A~)" (cl-ppcre:quote-meta-chars (second (find :variable ast :key #'car)))))
170 (defun ast->link (ast)
171 (format nil "variable-~(~A~)" (cl-ppcre:regex-replace-all "\\*" (second (find :variable ast :key #'car)) "")))
173 (defun ast->short-desc (ast)
174 (format-text (car (cadr (find :description ast :key #'car)))))