docstring for run-recipe, some site building utilities

2 files changed, 38 insertions, 1 deletions

diff --git a/flexo.lisp b/flexo.lisp
index d9db7d1..49788a9 100644
--- a/flexo.lisp
+++ b/flexo.lisp
@@ -84,7 +84,18 @@ artifact tables have changed."
   (not (tables-equal-p backup *site*)))
 
 (defun run-recipe (recipe)
-  "Runs the recipe in a fresh context and returns the site hash table it built."
+  "Runs the RECIPE, a function of zero arguments, in a fresh context
+   and returns the site hash table it built.
+
+   Recipes are functions of zero arguments run entirely for their side
+   affects on two dynamic variables: *CONTENT* and *ARTIFACTS* both of
+   of which hold hash tables. These two variables are referred to as
+   the build context of the recipe.
+
+   Whenever a subclass of CONTENT or ARTIFACT is instantiated, it is
+   added to the correct hash table.  These hash tables are used under
+   the hood by the content and artifact retrieval utility functions -
+   e.g. FIND-CONTENT, ARTIFACTS-WITH-CLASS, and so on."
   (let ((*site* (make-hash-table))
         (*content* (make-hash-table)))
     (funcall recipe)
@@ -313,6 +324,29 @@ artifact tables have changed."
    "Meant to be extended by all artifacts that are also files on
     disk."))
 
+;;; SITE BUILDING TOOLS
+
+(defun add-file (path class &rest keywords)
+  "Creates an instance of CLASS, which must be a subclass of FILE,
+  using the upplied path. Supplies this piece of content (which may or
+  maynot also be an ARTIFACT) with KEYWORDS for later retrieval."
+  (assert (subtypep class 'file) () "~s is not a subclass of FLEXO:FILE" class)
+  (assert (uiop:file-exists-p path) () "~s does not exist on disk" path)
+  (make-instance class
+                 :filepath path
+                 :keywords keywords))
+
+(defun add-files-matching (directory-path regex class &rest keywords)
+  "Given a root directory and a regular expression REGEX, call
+   ADD-FILE with the supplied CLASS and KEYWORDS for each file
+   pathname whose namestring is matched by the REGEX."
+  (dolist (path (uiop:directory-files directory-path))
+    (when (ppcre:scan regex (namestring path))
+      (apply #'add-file path class keywords)))
+  (dolist (subdir (uiop:subdirectories directory-path))
+    (apply #'add-files-matching subdir regex class keywords)))
+
+
 ;;; PUBLISH PROTOCOL
 
 (defgeneric publish (artifact location)
diff --git a/package.lisp b/package.lisp
index 30ea6e2..0a2d1ef 100644
--- a/package.lisp
+++ b/package.lisp
@@ -6,6 +6,8 @@
                 #:with-html
                 #:with-html-string)
   (:export
+   #:add-file
+   #:add-files-matching
    #:artifact
    #:artifacts-with-class
    #:artifacts-with-urlpath-like
@@ -27,6 +29,7 @@
    #:ps-script
    #:publish
    #:publish-site
+   #:run-recipe
    #:spinneret-page
    #:stop-hacking
    #:template-generated-text