Namespaces

From Gambit wiki

(Difference between revisions)
Jump to: navigation, search
m (Another small edit)
m (Corrected spelling and some grammar.)
Line 3: Line 3:
=== Introduction ===
=== Introduction ===
-
Gambit is implementing a namespace mechanism, which is being used to separate internals from user code and also to partition the Gambit internals into several parts (e.g. the compiler parts are using a different namespace than the interpreter parts).
+
Gambit implements a namespace mechanism, which is being used to separate internals from user code and also to partition the Gambit internals into several parts (e.g. the compiler parts use a different namespace than the interpreter parts).
-
The namespace mechanism is not described in the official documentation, but it is being used and hence shown in the examples bundled with the Gambit source code. Marc maybe didn't officially document it since he didn't want to sanction it as official mechanism that he would need to support into the indefinite future, and he maybe originally just wrote it for his own purposes (those is just speculations). In the mean time, as there is now an "official" module system in the form of SNOW!, users can also be encouraged to make use of the latter instead of using the namespace mechanism directly (the writer of these lines also intends to continue to work on his "chjmodule" module system to further explore dynamic programming and other concepts like parametrization).
+
The namespace mechanism is not described in the official documentation, but it is revealed by the examples bundled with the Gambit source code. Marc maybe didn't officially document it since he didn't want to sanction it as official mechanism that he would need to support into the indefinite future, and he maybe originally just wrote it for his own purposes (those are just speculations). In the meantime, as there is now an "official" module system in the form of SNOW!, users should make use of the latter instead of using the namespace mechanism directly (the writer of these lines also intends to continue to work on his "chjmodule" module system to further explore dynamic programming and other concepts like parametrization).
=== How does it work? ===
=== How does it work? ===
Line 13: Line 13:
==== Full qualification ====
==== Full qualification ====
-
Gambit is treating the # character (#\# in Scheme syntax) in identifier symbols as a special character separating the namespace from the local name. Example:
+
Gambit treats the # character (#\# in Scheme syntax) in identifier symbols as a special character separating the namespace from the local name. Example:
  foo#bar
  foo#bar
