Namespaces

From Gambit wiki

(Difference between revisions)
Jump to: navigation, search
m (Another small edit)
(Formatted more keywords as code. Fixed wiki link formatting. Moved and slightly rewrote a paragraph.)
 
(4 intermediate revisions not shown)
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 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? ===
-
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.
+
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. Both uses of the special form only affect unqualified identifiers.
==== 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 (<code>#\#</code> 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 which Gambit uses for most of its 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, and is also where Gambit puts the many non-internal identifiers described in the manual.
 +
 
 +
The qualifier syntax handles "##" like any other namespace. Similarly to the example above:
 +
 
 +
  ##include
 +
 
 +
is the <code>include</code> identifier in the "##" namespace.
 +
 
 +
But there is no qualifier syntax for the "" namespace, so there is no way to refer to identifiers in the "" namespace from outside it. (A single # at the beginning of a token might work, except that it's already used for many other purposes by the Scheme standards.)  If Gambit puts a name in the "" namespace, it often puts the same name in the "##" namespace. But when the names refer to functions, the two functions do not necessarily behave the same way; see [[#Usage|Usage]] for the details.
==== Declaring an identifier as belonging to a particular namespace ====
==== Declaring an identifier as belonging to a particular namespace ====
Line 31: Line 39:
  (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.
+
==== 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 active namespace 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. See the note above about <code>##namespace</code>.
==== Scope of namespace declarations ====
==== Scope of namespace declarations ====
-
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 <code>lambda</code> or <code>let</code> 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 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 changed. This then remains active until the next namespace declaration is entered or <code>eval</code>ed.
-
==== Switching default namespace in the repl ====
+
==== Accessing the <code>namespace</code> identifier ====
-
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.
+
Note that the identifier <code>namespace</code> is part of the empty namespace. Because of the exception to the qualifier syntax described [[#Full qualification|above]], if you change the default namespace, then you have to use <code>##namespace</code> instead. <code>##namespace</code> and <code>namespace</code> behave the same.  
=== Usage ===
=== Usage ===
Line 55: Line 65:
==== 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 feature 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 is even 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 78: Line 88:
  value at position 3:world
  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.)
+
(Note that if you accessed 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).

Latest revision as of 08:56, 16 March 2008

Contents

Namespaces

Introduction

Gambit implements a namespace mechanism, which is 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. Both uses of the special form only affect unqualified identifiers.

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 which Gambit uses for most of its 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, and is also where Gambit puts the many non-internal identifiers described in the manual.

The qualifier syntax handles "##" like any other namespace. Similarly to the example above:

 ##include

is the include identifier in the "##" namespace.

But there is no qualifier syntax for the "" namespace, so there is no way to refer to identifiers in the "" namespace from outside it. (A single # at the beginning of a token might work, except that it's already used for many other purposes by the Scheme standards.) If Gambit puts a name in the "" namespace, it often puts the same name in the "##" namespace. But when the names refer to functions, the two functions do not necessarily behave the same way; see Usage for the details.

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.

Switching the default namespace in code

Identifiers which do not contain a # character are treated as belonging to the active namespace 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. See the note above about ##namespace.

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 changed. This then remains active until the next namespace declaration is entered or evaled.

Accessing the namespace identifier

Note that the identifier namespace is part of the empty namespace. Because of the exception to the qualifier syntax described above, if you change the default namespace, then you have to use ##namespace instead. ##namespace and namespace behave the same.

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 feature 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 is even 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 accessed 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