home *** CD-ROM | disk | FTP | other *** search
/ Boston 2 / boston-2.iso / DOS / HILFEN / 4DOS / 4MAP / 4MAP.DOC next >
Text File  |  1993-12-01  |  16KB  |  495 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                 4MAP
  7.                 Version 1.01
  8.  
  9.             A Keybinding Program for 4DOS
  10.                  by
  11.                 Ho-Ping Tseng
  12.  
  13.     (c) Copyright 1990 by Ho-Ping Tseng, ALL RIGHTS RESERVED
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24. 4DOS a registered trademark of J.P. Software
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31. This program may be freely distributed for non-commercial, non-business,
  32. and non-governmental uses, provided this notice is attached with it.  My
  33. only request is that if you plan to use it regularly, you let me know of
  34. it through e-mail or postal mail, so that I have an idea of how useful
  35. this program is.  Please let me know of any comments that you may have
  36. and any suggestions or criticisms.
  37.     
  38.  
  39.             Ho-Ping Tseng
  40.             575 S. Rengstorff Ave., #26
  41.             Mountain View, Ca.  94040
  42.             e-mail:  tseng@tilden.stanford.edu
  43.             
  44.             
  45.             
  46.             
  47.             
  48.             
  49.             
  50. 1.  INTRODUCTION
  51.  
  52.     This program provides two basic capabilities for the 4DOS command
  53. line processing.  First, it filters keyboard inputs through a user-defined
  54. keymap, before they reach 4DOS.  Second, it can launch executable programs
  55. in response to keystrokes while within the 4DOS command line.
  56.  
  57.  
  58.     With these two functions, a user can customize and remap 4DOS key
  59. definitions.  In addition, 4DOS command line editing functions may be
  60. expanded.  As an example, a minimal vi-like implementation is included that
  61. uses many of the keys familiar to vi users and provides similar edit and
  62. insert modes.
  63.  
  64.  
  65.     Note that this program differs in purpose to that of the conventional
  66. keymapping programs.  It is meant to take effect only during command line
  67. processing, and it can map keystrokes sequences, not just a single keystroke.
  68. Also, editing functions can be added on top of that provided by 4DOS with
  69. its program launching capability.
  70.  
  71.  
  72.  
  73. 2.  REQUIREMENTS
  74.  
  75.     This program is implemented as a terminate and stay resident routine
  76. (TSR).  It takes up about 2500 bytes of memory.  It has been tested on the
  77. latest versions of 4DOS (3.01 and 3.02).
  78.  
  79.  
  80.  
  81. 3.  FILES
  82.  
  83.     The basic functionalities of this program is included in 3 files:
  84. "4map.exe," "putmap.exe," and "mapdef."  4map.exe implements the filter and
  85. stays resident in memory.  Putmap.exe installs the user-defined keymap into
  86. memory.  And finally, mapdef contains an example keymap.
  87.  
  88.  
  89.     Also included is "edit.zip," which contains programs that perform
  90. miscellaneous command line editing functions.  They are invoked by 4map.exe
  91. in response to keystroke sequences defined by mapdef.
  92.  
  93.  
  94.  
  95. 4.  INSTALLATION
  96.  
  97.     4map.exe and putmap.exe can be run from the command line or more
  98. conveniently placed in autoexec.bat.  They can be run either before or
  99. after starting 4DOS.  To run, type the following or include them in
  100. autoexec.bat:
  101.             4map
  102.             putmap mapdef
  103.  
  104.  
  105.     This assumes, of course, that 4map.exe and putmap.exe are placed
  106. in a directory that is in the search path.  Also, if mapdef is not in the
  107. current directory (root if these were invoked in autoexec.bat), its full
  108. pathname must be specified.
  109.  
  110.  
  111.     To install the programs in edit.zip, as defined by the contents of
  112. mapdef, make a directory on the C partition of the disk called MAP and copy 
  113. edit.zip into it.  Then unzip edit.zip.
  114.  
  115.  
  116.     Note that the functionalities provided by edit.zip is optional, and
  117. map.exe would function equally well (albeit without these functions) even
  118. if it is not installed.
  119.  
  120.  
  121.     The contents and format of the map definition are discussed next,
  122. plus a description of mapdef and edit.zip.
  123.  
  124.  
  125.  
  126. 5.  MAP DEFINITIONS
  127.  
  128.     A keymap file contains definitions of keystroke mappings that 4MAP
  129. uses to perform its operations.  Several sets of mappings are allowed in
  130. this file (with the first set being the default used when a keymap is first
  131. installed), and 4MAP gives provisions for switching from one to another.
  132. This will be described in more detail later.  For convenience, when a "map"
  133. is referred to below, it will mean a set of these mappings.
  134.  
  135.  
  136.     Each map is defined by the construct:
  137.  
  138.         mapname = {    rule1 ;
  139.                 rule2 ;
  140.                       .
  141.                   .
  142.                   .
  143.                 ruleN ; }
  144.  
  145. where "mapname" is a name given to this map and "ruleX" refers to the Xth
  146. mapping rule.  '= {', ';', and '}' correspond to delimiters required by
  147. 4MAP.
  148.  
  149.  
  150.     Each rule is further represented by two fields, the "pattern" and
  151. its "binding", defined by the construct:
  152.  
  153.                 pattern => binding
  154.  
  155. "Pattern" denotes a sequence of keystrokes that is used to match the
  156. keyboard input.  4MAP successively examines each pattern according to
  157. its location in the map, with the ones closer to the beginning of the
  158. map searched first.  When a partial match occurs (the input sequence
  159. matches the pattern so far but is shorter than the pattern), the search
  160. is suspended until more input is received.  At the first instance that
  161. 4MAP can determine whether or not the input sequence produces a match,
  162. certain actions are performed.  If a match did occur, "binding" is
  163. executed.  Otherwise the input sequence is sent to 4DOS unmodified.
  164.  
  165.  
  166.  
  167. 5.1  The Pattern
  168.  
  169.     Each pattern may contain keynames (such as "del" and "home")
  170. ascii codes, random keystrokes (e.g. abcd), and wildcard characters.
  171. Keynames are reserved words and are provided for convenience.  A list
  172. of them is provided in the Appendix.  Ascii codes may be specified in
  173. octal (preceded by 0, such as 0101 for the character 'A'), decimal
  174. (such as 65 for 'A'), or hex format (preceded by 0x, such as 0x41 for
  175. 'A').  Wildcard characters include '?' for matching any single keystroke
  176. and '*' for matching any sequence of keystrokes.  The special character
  177. '\' is used as an escape character, so that the character immediately
  178. following it is used literally as part of the pattern.  To use '\' in
  179. the pattern, just enter '\\' instead.  Also, commas, spaces, tabs, and
  180. carriage returns are treated as delimiters and ignored; they must be
  181. preceded by '\' to be part of the pattern (or specified by keynames
  182. where appropriate or in ascii codes).
  183.     
  184.  
  185.     For example,
  186.     
  187.         ab, del \4 ?s
  188.         
  189. denotes a keystroke sequence of:  'a', 'b', the delete key, '4', any keystroke,
  190. and 's'.  Note that in order to avoid '4' from being treated as control-d
  191. rather than the key '4', it must be preceded by the escape character.  In
  192. general, all numerals are treated as ascii codes unless preceded by '\'.
  193.  
  194.  
  195.     To use the sequence 'd', 'e', 'l' as part of the pattern rather
  196. than to specify the delete key, the above pattern may be changed to:
  197.  
  198.         ab, \del \4 ?s
  199.     or    ab, d el \4 ?s
  200.  
  201. or variations of these.
  202.     
  203.  
  204.  
  205. 5.2  The Binding
  206.  
  207.     A binding represents a list of actions that is performed when
  208. its corresponding pattern matches the keyboard input.  It is separated
  209. from the pattern by the delimiter '=>' and can be classified into two
  210. basic types.  Each of these are described below.
  211.  
  212.  
  213.     The first type simply performs the mapping function--given an
  214. input that matches the pattern, certain keystroke sequence is sent to
  215. 4DOS as though it had just been typed by the user.  To specify the
  216. sequence, similar mechanism to that used to specify the patterns is
  217. used here--it is specified with keynames, ascii codes, and random
  218. keystrokes.  As with patterns, commas, spaces, tabs, and carriage
  219. returns are used as delimiters, and '\' is used as the escape character.
  220. The various rules described above for the pattern specifications apply
  221. here as well (except wildcard characters are not used here).  For example,
  222.  
  223.         k    =>    del ins a ins
  224.  
  225. maps 'k' into the sequence:  del, ins, 'a', and ins.  In the context of 4DOS,
  226. this would mean that whenever 'k' is typed, the character at the cursor is
  227. replaced by the character 'a'.
  228.  
  229.  
  230.     The second type consists of command requests to 4MAP.  It currently
  231. includes a command to change the current map and one to invoke a program.
  232.  
  233.  
  234.     Switching to another map is facilitated by the keyword "changemap".
  235. When the binding containing this keyword is executed, the current map is
  236. changed to the one specified by the argument of "changemap", and subsequent
  237. inputs are mapped according to the definitions given in this new map.  Thus,
  238.  
  239.         i    =>    changemap insert
  240.  
  241. would change the current map to "insert".  Using this mechanism, several
  242. maps may be defined that could provide different mapping characteristics
  243. or "modes."  In the keymap provided, this is used to simulate the insert
  244. and edit modes of vi.  Note that when a keymap file is first installed,
  245. the first map becomes the current one.
  246.  
  247.  
  248.     Invoking a program requires enclosing the full pathname of the
  249. program file and its arguments inside the special character '`' (back
  250. quote).  It is used to launch a program in response to an input sequence.
  251. For example,
  252.  
  253.         i    =>    changemap insert, `\map\prog.exe 2`
  254.  
  255. changes the current map to "insert" and executes \map\prog.exe with an
  256. argument of 2 when 'i' is typed.  Note that to accommodate DOS and for
  257. convenience, '\' is not recognized as an escape character within the back
  258. quotes--there is no escape mechanism for program name specification.  Also,
  259. no error message is displayed if an error is encountered while executing the
  260. program.  In particular, if the program file does not exist, no action is
  261. performed.
  262.  
  263.  
  264.  
  265. 5.3  Comments
  266.  
  267.     Comments may be inserted anywhere in the keymap file to increase
  268. readability.  They are delimited by '/*' at the beginning and '*/' at
  269. the end--everything in between is ignored.
  270.  
  271.  
  272.  
  273. 5.4  Special Characters
  274.  
  275.     As a summary, characters or character sequences possessing special
  276. meanings to 4MAP are listed below:
  277.  
  278.     \        Escape character used in the patterns and the parts
  279.             of the bindings which specify the character mappings
  280.     = {        Beginning of a map definition
  281.     =>        End of pattern field and beginning of binding field
  282.     ;        End of binding field and a mapping rule definition
  283.     }        End of a map definition
  284.     /*        Beginning of a comment
  285.     */        End of a comment
  286.     ,        Delimiter used in the pattern and binding
  287.     0 through 9    Denote literal ascii codes
  288.     white spaces    Delimit keynames and otherwise ignored
  289.     
  290.  
  291.     
  292. 6.  MAPDEF and EDIT.ZIP
  293.  
  294.     As an example of the capabilities of 4MAP, a keymap definition
  295. file is included.  It defines three modes:  command, insert, and edit.
  296. In the following descriptions, '^X' will denote control-X (the keystroke
  297. where the control key is held down while simultaneously hitting 'X').
  298.  
  299.  
  300. 6.1  Command Mode
  301.  
  302.     At the beginning of each command line editing session, the command map
  303. is used.  This mode has very similar key-bindings to the 4DOS specifications,
  304. with a few modifications:
  305.  
  306.     ^U        Deletes the whole line
  307.     ^W        Deletes the previous word
  308.     ^D        Filename completion
  309.     ^B        Filename completion looping opposite direction to ^D
  310.     ^K        Previous command line in the history list
  311.     ^J        Next command line in the history list
  312.     esc        Changes to edit mode
  313.     ins        Changes to insert mode
  314.  
  315.  
  316. 6.2  Insert Mode
  317.  
  318.     In this mode, all inputs are entered onto the command line without
  319. deleting what was originally there.  Aside from that, it is very similar
  320. to the command mode:
  321.  
  322.     ^U        Deletes the whole line
  323.     ^W        Deletes the previous word
  324.     ^D        Filename completion
  325.     ^B        Filename completion looping opposite direction to ^D
  326.     esc        Changes to edit mode
  327.     ins        Changes to command mode
  328.  
  329.  
  330. 6.3  Edit Mode
  331.  
  332.     In this mode, all keystrokes correspond to commands and are not
  333. considered input to the command line:
  334.  
  335.     a        Moves one space to the right and changes to insert mode
  336.     b        Moves one word back
  337.     dd        Deletes the whole line
  338.     dw        Deletes the word to the right of the cursor
  339.     f <c>        Finds the character to the right corresponding to
  340.             the character <c>
  341.     h        Moves one character to the left
  342.     i        Changes to insert mode
  343.     j        Next command line in the history list
  344.     k        Previous command line in the history list
  345.     l        Moves one character to the right
  346.     r <c>        Changes the character to <c>
  347.     w        Moves one word forward
  348.     x        Deletes character
  349.     D        Deletes the rest of the line
  350.     0        Goes to the beginning of the line
  351.     $        Goes to the end of the line
  352.     space        Moves one character to the right
  353.     ^U        Deletes the whole line
  354.     ^W        Deletes the previous word
  355.     ^D        Filename completion
  356.     ^B        Filename completion looping opposite direction to ^D
  357.     ^K        Previous command line in the history list
  358.     ^J        Next command line in the history list
  359.     esc        Changes to command mode
  360.     ins        Changes to insert mode
  361.  
  362.  
  363. 6.4  Edit.zip
  364.  
  365.     This file contains programs that are invoked in mapdef.  These
  366. include the following:
  367.  
  368.     f.exe        Implements the find character function in edit mode
  369.     on.exe        Prints 'EDIT' on the right upper corner of the screen
  370.     off.exe        Erases 'EDIT' on the right upper corner of the screen
  371.     ion.exe        Prints 'INS' on the right upper corner of the screen
  372.     ioff.exe    Erases 'INS' on the right upper corner of the screen
  373.     r.exe        Implements the replace character function in edit mode
  374.  
  375.  
  376.     As it is, these programs must be located in C:\MAP.  To move them into
  377. a different directory, mapdef must be modified to incorporate the new path.
  378.  
  379.  
  380.  
  381. 7.  CAVEATS
  382.  
  383.     Care should be taken if a program is to be bound and launched.  In
  384. particular, it is found that launching command.com does not work and may
  385. hang the machine.
  386.  
  387.  
  388.     To keep the size down, the internal buffer sizes are minimized.
  389. This reduces the size of the resident keymap definitions to a total of
  390. about 550 bytes.  (The keymap file can be slightly larger than this but
  391. is roughly proportional.)  Mapdef, as it is, takes up a great portion of
  392. the 550 bytes.  Also as a consequence of the small buffers, "f.exe" can
  393. only advance at most 16 characters to the right at a time, even though it
  394. may find a matching character farther away.
  395.  
  396.  
  397.     These limitation and further improvements may occur in future
  398. versions depending on the demand and the author's time.
  399.  
  400.  
  401.  
  402. APPENDIX
  403.  
  404.     Here is a list of keynames that 4MAP recognizes with their
  405. corresponding scan code or ascii code:
  406.  
  407.         nul            0x00          
  408.         ctrl_a            0x01          
  409.         ctrl_b            0x02          
  410.         ctrl_c            0x03          
  411.         ctrl_d            0x04          
  412.         ctrl_e            0x05          
  413.         ctrl_f            0x06          
  414.         ctrl_g            0x07          
  415.         ctrl_h            0x08          
  416.         ctrl_i            0x09          
  417.         ctrl_j            0x0a          
  418.         ctrl_k            0x0b          
  419.         ctrl_l            0x0c          
  420.         ctrl_m            0x0d          
  421.         ctrl_n            0x0e          
  422.         ctrl_o            0x0f          
  423.         ctrl_p            0x10          
  424.         ctrl_q            0x11          
  425.         ctrl_r            0x12          
  426.         ctrl_s            0x13          
  427.         ctrl_t            0x14          
  428.         ctrl_u            0x15          
  429.         ctrl_v            0x16          
  430.         ctrl_w            0x17          
  431.         ctrl_x            0x18          
  432.         ctrl_y            0x19          
  433.         ctrl_z            0x1a          
  434.         esc            0x1b          
  435.         sp            0x20          
  436.         cr            0x0d          
  437.         lf            0x0a          
  438.         tab            0x09          
  439.         f1            0x00         0x3b         
  440.         f2            0x00         0x3c         
  441.         f3            0x00         0x3d         
  442.         f4            0x00         0x3e         
  443.         f5            0x00         0x3f         
  444.         f6            0x00         0x40         
  445.         f7            0x00         0x41         
  446.         f8            0x00         0x42         
  447.         f9            0x00         0x43         
  448.         f10            0x00         0x44         
  449.         home            0x00         0x47         
  450.         up            0x00         0x48         
  451.         pageup            0x00         0x49         
  452.         left            0x00         0x4b         
  453.         right            0x00         0x4d         
  454.         end            0x00         0x4f         
  455.         down            0x00         0x50         
  456.         pagedown        0x00         0x51         
  457.         ins            0x00         0x52         
  458.         del            0x00         0x53         
  459.         shft_f1            0x00         0x54         
  460.         shft_f2            0x00         0x55         
  461.         shft_f3            0x00         0x56         
  462.         shft_f4            0x00         0x57         
  463.         shft_f5            0x00         0x58         
  464.         shft_f6            0x00         0x59         
  465.         shft_f7            0x00         0x5a         
  466.         shft_f8            0x00         0x5b         
  467.         shft_f9            0x00         0x5c         
  468.         shft_f10        0x00         0x5d         
  469.         ctrl_f1            0x00         0x5e         
  470.         ctrl_f2            0x00         0x5f         
  471.         ctrl_f3            0x00         0x60         
  472.         ctrl_f4            0x00         0x61         
  473.         ctrl_f5            0x00         0x62         
  474.         ctrl_f6            0x00         0x63         
  475.         ctrl_f7            0x00         0x64         
  476.         ctrl_f8            0x00         0x65         
  477.         ctrl_f9            0x00         0x66         
  478.         ctrl_f10        0x00         0x67         
  479.         alt_f1            0x00         0x68         
  480.         alt_f2            0x00         0x69         
  481.         alt_f3            0x00         0x6a         
  482.         alt_f4            0x00         0x6b         
  483.         alt_f5            0x00         0x6c         
  484.         alt_f6            0x00         0x6d         
  485.         alt_f7            0x00         0x6e         
  486.         alt_f8            0x00         0x6f         
  487.         alt_f9            0x00         0x70         
  488.         alt_f10            0x00         0x71         
  489.         ctrl_left        0x00         0x73         
  490.         ctrl_right        0x00         0x74         
  491.         ctrl_end        0x00         0x75         
  492.         ctrl_pagedown        0x00         0x76         
  493.         ctrl_home        0x00         0x77         
  494.         ctrl_pageup        0x00         0x84         
  495.