199 lines
10 KiB
Plaintext
199 lines
10 KiB
Plaintext
FUEL, Factor's Ultimate Emacs Library
|
|
-------------------------------------
|
|
|
|
FUEL provides a complete environment for your Factor coding pleasure
|
|
inside Emacs, including source code edition and interaction with a
|
|
Factor listener instance running within Emacs.
|
|
|
|
FUEL was started by Jose A Ortega as an extension to Eduardo Cavazos'
|
|
original factor.el code. Eduardo is also responsible of naming the
|
|
beast.
|
|
|
|
* Installation
|
|
|
|
FUEL comes bundled with Factor's distribution. The folder misc/fuel
|
|
contains Elisp code, and there's a fuel vocabulary in extras/fuel.
|
|
|
|
To install FUEL, either add this line to your Emacs initialisation:
|
|
|
|
(load-file "<path/to/factor/installation>/misc/fuel/fu.el")
|
|
|
|
If all you want is a major mode for editing Factor code with pretty
|
|
font colors and indentation, without running the factor listener
|
|
inside Emacs, you can use instead:
|
|
|
|
(add-to-list 'load-path "<path/to/factor/installation>/fuel")
|
|
(setq factor-mode-use-fuel nil)
|
|
(require 'factor-mode)
|
|
|
|
* Basic usage
|
|
*** Running the listener
|
|
|
|
If you're using the default factor binary and images locations inside
|
|
the Factor's source tree, that should be enough to start using FUEL.
|
|
Editing any file with the extension .factor will put you in
|
|
factor-mode; try C-hm for a summary of available commands.
|
|
|
|
To start the listener, try M-x run-factor.
|
|
|
|
By default, FUEL will try to use the binary and image files in the
|
|
factor installation directory. You can customize them with:
|
|
|
|
(setq fuel-listener-factor-binary <full path to factor>)
|
|
(setq fuel-listener-factor-image <full path to factor image>)
|
|
|
|
Many aspects of the environment can be customized:
|
|
M-x customize-group fuel will show you how many.
|
|
|
|
*** Faster listener startup
|
|
|
|
On startup, run-factor loads the fuel vocabulary, which can take a
|
|
while. If you want to speedup the load process, type 'save' in the
|
|
listener prompt just after invoking run-factor. This will save a
|
|
factor image (overwriting the current one) with all the needed
|
|
vocabs.
|
|
|
|
Alternatively, you can add the following line to your
|
|
.factor-boot-rc file:
|
|
|
|
"fuel" require
|
|
|
|
This will ensure that the image generated while bootstrapping
|
|
Factor contains fuel and the vocabularies it depends on.
|
|
|
|
*** Connecting to a running Factor
|
|
|
|
'run-factor' starts a new factor listener process managed by Emacs.
|
|
If you prefer to start Factor externally, you can also connect
|
|
remotely from Emacs. Here's how to proceed:
|
|
|
|
- In the factor listener, run FUEL: "fuel" run
|
|
This will start a server listener in port 9000.
|
|
- Switch to Emacs and issue the command 'M-x connect-to-factor'.
|
|
|
|
That's it; you should be up and running. See the help for
|
|
'connect-to-factor' for how to use a different port.
|
|
|
|
*** Vocabulary creation
|
|
|
|
FUEL offers a basic interface to Factor's scaffolding utilities.
|
|
To create a new vocabulary directory and associated files:
|
|
|
|
M-x fuel-scaffold-vocab
|
|
|
|
and when in a vocab file, to create a docs file with boilerplate
|
|
for each word:
|
|
|
|
M-x fuel-scaffold-help
|
|
|
|
* Quick key reference
|
|
|
|
Triple chords ending in a single letter <x> accept also C-<x> (e.g.
|
|
C-cC-eC-r is the same as C-cC-er).
|
|
|
|
*** In factor source files:
|
|
|
|
Commands in parenthesis can be invoked interactively with
|
|
M-x <command>, not necessarily in a factor buffer.
|
|
|
|
|-----------------+------------------------------------------------------------|
|
|
| C-cz | switch to listener (run-factor) |
|
|
| C-co | cycle between code, tests and docs files |
|
|
| C-cr | switch to listener and refresh all loaded vocabs |
|
|
| C-cs | switch to other factor buffer (fuel-switch-to-buffer) |
|
|
| C-x4s | switch to other factor buffer in other window |
|
|
| C-x5s | switch to other factor buffer in other frame |
|
|
|-----------------+------------------------------------------------------------|
|
|
| M-. | edit word at point in Emacs (fuel-edit-word) |
|
|
| M-, | go back to where M-. was last invoked |
|
|
| M-TAB | complete word at point |
|
|
| C-cC-eu | update USING: line (fuel-update-usings) |
|
|
| C-cC-ev | edit vocabulary (fuel-edit-vocabulary) |
|
|
| C-cC-ew | edit word (fuel-edit-word-at-point) |
|
|
| C-cC-ed | edit word's doc (C-u M-x fuel-edit-word-doc-at-point) |
|
|
| C-cC-el | load vocabs in USING: form |
|
|
|-----------------+------------------------------------------------------------|
|
|
| C-cC-er | eval region |
|
|
| C-M-r, C-cC-ee | eval region, extending it to definition boundaries |
|
|
| C-M-x, C-cC-ex | eval definition around point |
|
|
| C-ck, C-cC-ek | run file (fuel-run-file) |
|
|
|-----------------+------------------------------------------------------------|
|
|
| C-cC-da | toggle autodoc mode (fuel-autodoc-mode) |
|
|
| C-cC-dd | help for word at point (fuel-help) |
|
|
| C-cC-ds | short help word at point (fuel-help-short) |
|
|
| C-cC-de | show stack effect of current sexp (with prefix, region) |
|
|
| C-cC-dp | find words containing given substring (fuel-apropos) |
|
|
| C-cC-dv | show words in current file (with prefix, ask for vocab) |
|
|
|-----------------+------------------------------------------------------------|
|
|
| C-cM-<, C-cC-d< | show callers of word or vocabulary at point |
|
|
| | (fuel-show-callers, fuel-vocab-usage) |
|
|
| C-cM->, C-cC-d> | show callees of word or vocabulary at point |
|
|
| | (fuel-show-callees, fuel-vocab-uses) |
|
|
|-----------------+------------------------------------------------------------|
|
|
| C-cC-xs | extract innermost sexp (up to point) as a separate word |
|
|
| | (fuel-refactor-extract-sexp) |
|
|
| C-cC-xr | extract region as a separate word |
|
|
| | (fuel-refactor-extract-region) |
|
|
| C-cC-xv | extract region as a separate vocabulary |
|
|
| | (fuel-refactor-extract-vocab) |
|
|
| C-cC-xi | replace word by its definition (fuel-refactor-inline-word) |
|
|
| C-cC-xw | rename all uses of a word (fuel-refactor-rename-word) |
|
|
| C-cC-xa | extract region as a separate ARTICLE: form |
|
|
| C-cC-xg | convert current word definition into GENERIC + method |
|
|
| | (fuel-refactor-make-generic) |
|
|
|-----------------+------------------------------------------------------------|
|
|
|
|
*** In the listener:
|
|
|
|
|------+----------------------------------------------------------|
|
|
| TAB | complete word at point |
|
|
| M-. | edit word at point in Emacs |
|
|
| C-cr | refresh all loaded vocabs |
|
|
| C-ca | toggle autodoc mode |
|
|
| C-cp | find words containing given substring (M-x fuel-apropos) |
|
|
| C-cs | toggle stack mode |
|
|
| C-cv | edit vocabulary |
|
|
| C-ch | help for word at point |
|
|
| C-ck | run file |
|
|
|------+----------------------------------------------------------|
|
|
|
|
*** In the debugger (it pops up upon eval/compilation errors):
|
|
|
|
|---------+-------------------------------------|
|
|
| g | go to error |
|
|
| <digit> | invoke nth restart |
|
|
| w/e/l | invoke :warnings, :errors, :linkage |
|
|
| q | bury buffer |
|
|
|---------+-------------------------------------|
|
|
|
|
*** In the help browser:
|
|
|
|
|-----------+----------------------------------------------------------|
|
|
| h | help for word at point |
|
|
| v | help for a vocabulary |
|
|
| a | find words containing given substring (M-x fuel-apropos) |
|
|
| e | edit current article |
|
|
| ba | bookmark current page |
|
|
| bb | display bookmarks |
|
|
| bd | delete bookmark at point |
|
|
| n/p | next/previous page |
|
|
| l | previous page |
|
|
| SPC/S-SPC | scroll up/down |
|
|
| TAB/S-TAB | next/previous link |
|
|
| k | kill current page and go to previous or next |
|
|
| r | refresh page |
|
|
| c | clean browsing history |
|
|
| M-. | edit word at point in Emacs |
|
|
| C-cz | switch to listener |
|
|
| q | bury buffer |
|
|
|-----------+----------------------------------------------------------|
|
|
|
|
*** In crossref buffers
|
|
|
|
|-----------------+-----------------------------|
|
|
| TAB/BACKTAB | navigate links |
|
|
| RET/mouse click | follow link |
|
|
| h | show help for word at point |
|
|
| q | bury buffer |
|
|
|-----------------+-----------------------------|
|