Permalink
Browse files

Initial restoration.

  • Loading branch information...
1 parent dc8eabf commit 759ae2c28d7408e4a074a4150e7c6a8dfc5a6611 Darren Hiebert committed Nov 2, 2001
Showing with 24,049 additions and 0 deletions.
  1. +7 −0 .cvsignore
  2. +340 −0 COPYING
  3. +212 −0 EXTENDING.html
  4. +371 −0 FAQ
  5. +215 −0 INSTALL
  6. +67 −0 INSTALL.oth
  7. +213 −0 Makefile.in
  8. +582 −0 NEWS
  9. +531 −0 QUOTES
  10. +69 −0 README
  11. +22 −0 Test/bit_field.c
  12. +123 −0 acconfig.h
  13. +505 −0 argproc.c
  14. +270 −0 args.c
  15. +59 −0 args.h
  16. +106 −0 asm.c
  17. +170 −0 asp.c
  18. +81 −0 awk.c
  19. +324 −0 beta.c
  20. +2,334 −0 c.c
  21. +82 −0 cobol.c
  22. +373 −0 configure.in
  23. +1,585 −0 ctags.1
  24. +27 −0 ctags.h
  25. +18 −0 ctags.lsm
  26. +42 −0 ctags.spec
  27. +116 −0 debug.c
  28. +71 −0 debug.h
  29. +68 −0 descrip.mms
  30. +984 −0 eiffel.c
  31. +822 −0 entry.c
  32. +98 −0 entry.h
  33. +1,684 −0 fortran.c
  34. +232 −0 general.h
  35. +622 −0 get.c
  36. +50 −0 get.h
  37. +253 −0 keyword.c
  38. +33 −0 keyword.h
  39. +139 −0 lisp.c
  40. +273 −0 mac.c
  41. +143 −0 mac.h
  42. +21 −0 magic.diff
  43. +1,385 −0 main.c
  44. +83 −0 main.h
  45. +393 −0 maintainer.mak
  46. +103 −0 make.c
  47. +46 −0 mk_bc3.mak
  48. +70 −0 mk_bc5.mak
  49. +13 −0 mk_djg.mak
  50. +59 −0 mk_manx.mak
  51. +26 −0 mk_ming.mak
  52. +118 −0 mk_mpw.mak
  53. +55 −0 mk_mvc.mak
  54. +83 −0 mk_os2.mak
  55. +93 −0 mk_qdos.mak
  56. +57 −0 mk_sas.mak
  57. +40 −0 mkinstalldirs
  58. +1,629 −0 options.c
  59. +140 −0 options.h
  60. +648 −0 parse.c
  61. +118 −0 parse.h
  62. +46 −0 parsers.h
  63. +257 −0 pascal.c
  64. +118 −0 perl.c
  65. +108 −0 php.c
  66. +118 −0 python.c
  67. +106 −0 qdos.c
  68. +524 −0 read.c
  69. +122 −0 read.h
  70. +736 −0 readtags.c
  71. +149 −0 readtags.h
  72. +688 −0 regex.c
  73. +39 −0 rexx.c
  74. +139 −0 ruby.c
  75. +111 −0 scheme.c
  76. +110 −0 sh.c
  77. +37 −0 slang.c
  78. +221 −0 sort.c
  79. +32 −0 sort.h
  80. +79 −0 source.mak
  81. +221 −0 strlist.c
  82. +51 −0 strlist.h
  83. +83 −0 tcl.c
  84. +135 −0 vim.c
  85. +212 −0 vstring.c
  86. +71 −0 vstring.h
  87. +40 −0 yacc.c
View
@@ -0,0 +1,7 @@
+configure
+config.h.in
+ctags.html
+.o
+.od
+ctags
+dctags
View
340 COPYING

Large diffs are not rendered by default.

