// Setup basic settings for the preprocessor. The values as shown below
// are the default values and can be omitted.
var settings = { 

   // signal string that starts a preprocessor command, 
   // only honoured at the beginning of a line.
   signal_char : '#',

   // function used to print warnings, the default 
   // implementation logs to the console.
   warn_func : null,

   // function used to print critical errors, the default 
   // implementation logs to the console and throws.
   error_func : null,
   
   // function to be invoked to fetch include files.
   // See the section "Handling include files" below.
   include_func : null,
   
   // function used to strip comments from the input file.
   // The default implementation handles C and C++-style
   // comments and also removes line continuations.
   // Since this function is invoked on all files before
   // any preprocessing happens, it can be thought of as a 
   // "preprocessor to the preprocessor".
   comment_stripper : null
}

// Create an instance of the library. `settings` is optional.
var pp = cpp_js( settings );

// Predefine some symbols, the same effect could be reached
// by prepending the corresponding #define's to the source
// code for preprocessing but this is way nicer.
// cpp.js by itself does not predefine any symbols.
var predefined = {
   DEBUG : '',               // equivalent to `#define DEBUG`
   ANOTHER_DEFINE : '248935' // equivalent to `#define ANOTHER_DEFINE 248935`
};

pp.define_multiple(predefined);

pp.define("macro_with_args(a,b)","a ## b");

pp.undef('DEBUG');
pp.defined('DEBUG'); // => false

// Now invoke the preprocesser on the given text block.
// The processor keeps the state obtained from executing the text 
// block. Therefore, if run() is invoked on multiple text blocks, any
// defines from a block will also apply to its successors.

// However, a text block is assumed to be syntactically complete 
// i.e. all conditional blocks and also all comments must be closed
// and may not leap into the next block.
var preprocessed_source = pp.run(text);

// Calling clear() resets all defined values. The effect is the same as if
// a fresh cpp.js instance with same settings was created.
pp.clear();

var cpp = require("./cpp");
var pp = cpp.create( settings );

// ...
// same as above

settings.include_func = function(file, is_global, resumer, error) {

	// `is_global` is `true` if the file name was enclosed
	// in < .. > rather than " .. ".

    do_fancy_magic_to_fetch_this_file(file, function(contents) {
		// call resumer(null) if the file is not accessible
	   resumer(contents);
	});
};

settings.completion_func = function(preprocessed_text) {
    // process result
};