michael@0: 
michael@0: # About GCLI
michael@0: 
michael@0: ## GCLI is a Graphical Command Line Interpreter.
michael@0: 
michael@0: GCLI is a command line for modern computers. When command lines were invented,
michael@0: computers were resource-limited, disconnected systems with slow multi-tasking
michael@0: and poor displays. The design of the Unix CLI made sense in 1970, but over 40
michael@0: years on, considering the pace of change, there are many improvements we can
michael@0: make.
michael@0: 
michael@0: CLIs generally suffer from poor discoverability; It's hard when faced with a
michael@0: blank command line to work out what to do. As a result the majority of programs
michael@0: today use purely graphical user interfaces, however in doing so, they lose some
michael@0: of the benefits of CLIs. CLIs are still used because generally, in the hands of
michael@0: a skilled user they are faster, and have a wider range of available options.
michael@0: 
michael@0: GCLI attempts to get the best of the GUI world and the CLI world to produce
michael@0: something that is both easy to use and learn as well as fast and powerful.
michael@0: 
michael@0: GCLI has a type system to help ensure that users are inputting valid commands
michael@0: and to enable us to provide sensible context sensitive help. GCLI provides
michael@0: integration with JavaScript rather than being an alternative (like CoffeeScript).
michael@0: 
michael@0: 
michael@0: ## History
michael@0: 
michael@0: GCLI was born as part of the
michael@0: [Bespin](http://ajaxian.com/archives/canvas-for-a-text-editor) project and was
michael@0: [discussed at the time](http://j.mp/bespin-cli). The command line component
michael@0: survived the rename of Bepsin to Skywriter and the merger with Ace, got a name
michael@0: of it's own (Cockpit) which didn't last long before the project was named GCLI.
michael@0: It is now being used in the Firefox's web console where it doesn't have a
michael@0: separate identity but it's still called GCLI outside of Firefox. It is also
michael@0: used in [Eclipse Orion](http://www.eclipse.org/orion/).
michael@0: 
michael@0: 
michael@0: ## Environments
michael@0: 
michael@0: GCLI is designed to work in a number of environments:
michael@0: 
michael@0: 1. As a component of Firefox developer tools.
michael@0: 2. As an adjunct to Orion/Ace and other online editors.
michael@0: 3. As a plugin to any web-page wishing to provide its own set of commands.
michael@0: 4. As part of a standalone web browser extension with it's own set of commands.
michael@0: 
michael@0: 
michael@0: ## Related Pages
michael@0: 
michael@0: Other sources of GCLI documentation:
michael@0: 
michael@0: - [Writing Commands](writing-commands.md)
michael@0: - [Writing Types](writing-types.md)
michael@0: - [Developing GCLI](developing-gcli.md)
michael@0: - [Writing Tests](writing-tests.md) / [Running Tests](running-tests.md)
michael@0: - [The Design of GCLI](design.md)
michael@0: - Source
michael@0:   - The most up-to-date source is in [this Github repository](https://github.com/joewalker/gcli/).
michael@0:   - When a feature is 'done' it's merged into the [Mozilla clone](https://github.com/mozilla/gcli/).
michael@0:   - From which it flows into [Mozilla Central](https://hg.mozilla.org/mozilla-central/file/tip/browser/devtools/commandline).
michael@0: - [Demo of GCLI](http://mozilla.github.com/gcli/) with an arbitrary set of demo
michael@0:   commands
michael@0: - Other Documentation
michael@0:   - [Embedding docs](https://github.com/mozilla/gcli/blob/master/docs/index.md)
michael@0:   - [Status page](http://mozilla.github.com/devtools/2011/status.html#gcli)
michael@0: 
michael@0: 
michael@0: ## Accessibility
michael@0: 
michael@0: GCLI uses ARIA roles to guide a screen-reader as to the important sections to
michael@0: voice. We welcome [feedback on how these roles are implemented](https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Developer+Tools:+Graphic+Commandline+and+Toolbar&rep_platform=All&op_sys=All&short_desc=GCLI).
michael@0: 
michael@0: The command line uses TAB as a method of completing current input, this
michael@0: prevents use of TAB for keyboard navigation. Instead of using TAB to move to
michael@0: the next field you can use F6. In addition to F6, ALT+TAB, CTRL+TAB, META+TAB
michael@0: make an attempt to move the focus on. How well this works depends on your
michael@0: OS/browser combination.
michael@0: 
michael@0: 
michael@0: ## Embedding GCLI
michael@0: 
michael@0: There are 3 basic steps in using GCLI in your system.
michael@0: 
michael@0: 1. Import a GCLI JavaScript file.
michael@0:    For serious use of GCLI you are likely to be creating a custom build (see
michael@0:    below) however if you just want to have a quick play, you can use
michael@0:    ``gcli-uncompressed.js`` from [the gh-pages branch of GCLI]
michael@0:    (https://github.com/mozilla/gcli/tree/gh-pages)
michael@0:    Just place the following wherever you place your script files.
michael@0: 
michael@0:         <script src="path/to/gcli-uncompressed.js" type="text/javascript"></script>
michael@0: 
michael@0: 2. Having imported GCLI, we need to tell it where to display. The simplest
michael@0:    method is to include an elements with the id of ``gcli-input`` and
michael@0:    ``gcli-display``.
michael@0: 
michael@0:         <input id="gcli-input" type="text"/>
michael@0:         <div id="gcli-display"></div>
michael@0: 
michael@0: 3. Tell GCLI what commands to make available. See the sections on Writing
michael@0:    Commands, Writing Types and Writing Fields for more information.
michael@0: 
michael@0:    GCLI uses the CommonJS AMD format for it's files, so a 'require' statement
michael@0:    is needed to get started.
michael@0: 
michael@0:         require([ 'gcli/index' ], function(gcli) {
michael@0:           gcli.addCommand(...); // Register custom commands
michael@0:           gcli.createTerminal(); // Create a user interface
michael@0:         });
michael@0: 
michael@0:    The createTerminal() function takes an ``options`` objects which allows
michael@0:    customization. At the current time the documentation of these object is left
michael@0:    to the source.
michael@0: 
michael@0: 
michael@0: ## Backwards Compatibility
michael@0: 
michael@0: The goals of the GCLI project are:
michael@0: 
michael@0: - Aim for very good backwards compatibility with code required from an
michael@0:   'index' module. This means we will not break code without a cycle of
michael@0:   deprecation warnings.
michael@0: 
michael@0:   There are currently 3 'index' modules:
michael@0:   - gcli/index (all you need to get started with GCLI)
michael@0:   - demo/index (a number of demo commands)
michael@0:   - gclitest/index (GCLI test suite)
michael@0: 
michael@0:   Code from these modules uses the module pattern to prevent access to internal
michael@0:   functions, so in essence, if you can get to it from an index module, you
michael@0:   should be ok.
michael@0: 
michael@0: - We try to avoid needless change to other modules, however we don't make any
michael@0:   promises, and don't provide a deprecation cycle.
michael@0: 
michael@0:   Code from other modules uses classes rather than modules, so member variables
michael@0:   are exposed. Many classes mark private members using the `_underscorePrefix`
michael@0:   pattern. Particular care should be taken if access is needed to a private
michael@0:   member.
michael@0: 
michael@0: 
michael@0: ## Creating Custom Builds
michael@0: 
michael@0: GCLI uses [DryIce](https://github.com/mozilla/dryice) to create custom builds.
michael@0: If dryice is installed (``npm install .``) then you can create a built
michael@0: version of GCLI simply using ``node gcli.js standard``. DryIce supplies a custom
michael@0: module loader to replace RequireJS for built applications.
michael@0: 
michael@0: The build will be output to the ``built`` directory. The directory will be
michael@0: created if it doesn't exist.