CXXEDITOR
[See also: CXXTOOLS.txt, CXXLIBRARY.txt, CXXDIRVIEWER, CXXCURSORWINDOWS.txt, and README]
==================
CXX TOOLKIT EDITOR
==================
INTRODUCTION
------------
There are actually 3 editors in the CXX toolkit: The ASCII file editor, the directory editor, and the
CSV file editor.
The CSV editor, designed for comma separated files has fairly limited functionality and is only invoked
if you edit a .csv or a .tsv (tab separated values) file. Note that if you only SHOW a file of one of the
above named times, you may not get the editor specific to thatfile type. Within the CXX tools, editing
and showing a given file typeare separte kinds ofoperatons.
The directory "editor" or rather viewer, lets you view and modifiy directories. It is documented separately,
see CXXDIRVIEWER.txt.
This document describes the ASCII file editor.
With them, you can
* edit or view
* ascii text files
* CSV files (partially implemented)
* TSV files (partially implemented)
* a C++ program database (generated by cpptagdb.exe)
* instantly find program symbols using either an ETAGS database or a program database
created by the cpptagdb.exe program which is part of the distribution.
* browse git and svn repositories (on linux/unix) using the STV/*.sh as appropriate.
* add your own extensions to browse other data on your system that is available
through command line logging programs by create STV/*.sh table viewer scripts.
EDITOR BASIC OPERATIONS OVERVIEW
--------------------------------
The editor is line oriented like VI but uses function keys as well as control key
sequences to perform basic function. It has context sensitive help which is invoked
with the F1 key.
The editor is NOT modal like VI. It has popup menus for various things like
finding strings, finding symbols in the program database, moving blocks of text
around, inserting files, save data, etc.
Unlike VI, EMACS, and many other editors, EDITOR pretends that all lines are infinitely
long. That is, you can use the arrow keys to navigate beyond the end of the preexisting
characters in a line. Only if you actually enter a keystroke in this region will the
characters between the pre-existing end of the line and the place where you type the new
character be instantiated. Basically, you don't have to pay attention while editing to
the line's actual end.
At most one block of whole lines can be marked. The marked lines are shown in reverse video.
Use F5 to toggle the mark on a given line. To mark a block, mark the first line and move to a
new line. To make the block go away, press F5 twice on the same line.
BLOCK OPERATIONS
----------------
Marked blocks can be manipulated in a variety of ways:
* copy
* delete
* slide left or right by deleting or inserting columns
* transform using a SED like script language (See BLOCK TRANSFORM, below)
* save to a file
SEARCH AND REPLACE
------------------
The editor provides 3 kinds of string search:
* literal text (both exact and case insensitive)
* word (only finds instances where a full word matches the search
string -- both exact and case insensitive)
* regular expression (both exact and case insensitive)
String replace operations can be singular or global. That is, either only the next
instance of the search criteria will be replaced or all of the instances below the
the current line will be replaced.
When a regular expression search and replace operation takes place, the "replacement"
part of the action can contain any of the following escape sequences:
\\0
\\1
...
\\9
The \\0 sequence means to include the full string that matched the search text
into the output. The other numbers \\1 - \\9 causing the inclusion of fragments
of the matching string in the replacement. Refer to a manual page on parenthetical
fragments in regular expressions for details.
EDITOR INTERNAL FUNCTIONS
-------------------------
Use F1 to get editor help and it will list the keyboard bindings for the following
functions.
Cursor movement:
----------------
page_down
page_up
char_left
char_right
char_matching -- find the '{' that matches '}', etc. Matches: {, [, <, >, [, and }
tab_right
tab_left
line_home -- move cursor to left most character on line
line_end -- move cursor to end of line
line_split -- split the line into two starting at current character
line_up
line_down
file_top -- move to line 1 of the file
file_bottom -- move to the last line
word_next -- move to next word
word_prev
Character editing:
------------------
undo -- undo all the most recent changes to the current line, block,
or global replace set
char_delprv -- delete the previous character
char_delete -- delete the characte under the cursor
char_insert -- typed characters are automatically inserted
word_delete -- delete the current word
Line editing:
-------------
line_del -- delete the current line
line_mark -- include the current line in the marked block
line_clreol -- clear to end of line
line_goto -- move to a specific line
line_join -- join current and next lines
line_insert -- insert a new line
file_insert -- insert a whole file above the current line
block_delete -- delete the currently selected block
block_copy -- copy the currently marked block to the paste buffer
block_paste -- insert the current paste buffer
block_insert -- insert a copy of the block without using the paste buffer
block_adjust -- add or delete characters to the lines in a marked block
block_transform -- use SED-like commands to manipulate a block's contents
using the muSED.h defined SED command interpreter.
(see BLOCK TRANSFORM)
file_insert -- insert a file by name
Find and Replace:
-----------------
word_sfind -- extract a word from the current line and find the next instance
find_first -- find a new string
find_next -- find the next instance of the most recently searched string
find_prev -- repeat most recent find command but work backwards
replace_first -- find and replace first instance of a string
replace_next -- repeat the most recent replace command
block_transform -- use SED-like commands to manipulate a block's contents
using the muSED.h defined SED command interpreter.
External File Actions:
----------------------
snatch_edit -- extract the name of a file from the text on the line and edit it
show_symbols -- list the symbols from the program database
etags_first -- find first instance of a symbol in the etags database
cpptags_first -- find the first instance of a symbol in the TAGPP.tagpp database
etags_next -- list all matching symbols from an etags database
etags_all -- list all matching symbols from the etags database
cpptags_all -- list all the matching symbols from TAGPP.tagpp database
to_edit -- convert a view only session into an edit session
reread -- reread the file
switch_source -- switch to corresponding source. .cpp goes to .h, etc
block_save -- save the marked block to afile
file_insert -- insert a file by name
BLOCK TRANSFORM
---------------
The editor's block transform capability is a mixture of "internal" and "external"
behavior. The actual editing and transform is of course internal to the edit session,
but the source of the script that performs the transformation can be internal or external.
The editor attempts to find a script to apply to the marked block by searching the list of
currently active viewers which are acting on file's whose names end in ".mused". If more
than one of them is found, the user will be prompted to see which is preferred. If only
one is found, the script will be applied immediately to the marked block. If there are no
viewers operating on mused files, then the user will be prompted for 3 strings using a dialog.
Note that it is not necessary for the an edit session to save the script that is used to
perform the block transform -- the in-memory copy is the one used by the block transform
process.
OTHER TOOLKIT FUNCTIONS
-----------------------
Also described in the F1 help page for the editor are other editor functions are common
to the cursor windowing toolkit provided by the CXX library. These include:
split the window horizontally after prompting the user for a filename
split the window vertically afer prompting the user for a filename
replace the current window a new tool (EDITOR is one of several tools):
- text editor
- text viewer
- CSV/TSV viewer
- keyboard character display tool (just lets you see the numeric values of keys)
- directory viewer
- symbol viewer
- scriptTableViewer (script executor/viewer)
- FTP interface to remote system (poor quality be careful)
POPUP MENUS
-----------
The editor and other tools employ a large variety of popup menus. They fall into
3 basic types:
DIALOG A collection of input fields arranged vertically with labels.
Dialog field types can include:
- string input
- single letter input
- OK select only fields
MESSAGE A warning or error message that the user must acknowlege
FILE SELECTION Lets the user dco the following:
- type in a file name (existing or not)
- select from a list of files in a directory
- select a sub-directory name
- navigate into subdirectories
- navigate to the parent directory
- navigate to a different directory completely
- ask for help using the F1 key to get context sensitive help
STRING/FILENAME Some menus, such as the ^X^F menu that lets you select a file
or directory to edit has the ability to perform file name
completion when you press the tab key. The feature is not available
in all cases but in the obvious cases it should be active.
NON-PRINTABLE CHARACTERS IN FILES
---------------------------------
This editor is designed to aid in the editing source code and simple ascii text files.
It is not designed to edit binaries of any form and will very likely bolix them up
completely if you try.
The editor is designed to add unix end of line (EOL) sequences on unix/linux and
MS Windows end of line sequences on Windows. However, it also attempts to preserve
the eol style of text which is not modified -- however it is often difficult to understand
if you have modified a line or not. Undo does not put the eol style back the way it was.
TAB characters are replaced with spaces in some kinds of files but not others. Files
with the names matching standard source code are saved without tabs. There is no way,
at the time of this writing to change that behavior.
On windows, ^Z is NOT recognized as end of file unless the C++ runtime does it.
Ditto on unix for ^D.
Except for tabs, all other characters are treated as printable unless they are known to
bolix up the display.
TEXT EDITOR FEATURES
--------------------
The following unusual features exist:
block transform: Lets you use a sed-like script language to modify the contents
of a marked block. See BLOCK TRANSFORM, below.
block adjust: When a block is marked, you can modify all lines in the block
using block_adjust: ^X^A^B. It lets you slide the lines left and
right using a number of columns. Spaces are inserted to slide the
lines right. Deletion is used to slide the lines left.
block insert: When a block is marked, you can insert a string at the same column
in all lines. Use ^X^A^I
match: When editing C++ code, you often want to match {}, [], (), etc.
Position the cursor on one of the characters, and press ^\\ to
find its match (or not move the cursor if there is not match).
In C++, <> are ALSO valid matching characters.
log files: The editor lets you snatch-edit files from grep logs and compiler
logs. That is, if a contains lines which define filenames and line
numbers in them, the editor can help you bounce between editing these
other file locations using the ^X-^W-^E key sequence. The following
filename line number formats are recognized:
filename:lineNo: -- grep format
file: -- grep without the -n
file lineNo: -- borland c output
"file", line 2: -- other compiler outputs
file(line) -- microsoft
#line 12 "file" -- ANSI C preprocessor output
<file> -- #include file names
#12 "file"
Error 112: "reports_pkg.c", line 48
Error (112): "reports_pkg.c", line 48
error: "reports_pkg.c", line 48
warning: "reports_pkg.c", line 48
Refer to StrTool::snatch_file_info() for the function that
extracts the file name and line number from the log file
being edit.
regex search The find and replace dialogs let you search for regular expressions.
and replace: The replace dialog supports \\(\\) sections which can be identified using
\\0 - \\9. Much like sed. & is not a special character to the editor.
snatch_find Use ^X-^W-^S to grab the word under the cursor and search for the next
instance thereof.
ETAGS AND CPPTAGS
-----------------
Both of these programs are used to scan source code and produce a program database.
The format of the two databases is quite different. ETAGS produces a format that spans
many languages, but cpptags is designed for only the C++ language. The structure of its
database is more amenable for visual display than that of ETAGS, but much of the same
information can be found in both.
To generate the TAGS file (produced by ETAGS), cd to the level directory of the source
code base you wish to generate tags for and execute the script scripts/makeTags.
To generate the TAGPP.tagpp file (produced by cpptagdb.exe), cd to the top level
directory of the source code base and execute the script scripts/makeCppTags.
Note that the TAGS file produced by ETAGS contains non-printable characters. To
print the database in a more human readable form, use scripts/dumpEtagsDb.
The EDITOR knows how to _view_ the TAGPP.tagpp database in a tree structured form.
If you edit that kind of file, it will look like normal text, but if you view it,
you will see the tree structured format. From this viewer, you can jump to the source
code for symbols.
EDITING OTHER FILES
-------------------
To editor or view other files and directories, use ^X-^F. This will bring up a dialog
that prompts you for the name of the file or directory of interest and will bring up
the editor or directory viewer as needed.
ESCAPING TO THE COMMAND SHELL
-----------------------------
To invoke the command shell temporarily, use ^X-^Z. When finished, type exit. Note that
this shell will not have your environment settings. If you want it to, on unix or linux,
use "bash -i" as the first command.
EDITOR INVOKING SHELL FUNCTIONS
-------------------------------
The unix bourne shell, as well as bash and other command line interpreter programs
support the definition of 'shell functions' which can be used to obtain another
feature of the EDITOR and CXX TOOLS. The general idea is that while you are editing,
you can press the ^X^J key sequence to exit the editor (or other tools) and have the
invoking shell program set its current working directory to the current directory within
the tool at the time that you press the key sequence. That is, the ^X^J sequence
instructs the invoking shell function to set the shell's current directory to a value
saved in a file by the ^X^J sequence.
Confused? Here's how you use this feature:
1. You are sitting in your bash shell command window in your home directory
2. You type 'edit' and bring up the editor and it shows you the files in your
home directory.
3. You navigate to /tmp
4. You then press ^X^J
5. The editor writes /tmp to ~/.tools_home/exitDir.txt
6. if you invoked the editor directly, then nothing happens -- except that
the exitDir.txt file contains /tmp
7. But, if you invoked the editor using shell function edit() defined in the
scripts/SHELL_FUNCTIONS example file, then your prompt will show that you are
sitting in /tmp instead of yoru home directory