-
is the <code>bar</code> identifier in the "foo#" namespace (I include the # separater character here since that's also how the namespace form works and because that allows to specify the empty namespace).
+
is the <code>bar</code> identifier in the "foo#" namespace (I include the # separator character here since that's also how the namespace form works and because that allows to specify the empty namespace).
-
There are two special namespaces, one is the "#" namespace being used for most basic internals, and the "" (empty) namespace being the default namespace for user code when the Gambit interpreter or compiler is being started.
+
There are two special namespaces.  One is the "#" namespace being used for most basic internals, and the other is the "" (empty) namespace.  The empty namespace is the default namespace for user code when the Gambit interpreter or compiler is started.
==== Declaring an identifier as belonging to a particular namespace ====
==== Declaring an identifier as belonging to a particular namespace ====
Line 31: Line 31:
  (namespace ("foo#" bar))
  (namespace ("foo#" bar))
-
says that whenever <code>bar</code> is being mentioned in the code that follows in the same scope or file, it is implicitely being treated as <code>foo#bar</code>.
+
says that whenever <code>bar</code> is mentioned in the code that follows in the same scope or file, it is to be implicitly treated as <code>foo#bar</code>.
Note that the identifier <code>namespace</code> is part of the empty namespace. If you change the default namespace (see below), you have to use <code>##namespace</code> instead.
Note that the identifier <code>namespace</code> is part of the empty namespace. If you change the default namespace (see below), you have to use <code>##namespace</code> instead.
Line 37: Line 37:
==== Switching the default namespace in code ====
==== Switching the default namespace in code ====
-
Identifiers which are not containing a # character are being treated as belonging to the namespace being active in the current scope (see below for what the scope is). This is the empty namespace by default. This can be changed by putting
+
Identifiers which do not contain a # character are treated as belonging to the namespace being active in the current scope (see below for what the scope is). This is the empty namespace by default. This can be changed by putting
  (namespace (STRING))
  (namespace (STRING))
-
before the rest of the code; e.g. using a namespace declaration without a list of identifiers. Note that once you've changed the default namespace, you cannot refer to <code>namespace</code> anymore, since this identifier is only being defined in the empty namespace and there is no way to fully qualify identifiers as belonging to the empty namespace, so you have to use the <code>##namespace</code> identifier instead (meaning the full qualification for the "#" internals namespace) which acts the same.
+
before the rest of the code; e.g. using a namespace declaration without a list of identifiers. Note that once you've changed the default namespace, you cannot refer to <code>namespace</code> anymore, since this identifier is only defined in the empty namespace and there is no way to fully qualify identifiers as belonging to the empty namespace, so you have to use the <code>##namespace</code> identifier instead (meaning the full qualification for the "#" internals namespace) which acts the same.
==== Scope of namespace declarations ====
==== Scope of namespace declarations ====
Line 47: Line 47:
A namespace declaration is in effect until the end of the current lambda or let construct (note that <code>begin</code> doesn't open a new scope), or, if specified at the top level of the file (or just inside a <code>begin</code> form residing in the top level) until the end of that file.
A namespace declaration is in effect until the end of the current lambda or let construct (note that <code>begin</code> doesn't open a new scope), or, if specified at the top level of the file (or just inside a <code>begin</code> form residing in the top level) until the end of that file.
-
==== Switching default namespace in the repl ====
+
==== Switching the default namespace in the repl ====
-
If entered in the repl, or run by the <code>eval</code> procedure, the default namespace used by the repl (which is also the empty namespace by default) is being changed. This then remains active until the next namespace declaration is being entered or eval'ed.
+
If entered in the repl, or run by the <code>eval</code> procedure, the default namespace used by the repl (which is also the empty namespace by default) is being changed. This then remains active until the next namespace declaration is entered or eval'ed.
=== Usage ===
=== Usage ===
Line 55: Line 55:
==== Modularization ====  
==== Modularization ====  
-
The namespace mechanism can be used to partition user code in a style similar to how C works, by writing a "header" file for a library which declares all the exported values to be in the namespace that has been choosen for that library. In the Gambit source code and the examples, Marc is employing the convention of adding the # character to the name of the module (e.g. if he writes a module "foo.scm" he will name the header file "foo#.scm").
+
The namespace mechanism can be used to partition user code in a style similar to how C works, by writing a "header" file for a library which declares all the exported values to be in the namespace that has been chosen for that library. In the Gambit source code and the examples, Marc uses the convention of adding the # character to the name of the module (e.g. if he writes a module "foo.scm" he will name the header file "foo#.scm").
==== Access to Gambit internals ====
==== Access to Gambit internals ====
-
Since the namespace handling doesn't prohibit access (it's just for the sake of convenience, not for protection), Gambit is somewhat special in that all of its internal procedures can be accessed by the user; this is very useful to learn how the internals work and also to extend the system without hacking the Gambit source code. It must be noted though, that most of those procedures are not checking their types, so you will quickly get a segfault when feeding them data of the wrong type. Sometimes this missing type check is also (mis)usable (or even being used explicitely by other Gambit internal procedures) to access data structures on a lower level:
+
Since the namespace handling doesn't prohibit access (it's just for the sake of convenience, not for protection), Gambit is somewhat special in that all of its internal procedures can be accessed by the user; this is very useful to learn how the internals work and also to extend the system without hacking the Gambit source code. It must be noted though, that most of those procedures do not check their types, so you will quickly get a segfault when feeding them data of the wrong type. Sometimes this missing type check is also (mis)usable (or even being used explicitly by other Gambit internal procedures) to access data structures on a lower level:
  (define-structure foo a b c)
  (define-structure foo a b c)
Line 80: Line 80:
(Note that if you access elements behind the given length, you would access unrelated memory contents or invalid memory addresses.)
(Note that if you access elements behind the given length, you would access unrelated memory contents or invalid memory addresses.)
-
==== Producing lowlevel unsafe code explicitely ====
+
==== Producing low-level unsafe code explicitly ====
-
It's also worthwhile knowing that the basic primitives (like memory accesses, lowlevel arithmetic, etc.) which are mapped by the compiler directly to C constructs (actually C macros as defined in the include/gambit.h file) are a bunch of such identifiers in the # namespace. Like <code>(##car obj)</code> will be translated to <code>___CAR(obj)</code> which is then expanded by the C compiler to basically a pointer dereference. So those can be used in user code to let the compiler output those lowlevel constructs, which are not doing any type checking (and are simple enough for the C compiler to enable optimizations on the C level) and thus very fast, without declaring your whole Scheme code as being unsafe by using the <code>declare</code> special form (which would achieve the same thing).
+
It's also worthwhile knowing that the basic primitives (like memory accesses, low-level arithmetic, etc.) which are mapped by the compiler directly to C constructs (actually C macros as defined in the include/gambit.h file) are a bunch of such identifiers in the # namespace. Like <code>(##car obj)</code> will be translated to <code>___CAR(obj)</code> which is then expanded by the C compiler to basically a pointer dereference. So those can be used in user code to let the compiler output those low-level constructs, which do not do any type checking (and are simple enough for the C compiler to enable optimizations on the C level) and thus very fast, without declaring your whole Scheme code as being unsafe by using the <code>declare</code> special form (which would achieve the same thing).

Revision as of 03:11, 12 March 2008

Contents

Namespaces

Introduction

Gambit implements a namespace mechanism, which is being used to separate internals from user code and also to partition the Gambit internals into several parts (e.g. the compiler parts use a different namespace than the interpreter parts).

The namespace mechanism is not described in the official documentation, but it is revealed by the examples bundled with the Gambit source code. Marc maybe didn't officially document it since he didn't want to sanction it as official mechanism that he would need to support into the indefinite future, and he maybe originally just wrote it for his own purposes (those are just speculations). In the meantime, as there is now an "official" module system in the form of SNOW!, users should make use of the latter instead of using the namespace mechanism directly (the writer of these lines also intends to continue to work on his "chjmodule" module system to further explore dynamic programming and other concepts like parametrization).

How does it work?

There is a special rule for fully qualifying an identifier, and there is a special form which can be used to (a) declare the currently active default namespace, and (b) to declare a list of given identifiers to be in a particular namespace.

Full qualification

Gambit treats the # character (#\# in Scheme syntax) in identifier symbols as a special character separating the namespace from the local name. Example:

foo#bar

is the bar identifier in the "foo#" namespace (I include the # separator character here since that's also how the namespace form works and because that allows to specify the empty namespace).

There are two special namespaces. One is the "#" namespace being used for most basic internals, and the other is the "" (empty) namespace. The empty namespace is the default namespace for user code when the Gambit interpreter or compiler is started.

Declaring an identifier as belonging to a particular namespace

The

(namespace (STRING SYMBOL...))

special form specifies that the list of the given identifiers (symbols) are to be treated as belonging to the namespace given in STRING. Example:

(namespace ("foo#" bar))

says that whenever bar is mentioned in the code that follows in the same scope or file, it is to be implicitly treated as foo#bar.

Note that the identifier namespace is part of the empty namespace. If you change the default namespace (see below), you have to use ##namespace instead.

Switching the default namespace in code

Identifiers which do not contain a # character are treated as belonging to the namespace being active in the current scope (see below for what the scope is). This is the empty namespace by default. This can be changed by putting

(namespace (STRING))

before the rest of the code; e.g. using a namespace declaration without a list of identifiers. Note that once you've changed the default namespace, you cannot refer to namespace anymore, since this identifier is only defined in the empty namespace and there is no way to fully qualify identifiers as belonging to the empty namespace, so you have to use the ##namespace identifier instead (meaning the full qualification for the "#" internals namespace) which acts the same.

Scope of namespace declarations

A namespace declaration is in effect until the end of the current lambda or let construct (note that begin doesn't open a new scope), or, if specified at the top level of the file (or just inside a begin form residing in the top level) until the end of that file.

Switching the default namespace in the repl

If entered in the repl, or run by the eval procedure, the default namespace used by the repl (which is also the empty namespace by default) is being changed. This then remains active until the next namespace declaration is entered or eval'ed.

Usage

Modularization

The namespace mechanism can be used to partition user code in a style similar to how C works, by writing a "header" file for a library which declares all the exported values to be in the namespace that has been chosen for that library. In the Gambit source code and the examples, Marc uses the convention of adding the # character to the name of the module (e.g. if he writes a module "foo.scm" he will name the header file "foo#.scm").

Access to Gambit internals

Since the namespace handling doesn't prohibit access (it's just for the sake of convenience, not for protection), Gambit is somewhat special in that all of its internal procedures can be accessed by the user; this is very useful to learn how the internals work and also to extend the system without hacking the Gambit source code. It must be noted though, that most of those procedures do not check their types, so you will quickly get a segfault when feeding them data of the wrong type. Sometimes this missing type check is also (mis)usable (or even being used explicitly by other Gambit internal procedures) to access data structures on a lower level:

(define-structure foo a b c)
(let ((v (make-foo 123 "hello" 'world)))
  ;; (mis)treat the structure as vector:
  (let ((len (##vector-length v)))
    (let lp ((i 0))
      (if (< i len)
        (begin
          (println "value at position " i ":" (##vector-ref v i))
          (lp (+ i 1)))))))

This prints

value at position 0:#<type #2 foo>
value at position 1:123
value at position 2:hello
value at position 3:world

(Note that if you access elements behind the given length, you would access unrelated memory contents or invalid memory addresses.)

Producing low-level unsafe code explicitly

It's also worthwhile knowing that the basic primitives (like memory accesses, low-level arithmetic, etc.) which are mapped by the compiler directly to C constructs (actually C macros as defined in the include/gambit.h file) are a bunch of such identifiers in the # namespace. Like (##car obj) will be translated to ___CAR(obj) which is then expanded by the C compiler to basically a pointer dereference. So those can be used in user code to let the compiler output those low-level constructs, which do not do any type checking (and are simple enough for the C compiler to enable optimizations on the C level) and thus very fast, without declaring your whole Scheme code as being unsafe by using the declare special form (which would achieve the same thing).

Personal tools
documentation