Doc: add missing engraver to example of a user-defined context (3195)

[lilypond.git] / scm / lily.scm

diff --git a/scm/lily.scm b/scm/lily.scm
index d7c4bf65874c8766fe5a2dcd75bae743fb296258..496598bbbcab42af60f8b98621a28de7686a683d 100644 (file)
--- a/scm/lily.scm
+++ b/scm/lily.scm
@@ -43,7 +43,37 @@
    (string-downcase
     (car (string-tokenize (utsname:sysname (uname)))))))
 
+;;
+;; Session-handling variables and procedures.
+;;
+;;  A "session" corresponds to one .ly file processed on a LilyPond
+;;  command line.  Every session gets to see a reasonably fresh state
+;;  of LilyPond and should work independently from previous files.
+;;
+;;  Session management relies on cooperation, namely the user not
+;;  trying to change variables and data structures internal to
+;;  LilyPond.  It is not proof against in-place modification of data
+;;  structures (as they are just reinitialized with the original
+;;  identities), and it is not proof against tampering with internals.
+;;
+;;  As a consequence, session management is not sufficient for
+;;  separating multiple independent .ly files in "-dsafe" mode: you
+;;  should give each its own LilyPond process when reliable separation
+;;  is mandatory.
+;;
+;;  For standard tasks and programming practices, multiple sessions in
+;;  the same LilyPond job should work reasonably independently and
+;;  without "bleed-over" while still loading and compiling the
+;;  relevant .scm and .ly files only once.
+;;
+
 (define lilypond-declarations '())
+(define after-session-hook (make-hook))
+
+(define-public (call-after-session thunk)
+  (if (ly:undead? lilypond-declarations)
+      (ly:error (_ "call-after-session used after session start")))
+  (add-hook! after-session-hook thunk #t))
 
 (defmacro-public define-session (name value)
   "This defines a variable @var{name} with the starting value
@@ -74,9 +104,13 @@ session has started."
 
 (define (session-terminate)
   (if (ly:undead? lilypond-declarations)
-      (for-each
-       (lambda (p) (variable-set! (cadr p) (cddr p)))
-       (ly:get-undead lilypond-declarations))))
+      (begin
+        (for-each
+         (lambda (p) (variable-set! (cadr p) (cddr p)))
+         (ly:get-undead lilypond-declarations))
+        (run-hook after-session-hook))))
+
+(define lilypond-interfaces #f)
 
 (define-public (session-initialize thunk)
   "Initialize this session.  The first session in a LilyPond run is
@@ -96,6 +130,7 @@ variables to their value after the initial call of @var{thunk}."
 
   (if (ly:undead? lilypond-declarations)
       (begin
+        (module-use-interfaces! (current-module) (reverse lilypond-interfaces))
         (for-each
          (lambda (p)
            (let ((var (cadr p))
@@ -106,6 +141,9 @@ variables to their value after the initial call of @var{thunk}."
          (ly:get-undead lilypond-declarations)))
       (begin
         (thunk)
+        (set! lilypond-interfaces
+              (filter (lambda (m) (eq? 'interface (module-kind m)))
+                      (module-uses (current-module))))
         (let ((decl (map! (lambda (v)
                             (cons* #f v (variable-ref v)))
                           lilypond-declarations)))
@@ -209,9 +247,6 @@ file to given string.")
     (music-strings-to-paths #f
 "Convert text strings to paths when glyphs belong
 to a music font.")
-    (old-relative #f
-"Make \\relative mode for simultaneous music work
-similar to chord syntax.")
     (point-and-click #t
 "Add point & click links to PDF output.")
     (paper-size "a4"
@@ -458,6 +493,7 @@ messages into errors.")
     "define-note-names.scm"
     "c++.scm"
     "chord-entry.scm"
+    "skyline.scm"
     "stencil.scm"
     "define-markup-commands.scm"
     "markup.scm"
@@ -496,6 +532,7 @@ messages into errors.")
     "define-grobs.scm"
     "define-grob-interfaces.scm"
     "define-stencil-commands.scm"
+    "scheme-engravers.scm"
     "titling.scm"
     "text.scm"
 
@@ -568,14 +605,13 @@ messages into errors.")
     (,fraction? . "fraction, as pair")
     (,grob-list? . "list of grobs")
     (,index? . "non-negative integer")
-    ;; this is built on cheap-list
-    (,list-or-symbol? . "list or symbol")
     (,markup? . "markup")
     (,markup-command-list? . "markup command list")
     (,markup-list? . "markup list")
     (,moment-pair? . "pair of moment objects")
     (,number-list? . "number list")
     (,number-or-grob? . "number or grob")
+    (,number-or-markup? . "number or markup")
     (,number-or-pair? . "number or pair")
     (,number-or-string? . "number or string")
     (,number-pair? . "pair of numbers")
@@ -584,6 +620,9 @@ messages into errors.")
     (,string-or-pair? . "string or pair")
     (,string-or-music? . "string or music")
     (,string-or-symbol? . "string or symbol")
+    (,symbol-list? . "symbol list")
+    (,symbol-list-or-music? . "symbol list or music")
+    (,symbol-list-or-symbol? . "symbol list or symbol")
     (,void? . "void")
     ))