2 smobs.hh -- declare smob related stuff.
4 source file of the GNU LilyPond music typesetter
6 (c) 1999--2004 Han-Wen Nienhuys <hanwen@cs.uu.nl>
13 #include "lily-guile.hh"
17 Smobs are GUILEs mechanism of exporting C(++) objects to the Scheme
18 world. They are documented in the GUILE manual.
21 In LilyPond, smobs are created from C++ objects through macros.
22 There are two types of smob objects.
24 1. Simple smobs are intended for simple objects like numbers:
25 immutable objects that can be copied without change of meaning.
27 To obtain an SCM version of a simple smob, use the member function
30 Simple smobs are created by adding the
31 DECLARE_SIMPLE_SMOBS(Classname,) to the declaration
33 2. Complex smobs are objects that have an identity. These objects
34 carry this identity in the form of a self_scm () method, which is a
35 SCM pointer to the object itself.
37 The constructor for a complex smob should have 3 steps:
39 * initialize all SCM members to a non-immediate value (like SCM_EOL)
41 * call smobify_self ()
43 * initialize SCM members
47 Complex_smob::Complex_smob () {
50 scm_member_ = <..what you want to store..>
53 after creation, the self_scm() field of a complex smob is protected
54 from Garbage Collection. This protection should be removed once the
55 object is put into another (reachable) Scheme data structure, ie.
57 Complex_smob * p = new Complex_smob;
58 list = scm_cons (p->self_scm (), list);
59 scm_gc_unprotect_object (p->self_scm ());
61 Complex smobs are made with DECLARE_SMOBS(Classname,) in the class
66 Common public methods to C++ smob objects:
68 unsmob (SCM x) - unpacks X and returns pointer to the C++ object, or 0
69 if it has the wrong type.
71 SCM equal_p (SCM a, SCM b) - compare A and B. Returns a Scheme boolean
76 For implementating a class, the following should be provided
78 - an equal_p() function (a default is in the
79 IMPLEMENT_DEFAULT_EQUAL_P macro in ly-smobs.icc)
81 - mark_smob () function, that calls scm_gc_mark () on all Scheme
84 - a print_smob () function, that displays a representation for
87 - A call to one of the IMPLEMENT_SMOBS or IMPLEMENT_SIMPLE_SMOBS macros
88 from file "ly-smobs.icc"
92 #define DECLARE_SIMPLE_SMOBS(CL,dummy) \
94 SCM smobbed_copy () const; \
95 DECLARE_BASE_SMOBS(CL)
98 #define DECLARE_BASE_SMOBS(CL) \
99 friend class Non_existant_class ; \
101 static scm_t_bits smob_tag_; \
102 static SCM mark_smob (SCM); \
103 static size_t free_smob (SCM s); \
104 static int print_smob (SCM s, SCM p, scm_print_state*); \
106 static SCM equal_p (SCM a, SCM b);\
107 static CL * unsmob (SCM s){\
108 if (SCM_NIMP (s) && SCM_CELL_TYPE (s) == smob_tag_) \
109 return (CL*) SCM_CELL_WORD_1 (s); \
113 static SCM smob_p (SCM);\
114 static void init_smobs (); \
118 #define DECLARE_SMOBS(CL,dummy) \
119 DECLARE_BASE_SMOBS (CL) \
122 SCM unprotected_smobify_self ();\
124 SCM smobify_self (); \
127 SCM self_scm () const { return self_scm_; } \
130 #define DECLARE_UNSMOB(CL,name) \
132 unsmob_ ## name (SCM s) \
134 return CL::unsmob (s); \
139 #endif /* SMOBS_HH */