From e593dba21a806902c959bf4bb0870cd4369322d0 Mon Sep 17 00:00:00 2001 From: David Kastrup Date: Wed, 3 Jun 2015 12:17:11 +0200 Subject: [PATCH] Issue 4421/7: Documentation and Changes entry --- Documentation/changes.tely | 12 +++++++++ .../extending/programming-interface.itely | 25 +++++++++++++------ 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/Documentation/changes.tely b/Documentation/changes.tely index 6735a03b08..f6137cf8f2 100644 --- a/Documentation/changes.tely +++ b/Documentation/changes.tely @@ -61,6 +61,18 @@ which scares away people. @end ignore +@item +LilyPond functions defined with @code{define-music-function}, +@code{define-event-function}, @code{define-scheme-function} and +@code{define-void-function} can now be directly called from Scheme +as if they were genuine Scheme procedures. Argument checking and +matching will still be performed in the same manner as when +calling the function through LilyPond input. This includes the +insertion of defaults for optional arguments not matching their +predicates. Instead of using @code{\default} in the actual +argument list for explicitly skipping a sequence of optional +arguments, @code{*unspecified*} can be employed. + @item The definition of LilyPond functions with @code{define-music-function}, @code{define-event-function}, diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely index e8f41a9338..f572fc9d83 100644 --- a/Documentation/extending/programming-interface.itely +++ b/Documentation/extending/programming-interface.itely @@ -197,14 +197,15 @@ Installed Files: @subsection Scheme function usage Scheme functions can be called pretty much anywhere where a Scheme -expression starting with @code{#} can be written. You call a scheme -function by writing its name preceded by @code{\}, followed by its -arguments. Once an optional argument predicate does not match an -argument, LilyPond skips this and all following optional arguments, -replacing them with their specified default, and @q{backs up} the -argument that did not match to the place of the next mandatory argument. -Since the backed up argument needs to go somewhere, optional arguments -are not actually considered optional unless followed by a mandatory +expression starting with @code{#} can be written. You call a +scheme function from LilyPond by writing its name preceded by +@code{\}, followed by its arguments. Once an optional argument +predicate does not match an argument, LilyPond skips this and all +following optional arguments, replacing them with their specified +default, and @q{backs up} the argument that did not match to the +place of the next mandatory argument. Since the backed up +argument needs to go somewhere, optional arguments are not +actually considered optional unless followed by a mandatory argument. There is one exception: if you write @code{\default} in the place of an @@ -224,6 +225,14 @@ some context, you should use normal scheme functions only for those cases where you always return a useful value, and use void scheme functions (@pxref{Void scheme functions}) otherwise. +For convenience, scheme functions may also be called directly from +Scheme bypassing the LilyPond parser. Their name can be used like +the name of an ordinary function. Typechecking of the arguments +and skipping optional arguments will happen in the same manner as +when called from within LilyPond, with the Scheme value +@code{*unspecified*} taking the role of the @code{\default} +reserved word for explicitly skipping optional arguments. + @node Void scheme functions @subsection Void scheme functions @funindex define-void-function -- 2.39.2