Package com.raelity.jvi

This is the main package of the jVi editor; it contains the primary editing engine.


Interface Summary
ColonCommandFlags Flags used to direct ":" command parsing.
KeyDefs The vim code uses character constants and key constants.
ViCmdEntry This is used by vi to get command line input.
ViCursor Salient variables for doing a vi cursor.
ViFactory This provides Vi the items it needs to interface with swing UI environment.
ViFPOS A position in a file/document.
ViFS jVi's interactions with files are funnelled through this interface.
ViMark A Mark represents a position within a document.
ViOptionBag Interface for classes that have vim options, i.e.
ViOutputStream When jVi wants to output multi-line information, for example lines matching a search or result of some command execution, the output is sent to a ViOutputStream.
ViStatusDisplay Display state of the editor is sent through this interface.
ViTextView The information needed by vim when running on a GUI.
ViXlateKey Actions that are put into vi xlation maps implement this

Class Summary
AbbrevLookup This is a lookup table where the key can be abbreviated.
AbbrevLookup.CommandElement A registered command is represented by this class.
Buffer Buffer: structure that holds information about one file, primarily per file options.
ColonCommands This class handles registration, command input, parsing, dispatching and in some instances execution of ":" commands.
ColonCommands.ColonAction Commands that take arguments subclass this.
ColonCommands.ColonEvent The event passed to ColonCommands.ColonAction.
FPOS File position, accessable as line number, 1 based, and column, 0 based.
Normal Contains the main routine for processing characters in command mode.
OPARG Arguments for operators.
Options Option handling from external sources.
Options.SetCommand Implement ":se[t]".
OptionsBean Simple class so there is some way to change vi options in the IDE.
OptionsBeanBase Base class for jVi options beans.
OutputStreamAdaptor Use this class instead of the interface, to make it easier to augment the interface in a compatible way.
Search Searching, regexp and substitution.
ViManager This class coordinates things.
ViManager.jViVersion version is of the form #.#.# or #.#.#.[x|alpha|beta|rc]#, examples 0.9.1, 0.9.1.beta1 also, 0.9.1.beta1.3 for tweaking between exposed releases
Window Vim references values in a structure, but we need to present a method interface, so the vim code is not preserved as we'd like.

Enum Summary
ViTextView.JLOP jump list operations
ViTextView.MARKOP annonymous mark operations
ViTextView.NLOP open new line forward/backward
ViTextView.TABOP move to other tab
ViTextView.TAGOP tags and tagstack operations
ViTextView.WMOP word match opertations

Exception Summary

Package com.raelity.jvi Description

This is the main package of the jVi editor; it contains the primary editing engine.

If you want to work on the source in this package, you should pick up a copy of the vim source, v5.4, from the vim website. This applies especially to Normal, Edit, ColonCommands and Misc. The class file Misc contains functions from several vim C files, including misc1.c, misc2.c, ops.c, ui.c, screen.c, undo.c, charset.c, ex_getln.c, term.c and window.c. Finally there is the class file Util which contains random stuff. It should probably be put into Misc.

Embedding and Porting Notes

jVi is embedded in an application by implementing several interfaces through which the vi editing engine works on its environment. These are tasks such as adding and deleting text, view manipulation and file IO. The main editor accesses these various interfaces through ViFactory. A ViFactory is implemented that creates concrete instantiations of the various interfaces. Access to the factory and other capabilities is co-ordinated throug the ViManager class. Take a look at org.jbopentools.editor.jbvi and com.raelity.jvi.cmd for examples of jvi embedded in an application.

A key interface for embedding jVi is ViTextView. This interface is used to access the display and text. There is a default implementation, TextView, for swing that works with a JEditorPane and Document. If jVi is being embedded in a swing application you can probably subclass this implementation as a starting point. There are methods in this interface, win_*, which provide for the manipulation of edit views (windows); they probably should be in a separate class.

File handling is provided through the ViFS interface. Status and other messages are output through the ViStatusDisplay, interface.

There are two ways in which jVi captures keystrokes, through normal mode and through line entry. Line entry is for specifying colon commands and search patterns. There is an interface, ViCmdEntry, through which command mode entry is done. There are two implementations of higher level gui objects which have ViCmdEntry as part of them, WindowCmdEntry and com.raelity.jvi.swing.DefaultCmdEntry. Only WindowCmdEntry should be used for now because it is modal.

Colon Commands

It is pretty simple to add new colon commands. The handler for a colon command is an Action. Colon command handling is in the class ColonCommands. If a colon command takes no arguments, then you can register a ActionListener to handle the command. If the command takes arguments, then you register a ColonCommands.ColonAction to handle the command. A ColonCommands.ColonEvent is passed to the action that handles a colon command. Through this event the arguments to the command can be accessed. The command that was used to invoke the action is also available, so a single action could handle multiple commands; and there are other techniques to achieve this affect.

Normal Mode Command Parsing

Normal mode Vi comands can have up to three chunks: buffer-operator-motion. For example: "a3y4<CR> has

The original vim invokes normal, similar in function to jVi's Normal, 3 times, one for each chunk. The caller had no knowledge of how many chunks there are in a single command, it just called normal in a loop. normal kept control, calling safe_getc as needed to pick up all the characters that make up a chunk, and returned as each chunk was completed. Accumulated information was saved in OPARG. normal detected when a complete command was ready and then executed it, often times in do_pending_op. CMDARG has per chunk information, and OPARG is cleared after each command.

To fit into a java gui environment, we want to be able to handle and parse one character at a time as delivered through an action from the event thread. This means we have to return after each character. So we must maintain a bunch of "where am i" state information between each character. The original code is more or less intact sourounded by a variety of "what state am i in" conditionals; this is messy. Input characters come in through Normal.processInputChar(char, boolean),
NEEDSWORK:get the char parsing to look like a classic state machine this should at least keep it managable.

Operator and motion are very similar, syntacticly they are usually like [<count>]<char> or sometimes more than one char. A motion can also be a search.

Working with Three types of Options

vim/vi have three types of options: global, buffer and window. jVi mirrors this structure (finally in 2007 per buffer/document options are supported). Global options are static and are found in G. Per file options are in Buffer and per window options are in ViTextView. Both Buffer and ViTextView implement ViOptionBag. ViOptionBag is the primary source of information about handling options. Multiple views/windows of the same document share the Buffer variables; for example, if you do ":set sw=8" on a file, any open windows into that file all have the same shiftwidth.