Left: | ||
Right: |
LEFT | RIGHT |
---|---|
1 @c -*- coding: us-ascii; mode: texinfo; -*- | 1 @c -*- coding: us-ascii; mode: texinfo; -*- |
2 @node Programming work | 2 @node Programming work |
3 @chapter Programming work | 3 @chapter Programming work |
4 | 4 |
5 @menu | 5 @menu |
6 * Overview of LilyPond architecture:: | 6 * Overview of LilyPond architecture:: |
7 * LilyPond programming languages:: | 7 * LilyPond programming languages:: |
8 * Programming without compiling:: | 8 * Programming without compiling:: |
9 * Finding functions:: | 9 * Finding functions:: |
10 * Code style:: | 10 * Code style:: |
11 * Debugging LilyPond:: | 11 * Debugging LilyPond:: |
12 * Adding or modifying features:: | 12 * Adding or modifying features:: |
13 * Iterator tutorial:: | 13 * Iterator tutorial:: |
14 * Engraver tutorial:: | 14 * Engraver tutorial:: |
15 * Callback tutorial:: | 15 * Callback tutorial:: |
16 * LilyPond scoping:: | |
16 @end menu | 17 @end menu |
17 | 18 |
18 @node Overview of LilyPond architecture | 19 @node Overview of LilyPond architecture |
19 @section Overview of LilyPond architecture | 20 @section Overview of LilyPond architecture |
20 | 21 |
21 LilyPond processes the input file into graphical and musical output in a | 22 LilyPond processes the input file into graphical and musical output in a |
22 number of stages. This process, along with the types of routines that | 23 number of stages. This process, along with the types of routines that |
23 accomplish the various stages of the process, is described in this section. A | 24 accomplish the various stages of the process, is described in this section. A |
24 more complete description of the LilyPond architecture and internal program | 25 more complete description of the LilyPond architecture and internal program |
25 execution is found in Erik Sandberg's | 26 execution is found in Erik Sandberg's |
(...skipping 19 matching lines...) Expand all Loading... | |
45 music event is assigned a moment, or a time in the music when the event | 46 music event is assigned a moment, or a time in the music when the event |
46 begins. | 47 begins. |
47 | 48 |
48 Each type of music event has an associated iterator. Iterators are defined in | 49 Each type of music event has an associated iterator. Iterators are defined in |
49 *-iterator.cc. During iteration, an | 50 *-iterator.cc. During iteration, an |
50 event's iterator is called to deliver that music event to the appropriate | 51 event's iterator is called to deliver that music event to the appropriate |
51 context(s). | 52 context(s). |
52 | 53 |
53 The final stage of LilyPond processing is @emph{translation}. During | 54 The final stage of LilyPond processing is @emph{translation}. During |
54 translation, music events are prepared for graphical or midi output. The | 55 translation, music events are prepared for graphical or midi output. The |
55 translation step is accomplished by translators or engravers (the distinction | 56 translation step is accomplished by the polymorphic base class Translator |
56 is unclear). | 57 through its two derived classes: Engraver (for graphical output) and |
57 | 58 Performer (for midi output). |
58 Translators are defined in C++ files named *-engraver.cc. In *-engraver.cc, a | 59 |
59 C++ class of Engraver type is created. The Engraver is also declared as a | 60 Translators are defined in C++ files named *-engraver.cc and *-performer.cc. |
60 translator. Much of the work of translating is handled by Scheme functions, | 61 Much of the work of translating is handled by Scheme functions, |
61 which is one of the keys to LilyPond's exceptional flexibility. | 62 which is one of the keys to LilyPond's exceptional flexibility. |
63 | |
64 @sourceimage{architecture-diagram,,,png} | |
62 | 65 |
63 | 66 |
64 @node LilyPond programming languages | 67 @node LilyPond programming languages |
65 @section LilyPond programming languages | 68 @section LilyPond programming languages |
66 | 69 |
67 Programming in LilyPond is done in a variety of programming languages. Each | 70 Programming in LilyPond is done in a variety of programming languages. Each |
68 language is used for a specific purpose or purposes. This section describes | 71 language is used for a specific purpose or purposes. This section describes |
69 the languages used and provides links to reference manuals and tutorials for | 72 the languages used and provides links to reference manuals and tutorials for |
70 the relevant language. | 73 the relevant language. |
71 | 74 |
72 @subsection C++ | 75 @subsection C++ |
73 | 76 |
74 The core functionality of LilyPond is implemented in C++. | 77 The core functionality of LilyPond is implemented in C++. |
75 | 78 |
76 C++ is so ubiquitous that it is difficult to identify either a reference | 79 C++ is so ubiquitous that it is difficult to identify either a reference |
77 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some | 80 manual or a tutorial. Programmers unfamiliar with C++ will need to spend some |
78 time to learn the language before attempting to modify the C++ code. | 81 time to learn the language before attempting to modify the C++ code. |
79 | 82 |
80 The C++ code calls Scheme/GUILE through the GUILE interface, which is | 83 The C++ code calls Scheme/GUILE through the GUILE interface, which is |
81 documented in the | 84 documented in the |
82 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE | 85 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, GUILE |
83 Reference Manual}. | 86 Reference Manual}. |
87 | |
88 @subsection Flex | |
89 | |
90 The LilyPond lexer is implemented in Flex, an implementation of the Unix lex | |
91 lexical analyser generator. Resources for Flex can be found | |
92 @uref{http://flex.sourceforge.net/, here}. | |
84 | 93 |
85 @subsection GNU Bison | 94 @subsection GNU Bison |
86 | 95 |
87 The LilyPond parser is implemented in Bison, a GNU parser generator. The | 96 The LilyPond parser is implemented in Bison, a GNU parser generator. The |
88 Bison homepage is found at @uref{http://www.gnu.org/software/bison/, | 97 Bison homepage is found at @uref{http://www.gnu.org/software/bison/, |
89 gnu.org}. The manual (which includes both a reference and tutorial) is | 98 gnu.org}. The manual (which includes both a reference and tutorial) is |
90 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a | 99 @uref{http://www.gnu.org/software/bison/manual/index.html, available} in a |
91 variety of formats. | 100 variety of formats. |
92 | 101 |
93 @subsection GNU Make | 102 @subsection GNU Make |
94 | 103 |
95 GNU Make is used to control the compiling process and to build the | 104 GNU Make is used to control the compiling process and to build the |
96 documentation and the website. GNU Make documentation is available at | 105 documentation and the website. GNU Make documentation is available at |
97 @uref{http://www.gnu.org/software/make/manual/, the GNU website}. | 106 @uref{http://www.gnu.org/software/make/manual/, the GNU website}. |
98 | 107 |
99 @subsection GUILE or Scheme | 108 @subsection GUILE or Scheme |
100 | 109 |
101 GUILE is the dialect of Scheme that is used as LilyPond's extension language. M any extensions to LilyPond are written entirely in GUILE. The | 110 GUILE is the dialect of Scheme that is used as LilyPond's extension language. |
111 Many extensions to LilyPond are written entirely in GUILE. The | |
102 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, | 112 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, |
103 GUILE Reference Manual} is available online. | 113 GUILE Reference Manual} is available online. |
104 | 114 |
105 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and | 115 @uref{http://mitpress.mit.edu/sicp/full-text/book/book.html, Structure and |
106 Interpretation of Computer Programs}, a popular textbook used to teach | 116 Interpretation of Computer Programs}, a popular textbook used to teach |
107 programming in Scheme is available in its entirety online. | 117 programming in Scheme is available in its entirety online. |
108 | 118 |
109 An introduction to Guile/Scheme as used in LilyPond can be found in the | 119 An introduction to Guile/Scheme as used in LilyPond can be found in the |
110 Learning Manual, see @rlearning{Scheme tutorial}. | 120 Learning Manual, see @rlearning{Scheme tutorial}. |
111 | 121 |
(...skipping 639 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
751 In order to experiment with Scheme programming in the LilyPond | 761 In order to experiment with Scheme programming in the LilyPond |
752 environment, it is convenient to have a Guile interpreter that | 762 environment, it is convenient to have a Guile interpreter that |
753 has all the LilyPond modules loaded. This requires the following | 763 has all the LilyPond modules loaded. This requires the following |
754 steps. | 764 steps. |
755 | 765 |
756 First, define a Scheme symbol for the active module | 766 First, define a Scheme symbol for the active module |
757 in the .ly file: | 767 in the .ly file: |
758 | 768 |
759 @example | 769 @example |
760 #(module-define! (resolve-module '(guile-user)) | 770 #(module-define! (resolve-module '(guile-user)) |
761 'lilypond-module (current-module)) | 771 'lilypond-module (current-module)) |
762 @end example | 772 @end example |
763 | 773 |
764 Second, place a Scheme function in the .ly file that gives an interactive Guile | 774 Second, place a Scheme function in the .ly file that gives an interactive Guile |
765 prompt: | 775 prompt: |
766 | 776 |
767 @example | 777 @example |
768 #(top-repl) | 778 #(top-repl) |
769 @end example | 779 @end example |
770 | 780 |
771 When the .ly file is compiled, this causes the compilation to be interrupted | 781 When the .ly file is compiled, this causes the compilation to be interrupted |
(...skipping 128 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
900 The comment @qq{% begin verbatim} should be removed. The syntax of | 910 The comment @qq{% begin verbatim} should be removed. The syntax of |
901 the snippet should then be manually edited. | 911 the snippet should then be manually edited. |
902 | 912 |
903 Where snippets in Documentation/snippets are made obsolete, the snippet | 913 Where snippets in Documentation/snippets are made obsolete, the snippet |
904 should be copied to Documentation/snippets/new. The comments and | 914 should be copied to Documentation/snippets/new. The comments and |
905 texidoc strings should be removed as described above. Then the body | 915 texidoc strings should be removed as described above. Then the body |
906 of the snippet should be changed to: | 916 of the snippet should be changed to: |
907 | 917 |
908 @example | 918 @example |
909 \markup @{ | 919 \markup @{ |
910 "This snippet is deprecated as of version X.Y.Z and | 920 This snippet is deprecated as of version X.Y.Z and |
911 will be removed from the documentation." | 921 will be removed from the documentation. |
912 @} | 922 @} |
913 @end example | 923 @end example |
914 | 924 |
915 @noindent | 925 @noindent |
916 where X.Y.Z is the version number for which the convert-ly rule was | 926 where X.Y.Z is the version number for which the convert-ly rule was |
917 written. | 927 written. |
918 | 928 |
919 Update the snippet files by running: | 929 Update the snippet files by running: |
920 | 930 |
921 @example | 931 @example |
922 scripts\auxiliar\makelsr.py | 932 scripts/auxiliar/makelsr.py |
923 @end example | 933 @end example |
924 | 934 |
925 Where the convert-ly rule is not able to automatically update regression | 935 Where the convert-ly rule is not able to automatically update regression |
926 tests, the regression tests in input/regression should be manually | 936 tests, the regression tests in input/regression should be manually |
927 edited. | 937 edited. |
928 | 938 |
929 Although it is not required, it is helpful if the developer | 939 Although it is not required, it is helpful if the developer |
930 can write relevant material for inclusion in the Notation | 940 can write relevant material for inclusion in the Notation |
931 Reference. If the developer does not feel qualified to write | 941 Reference. If the developer does not feel qualified to write |
932 the documentation, a documentation editor will be able to | 942 the documentation, a documentation editor will be able to |
933 write it from the regression tests. The text that is added to | 943 write it from the regression tests. The text that is added to |
934 or removed from the documentation should be changed only in | 944 or removed from the documentation should be changed only in |
935 the English version. | 945 the English version. |
936 | 946 |
937 @subsection Write NEWS entry | 947 @subsection Edit changes.tely |
938 | 948 |
939 An entry should be added to the NEWS file to describe the feature | 949 An entry should be added to Documentation/changes.tely to describe |
940 changes to be implemented. This is especially important for changes | 950 the feature changes to be implemented. This is especially important |
941 that change input file syntax. | 951 for changes that change input file syntax. |
942 | 952 |
943 Hints for NEWS file entries are given at the top of the NEWS file. | 953 Hints for changes.tely entries are given at the top of the file. |
944 | 954 |
945 New entries in NEWS go at the top of the file. | 955 New entries in changes.tely go at the top of the file. |
946 | 956 |
947 The NEWS entry should be written to show how the new change | 957 The changes.tely entry should be written to show how the new change |
948 improves LilyPond, if possible. | 958 improves LilyPond, if possible. |
949 | 959 |
950 @subsection Verify successful build | 960 @subsection Verify successful build |
951 | 961 |
952 When the changes have been made, successful completion must be | 962 When the changes have been made, successful completion must be |
953 verified by doing | 963 verified by doing |
954 | 964 |
955 @example | 965 @example |
956 make all | 966 make all |
957 make doc | 967 make doc |
958 @end example | 968 @end example |
959 | 969 |
960 When these commands complete without error, the patch is | 970 When these commands complete without error, the patch is |
961 considered to function successfully. | 971 considered to function successfully. |
962 | 972 |
963 Developers on Windows who are unable to build LilyPond should | 973 Developers on Windows who are unable to build LilyPond should |
964 get help from a Linux or OSX developer to do the make tests. | 974 get help from a Linux or OSX developer to do the make tests. |
965 | 975 |
966 @subsection Verify regression test | 976 @subsection Verify regression test |
967 | 977 |
968 In order to avoid breaking LilyPond, it is important to verify that | 978 In order to avoid breaking LilyPond, it is important to verify that |
969 the regression tests all succeed. This process is described in | 979 the regression tests all succeed. This process is described in |
970 @ref{Regression tests}. | 980 @ref{Regression tests}. |
971 | 981 |
972 @subsection Post patch for comments | 982 @subsection Post patch for comments |
973 | 983 |
974 For any change other than a minor change, a patch set should be | 984 For any change other than a minor change, a patch set should be |
975 posted on Rietveld for comment. This requires the use of an | 985 posted on @uref{http://codereview.appspot.com/, Rietveld} for comment. |
976 external package, git-cl. | 986 This requires the use of an external package, git-cl, and an email |
987 account on Google. | |
977 | 988 |
978 git-cl is installed by: | 989 git-cl is installed by: |
979 | 990 |
980 @example | 991 @example |
981 git clone git://neugierig.org/git-cl.git | 992 git clone git://neugierig.org/git-cl.git |
982 @end example | 993 @end example |
983 | 994 |
984 Then, add the git-cl directory to your PATH, or create a | 995 Then, add the git-cl directory to your PATH, or create a |
985 symbolic link to the git-cl and upload.py in one of your | 996 symbolic link to the git-cl and upload.py in one of your |
986 PATH directories (like usr/bin). git-cl will is then | 997 PATH directories (like usr/bin). git-cl is then |
987 configured by | 998 configured by entering the command |
988 | 999 |
989 @example | 1000 @example |
990 git-cl config | 1001 git cl config |
991 @end example | 1002 @end example |
992 | 1003 |
993 @noindent | 1004 @noindent |
994 and answering the questions that are asked. | 1005 in the LilyPond git directory and answering the questions that |
995 | 1006 are asked. If you do not understand the question answer with just |
996 The patch set is posted by issuing the following command, after | 1007 a newline (CR). |
997 first committing all changes: | 1008 |
998 | 1009 The patch set is posted to Rietveld as follows. Ensure your changes |
999 @example | 1010 are committed in a separate branch, which should differ from the |
1000 git-cl upload <reference SHA1 ID> | 1011 reference branch to be used by just the changes to be uploaded. |
1012 If the reference branch is to be origin/master, ensure this is | |
1013 up-to-date. If necessary, use git rebase to rebase the branch | |
1014 containing the changes to the head of origin/master. Finally, | |
1015 check out branch with the changes and enter the command: | |
1016 | |
1017 @example | |
1018 git cl upload <reference SHA1 ID> | |
1001 @end example | 1019 @end example |
1002 | 1020 |
1003 @noindent | 1021 @noindent |
1004 where <reference SHA1 ID> is the SHA1 ID of the commit to be used | 1022 where <reference SHA1 ID> is the SHA1 ID of the commit to be used |
1005 as a reference source for the patch (generally, this will be the | 1023 as a reference source for the patch. Generally, this will be the |
1006 SHA1 ID of origin/master). | 1024 SHA1 ID of origin/master, and in that case the command |
1007 | 1025 |
1008 After prompting for an email and a password, the patch set will be | 1026 @example |
1009 posted to Rietveld. | 1027 git cl upload origin/master |
1010 | 1028 @end example |
1011 An email should then be sent to lilypond-devel, with a subject line | 1029 |
1030 @noindent | |
1031 can be used. | |
1032 | |
1033 After prompting for your Google email address and password, the | |
1034 patch set will be posted to Rietveld. | |
1035 | |
1036 You should then announce the patch by sending | |
1037 an email to lilypond-devel, with a subject line | |
1012 starting with PATCH:, asking for comments on the patch. | 1038 starting with PATCH:, asking for comments on the patch. |
1013 | 1039 |
1014 As revisions are made in response to comments, successive patch sets | 1040 As revisions are made in response to comments, successive patch sets |
1015 for the same issue can be uploaded by reissuing the git-cl command. | 1041 for the same issue can be uploaded by reissuing the git-cl command |
1042 with the modified branch checked out. | |
1016 | 1043 |
1017 @subsection Push patch | 1044 @subsection Push patch |
1018 | 1045 |
1019 Once all the comments have been addressed, the patch can be pushed. | 1046 Once all the comments have been addressed, the patch can be pushed. |
1020 | 1047 |
1021 If the author has push privileges, the author will push the patch. | 1048 If the author has push privileges, the author will push the patch. |
1022 Otherwise, a developer with push privileges will push the patch. | 1049 Otherwise, a developer with push privileges will push the patch. |
1023 | 1050 |
1024 @subsection Closing the issues | 1051 @subsection Closing the issues |
1025 | 1052 |
1026 Once the patch has been pushed, all the relevant issues should be | 1053 Once the patch has been pushed, all the relevant issues should be |
1027 closed. | 1054 closed. |
1028 | 1055 |
1029 On Rietveld, the author should log in an close the issue either by | 1056 On Rietveld, the author should log in an close the issue either by |
1030 using the @q{Edit Issue} link, or by clicking the circled x icon | 1057 using the @q{Edit Issue} link, or by clicking the circled x icon |
1031 to the left of the issue name. | 1058 to the left of the issue name. |
1032 | 1059 |
1033 If the changes were in response to a feature request on the Google | 1060 If the changes were in response to a feature request on the Google |
1034 issue tracker for LilyPond, the author should change the status to | 1061 issue tracker for LilyPond, the author should change the status to |
1035 @q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If | 1062 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was |
1063 fixed in version x.y.z. If | |
1036 the author does not have privileges to change the status, an email | 1064 the author does not have privileges to change the status, an email |
1037 should be sent to bug-lilypond requesting the BugMeister to change | 1065 should be sent to bug-lilypond requesting the BugMeister to change |
1038 the status. | 1066 the status. |
1039 | 1067 |
1040 @node Iterator tutorial | 1068 @node Iterator tutorial |
1041 @section Iterator tutorial | 1069 @section Iterator tutorial |
1042 | 1070 |
1043 FIXME -- this is a placeholder for a tutorial on iterators | 1071 FIXME -- this is a placeholder for a tutorial on iterators |
1044 | 1072 |
1045 Iterators are routines written in C++ that process music expressions | 1073 Iterators are routines written in C++ that process music expressions |
1046 and sent the music events to the appropriate engravers and/or | 1074 and sent the music events to the appropriate engravers and/or |
1047 performers. | 1075 performers. |
1048 | 1076 |
1049 @node Engraver tutorial | 1077 @node Engraver tutorial |
1050 @section Engraver tutorial | 1078 @section Engraver tutorial |
1051 | 1079 |
1052 FIXME -- This is a placeholder for a tutorial on how engravers work. | 1080 FIXME -- This is a placeholder for a tutorial on how engravers work. |
1053 | 1081 |
1054 Engravers are C++ classes that catch music events and | 1082 Engravers are C++ classes that catch music events and |
1055 create the appropriate grobs for display on the page. Each different | 1083 create the appropriate grobs for display on the page. Though the |
1056 type of grob has its own engraver. | 1084 majority of engravers are responsible for the creation of a single grob, |
1057 | 1085 in some cases (e.g. @code{New_fingering_engraver}), several different grobs |
1058 A typical engraver has protected functions including some or all | 1086 may be created. |
1059 of the following: | 1087 |
1088 @subsection Useful methods for information processing | |
1089 | |
1090 An engraver inherits the following public methods from the Translator | |
1091 base class, which can be used to process listened events and acknowledged | |
1092 grobs: | |
1060 | 1093 |
1061 @itemize | 1094 @itemize |
1062 @item @code{start_translation_timestep ()} | 1095 @item @code{virtual void initialize ()} |
1063 @item @code{process_music ()} | 1096 @item @code{void start_translation_timestep ()} |
1064 @item @code{stop_translation_timestep ()} | 1097 @item @code{void process_music ()} |
1065 @item @code{derived_mark ()} | 1098 @item @code{void process_acknowledged ()} |
1066 @item @code{try_music ()} | 1099 @item @code{void stop_translation_timestep ()} |
1067 @item @code{finalize ()} | 1100 @item @code{virtual void finalize ()} |
1068 @end itemize | 1101 @end itemize |
1069 | 1102 |
1070 There are also protected functions that are specific to particular | 1103 These methods are listed in order of translation time, with |
1071 engraver, as needed by the engraving process. | 1104 @code{initialize ()} and @code{finalize ()} bookending the whole |
1105 process. @code{initialize ()} can be used for one-time initialization | |
1106 of context properties before translation starts, whereas | |
1107 @code{finalize ()} is often used to tie up loose ends at the end of | |
1108 translation: for example, an unterminated spanner might be completed | |
1109 automatically or reported with a warning message. | |
1110 | |
1111 @subsection Translation process | |
1112 | |
1113 At each timestep in the music, translation proceeds by calling the | |
1114 following methods in turn: | |
1115 | |
1116 @code{start_translation_timestep ()} is called before any user information enter s | |
1117 the translators, i.e., no property operations (\set, \override, etc.) or events | |
1118 have been processed yet. | |
1119 | |
1120 @code{process_music ()} and @code{process_acknowledged ()} are called after even ts | |
1121 have been heard, or grobs have been acknowledged. The latter tends to be used | |
1122 exclusively with engravers which only acknowledge grobs, whereas the former is | |
1123 the default method for main processing within engravers. | |
1124 | |
1125 @code{stop_translation_timestep ()} is called after all user information has bee n | |
1126 processed prior to beginning the translation for the next timestep. | |
1127 | |
1128 @subsection Preventing garbage collection for SCM member variables | |
1129 | |
1130 In certain cases, an engraver might need to ensure private Scheme variables | |
1131 (with type SCM) do not get swept away by Guile's garbage collector: for example, | |
1132 a cache of the previous key signature which must persist persist between timeste ps. | |
1133 The method @code{virtual derived_mark () const} can be used in such cases to mar k | |
1134 such objects as follows: | |
1135 | |
1136 @example | |
1137 Engraver_name::derived_mark () | |
1138 @{ | |
1139 scm_gc_mark (private_scm_member_) | |
1140 @} | |
1141 @end example | |
1142 | |
1143 | |
1144 @subsection Listening to music events | |
1072 | 1145 |
1073 External interfaces to to the engraver are implemented by protected | 1146 External interfaces to to the engraver are implemented by protected |
1074 macros including one or more of the following: | 1147 macros including one or more of the following: |
1075 | 1148 |
1076 @itemize | 1149 @itemize |
1077 @item @code{DECLARE_ACKNOWLEDGER (grob)} | 1150 @item @code{DECLARE_TRANSLATOR_LISTENER (event_name)} |
1078 @item @code{DECLARE_TRANSLATOR_LISTENER (grob)} | 1151 @item @code{IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name)} |
1079 @item @code{DECLARE_END_ACKNOWLEDGER (grob)} | |
1080 @end itemize | 1152 @end itemize |
1081 | 1153 |
1082 @noindent | 1154 @noindent |
1083 where @var{grob} is the | 1155 where @var{event_name} is the type of event required to provide the |
1084 type of grob with which the engraver works. | 1156 input the engraver needs and @var{Engraver_name} is the name of the |
1085 These macros declare the kinds of grobs that will be processed by | 1157 engraver. |
1086 the engraver. | 1158 |
1087 | 1159 Following declaration of a listener, the method is implemented as follows: |
1088 An engraver will also generally have a public macro | 1160 |
1161 @example | |
1162 IMPLEMENT_TRANSLATOR_LISTENER (Engraver_name, event_name) | |
1163 void | |
1164 Engraver_name::listen_event_name (Stream event *event) | |
1165 @{ | |
1166 ...body of listener method... | |
1167 @} | |
1168 @end example | |
1169 | |
1170 @subsection Acknowledging grobs | |
1171 | |
1172 Some engravers also need information from grobs as they are created | |
1173 and as they terminate. The mechanism and methods to obtain this | |
1174 information are set up by the macros: | |
1175 | |
1176 @itemize | |
1177 @item @code{DECLARE_ACKNOWLEDGER (grob_interface)} | |
1178 @item @code{DECLARE_END_ACKNOWLEDGER (grob_interface)} | |
1179 @end itemize | |
1180 | |
1181 where @var{grob_interface} is an interface supported by the | |
1182 grob(s) which should be acknowledged. For example, the following | |
1183 code would declare acknowledgers for a @code{NoteHead} grob (via the | |
1184 @code{note-head-interface}) and any grobs which support the | |
1185 @code{side-position-interface}: | |
1186 | |
1187 @example | |
1188 @code{DECLARE_ACKNOWLEDGER (note_head)} | |
1189 @code{DECLARE_ACKNOWLEDGER (side_position)} | |
1190 @end example | |
1191 | |
1192 The @code{DECLARE_END_ACKNOWLEDGER ()} macro sets up a spanner-specific | |
1193 acknowledger which will be called whenever a spanner ends. | |
1194 | |
1195 Following declaration of an acknowledger, the method is coded as follows: | |
1196 | |
1197 @example | |
1198 void | |
1199 Engraver_name::acknowledge_interface_name (Grob_info info) | |
1200 @{ | |
1201 ...body of acknowledger method... | |
1202 @} | |
1203 @end example | |
1204 | |
1205 @subsection Engraver declaration/documentation | |
1206 | |
1207 An engraver must have a public macro | |
1089 | 1208 |
1090 @itemize | 1209 @itemize |
1091 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)} | 1210 @item @code{TRANSLATOR_DECLARATIONS (Engraver_name)} |
1092 @end itemize | 1211 @end itemize |
1093 | 1212 |
1094 @noindent | 1213 @noindent |
1095 where @code{Engraver_name} is the name of the engraver. | 1214 where @code{Engraver_name} is the name of the engraver. This |
1096 | 1215 defines the common variables and methods used by every engraver. |
1097 At the end of the engraver file, the following macros are generally | 1216 |
1098 called: | 1217 At the end of the engraver file, one or both of the following |
1218 macros are generally called to document the engraver in the | |
1219 Internals Reference: | |
1099 | 1220 |
1100 @itemize | 1221 @itemize |
1101 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob)} | 1222 @item @code{ADD_ACKNOWLEDGER (Engraver_name, grob_interface)} |
1102 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc, | 1223 @item @code{ADD_TRANSLATOR (Engraver_name, Engraver_doc, |
1103 Engraver_creates, Engraver_reads, Engraver_writes)} | 1224 Engraver_creates, Engraver_reads, Engraver_writes)} |
1104 @end itemize | 1225 @end itemize |
1105 | 1226 |
1106 @noindent | 1227 @noindent |
1107 where @code{Engraver_name} is the name of the engraver, @code{grob} | 1228 where @code{Engraver_name} is the name of the engraver, @code{grob_interface} |
1108 is a placeholder for a grob that will be acknowledged, | 1229 is the name of the interface that will be acknowledged, |
1109 @code{Engraver_doc} is a docstring for the engraver, | 1230 @code{Engraver_doc} is a docstring for the engraver, |
1110 @code{Engraver_creates} is the grob created by the engraver, | 1231 @code{Engraver_creates} is the set of grobs created by the engraver, |
1111 @code{Engraver_reads} is the set of properties read by the engraver, | 1232 @code{Engraver_reads} is the set of properties read by the engraver, |
1112 and @code{Engraver_writes} is the set of properties written by | 1233 and @code{Engraver_writes} is the set of properties written by |
1113 the engraver. | 1234 the engraver. |
1114 | 1235 |
1115 @node Callback tutorial | 1236 @node Callback tutorial |
1116 @section Callback tutorial | 1237 @section Callback tutorial |
1117 | 1238 |
1118 FIXME -- This is a placeholder for a tutorial on callback functions. | 1239 FIXME -- This is a placeholder for a tutorial on callback functions. |
1119 | 1240 |
1241 @node LilyPond scoping | |
1242 @section LilyPond scoping | |
1243 | |
1244 The Lilypond language has a concept of scoping, ie you can do | |
Ian Hulin
2009/12/26 20:05:16
"The Lilyond language has a concept of scoping, i.
| |
1245 | |
1246 @example | |
1247 foo = 1 | |
1248 | |
1249 #(begin | |
1250 (display (+ foo 2))) | |
1251 @end example | |
1252 | |
1253 @noindent with @code{\paper}, @code{\midi} and @code{\header} being | |
Ian Hulin
2009/12/26 20:05:16
@noindent. @code{\paper}, @code{\midi} and @code{
| |
1254 nested scope inside the @file{.ly} file-level scope. @w{@code{foo = 1}} | |
Ian Hulin
2009/12/26 20:05:16
"nested scope" --> "scope definitions nested"
| |
1255 is translated in to a scheme variable definition. | |
1256 | |
1257 This implemented using modules, with each scope being an anonymous | |
Ian Hulin
2009/12/26 20:05:16
"This is implemented using modules; each of these
| |
1258 module that imports its enclosing scope's module. | |
Ian Hulin
2009/12/26 20:05:16
See comment for above line.
| |
1259 | |
1260 Lilypond's core, loaded from @file{.scm} files, is usually placed in the | |
1261 @code{lily} module, outside the @file{.ly} level. In the case of | |
Ian Hulin
2009/12/26 20:05:16
Lilypond's core, loaded from various @file{.scm} f
| |
1262 | |
1263 @example | |
1264 lilypond a.ly b.ly | |
1265 @end example | |
1266 | |
1267 @noindent | |
1268 we want to reuse the built-in definitions, without changes effected in | |
Ian Hulin
2009/12/26 20:05:16
Here we want to re-use the built-in definitions wi
| |
1269 user-level @file{a.ly} leaking into the processing of @file{b.ly}. | |
1270 | |
1271 The user-accessible definition commands have to take care to avoid | |
1272 memory leaks that could occur when running multiple files. All | |
Ian Hulin
2009/12/26 20:05:16
"memory leaks which could occur when compiling mor
| |
1273 information belonging to user-defined commands and markups is stored in | |
1274 a manner that allows it to be garbage-collected when the module is | |
1275 dispersed, either by being stored module-locally, or in weak hash | |
1276 tables. | |
LEFT | RIGHT |