TheNittyGritty.org

The Nitty Gritty

In general, define-namespace should work as you expect it to. But if you need to understand why something is or isn’t being namespaced, here’s the nitty gritty of how it happens.

Quoted Lists

Quoted lists (be it with quote or function) are namespaced only of the list is a lambda form (or a macro form). Arbitrary lists are returned untouched (they are way too arbitrary to be handled sanely). That is:

(define-namespace foo-
(defun infinite (y)
  (mapcar
   '(lambda (x) (infinite x))
   '(not a lambda (infinite x))))
)

expands to

(defun foo-infinite (y)
  (mapcar
   '(lambda (x) (foo-infinite x))
   '(not a lambda (infinite x))))

Note that  '(lambda ...) is bad practice in Emacs, you should use (lambda ...) instead (which is also namespaced just fine).

Symbols Quoted with Quote

A symbol quoted with quote (or  ' ) is never namespaced.

(define-namespace foo-
(defvar var nil)
(defvaralias 'varalias 'var)
(defun fun nil)
(defalias 'alias 'fun)
(defalias 'otheralias 'var)
)

expands to

(defvar foo-var nil)
(defvaralias 'varalias 'var)
(defun foo-fun nil)
(defalias 'alias 'fun)
;;; foo-var is not a function, so:
(defalias 'otheralias 'var)

If you provide the :assume-var-quote keyword, quoted symbols will be namespaced as variables instead.

Symbols Quoted with Function

A symbol quoted with function (or #' ) is assumed to be the name of a function, and will be namespaced as such if possible. You may provide the :dont-assume-function-quote keyword to disable this behaviour, function will then be treated like quote.

(define-namespace foo-
(defun fun (x) x)
(mapcar 'fun somelist)
(mapcar #'fun somelist)
)

expands to

(defun foo-fun (x) x)
(mapcar 'fun somelist)
(mapcar #'foo-fun somelist)

Backticks (quasi-quotes)

Backticks (or `) are handled as you would expect. Lists or simbles quoted with a backtick are treated the same as those quoted with regular quotes (see above), except anything prefixed by a comma (which is effectively not quoted) is namespaced as usual.

Local Variables Take Precedence

Local variables take precedence over namespace variables. For instance

(define-namespace foo-
(defvar bar "2")

(defun funca (bar)
  (string-to-int bar))
)

expands to

(defvar foo-bar "2")

(defun funca (bar)
  (string-to-int bar))

Note how the last bar isn’t namespaced. That’s because it is local to the funca function, and takes precedence over the global foo-bar. The argument list of functions, macros, and lambdas are all local definitions.

By default, this does not happen with let bindings, they are namespaced as usual (if the variable name in question has a global definition). The reason is that let bindings are commonly used to temporarily override global bindings.

You can customize this behaviour with the :no-let-vars keyword. Then:

(define-namespace foo- :no-let-vars
(defvar bar "2")

(let ((bar "1"))
  (string-to-int bar))
)

will expand to

(defvar foo-bar "2")

(let ((bar "1"))
  (string-to-int bar))

Macros

Macros are handled in a very intelligent manner.

Names needs to know which parts of a macro’s arguments are evaluatable forms, and which are just arbitrary symbols. This presents a challenge because macro arguments could be absolutely anything. Fortunately, (good) macros already provide that information in their debug declaration.

Thus, Names uses the macro’s edebug-spec-list to find out which arguments are evaluatable forms, and namespaces only those. Other arguments are left untouched. Usually, this is not something you’ll need to worry about, it should just do what you expect from it.

This is only relevant if you write your own macros. If you do, remember to add a debug declaration in them.

The theading macros (-> and -->)

The threading macros would require special treatment to namespace correctly. However, you can use the :functionlike-macros keyword to tell Names to treat them as regular functions.

For example, in the following snippet:

(require 'dash)
(define-namespace foo-
:functionlike-macros (-> ->>)

(defvar var nil)
(defun fun (x &optional y)
  (concat x y))

(-> "some string"
    (fun var)
    fun)
)

the (fun var) part would be namespaced prefectly fine (fun and var will be identified as a function and variable respectively), because it looks like a regular function call. However, the second use of fun will not be correctly namespaced, because that fun looks like a variable.

In other words, you should use these macros like this instead:

(-> "some string"
    (fun var)
    (fun))

Accessing Global Symbols

If one of your definitions shadows a global definition, you can still access it by prefixing it with ::.

(define-namespace foo-
(defun message ()  
  (message)
  (::message "Hi"))
)

expands to

(defun foo-message ()  
  (foo-message)
  (message "Hi"))

When in doubt feel free to use ::, it will always get removed (as long as it’s not inside a quote). You may also change this prefix to something else with the :prefix keyword.