/[guile]/guile/guile-core/doc/ref/scheme-modules.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-modules.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.14 by mvo, Mon Aug 12 23:10:38 2002 UTC revision 1.15 by mvo, Tue Aug 27 17:40:10 2002 UTC
# Line 151  of symbols (names) to Scheme objects. Line 151  of symbols (names) to Scheme objects.
151  An environment is a mapping from identifiers (or symbols) to locations,  An environment is a mapping from identifiers (or symbols) to locations,
152  i.e., a set of bindings.  i.e., a set of bindings.
153  There are top-level environments and lexical environments.  There are top-level environments and lexical environments.
154  Environment in which a lambda is excuted is remembered as part of its  The environment in which a lambda is executed is remembered as part of its
155  definition.  definition.
156    
157  Within a module, all bindings are visible.  Certain bindings  Within a module, all bindings are visible.  Certain bindings
# Line 496  The following procedures are available. Line 496  The following procedures are available.
496  Return the module that is the @emph{current module}.  Return the module that is the @emph{current module}.
497  @end deftypefn  @end deftypefn
498    
499  @deftypefn {C Procedure} SCM scm_set_current_module (SCM module)  @deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module})
500  Set the current module to @var{module} and return the previous current  Set the current module to @var{module} and return the previous current
501  module.  module.
502  @end deftypefn  @end deftypefn
503    
504  @deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM module, SCM (*func)(void *), void *data)  @deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
505  Call @var{func} and make @var{module} the current module during the  Call @var{func} and make @var{module} the current module during the
506  call.  The argument @var{data} is passed to @var{func}.  The return  call.  The argument @var{data} is passed to @var{func}.  The return
507  value of @code{scm_c_call_with_current_module} is the return value of  value of @code{scm_c_call_with_current_module} is the return value of
508  @var{func}.  @var{func}.
509  @end deftypefn  @end deftypefn
510    
511  @deftypefn {C Procedure} SCM scm_c_lookup (const char *name)  @deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
512  Return the variable bound to the symbol indicated by @var{name} in the  Return the variable bound to the symbol indicated by @var{name} in the
513  current module.  If there is no such binding or the symbol is not  current module.  If there is no such binding or the symbol is not
514  bound to a variable, signal an error.  bound to a variable, signal an error.
515  @end deftypefn  @end deftypefn
516    
517  @deftypefn {C Procedure} SCM scm_lookup (SCM name)  @deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
518  Like @code{scm_c_lookup}, but the symbol is specified directly.  Like @code{scm_c_lookup}, but the symbol is specified directly.
519  @end deftypefn  @end deftypefn
520    
521  @deftypefn {C Procedure} SCM scm_c_module_lookup (SCM module, const char *name)  @deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name})
522  @deftypefnx {C Procedure} SCM scm_module_lookup (SCM module, SCM name)  @deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
523  Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified  Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
524  module is used instead of the current one.  module is used instead of the current one.
525  @end deftypefn  @end deftypefn
526    
527  @deftypefn {C Procedure} SCM scm_c_define (const char *name, SCM val)  @deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
528  Bind the symbol indicated by @var{name} to a variable in the current  Bind the symbol indicated by @var{name} to a variable in the current
529  module and set that variable to @var{val}.  When @var{name} is already  module and set that variable to @var{val}.  When @var{name} is already
530  bound to a variable, use that.  Else create a new variable.  bound to a variable, use that.  Else create a new variable.
531  @end deftypefn  @end deftypefn
532    
533  @deftypefn {C Procedure} SCM scm_define (SCM name, SCM val)  @deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
534  Like @code{scm_c_define}, but the symbol is specified directly.  Like @code{scm_c_define}, but the symbol is specified directly.
535  @end deftypefn  @end deftypefn
536    
537  @deftypefn {C Procedure} SCM scm_c_module_define (SCM module, const char *name, SCM val)  @deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val})
538  @deftypefnx {C Procedure} SCM scm_module_define (SCM module, SCM name, SCM val)  @deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
539  Like @code{scm_c_define} and @code{scm_define}, but the specified  Like @code{scm_c_define} and @code{scm_define}, but the specified
540  module is used instead of the current one.  module is used instead of the current one.
541  @end deftypefn  @end deftypefn
542    
543  @deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM module, SCM variable)  @deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
544  Find the symbol that is bound to @var{variable} in @var{module}.  When no such binding is found, return @var{#f}.  Find the symbol that is bound to @var{variable} in @var{module}.  When no such binding is found, return @var{#f}.
545  @end deftypefn  @end deftypefn
546    
547  @deftypefn {C Procedure} SCM scm_c_define_module (const char *name, void (*init)(void *), void *data)  @deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data})
548  Define a new module named @var{name} and make it current while  Define a new module named @var{name} and make it current while
549  @var{init} is called, passing it @var{data}.  Return the module.  @var{init} is called, passing it @var{data}.  Return the module.
550    
# Line 556  When there already exists a module named Line 556  When there already exists a module named
556  unchanged, otherwise, an empty module is created.  unchanged, otherwise, an empty module is created.
557  @end deftypefn  @end deftypefn
558    
559  @deftypefn {C Procedure} SCM scm_c_resolve_module (const char *name)  @deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name})
560  Find the module name @var{name} and return it.  When it has not  Find the module name @var{name} and return it.  When it has not
561  already been defined, try to auto-load it.  When it can't be found  already been defined, try to auto-load it.  When it can't be found
562  that way either, create an empty module.  The name is interpreted as  that way either, create an empty module.  The name is interpreted as
563  for @code{scm_c_define_module}.  for @code{scm_c_define_module}.
564  @end deftypefn  @end deftypefn
565    
566  @deftypefn {C Procedure} SCM scm_resolve_module (SCM name)  @deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name})
567  Like @code{scm_c_resolve_module}, but the name is given as a real list  Like @code{scm_c_resolve_module}, but the name is given as a real list
568  of symbols.  of symbols.
569  @end deftypefn  @end deftypefn
570    
571  @deftypefn {C Procedure} SCM scm_c_use_module (const char *name)  @deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name})
572  Add the module named @var{name} to the uses list of the current  Add the module named @var{name} to the uses list of the current
573  module, as with @code{(use-modules @var{name})}.  The name is  module, as with @code{(use-modules @var{name})}.  The name is
574  interpreted as for @code{scm_c_define_module}.  interpreted as for @code{scm_c_define_module}.
575  @end deftypefn  @end deftypefn
576    
577  @deftypefn {C Procedure} SCM scm_c_export (const char *name, ...)  @deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...)
578  Add the bindings designated by @var{name}, ... to the public interface  Add the bindings designated by @var{name}, ... to the public interface
579  of the current module.  The list of names is terminated by  of the current module.  The list of names is terminated by
580  @code{NULL}.  @code{NULL}.
# Line 607  to explicitly take advantage of it from Line 607  to explicitly take advantage of it from
607  many operating systems that support shared libraries do just that, and  many operating systems that support shared libraries do just that, and
608  chances are that Guile will allow you to access this feature from within  chances are that Guile will allow you to access this feature from within
609  your Scheme programs.  As you might have guessed already, this feature  your Scheme programs.  As you might have guessed already, this feature
610  is called @dfn{dynamic linking}@footnote{Some people also refer to the  is called @dfn{dynamic linking}.@footnote{Some people also refer to the
611  final linking stage at program startup as `dynamic linking', so if you  final linking stage at program startup as `dynamic linking', so if you
612  want to make yourself perfectly clear, it is probably best to use the  want to make yourself perfectly clear, it is probably best to use the
613  more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit  more technical term @dfn{dlopening}, as suggested by Gordon Matzigkeit
# Line 805  example, we will only implement this for Line 805  example, we will only implement this for
805    
806  @smallexample  @smallexample
807  #include <math.h>  #include <math.h>
808  #include <guile/gh.h>  #include <libguile.h>
809    
810  SCM  SCM
811  j0_wrapper (SCM x)  j0_wrapper (SCM x)
812  @{  @{
813    return gh_double2scm (j0 (gh_scm2double (x)));    return scm_double2num (j0 (scm_num2dbl (x, "j0")));
814  @}  @}
815    
816  void  void
817  init_math_bessel ()  init_math_bessel ()
818  @{  @{
819    gh_new_procedure1_0 ("j0", j0_wrapper);    scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
820  @}  @}
821  @end smallexample  @end smallexample
822    
# Line 851  Fun, isn't it?  But we are only half way Line 851  Fun, isn't it?  But we are only half way
851  @code{apropos} has to say about @code{j0}:  @code{apropos} has to say about @code{j0}:
852    
853  @smallexample  @smallexample
854  (apropos 'j0)  (apropos "j0")
855  @print{} the-root-module: j0     #<primitive-procedure j0>  @print{} (guile-user): j0     #<primitive-procedure j0>
856  @end smallexample  @end smallexample
857    
858  As you can see, @code{j0} is contained in the root module, where all  As you can see, @code{j0} is contained in the root module, where all
859  the other Guile primitives like @code{display}, etc live.  In general,  the other Guile primitives like @code{display}, etc live.  In general,
860  a primitive is put into whatever module is the @dfn{current module} at  a primitive is put into whatever module is the @dfn{current module} at
861  the time @code{gh_new_procedure} is called.  the time @code{scm_c_define_gsubr} is called.
862    
863  A compiled module should have a specially named @dfn{module init  A compiled module should have a specially named @dfn{module init
864  function}.  Guile knows about this special name and will call that  function}.  Guile knows about this special name and will call that
865  function automatically after having linked in the shared library.  For  function automatically after having linked in the shared library.  For
866  our example, we add the following code to @file{bessel.c}:  our example, we replace @code{init_math_bessel} with the following code in
867    @file{bessel.c}:
868    
869  @smallexample  @smallexample
870  void scm_init_math_bessel_module ()  void
871    init_math_bessel (void *unused)
872    @{
873      scm_c_define_gsubr ("j0", 1, 0, 0, j0_wrapper);
874      scm_c_export ("j0", NULL);
875    @}
876    
877    void
878    scm_init_math_bessel_module ()
879  @{  @{
880     /* contents currently unavailable.  */    scm_c_define_module ("math bessel", init_math_bessel, NULL);  
881  @}  @}
882  @end smallexample  @end smallexample
883    
# Line 877  The general pattern for the name of a mo Line 886  The general pattern for the name of a mo
886  individual hierarchical components are concatenated with underscores,  individual hierarchical components are concatenated with underscores,
887  followed by @samp{_module}.  followed by @samp{_module}.
888    
889  After @file{libbessel.so} has been rebuild, we need to place the shared  After @file{libbessel.so} has been rebuilt, we need to place the shared
890  library into the right place.  library into the right place.
891    
892  Once the module has been correctly installed, it should be possible to  Once the module has been correctly installed, it should be possible to
893  use it like this:  use it like this:
894    
895  @smallexample  @smallexample
896    guile> (load-extension "./libbessel.so" "scm_init_math_bessel_module")
897  guile> (use-modules (math bessel))  guile> (use-modules (math bessel))
898  guile> (j0 2)  guile> (j0 2)
899  0.223890779141236  0.223890779141236
900  guile> (apropos 'j0)  guile> (apropos "j0")
901  @print{} bessel: j0      #<primitive-procedure j0>  @print{} (math bessel): j0      #<primitive-procedure j0>
902  @end smallexample  @end smallexample
903    
904  That's it!  That's it!

Legend:
Removed from v.1.14  
changed lines
  Added in v.1.15

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26