Print this page
11972 resync smatch
*** 1,3 ****
- There are some documents under the Documentation/ directory.
-
For parsing implicit dependencies, see smatch_scripts/implicit_dependencies.
--- 1,72 ----
For parsing implicit dependencies, see smatch_scripts/implicit_dependencies.
+ =======
+ sparse (spärs), adj,., spars-er, spars-est.
+ 1. thinly scattered or distributed; "a sparse population"
+ 2. thin; not thick or dense: "sparse hair"
+ 3. scanty; meager.
+ 4. semantic parse
+ [ from Latin: spars(us) scattered, past participle of
+ spargere 'to sparge' ]
+
+ Antonym: abundant
+
+ Sparse is a semantic parser of source files: it's neither a compiler
+ (although it could be used as a front-end for one) nor is it a
+ preprocessor (although it contains as a part of it a preprocessing
+ phase).
+
+ It is meant to be a small - and simple - library. Scanty and meager,
+ and partly because of that easy to use. It has one mission in life:
+ create a semantic parse tree for some arbitrary user for further
+ analysis. It's not a tokenizer, nor is it some generic context-free
+ parser. In fact, context (semantics) is what it's all about - figuring
+ out not just what the grouping of tokens are, but what the _types_ are
+ that the grouping implies.
+
+ And no, it doesn't use lex and yacc (or flex and bison). In my personal
+ opinion, the result of using lex/yacc tends to end up just having to
+ fight the assumptions the tools make.
+
+ The parsing is done in five phases:
+
+ - full-file tokenization
+ - pre-processing (which can cause another tokenization phase of another
+ file)
+ - semantic parsing.
+ - lazy type evaluation
+ - inline function expansion and tree simplification
+
+ Note the "full file" part. Partly for efficiency, but mostly for ease of
+ use, there are no "partial results". The library completely parses one
+ whole source file, and builds up the _complete_ parse tree in memory.
+
+ Also note the "lazy" in the type evaluation. The semantic parsing
+ itself will know which symbols are typedefines (required for parsing C
+ correctly), but it will not have calculated what the details of the
+ different types are. That will be done only on demand, as the back-end
+ requires the information.
+
+ This means that a user of the library will literally just need to do
+
+ struct string_list *filelist = NULL;
+ char *file;
+
+ action(sparse_initialize(argc, argv, filelist));
+
+ FOR_EACH_PTR(filelist, file) {
+ action(sparse(file));
+ } END_FOR_EACH_PTR(file);
+
+ and he is now done - having a full C parse of the file he opened. The
+ library doesn't need any more setup, and once done does not impose any
+ more requirements. The user is free to do whatever he wants with the
+ parse tree that got built up, and needs not worry about the library ever
+ again. There is no extra state, there are no parser callbacks, there is
+ only the parse tree that is described by the header files. The action
+ funtion takes a pointer to a symbol_list and does whatever it likes with it.
+
+ The library also contains (as an example user) a few clients that do the
+ preprocessing, parsing and type evaluation and just print out the
+ results. These clients were done to verify and debug the library, and
+ also as trivial examples of what you can do with the parse tree once it
+ is formed, so that users can see how the tree is organized.