Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(1033)

Side by Side Diff: Documentation/contributor/programming-work.itexi

Issue 4917044: lily-guile updates and CG: "Scheme->C interface" section.
Patch Set: Typo again. Created 12 years, 6 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | lily/general-scheme.cc » ('j') | lily/lily-guile.cc » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 @c -*- coding: utf-8; mode: texinfo; -*- 1 @c -*- coding: utf-8; 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 * Warnings Errors Progress and Debug Output:: 11 * Warnings Errors Progress and Debug Output::
12 * Debugging LilyPond:: 12 * Debugging LilyPond::
13 * Tracing object relationships:: 13 * Tracing object relationships::
14 * Adding or modifying features:: 14 * Adding or modifying features::
15 * Iterator tutorial:: 15 * Iterator tutorial::
16 * Engraver tutorial:: 16 * Engraver tutorial::
17 * Callback tutorial:: 17 * Callback tutorial::
18 * LilyPond scoping:: 18 * LilyPond scoping::
19 * Scheme->C interface::
19 * LilyPond miscellany:: 20 * LilyPond miscellany::
20 @end menu 21 @end menu
21 22
22 @node Overview of LilyPond architecture 23 @node Overview of LilyPond architecture
23 @section Overview of LilyPond architecture 24 @section Overview of LilyPond architecture
24 25
25 LilyPond processes the input file into graphical and musical output in a 26 LilyPond processes the input file into graphical and musical output in a
26 number of stages. This process, along with the types of routines that 27 number of stages. This process, along with the types of routines that
27 accomplish the various stages of the process, is described in this section. A 28 accomplish the various stages of the process, is described in this section. A
28 more complete description of the LilyPond architecture and internal program 29 more complete description of the LilyPond architecture and internal program
(...skipping 1507 matching lines...) Expand 10 before | Expand all | Expand 10 after
1536 If the author has push privileges, the author will push the patch. 1537 If the author has push privileges, the author will push the patch.
1537 Otherwise, a developer with push privileges will push the patch. 1538 Otherwise, a developer with push privileges will push the patch.
1538 1539
1539 1540
1540 @node Closing the issues 1541 @node Closing the issues
1541 @subsection Closing the issues 1542 @subsection Closing the issues
1542 1543
1543 Once the patch has been pushed, all the relevant issues should be 1544 Once the patch has been pushed, all the relevant issues should be
1544 closed. 1545 closed.
1545 1546
1546 On Rietveld, the author should log in an close the issue either by 1547 On Rietveld, the author should log in and close the issue either by
1547 using the @q{Edit Issue} link, or by clicking the circled x icon 1548 using the @q{Edit Issue} link, or by clicking the circled x icon
1548 to the left of the issue name. 1549 to the left of the issue name.
1549 1550
1550 If the changes were in response to a feature request on the Google 1551 If the changes were in response to a feature request on the Google
1551 issue tracker for LilyPond, the author should change the status to 1552 issue tracker for LilyPond, the author should change the status to
1552 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was 1553 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was
1553 fixed in version x.y.z. If 1554 fixed in version x.y.z. If
1554 the author does not have privileges to change the status, an email 1555 the author does not have privileges to change the status, an email
1555 should be sent to bug-lilypond requesting the BugMeister to change 1556 should be sent to bug-lilypond requesting the BugMeister to change
1556 the status. 1557 the status.
(...skipping 247 matching lines...) Expand 10 before | Expand all | Expand 10 after
1804 we want to reuse the built-in definitions, without changes effected in 1805 we want to reuse the built-in definitions, without changes effected in
1805 user-level @file{a.ly} leaking into the processing of @file{b.ly}. 1806 user-level @file{a.ly} leaking into the processing of @file{b.ly}.
1806 1807
1807 The user-accessible definition commands have to take care to avoid 1808 The user-accessible definition commands have to take care to avoid
1808 memory leaks that could occur when running multiple files. All 1809 memory leaks that could occur when running multiple files. All
1809 information belonging to user-defined commands and markups is stored in 1810 information belonging to user-defined commands and markups is stored in
1810 a manner that allows it to be garbage-collected when the module is 1811 a manner that allows it to be garbage-collected when the module is
1811 dispersed, either by being stored module-locally, or in weak hash 1812 dispersed, either by being stored module-locally, or in weak hash
1812 tables. 1813 tables.
1813 1814
1815
1816 @node Scheme->C interface
1817 @section Scheme->C interface
1818
1819 Most of the C functions interfacing with Guile/Scheme used in LilyPond
1820 are described in the API Reference of the
1821 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html,
1822 GUILE Reference Manual}.
1823
1824 The remaining functions are defined in @file{lily/lily-guile.cc},
1825 @file{lily/include/lily-guile.hh} and
1826 @file{lily/include/lily-guile-macros.hh}.
1827 Although their names are meaningful there's a few things you should know
1828 about them.
1829
1830 @menu
1831 * Comparison::
1832 * Conversion::
1833 @end menu
1834
1835 @node Comparison
1836 @subsection Comparison
1837
1838 This is the trickiest part of the interface.
1839
1840 Mixing Scheme values with C comparison operators won't produce any crash
1841 or warning when compiling but must be avoided:
1842
1843 @example
1844 scm_string_p (scm_value) == SCM_BOOL_T
1845 @end example
1846
1847 As we can read in the reference, @code{scm_string_p} returns a Scheme
1848 value: either @code{#t} or @code{#f} which are written @code{SCM_BOOL_T}
1849 and @code{SCM_BOOL_F} in C. This will work, but it is not following
1850 to the API guidelines. For further information, read this discussion:
1851
1852 @smallexample
1853 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00646.html}
1854 @end smallexample
1855
1856 There are functions in the Guile reference that returns C values
1857 instead of Scheme values. In our example, a function called
1858 @code{scm_is_string} (described after @code{string?} and @code{scm_string_p})
1859 returns the C value 0 or 1.
1860
1861 So the best solution was simply:
1862
1863 @example
1864 scm_is_string (scm_value)
1865 @end example
1866
1867 There a simple solution for almost every common comparison. Another example:
1868 we want to know if a Scheme value is a non-empty list. Instead of:
1869
1870 @example
1871 (scm_list_p (scm_value) && scm_value != SCM_EOL)
dak 2011/10/23 21:23:11 scm_list_p is _always_ true according to C since i
1872 @end example
1873
1874 one should use:
1875
1876 @example
1877 scm_is_pair (scm_value)
1878 @end example
1879
1880 since a list of at least one member is considered as a pair.
dak 2011/10/23 21:23:11 But not every pair is a proper list. scm_list_[ r
1881
1882 Unfortunately, there is not a @code{scm_is_[something]} function for
1883 everything. That's one of the reasons why LilyPond has its own Scheme
1884 interface.
dak 2011/10/23 21:23:11 As a rule of thumb, you get an scm_is_[something]
1885
1886 @subheading General definitions
1887
1888 @subsubheading bool to_boolean (SCM b)
1889
1890 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
1891
1892 This should be used instead of @code{scm_is_true} and @code{scm_is_false}
dak 2011/10/23 21:23:11 Both scm_is_true and scm_is_false compare only for
1893 for properties since empty lists are sometimes used to unset them.
dak 2011/10/23 21:23:11 since reading any unset property returns an empty
1894
1895 @subsubheading bool ly_is_[something] (args)
1896
1897 Behave the same as scm_is_[something] would do if it existed.
1898
1899 @subsubheading bool is_[type] (SCM s)
1900
1901 Test whether the type of @var{s} is [type].
1902 [type] is a LilyPond-only type of value (direction, axis...).
1903
1904 @node Conversion
dak 2011/10/23 21:23:11 The whole node is duplication.
1905 @subsection Conversion
1906
1907 @subheading General definitions
1908
1909 @subsubheading bool to_boolean (SCM b)
1910
1911 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
1912
1913 This should be used instead of @code{scm_is_true} and @code{scm_is_false}
1914 for properties since empty lists are sometimes used to unset them.
1915
1916 @subsubheading [C type] ly_scm2[C type] (SCM s)
1917
1918 Behave the same as scm_to_[C type] would do if it existed.
1919
1920 @subsubheading [C type] robust_scm2[C type] (SCM s, [C type] d)
1921
1922 Behave the same as scm_to_[C type] would do if it existed.
1923 Return @var{d} if type verification fails.
1924
1925
1814 @node LilyPond miscellany 1926 @node LilyPond miscellany
1815 @section LilyPond miscellany 1927 @section LilyPond miscellany
1816 1928
1817 This is a place to dump information that may be of use to developers 1929 This is a place to dump information that may be of use to developers
1818 but doesn't yet have a proper home. Ideally, the length of this section 1930 but doesn't yet have a proper home. Ideally, the length of this section
1819 would become zero as items are moved to other homes. 1931 would become zero as items are moved to other homes.
1820 1932
1821 1933
1822 @menu 1934 @menu
1823 * Spacing algorithms:: 1935 * Spacing algorithms::
(...skipping 397 matching lines...) Expand 10 before | Expand all | Expand 10 after
2221 #(display conditionalMark) 2333 #(display conditionalMark)
2222 @end example 2334 @end example
2223 2335
2224 noindent 2336 noindent
2225 inside the @file{.ly} file. 2337 inside the @file{.ly} file.
2226 2338
2227 The breakpoint failing may have to do with the call sequence. See 2339 The breakpoint failing may have to do with the call sequence. See
2228 @file{parser.yy}, run_music_function(). The function is called directly from 2340 @file{parser.yy}, run_music_function(). The function is called directly from
2229 C++, without going through the GUILE evaluator, so I think that is why 2341 C++, without going through the GUILE evaluator, so I think that is why
2230 there is no debugger trap. 2342 there is no debugger trap.
OLDNEW
« no previous file with comments | « no previous file | lily/general-scheme.cc » ('j') | lily/lily-guile.cc » ('J')

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b