This document describes the module system that was introduced with version 0.9.2.

= glossary =

 application (or global) scope::
 :: This refers to the scope of the singleton `conkeror` object, defined in `components/application.js`.

 feature::
 :: A symbol (given as a string) added to the `features` list by a module, which other modules can use to tell if that module has been loaded.  Features should be lower case, using only hyphens for punctuation.  A module which provides a given feature should have that feature name as its file name, plus a `.js` extension.

= load =

The default behavior of `load` is to try to load the module directly into application scope.

= require =

Require is simply a conditional load.  Require parses passed module spec (filename) and guesses what feature that file provides.  If that feature has already been provided, it returns without loading.  The default behavior of `require` is to try to load the module in its own namespace.


= Optional Modules =

{{{#!wiki caution
to-do: rewrite this bit as a concise description of Optional Modules
}}}

Conkeror has a number of core module that are required for Conkeror to run and which are always loaded at startup.  In addition, though, there are a growing number of optional modules that provide additional functionality.  Such modules include
 * `bindings/default/bindings.js` - provides the default key bindings;
 * `tab-bar.js` - provides a Firefox-style tab bar;
 * `clicks-in-new-buffer.js` - load middle-clicked links in new buffers. See [[Tips]] for more information.
 * `mode-line.js` - provides an Emacs-style mode line;
 * `daemon.js` - provides support for pre-loading Conkeror without opening any Windows and allowing it to remain running even after all open windows have closed;
 * `extensions/dom-inspector.js` - provides a Conkeror-specific interface to the DOM inspector [[Extensions|extension]];
 * various [[PageModes|page modes]], analogous to Emacs major modes, that provide certain Greasemonkey-like functionality for individual sites including Youtube, Google Video, Google Reader, Google Mail, Google search results pages, and Reddit.

Certain [[MozillaPreferences|Mozilla preferences]] are used to specify which, if any, of these optional modules are loaded at startup.  Specifically, whether a particular module `<module-name>.js` (where `<modules-name>` might be `extensions/dom-inspector` as an example) is loaded automatically at startup (note that you can also load modules explicitly in your [[ConkerorRC]] file, and that is unrelated to these preferences) is controlled by the three preferences
 * `conkeror.loadDefaultModules` - "tristate" integer, defaulting to 1 (it is "tristate" in that it has only three distinct meanings, dependent on whether it is positive, zero, or negative);
 * `conkeror.loadModules` - string specifying a regular expression to match against `<module-name>` (i.e. it should not attempt to match a `.js` extension), defaulting to the empty string, which doesn't match anything;
 * `conkeror.load.<module-name>` - "tristate" integer, which may default to either 1 or 0, or alternatively may be unset, but most if not all optional modules have a default setting for this preference; whether this preference has a ''user-set'' value as opposed to just its default value is significant.
The module is loaded according to the following rules:
 * The module is never loaded unless `conkeror.load.<module-name>` has a non-negative value.  In particular, if this preference has no value set, then the module is not loaded.
 * If `conkeror.loadDefaultModules` is positive and `conkeror.load.<module-name>` has a positive value, then the module is loaded.
 * If `conkeror.loadDefaultModules` is zero and `conkeror.load.<module-name>` has a positive ''user-set'' value (i.e. not merely a default value that is positive), then the module is also loaded.
 * Regardless of the setting of `conkeror.loadDefaultModules`, if the regular expression `conkeror.loadModules` matches `<module-name>` completely (i.e. a partial match is not sufficient), then the module is still loaded.
 * Otherwise, the module is not loaded.

Modules that meet these condiions are loaded in an arbitrary order consistent with their dependencies (where the dependencies are given by any calls to the `require` function in the module itself).

Note that the `conkeror.loadModules` preference only has an effect if `conkeror.loadDefaultModules` is non-positive.  It can be useful for concisely specifying that only certain classes of modules are desired by default.  For example, if it is set to `"(bindings/default|extensions|page-modes)/.*"`, exactly the set of modules in the directories `bindings/default/` (the default key bindings), `extensions/` (extension support modules), and `page-modes/` that have a `conkeror.load.<module-name>` preference set to a non-negative value (all modules by default) will be loaded automatically at startup.