Package com.raelity.jvi

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

See:
Description

Interface Summary

ColonCommandFlags	Flags used to direct ":" command parsing.
Constants
KeyDefs	The vim code uses character constants and key constants.
ViBuffer
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.
BooleanOption
BooleanOption.Validator
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.BangAction
ColonCommands.ColonAction	Commands that take arguments subclass this.
ColonCommands.ColonEvent	The event passed to ColonCommands.ColonAction.
DefaultViFS
Edit
FPOS	File position, accessable as line number, 1 based, and column, 0 based.
G
GetChar
IntegerOption
IntegerOption.Validator
Misc
Msg
MutableBoolean
MutableInt
Normal	Contains the main routine for processing characters in command mode.
OPARG	Arguments for operators.
Option
Option.ColorOption
Option.ColorOption.Validator
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.
OptionsBean.CursorWrap
OptionsBean.Debug
OptionsBean.ExternalProcess
OptionsBean.General
OptionsBean.Modify
OptionsBean.Platform
OptionsBean.Search
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.
StringOption
StringOption.Validator
Util
ViFPOS.abstractFPOS
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

Options.Category
ViManager.OsVersion
ViTextView.FOLDOP
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

NonExistentWindowException
ViMark.MarkException
ViMark.MarkOrphanException

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

• buffer: "a
• operator: 3y
• motion: 4<CR>

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.