home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vile-src.zip / vile-8.1 / doc / modes.doc < prev    next >
Text File  |  1998-05-13  |  7KB  |  234 lines
  1. Major (and minor) modes in Vile
  2. ===============================
  3.  
  4. Goals
  5. -----
  6.  
  7. This document describes the proposed implementation and use of major
  8. modes in vile.  My goal is to extend the notion of the C mode (cmode)
  9. to allow runtime definable major modes.
  10.  
  11. The C mode is a collection of modes that are useful for editing C
  12. program source:
  13.  
  14.     c-suffixes
  15.     c-tabstop
  16.     c-shiftwidth
  17.  
  18. as well as builtin functionality:
  19.  
  20.     autoindention of C statements taking into account curly braces
  21.     fence matching for /*...*/ comments and C preprocessor statements
  22.     comment formatting
  23.  
  24. Both the modes and functionality are extensions of other features in
  25. vile.  It would be useful to combine modes to support other languages
  26. in a similar fashion.  Likewise, the autoindention, etc., could be
  27. parameterized and made reusable to support other languages.  For an
  28. initial implementation, I am focusing on the combining of modes,
  29. providing a structure for the parameterization.
  30.  
  31. One thing that is not clear to many users (and possibly should be
  32. changed) is the manner in which the C mode is attached to a buffer. 
  33. It is currently set as a boolean - if active before a buffer is
  34. loaded, then vile checks the file suffix to see if it matches the
  35. c-suffixes mode, and if so, sets the C mode for the buffer.  C mode
  36. can be explicitly set by a ":setl cmode", and unset by ":setl
  37. nocmode".  In the new scheme,
  38.  
  39.     + vile will search the list of all active majormodes, first
  40.       testing if any match with the majormode's suffixes, then if
  41.       any preamble (first line regular expression) matches.
  42.  
  43.       The search is in alphabetic order, by majormode name.  The
  44.       first match each, of suffixes and preamble terminate the
  45.       search, but a match of preamble overrides a match of suffixes.
  46.  
  47.     + majormodes can be disabled (e.g., ":set nocmode"), as before.
  48.       However, there is no global sense of majormode; unsetting a
  49.       buffer's local value of a majormode simply makes it not have a
  50.       majormode associated with it.
  51.  
  52.  
  53. Commands
  54. --------
  55.  
  56. These are the commands which I think are necessary:
  57.  
  58.     define-majormode {majormode}
  59.  
  60.     define-submode {majormode} {minormode}[={value}]
  61.  
  62.     remove-majormode {majormode}
  63.  
  64.     remove-submode {majormode} {minormode}
  65.  
  66. The {majormode} is a new symbol.
  67.  
  68. The {minormode} can be any one of the existing buffer modes, except for
  69. a {majormode}.
  70.     
  71.  
  72. Example
  73. -------
  74.  
  75.     define-majormode c
  76.     ; Declares a mode 'c', and corresponding symbol 'cmode'
  77.  
  78.     define-submode c suffixes=\\.\\(\\([Cchisyl]\\)\\|CC\\|cc|cpp\\|cxx\\|hxx\\|scm\\)$
  79.     ; Specifies the filename suffixes which control whether a newly-loaded
  80.     ; buffer is set to 'c' mode.
  81.  
  82.     define-submode c tabstops=4
  83.     define-submode c shiftwidth=4
  84.     ; Defines the 'c' tabstops and shiftwidth.  If no "define-submode"
  85.     ; command is given, no separate symbol is defined.
  86.  
  87. As an example, to define a new major mode for perl programming, you might
  88. include the following in your .vilerc file:
  89.  
  90.     define-majormode perl
  91.     define-submode perl preamble "^#.*perl\\>"
  92.     define-submode perl suffixes "\\.pl$"
  93.     define-submode perl shiftwidth 4
  94.  
  95.  
  96. The "define-majormode" command
  97. ------------------------------
  98.  
  99. This takes a single argument, a majormode name.  To follow existing
  100. convention, the string "mode" is automatically appended to the given
  101. name.  Associated modes are defined or modified with the define-submode
  102. command.  Vile maintains a list of majormodes.  Only one majormode can
  103. be associated with a buffer (none need be associated).  After
  104. definition, a majormode can be set or unset just like any other buffer
  105. mode:
  106.  
  107.     define-majormode c
  108.     ; defines "cmode"
  109.  
  110.     set cmode
  111.     ; sets the default mode for new buffers
  112.  
  113.     setl cmode
  114.     ; sets the mode for the current buffer
  115.  
  116.     setl nocmode
  117.     ; clear c mode (existing implementation)
  118.  
  119.     unsetl cmode
  120.     ; clear c mode (not currently implemented)
  121.  
  122. The restriction to a single majormode is because mode values are
  123. internally represented as structures with a pointer.  The pointer
  124. denotes which value (currently local or global) is used.  The
  125. majormode implementation adds a level to this, e.g.,
  126.  
  127.     value -> self (local)
  128.     value -> global (global)
  129.     value -> major (majormode)
  130.  
  131. When a majormode is defined, an array of the existing minor mode values
  132. is allocated, all pointing to the global modes.  The define-submode
  133. command modifies these to make them local pointers.  When a buffer is
  134. associated with a majormode, all of its buffer mode values are pointed
  135. to the majormode's values.  (To keep the bookkeeping straight, modifying
  136. a global buffer mode must also modify the copies of non-local buffer
  137. mode values).
  138.  
  139.  
  140. The "define-submode" command
  141. ----------------------------
  142.  
  143. This command sets local values of buffer modes for the given majormode,
  144. e.g.,
  145.  
  146.     define-submode c autoindent
  147.  
  148. The majormode name is required.  Any number of modes can be modified
  149. in a single command.
  150.  
  151. The following are keywords that aren't minor modes, but are recognized
  152. solely by the define-submode command:
  153.  
  154.     suffixes
  155.         The filename suffix which is tested to trigger
  156.         association with a majormode (e.g., c-suffixes)
  157.  
  158.         Note that since the default value for the c-suffixes mode
  159.         is a regular expression that will match some other file
  160.         types (C++ files, for instance), if you define a new major
  161.         mode for one of those suffixes you may want to reset
  162.         c-suffixes to something less inclusive.
  163.  
  164.     preamble
  165.         Regular expression, matched against the beginning of a
  166.         file (the first line) used to trigger association with
  167.         a majormode (e.g., "^!#.*\/perl[^a-z]").
  168.  
  169.     fences
  170.         "fence-" followed by any of the following keywords with a
  171.         regular expression:  if, elif, else, fi,
  172.  
  173.     comments
  174.         To support C-style comments, with the '%' going between
  175.         "/* and "*/", use "fence-" followed any of the following
  176.         keywords with a regular expression:  begin, end.
  177.  
  178.     indent
  179.         The keyword "cstyle", or any of the following keywords
  180.         with a regular expression: begin, end, if, then, else,
  181.         elif, endif.
  182.  
  183. Other features which should be controlled by majormodes include limiting
  184. the scope of the entab and detab commands.
  185.  
  186.  
  187. The "remove-majormode" command"
  188. -------------------------------
  189.  
  190. This command has two forms:
  191.  
  192.     remove-majormode {majormode}
  193.  
  194.         This removes the definition of the majormode.  Buffers
  195.         that were associated with the mode revert to no
  196.         majormode.
  197.  
  198. or
  199.     remove-majormode {majormode} {name}
  200.  
  201.         This removes the value of {name} from {majormode},
  202.         leaving it set to the global value, if any.
  203.  
  204.  
  205. The "remove-submode" command"
  206. -----------------------------
  207.  
  208. Remove the special association of a submode from a majormode.
  209.  
  210. Example
  211. -------
  212.  
  213. The builtin C/C++ majormode description is equivalent to
  214.  
  215. define-mode c
  216. set csuf "\\.\\(\\([Cchisyl]\\)\\|CC\\|cc|cpp\\|cxx\\|hxx\\|scm\\)$"
  217. set c-comment-prefix="^\\s*\\(\\s*[#*>]\\)\\+"
  218. set c-comments="^\\s*/\\?\\(\\s*[#*>]\\)\\+/\\?\\s*$"
  219. set c-fence-begin="/\\*"
  220. set c-fence-end="\\*/"
  221. set c-fence-if="^\\s*#\\s*if"
  222. set c-fence-elif="^\\s*#\\s*elif\\>"
  223. set c-fence-else="^\\s*#\\s*else\\>"
  224. set c-fence-fi="^\\s*#\\s*endif\\>"
  225.  
  226. Note that the following are equivalent once you have defined the majormode "c":
  227.     set cts=8
  228.     set c-tabstop=8
  229.     define-submode c tabstop=8
  230.  
  231. -------------------------------
  232. $Header: /usr/build/vile/vile/doc/RCS/modes.doc,v 1.1 1998/05/13 10:20:30 tom Exp $
  233. -------------------------------
  234.