Oops, something went wrong.
View
@@ -0,0 +1,212 @@
+<html>
+<head>
+<title>Exuberant Ctags: Adding a new parser</title>
+</head>
+<body>
+
+<h1>How to Add a New Parser to Exuberant Ctags</h1>
+
+<b>Exuberant Ctags</b> has been designed to make it very easy to add your own
+custom language parser.
+
+<h2>Operational background</h2>
+As ctags considers each file name, it tries to determine the language of the
+file by applying the following three tests in order: if the file extension has
+been mapped to a language, if the file name matches a shell pattern mapped to
+a language, and finally if the file is executable and its first line specifies
+an interpreter using the Unix-style "#!" specification (if supported on the
+platform). If a language was identified, the file is opened and then the
+appropriate language parser is called to operate on the currently open file.
+The parser parses through the file and whenever it finds some interesting
+token, calls a function to define a tag entry.
+
+<h2>Integrating a new parser</h2>
+
+Let's assume that I want to add support for my new language, <em>Swine</em>,
+the successor to Perl (i.e. Perl before Swine &lt;wince&gt;).
+
+<p>
+First, I create a new module, <code>swine.c</code>, and add one externally
+visible function to it, <code>extern parserDefinition *SwineParser(void)</code>,
+and add its name to the table in <code>parsers.h</code>. The job of this
+parser definition function is to create an instance of the
+<code>parserDefinition</code> structure (using <code>parserNew()</code>) and
+populate it with information defining how files of this language are
+recognized, what kinds of tags it can locate, and the function used to invoke
+the parser on the currently open file.
+
+<p>
+The structure <code>parserDefinition</code> allows assignment of the following
+fields:
+
+<p>
+<pre>
+ const char *name; /* name of language */
+ kindOption *kinds; /* tag kinds handled by parser */
+ unsigned int kindCount; /* size of `kinds' list */
+ const char *const *extensions; /* list of default extensions */
+ const char *const *patterns; /* list of default file name patterns */
+ parserInitialize initialize; /* initialization routine, if needed */
+ simpleParser parser; /* simple parser (common case) */
+ rescanParser parser2; /* rescanning parser (unusual case) */
+ boolean regex; /* is this a regex parser? */
+</pre>
+
+<p>
+The <code>name</code> field must be set to a non-empty string. Also, unless
+<code>regex</code> is set true (see below), either <code>parser</code> or
+<code>parser2</code> must set to point to a parsing routine which will
+generate the tag entries. All other fields are optional.
+
+<p>
+Now all that is left is to implement the parser. In order to do its job, the
+parser should read the file stream using using one of the two I/O interfaces:
+either the character-oriented <code>fileGetc()</code>, or the line-oriented
+<code>fileReadLine()</code>. When using <code>fileGetc()</code>, the parser
+can put back a character using <code>fileUngetc()</code>. How our Swine parser
+actually parses the contents of the file is entirely up to the writer of the
+parser--it can be as crude or elegant as desired. You will note a variety of
+examples from the most complex (c.c) to the simplest (make.c).
+
+<p>
+When the Swine parser identifies an interesting token for which it wants to
+add a tag to the tag file, it should create a <code>tagEntryInfo</code>
+structure and initialize it by calling <code>initTagEntry()</code>, which
+initializes defaults and fills information about the current line number and
+the file position of the beginning of the line. After filling in information
+defining the current entry (and possibly overriding the file position or other
+defaults), the parser passes this structure to <code>makeTagEntry()</code>.
+
+<p>
+Instead of writing a parser, it may be possible to specify regular expressions
+which define the tags. In this case, instead of defining a parsing function,
+<code>SwineParser()</code>, sets <code>regex</code> to true, and points
+<code>initialize</code> to a function which calls
+<code>addLanguageRegex()</code> to install the regular expressions which
+define its tags.
+
+<p>
+This is all there is to it. All other details are specific to the parser and
+how it wants to do its job. There are some support functions which can take
+care of some commonly needed parsing tasks, such as keyword table lookups (see
+keyword.c), which you can make use of if desired (examples of its use can be
+found in c.c, eiffel.c, and fortran.c). Almost everyting is already taken care
+of automatically for you by the infrastructure. Writing the actual parsing
+algorithm is the hardest part, but is not constrained by any need to conform
+to anything in ctags other than that mentioned above.
+
+<p>
+There are several different approaches used in the parsers inside <b>Exuberant
+Ctags</b> and you can browse through these as examples of how to go about it.
+
+<h2>Examples</h2>
+
+ Below you will find two example parsers. The first is for our mythical Swine
+ parser, which provides tags for lines beginning with "<CODE>def</CODE>"
+ followed by some name. The second is a simple regex parser for makefile
+ macros.
+
+<pre>
+/***************************************************************************
+ * swine.c
+ * Parser for Swine definitions
+ **************************************************************************/
+/* INCLUDE FILES */
+#include "general.h" /* always include first */
+
+#include &lt;string.h&gt; /* to declare strxxx() functions */
+#include &lt;string.h&gt; /* to define isxxx() macros */
+
+#include "parse.h" /* always include */
+#include "read.h" /* to define file fileReadLine() */
+
+/* DATA DEFINITIONS */
+typedef enum eSwineKinds {
+ K_DEFINE
+} swineKind;
+
+static kindOption SwineKinds [] = {
+ { TRUE, 'd', "definition", "pig definition" }
+};
+
+/* FUNCTION DEFINITIONS */
+
+static void findSwineTags (void)
+{
+ vString *name = vStringNew ();
+ const unsigned char *line;
+
+ while ((line = fileReadLine ()) != NULL)
+ {
+ /* Look for a line beginning with "def" followed by name */
+ if (strncmp ((const char*) line, "def", (size_t) 3) == 0 &amp;&amp;
+ isspace ((int) line [3]))
+ {
+ const unsigned char *cp = line + 4;
+ while (isspace ((int) *cp))
+ ++cp;
+ while (isalnum ((int) *cp) || *cp == '_')
+ {
+ vStringPut (name, (int) *cp);
+ ++cp;
+ }
+ vStringTerminate (name);
+ makeSimpleTag (name, SwineKinds, K_DEFINE);
+ vStringClear (name);
+ }
+ }
+ vStringDelete (name);
+}
+
+/* Create parser definition stucture */
+extern parserDefinition* SwineParser (void)
+{
+ static const char *const extensions [] = { "swn", NULL };
+ parserDefinition* def = parserNew ("Swine");
+ def-&gt;kinds = SwineKinds;
+ def-&gt;kindCount = KIND_COUNT (SwineKinds);
+ def-&gt;extensions = extensions;
+ def-&gt;parser = findSwineTags;
+ return def;
+}
+</pre>
+
+
+<pre>
+/***************************************************************************
+ * make.c
+ * Regex-based parser for makefile macros
+ **************************************************************************/
+/* INCLUDE FILES */
+#include "general.h" /* always include first */
+#include "parse.h" /* always include */
+
+/* FUNCTION DEFINITIONS */
+
+static void installMakefileRegex (const langType language)
+{
+ addLanguageRegex (language, "/(^|[ \t])([A-Z0-9_]+)[ \t]*:?=/\\2/m,macro/i");
+}
+
+/* Create parser definition stucture */
+extern parserDefinition* MakefileParser (void)
+{
+ static const char *const patterns [] = { "[Mm]akefile", NULL };
+ static const char *const extensions [] = { "mak", NULL };
+ parserDefinition* const def = parserNew ("Makefile");
+ def-&gt;patterns = patterns;
+ def-&gt;extensions = extensions;
+ def-&gt;initialize = installMakefileRegex;
+ def-&gt;regex = TRUE;
+ return def;
+}
+</pre>
+
+<hr>
+<a href="http:index.html">
+ <img align=left border=0 src="http:../images/return.gif" alt="Return">
+ Back to <strong>Exuberant Ctags</strong>
+</a>
+
+</body>
+</html>
Oops, something went wrong.

0 comments on commit 759ae2c

Please sign in to comment.