11f5207b7SJohn Levon 2*efe51d0cSJohn Levon sparse (spärs), adj,., spars-er, spars-est. 31f5207b7SJohn Levon 1. thinly scattered or distributed; "a sparse population" 41f5207b7SJohn Levon 2. thin; not thick or dense: "sparse hair" 51f5207b7SJohn Levon 3. scanty; meager. 61f5207b7SJohn Levon 4. semantic parse 71f5207b7SJohn Levon [ from Latin: spars(us) scattered, past participle of 81f5207b7SJohn Levon spargere 'to sparge' ] 91f5207b7SJohn Levon 101f5207b7SJohn Levon Antonym: abundant 111f5207b7SJohn Levon 121f5207b7SJohn LevonSparse is a semantic parser of source files: it's neither a compiler 131f5207b7SJohn Levon(although it could be used as a front-end for one) nor is it a 141f5207b7SJohn Levonpreprocessor (although it contains as a part of it a preprocessing 151f5207b7SJohn Levonphase). 161f5207b7SJohn Levon 171f5207b7SJohn LevonIt is meant to be a small - and simple - library. Scanty and meager, 181f5207b7SJohn Levonand partly because of that easy to use. It has one mission in life: 191f5207b7SJohn Levoncreate a semantic parse tree for some arbitrary user for further 201f5207b7SJohn Levonanalysis. It's not a tokenizer, nor is it some generic context-free 211f5207b7SJohn Levonparser. In fact, context (semantics) is what it's all about - figuring 221f5207b7SJohn Levonout not just what the grouping of tokens are, but what the _types_ are 231f5207b7SJohn Levonthat the grouping implies. 241f5207b7SJohn Levon 251f5207b7SJohn LevonAnd no, it doesn't use lex and yacc (or flex and bison). In my personal 261f5207b7SJohn Levonopinion, the result of using lex/yacc tends to end up just having to 271f5207b7SJohn Levonfight the assumptions the tools make. 281f5207b7SJohn Levon 291f5207b7SJohn LevonThe parsing is done in five phases: 301f5207b7SJohn Levon 311f5207b7SJohn Levon - full-file tokenization 321f5207b7SJohn Levon - pre-processing (which can cause another tokenization phase of another 331f5207b7SJohn Levon file) 341f5207b7SJohn Levon - semantic parsing. 351f5207b7SJohn Levon - lazy type evaluation 361f5207b7SJohn Levon - inline function expansion and tree simplification 371f5207b7SJohn Levon 381f5207b7SJohn LevonNote the "full file" part. Partly for efficiency, but mostly for ease of 391f5207b7SJohn Levonuse, there are no "partial results". The library completely parses one 401f5207b7SJohn Levonwhole source file, and builds up the _complete_ parse tree in memory. 411f5207b7SJohn Levon 421f5207b7SJohn LevonAlso note the "lazy" in the type evaluation. The semantic parsing 431f5207b7SJohn Levonitself will know which symbols are typedefines (required for parsing C 441f5207b7SJohn Levoncorrectly), but it will not have calculated what the details of the 451f5207b7SJohn Levondifferent types are. That will be done only on demand, as the back-end 461f5207b7SJohn Levonrequires the information. 471f5207b7SJohn Levon 481f5207b7SJohn LevonThis means that a user of the library will literally just need to do 491f5207b7SJohn Levon 501f5207b7SJohn Levon struct string_list *filelist = NULL; 511f5207b7SJohn Levon char *file; 521f5207b7SJohn Levon 531f5207b7SJohn Levon action(sparse_initialize(argc, argv, filelist)); 541f5207b7SJohn Levon 551f5207b7SJohn Levon FOR_EACH_PTR_NOTAG(filelist, file) { 561f5207b7SJohn Levon action(sparse(file)); 571f5207b7SJohn Levon } END_FOR_EACH_PTR_NOTAG(file); 581f5207b7SJohn Levon 591f5207b7SJohn Levonand he is now done - having a full C parse of the file he opened. The 601f5207b7SJohn Levonlibrary doesn't need any more setup, and once done does not impose any 611f5207b7SJohn Levonmore requirements. The user is free to do whatever he wants with the 621f5207b7SJohn Levonparse tree that got built up, and needs not worry about the library ever 631f5207b7SJohn Levonagain. There is no extra state, there are no parser callbacks, there is 641f5207b7SJohn Levononly the parse tree that is described by the header files. The action 651f5207b7SJohn Levonfuntion takes a pointer to a symbol_list and does whatever it likes with it. 661f5207b7SJohn Levon 671f5207b7SJohn LevonThe library also contains (as an example user) a few clients that do the 681f5207b7SJohn Levonpreprocessing, parsing and type evaluation and just print out the 691f5207b7SJohn Levonresults. These clients were done to verify and debug the library, and 701f5207b7SJohn Levonalso as trivial examples of what you can do with the parse tree once it 711f5207b7SJohn Levonis formed, so that users can see how the tree is organized. 72