From f8eebf9751f142cedcedb370b34b5cc2d0fc737c Mon Sep 17 00:00:00 2001 From: Bertrand Bordage Date: Fri, 19 Aug 2011 16:17:12 +0200 Subject: [PATCH] lily-guile updates and CG: "Scheme->C interface" section. --- .../contributor/programming-work.itexi | 136 +++++++++++++++++- lily/general-scheme.cc | 2 +- lily/include/lily-guile.hh | 14 +- lily/lily-guile.cc | 28 ++-- 4 files changed, 160 insertions(+), 20 deletions(-) diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi index aa243e0e0c..3dfd49705c 100644 --- a/Documentation/contributor/programming-work.itexi +++ b/Documentation/contributor/programming-work.itexi @@ -16,6 +16,7 @@ * Engraver tutorial:: * Callback tutorial:: * LilyPond scoping:: +* Scheme->C interface:: * LilyPond miscellany:: @end menu @@ -1543,7 +1544,7 @@ Otherwise, a developer with push privileges will push the patch. Once the patch has been pushed, all the relevant issues should be closed. -On Rietveld, the author should log in an close the issue either by +On Rietveld, the author should log in and close the issue either by using the @q{Edit Issue} link, or by clicking the circled x icon to the left of the issue name. @@ -1801,6 +1802,139 @@ a manner that allows it to be garbage-collected when the module is dispersed, either by being stored module-locally, or in weak hash tables. + +@node Scheme->C interface +@section Scheme->C interface + +Most of the C functions interfacing with Guile/Scheme used in LilyPond +are described in the API Reference of the Guile Reference Manual +(see @ref{LilyPond programming languages}). + +The remaining functions are defined in @file{lily/lily-guile.cc}, +@file{lily/include/lily-guile.hh} and +@file{lily/include/lily-guile-macros.hh}. +Although their names are meaningful there's a few things you should know +about them. + +@menu +* Comparison:: +* Conversion:: +@end menu + +@node Comparison +@subsection Comparison + +This is the trickiest part of the interface. + +Mixing Scheme values with C comparison operators won't produce any crash +or warning when compiling but must be avoided: + +@example +scm_string_p ([any_SCM_you_want]) == SCM_BOOL_T +@end example + +As we can read in the reference, @code{scm_string_p} returns a Scheme +value: either @code{#t} or @code{#f} which are written @code{SCM_BOOL_T} +and @code{SCM_BOOL_F} in C. This looks correct but is dirty since it +isn't idiomatic and because the proper way would be shorter to write and +quicker in terms of execution time. + +Let's take a look at the Guile reference again; there's a function called +@code{scm_is_string} described after @code{string?} and @code{scm_string_p} +that returns 0 or 1. These are C values. I specify it because there is +a misnomer in the reference: it says @code{scm_is_string} returns @code{#t} +or @code{#f} instead of @code{SCM_BOOL_T} and @code{SCM_BOOL_F}, so we may +think 0 and 1 are Scheme values. + +So the best solution was simply: + +@example +scm_is_string ([any_SCM_you_want]) +@end example + +There a simple solution for almost every common comparison. Another example: +we want to know if a Scheme value is a non-empty list. Instead of: + +@example +scm_list_p ([SCM_value]) && [SCM_value] != SCM_EOL) +@end example + +one should use: + +@example +scm_is_pair ([SCM_value]) +@end example + +since a list of at least one member is considered as a pair. + +Unfortunately, there is not a @code{scm_is_[something]} function for +everything. That's one of the reasons why LilyPond has its own Scheme +interface. + +@subheading Reference + +Here is a list of these functions: + +TODO: complete this list. + +@subsubheading bool to_boolean (SCM b) + +Convert a Scheme boolean @var{b} to a C boolean, else return false. + +This should be used instead of @code{scm_is_true} and @code{scm_is_false} +for properties since empty lists are sometimes used to unset them. + +@subsubheading bool ly_is_equal (SCM x, SCM y) + +Return @code{true} if @var{x} and @var{y} are the same type, and their +contents or value are equal, else return @code{false}. + +@subsubheading bool is_direction (SCM x) + +Return @code{true} if @var{x} is -1, 0 or 1, +else return @code{false}. + +@subsubheading bool is_axis (SCM x) + +Return @code{true} if @var{x} is 0 or 1, +else return @code{false}. + +@subsubheading bool is_number_pair (SCM p) + +Return @code{true} if @var{key} and @var{value} of a pair @var{p} +are numbers, else return @code{false}. + +@subsubheading bool ly_is_alist_equal (SCM a, SCM b) + +Return @code{true} if the contents of the alists @var{a} and @var{b} +are equal, else return @code{false}. This is order-insensitive, +contrary to equal. + +@node Conversion +@subsection Conversion + +@subheading Reference + +TODO: complete this list. + +@subsubheading bool to_boolean (SCM b) + +Convert a Scheme boolean @var{b} to a C boolean, else return false. + +This should be used instead of @code{scm_is_true} and @code{scm_is_false} +for properties since empty lists are sometimes used to unset them. + +@subsubheading Interval ly_scm2interval (SCM p) + +Convert a pair of floating point numbers @var{p} to an interval, +else return @code{Interval (0, 0)}. + +@subsubheading Offset ly_scm2offset (SCM p) + +Convert a pair of floating point numbers @var{p} to an offset, +else return @code{Offset (0, 0)}. + + @node LilyPond miscellany @section LilyPond miscellany diff --git a/lily/general-scheme.cc b/lily/general-scheme.cc index af2bcd73b4..47613b5ca3 100644 --- a/lily/general-scheme.cc +++ b/lily/general-scheme.cc @@ -107,7 +107,7 @@ LY_DEFINE (ly_dir_p, "ly:dir?", " left or down, @code{1}@tie{}represents right or up, and @code{0}" " represents a neutral direction.") { - if (scm_is_number (s)) + if (scm_is_integer (s)) { int i = scm_to_int (s); return (i >= -1 && i <= 1) ? SCM_BOOL_T : SCM_BOOL_F; diff --git a/lily/include/lily-guile.hh b/lily/include/lily-guile.hh index 5b76625103..806211ca45 100644 --- a/lily/include/lily-guile.hh +++ b/lily/include/lily-guile.hh @@ -92,12 +92,14 @@ SCM ly_hash2alist (SCM tab); SCM ly_hash_table_keys (SCM tab); SCM ly_assoc_prepend_x (SCM alist, SCM key, SCM val); +// is SCM_FRACTIONP (x) now scm_is_true (scm_rational_p (x)) +// or scm_is_true (scm_exact_p (x)) ? inline bool ly_is_fraction (SCM x) { return SCM_FRACTIONP (x) || scm_is_integer (x); } -inline bool ly_is_list (SCM x) { return SCM_NFALSEP (scm_list_p (x)); } +inline bool ly_is_list (SCM x) { return scm_is_true (scm_list_p (x)); } inline bool ly_cheap_is_list (SCM x) { return scm_is_pair (x) || x == SCM_EOL; } -inline bool ly_is_procedure (SCM x) { return SCM_NFALSEP (scm_procedure_p (x)); } -inline bool ly_is_port (SCM x) { return SCM_NFALSEP (scm_port_p (x)); } +inline bool ly_is_procedure (SCM x) { return scm_is_true (scm_procedure_p (x)); } +inline bool ly_is_port (SCM x) { return scm_is_true (scm_port_p (x)); } /* want to take the address of this function; scm_is_symbol() is a @@ -107,12 +109,12 @@ inline bool ly_is_symbol (SCM x) { return scm_is_symbol (x); } inline bool ly_is_equal (SCM x, SCM y) { - return SCM_NFALSEP (scm_equal_p (x, y)); + return scm_is_true (scm_equal_p (x, y)); } -inline bool ly_scm2bool (SCM x) { return SCM_NFALSEP (x); } +inline bool ly_scm2bool (SCM x) { return scm_is_true (x); } inline char ly_scm2char (SCM x) { return (char)SCM_CHAR (x); } -inline SCM ly_bool2scm (bool x) { return SCM_BOOL (x); } +inline SCM ly_bool2scm (bool x) { return scm_from_bool (x); } inline SCM ly_append2 (SCM x1, SCM x2) { diff --git a/lily/lily-guile.cc b/lily/lily-guile.cc index ff3f7064bf..e9cf0909f2 100644 --- a/lily/lily-guile.cc +++ b/lily/lily-guile.cc @@ -178,7 +178,7 @@ ly_scm_hash (SCM s) bool is_axis (SCM s) { - if (scm_is_number (s)) + if (scm_is_integer (s)) { int i = scm_to_int (s); return i == 0 || i == 1; @@ -212,7 +212,7 @@ robust_scm2dir (SCM d, Direction def) bool is_direction (SCM s) { - if (scm_is_number (s)) + if (scm_is_integer (s)) { int i = scm_to_int (s); return i >= -1 && i <= 1; @@ -226,7 +226,10 @@ is_direction (SCM s) Interval ly_scm2interval (SCM p) { - return Interval (scm_to_double (scm_car (p)), scm_to_double (scm_cdr (p))); + return is_number_pair (p) ? + Interval (scm_to_double (scm_car (p)), + scm_to_double (scm_cdr (p))) : + Interval (0, 0); } Drul_array @@ -284,8 +287,10 @@ ly_offset2scm (Offset o) Offset ly_scm2offset (SCM s) { - return Offset (scm_to_double (scm_car (s)), - scm_to_double (scm_cdr (s))); + return is_number_pair (s) ? + Offset (scm_to_double (scm_car (s)), + scm_to_double (scm_cdr (s))) : + Offset (0, 0); } Offset @@ -320,20 +325,19 @@ ly_scm2offsets (SCM s) /* ALIST */ - +// This one is used nowhere. bool -alist_equal_p (SCM a, SCM b) +ly_is_alist_equal (SCM a, SCM b) { - for (SCM s = a; - scm_is_pair (s); s = scm_cdr (s)) + if (!scm_is_pair (a) || !scm_is_pair (b)) + return false; + for (SCM s = a; scm_is_pair (s); s = scm_cdr (s)) { SCM key = scm_caar (s); SCM val = scm_cdar (s); SCM l = scm_assoc (key, b); - if (l == SCM_BOOL_F - || !ly_is_equal (scm_cdr (l), val)) - + if (scm_is_false (l) || !ly_is_equal (scm_cdr (l), val)) return false; } return true; -- 2.39.5