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.
     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.
     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
     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:
     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.
     Use F1 to get editor help and it will list the keyboard bindings for the following
 	Cursor movement:
 	char_matching -- find the '{' that matches '}', etc. Matches:  {, [, <, >, [, and }
         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
 	file_top      -- move to line 1 of the file
         file_bottom   -- move to the last line
 	word_next     -- move to next word
 	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
     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
     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)
     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.
     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.
     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.
     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.
     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.
     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.
     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
Generated on Wed Feb 29 22:51:48 2012 for CXXUtilities by  doxygen 1.6.3