From 673509f84f8b0fe3e5593e5473c844ce97c6075b Mon Sep 17 00:00:00 2001 From: =?utf8?q?Martin=20Grabm=C3=BCller?= Date: Thu, 14 Jun 2001 20:36:06 +0000 Subject: [PATCH] * scripts/README, scripts/hello.scm, safe/untrusted.scm, safe/evil.scm, safe/README, modules/README, modules/main, modules/module-0.scm, modules/module-1.scm, modules/module-2.scm: Minor cleanup. * README: Added intro stuff, restructured a bit. * box-dynamic/README, box-module/README, box/README: Cleanup and restructuring. * box-dynamic-module/box-mixed.scm: New file, demonstrating usage of extension library functionality, but without exporting procedures from the library. Thanks to Thomas Wawrzinek for the idea and example code! * box-dynamic-module/box-module.scm: Add comments, export make-box, box-ref, box-set!. * box-dynamic-module/README: Integrate new module (box-mixed), restructure and cleanup a bit. --- examples/ChangeLog | 24 +++++++++++ examples/README | 21 +++++++++- examples/box-dynamic-module/Makefile.am | 2 +- examples/box-dynamic-module/README | 47 ++++++++++++++++++---- examples/box-dynamic-module/box-mixed.scm | 44 ++++++++++++++++++++ examples/box-dynamic-module/box-module.scm | 12 +++++- examples/box-dynamic-module/box.c | 35 ++++------------ examples/box-dynamic/README | 25 ++++++++++-- examples/box-module/README | 16 +++++++- examples/box/README | 16 +++++++- examples/modules/README | 12 ++++-- examples/modules/module-0.scm | 2 + examples/modules/module-1.scm | 2 + examples/modules/module-2.scm | 2 + examples/safe/README | 13 ++++-- examples/safe/evil.scm | 2 + examples/safe/untrusted.scm | 2 + examples/scripts/README | 13 ++++-- examples/scripts/fact | 1 - examples/scripts/hello | 1 - examples/scripts/simple-hello.scm | 2 + 21 files changed, 235 insertions(+), 59 deletions(-) create mode 100644 examples/box-dynamic-module/box-mixed.scm diff --git a/examples/ChangeLog b/examples/ChangeLog index fda148a24..5af8d9b05 100644 --- a/examples/ChangeLog +++ b/examples/ChangeLog @@ -1,3 +1,27 @@ +2001-06-14 Martin Grabmueller + + * scripts/README, scripts/hello.scm, safe/untrusted.scm, + safe/evil.scm, safe/README, modules/README, modules/main, + modules/module-0.scm, modules/module-1.scm, modules/module-2.scm: + Minor cleanup. + + * README: Added intro stuff, restructured a bit. + + * box-dynamic/README, box-module/README, box/README: Cleanup and + restructuring. + + * box-dynamic-module/box-mixed.scm: New file, demonstrating usage + of extension library functionality, but without exporting + procedures from the library. + + Thanks to Thomas Wawrzinek for the idea and example code! + + * box-dynamic-module/box-module.scm: Add comments, export + make-box, box-ref, box-set!. + + * box-dynamic-module/README: Integrate new module (box-mixed), + restructure and cleanup a bit. + 2001-06-06 Martin Grabmueller * box-dynamic-module/box-module.scm: New file. diff --git a/examples/README b/examples/README index 2a362f2cd..793d131c8 100644 --- a/examples/README +++ b/examples/README @@ -1,12 +1,28 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory contains examples illustrating various aspects of Guile programming. +If you plan writing Scheme programs, have a look at the `scripts' +directory. To learn more about Guile modules, check out the `modules' +directory, and maybe the `box-module' and `box-dynamic-module' +directories, if you are into C programming or shared libraries, +respectively. The `safe' directory contains examples for evaluation +Scheme code in controlled environments (sandboxing). The directories +`box', `box-module', `box-dynamic' and `box-dynamic-module' are +interesting if you plan writing Guile extensions. + See the README files in the subdirectories for details. + +* Included Examples + scripts Examples for writing simple scripts in Guile Scheme. + box Example for extending Guile with a new data type. + box-module Similar to `box', but defines new procedures in a named module. box-dynamic Implements the box type in a dynamically loadable @@ -14,6 +30,7 @@ box-dynamic Implements the box type in a dynamically loadable box-dynamic-module Combination of `box-module' and `box-dynamic': Implements the `box' type in a shared library and defines the procedures in a Guile module. + modules Examples for writing and using Guile modules. -safe Examples for creating and using safe environments. +safe Examples for creating and using safe environments. diff --git a/examples/box-dynamic-module/Makefile.am b/examples/box-dynamic-module/Makefile.am index ca157f2bc..4d7df0210 100644 --- a/examples/box-dynamic-module/Makefile.am +++ b/examples/box-dynamic-module/Makefile.am @@ -19,7 +19,7 @@ ## to the Free Software Foundation, Inc., 59 Temple Place, Suite ## 330, Boston, MA 02111-1307 USA -EXTRA_DIST = README box.c box-module.scm +EXTRA_DIST = README box.c box-module.scm box-mixed.scm CFLAGS=`guile-config compile` LIBS=`guile-config link` diff --git a/examples/box-dynamic-module/README b/examples/box-dynamic-module/README index 6e4636fa3..5097ec7d9 100644 --- a/examples/box-dynamic-module/README +++ b/examples/box-dynamic-module/README @@ -1,35 +1,44 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes an example program for extending Guile with a new (and even useful) data type, putting it into a shared library, so it can be called from an unmodified guile interpreter. Further, the shared library defines a new guile module. + +* Build Instructions + To build the example, simply type make libbox-module in this directory. + +* The Box Data Type + A box is simply an object for storing one other object in. It can be used for passing parameters by reference, for example. You simply store an object into a box, pass it to another procedure which can store a new object into it and thus return a value via the box. + +** Usage + Box objects are created with `make-box', set with `box-set!' and examined with `box-ref'. Note that these procedures are placed in a module called (box-module) and can thus only be accessed after using -this module. See the following example session for usage details: +this module. See the following example session for usage details. + + +** The Module (box-module) Extend your LD_LIBRARY_PATH variable (or equivalent) to include . and .libs and make sure that your current working directory is the one this file is contained in. -If you like this example so much that you want to have it available -for normal usage, install the dynamic libraries in the .libs directory -to the directory $(prefix)/lib and the scheme file `box-module.scm' in -a directory in your GUILE_LOAD_PATH. - $ guile guile> (use-modules (box-module)) guile> (define b (make-box)) @@ -42,3 +51,27 @@ guile> (box-ref b) (list of values) guile> (quit) $ + + +** The Module (box-mixed) + +The following example uses the module (box-mixed), also included in +this directory. It uses the shared library libbox-module like the +module (box-module) above, but does not export the procedures from +that module. It only implements some procedures for dealing with box +objects. + +$ guile +guile> (use-modules (box-mixed)) +guile> (define bl (make-box-list 1 2 3)) +guile> bl +(# # #) +guile> (box-map (lambda (el) (make-box-list (list el))) bl) +(#)> #)> #)>) +guile> (quit) +$ + +If you like this example so much that you want to have it available +for normal usage, install the dynamic libraries in the .libs directory +to the directory $(prefix)/lib and the scheme file `box-module.scm' in +a directory in your GUILE_LOAD_PATH. diff --git a/examples/box-dynamic-module/box-mixed.scm b/examples/box-dynamic-module/box-mixed.scm new file mode 100644 index 000000000..9e6135291 --- /dev/null +++ b/examples/box-dynamic-module/box-mixed.scm @@ -0,0 +1,44 @@ +;;; examples/box-dynamic-module/box-mixed.scm -- Scheme module using some +;;; functionality from the shared library libbox-module, but do not +;;; export procedures from the module. + +;;; Commentary: + +;;; This is the Scheme module box-mixed. It uses some functionality +;;; from the shared library libbox-module, but does not export it. + +;;; Code: + +;;; Author: Thomas Wawrzinek +;;; Date: 2001-06-08 +;;; Changed: 2001-06-14 by martin, some commenting, cleanup and integration. + +(define-module (box-mixed)) + +;; First, load the library. +;; +(load-extension "libbox-module" "scm_init_box") + +;; Create a list of boxes, each containing one element from ARGS. +;; +(define (make-box-list . args) + (map (lambda (el) + (let ((b (make-box))) + (box-set! b el) b)) + args)) + +;; Map the procedure FUNC over all elements of LST, which must be a +;; list of boxes. The result is a list of freshly allocated boxes, +;; each containing the result of an application of FUNC. +(define (box-map func lst) + (map (lambda (el) + (let ((b (make-box))) + (box-set! b (func (box-ref el))) + b)) + lst)) + +;; Export the procedures, so that they can be used by others. +;; +(export make-box-list box-map) + +;;; End of file. diff --git a/examples/box-dynamic-module/box-module.scm b/examples/box-dynamic-module/box-module.scm index cab41c7e5..ab589ba1b 100644 --- a/examples/box-dynamic-module/box-module.scm +++ b/examples/box-dynamic-module/box-module.scm @@ -1,5 +1,5 @@ -;;; examples/box-dynamic-module/box-module.scm -- Scheme part of the -;;; dynamic module (box-module) +;;; examples/box-dynamic-module/box-module.scm -- Scheme module exporting +;;; some functionality from the shared library libbox-module. ;;; Commentary: @@ -14,4 +14,12 @@ (define-module (box-module)) +;; First, load the library. +;; (load-extension "libbox-module" "scm_init_box") + +;; Then export the procedures which should be visible to module users. +;; +(export make-box box-ref box-set!) + +;;; End of file. diff --git a/examples/box-dynamic-module/box.c b/examples/box-dynamic-module/box.c index fa9eaff41..c159a8f82 100644 --- a/examples/box-dynamic-module/box.c +++ b/examples/box-dynamic-module/box.c @@ -107,14 +107,13 @@ box_set_x (SCM b, SCM value) #undef FUNC_NAME -/* Create and initialize the new smob type, and register the - primitives withe the interpreter library. - - This function must be declared a bit different from the example in - the ../box directory, because it will be called by - `scm_c_define_module', called from below. */ -static void -init_box_type (void * unused) +/* This is the function which must be given to `load-extension' as the + second argument. In this example, the Scheme file box-module.scm + (or box-mixed.scm) is responsible for doing the load-extension + call. The Scheme modules are also responsible for placing the + procedure definitions in the correct module. */ +void +scm_init_box () { scm_tc16_box = scm_make_smob_type ("box", 0); scm_set_smob_mark (scm_tc16_box, mark_box); @@ -123,26 +122,6 @@ init_box_type (void * unused) scm_c_define_gsubr ("make-box", 0, 0, 0, make_box); scm_c_define_gsubr ("box-set!", 2, 0, 0, box_set_x); scm_c_define_gsubr ("box-ref", 1, 0, 0, box_ref); - - /* This is new too: Since the procedures are now in a module, we - have to explicitly export them before they can be used. */ - scm_c_export ("make-box", "box-set!", "box-ref", NULL); -} - -/* This is the function which must be given to `load-extension' as the - second argument. It will initialize the shared, library, but will - place the definitions in a module called (box-module), so that an - additional (use-modules (box-module)) is needed to make them - accessible. In this example, the Scheme file box-module.scm is - responsible for doing the load-extension call. */ -void -scm_init_box () -{ - /* Unlike the example in ../box, init_box_type is not called - directly, but by scm_c_define_module, which will create a module - named (box-module) and make this module current while called - init_box_type, thus placing the definitions into that module. */ - scm_c_define_module ("box-module", init_box_type, NULL); } /* End of file. */ diff --git a/examples/box-dynamic/README b/examples/box-dynamic/README index 561e4841a..bb87b5db7 100644 --- a/examples/box-dynamic/README +++ b/examples/box-dynamic/README @@ -1,20 +1,31 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes an example program for extending Guile with a new (and even useful) data type, putting it into a shared library, so it can be called from an unmodified guile interpreter. + +* Build Instructions + To build the example, simply type make libbox in this directory. + +* The Box Data Type + A box is simply an object for storing one other object in. It can be used for passing parameters by reference, for example. You simply store an object into a box, pass it to another procedure which can store a new object into it and thus return a value via the box. + +** Usage + Box objects are created with `make-box', set with `box-set!' and examined with `box-ref'. Note that these procedures are placed in a module called (box-module) and can thus only be accessed after using @@ -23,9 +34,8 @@ this module. See the following example session for usage details: Extend your LD_LIBRARY_PATH variable (or equivalent) to include . and .libs -If you like this example so much that you want to have it available -for normal usage, install the dynamic libraries in the .libs directory -to the directory $(prefix)/lib + +** Example Session $ ./guile guile> (load-extension "libbox" "scm_init_box") @@ -39,3 +49,10 @@ guile> (box-ref b) (list of values) guile> (quit) $ + + +* Module Installation + +If you like this example so much that you want to have it available +for normal usage, install the dynamic libraries in the .libs directory +to the directory $(prefix)/lib diff --git a/examples/box-module/README b/examples/box-module/README index 7f5d8521d..e1f1cd7af 100644 --- a/examples/box-module/README +++ b/examples/box-module/README @@ -1,4 +1,6 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes an example program for extending Guile with a new (and even useful) data type. @@ -9,6 +11,9 @@ interpreter in this directory will place all defined primitive procedures in a module called (box-module). That means that this module must be used before the primitives can be accessed. + +* Build Instructions + To build the example, simply type make box @@ -18,16 +23,25 @@ in this directory. The resulting `box' program is a Guile interpreter which has one additional data type called `box'. + +* The Box Data Type + A box is simply an object for storing one other object in. It can be used for passing parameters by reference, for example. You simply store an object into a box, pass it to another procedure which can store a new object into it and thus return a value via the box. + +** Usage + Box objects are created with `make-box', set with `box-set!' and examined with `box-ref'. Note that these procedures are placed in a module called (box-module) and can thus only be accessed after using this module. See the following example session for usage details: + +** Example Session + $ ./box guile> (use-modules (box-module)) guile> (define b (make-box)) diff --git a/examples/box/README b/examples/box/README index 78b7762ef..fb0ef1305 100644 --- a/examples/box/README +++ b/examples/box/README @@ -1,8 +1,13 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes an example program for extending Guile with a new (and even useful) data type. + +* Build Instructions + To build the example, simply type make box @@ -12,15 +17,24 @@ in this directory. The resulting `box' program is a Guile interpreter which has one additional data type called `box'. + +* The Box Data Type + A box is simply an object for storing one other object in. It can be used for passing parameters by reference, for example. You simply store an object into a box, pass it to another procedure which can store a new object into it and thus return a value via the box. + +** Usage + Box objects are created with `make-box', set with `box-set!' and examined with `box-ref'. See the following example session for usage details: + +** Example Session + $ ./box guile> (define b (make-box)) guile> b diff --git a/examples/modules/README b/examples/modules/README index 12df77f69..ddad881cc 100644 --- a/examples/modules/README +++ b/examples/modules/README @@ -1,4 +1,6 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes examples which show how to write and use Guile modules in Scheme programs. @@ -7,7 +9,11 @@ The descriptions below assume that you have a working copy of Guile installed and available with the standard installation prefix `/usr/local'. -main: + +* Included Examples + + +** main The main program, which uses the modules described below to perform some actions. Module usage and selective importing as well as @@ -19,7 +25,7 @@ main: guile -s main -module-0.scm, module-1.scm, module-2.scm: +** module-0.scm, module-1.scm, module-2.scm Two modules which export several procedure, some of which have the same names (so that renaming/selection is required for proper diff --git a/examples/modules/module-0.scm b/examples/modules/module-0.scm index 47e8433c7..a5a001b64 100644 --- a/examples/modules/module-0.scm +++ b/examples/modules/module-0.scm @@ -20,3 +20,5 @@ (define (bar) (display "module-0 bar") (newline)) + +;;; End of file. diff --git a/examples/modules/module-1.scm b/examples/modules/module-1.scm index d62264021..6a7bb43e0 100644 --- a/examples/modules/module-1.scm +++ b/examples/modules/module-1.scm @@ -20,3 +20,5 @@ (define (bar) (display "module-1 bar") (newline)) + +;;; End of file. diff --git a/examples/modules/module-2.scm b/examples/modules/module-2.scm index a63d5e492..3147b2cab 100644 --- a/examples/modules/module-2.scm +++ b/examples/modules/module-2.scm @@ -24,3 +24,5 @@ (define (braz) (display "module-2 braz") (newline)) + +;;; End of file. diff --git a/examples/safe/README b/examples/safe/README index be16e1e74..47abcbf9f 100644 --- a/examples/safe/README +++ b/examples/safe/README @@ -1,4 +1,6 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes examples which show how to create and use safe environments for safe (sand-boxed) execution of Scheme programs. @@ -12,7 +14,10 @@ The descriptions below assume that you have a working copy of Guile installed and available with the standard installation prefix `/usr/local'. -safe: +* Included Examples + + +** safe The main program, which executes the Scheme code in a file given on the command line in a safe environment. The following command will @@ -24,12 +29,12 @@ safe: guile -s safe untrusted.scm -untrusted.scm: +** untrusted.scm This file contains some Scheme code, which will be executed in a safe environment by the `safe' script. -evil.scm +** evil.scm This file also contains Scheme code, but it tries to do evil things. Evaluating this with the `safe' script will abort on those evil diff --git a/examples/safe/evil.scm b/examples/safe/evil.scm index 9eb64db8e..f9ee9082f 100644 --- a/examples/safe/evil.scm +++ b/examples/safe/evil.scm @@ -23,3 +23,5 @@ (let lp ((ch (read-char passwd))) (if (not (eof-object? ch)) (lp (read-char passwd)))) + +;;; End of file. diff --git a/examples/safe/untrusted.scm b/examples/safe/untrusted.scm index 9cdf1b640..f3ae5fe97 100644 --- a/examples/safe/untrusted.scm +++ b/examples/safe/untrusted.scm @@ -29,3 +29,5 @@ ((= x 11)) (display (fact x)) (newline)) + +;;; End of file. diff --git a/examples/scripts/README b/examples/scripts/README index 491007c27..f3e965b5a 100644 --- a/examples/scripts/README +++ b/examples/scripts/README @@ -1,4 +1,6 @@ - -*- text -*- + -*- outline -*- + +* Overview This directory includes examples which show how to write scripts using Guile. @@ -7,13 +9,16 @@ The descriptions below assume that you have a working copy of Guile installed and available with the standard installation prefix `/usr/local'. -simple-hello.scm: +* Included Examples + + +** simple-hello.scm The simplest "Hello World!" program for Guile. Run it like this: $ guile -s simple-hello.scm -hello: +** hello An advanced version of the script above, with command line handling for the important options --help and --version. Run it like this: @@ -24,7 +29,7 @@ hello: guile -s hello -fact: +** fact Command-line factorial calculator. Run it like this: diff --git a/examples/scripts/fact b/examples/scripts/fact index 90eecd7c2..05bcc9ffe 100755 --- a/examples/scripts/fact +++ b/examples/scripts/fact @@ -67,4 +67,3 @@ ;; Local variables: ;; mode: scheme ;; End: - diff --git a/examples/scripts/hello b/examples/scripts/hello index 4108db400..afeb64781 100755 --- a/examples/scripts/hello +++ b/examples/scripts/hello @@ -55,4 +55,3 @@ ;; Local variables: ;; mode: scheme ;; End: - diff --git a/examples/scripts/simple-hello.scm b/examples/scripts/simple-hello.scm index 713a1aee4..b46bc36ff 100644 --- a/examples/scripts/simple-hello.scm +++ b/examples/scripts/simple-hello.scm @@ -12,3 +12,5 @@ (display "Hello, World!") (newline) + +;;; End of file. -- 2.20.1