Compile examples on the stack, whose topmost item is the last example
        seen but not yet handled so far.

        :howmany: How many of the topmost examples on the stack to compile.
           You can pass a number, or 'all' to indicate that all examples should
           be compiled.

        :pop: How many of the topmost examples to discard.  By default, all of
           the examples that are compiled are discarded.
        
        :expect_error: Whether a compilation error is to be expected.  Any value
           > 1 will cause the expected diagnostic's text to be dumped for
           diagnostic purposes.  It's common to expect an error but see a
           completely unrelated one because of bugs in the example (you can get
           this behavior for all examples by setting show_expected_error_output
           in your config).

        :extension: The extension of the file to build (set to .exe for
           run)

        :options: Compiler flags

        :built_file: A path to use for the built file.  By default, a temp
            filename is conjured up
            
        :built_handler: A function that's called with the name of the built file
           upon success.

        :source_file: The full name of the source file to write
        
        :source_suffix: If source_file is None, the suffix to use for the source file

        :make_comment: A function that transforms text into an appropriate comment.
        
        :command: A function that is passed (includes, opts, target, source), where
           opts is a string representing compiler options, target is the name of
           the file to build, and source is the name of the file into which the
           example code is written.  By default, the function formats
           litre.config.compiler with its argument tuple.

def compile(
          self
        , howmany = 1
        , pop = -1
        , expect_error = False
        , extension = '.o'
        , options = ['-c']
        , built_handler = lambda built_file: None
        , source_file = None
        , source_suffix = '.cpp'
          # C-style comments by default; handles C++ and YACC
        , make_comment = lambda text: '/*\n%s\n*/' % text 
        , built_file = None
        , command = None
        ):
        """
        Compile examples on the stack, whose topmost item is the last example
        seen but not yet handled so far.

        :howmany: How many of the topmost examples on the stack to compile.
           You can pass a number, or 'all' to indicate that all examples should
           be compiled.

        :pop: How many of the topmost examples to discard.  By default, all of
           the examples that are compiled are discarded.
        
        :expect_error: Whether a compilation error is to be expected.  Any value
           > 1 will cause the expected diagnostic's text to be dumped for
           diagnostic purposes.  It's common to expect an error but see a
           completely unrelated one because of bugs in the example (you can get
           this behavior for all examples by setting show_expected_error_output
           in your config).

        :extension: The extension of the file to build (set to .exe for
           run)

        :options: Compiler flags

        :built_file: A path to use for the built file.  By default, a temp
            filename is conjured up
            
        :built_handler: A function that's called with the name of the built file
           upon success.

        :source_file: The full name of the source file to write
        
        :source_suffix: If source_file is None, the suffix to use for the source file

        :make_comment: A function that transforms text into an appropriate comment.
        
        :command: A function that is passed (includes, opts, target, source), where
           opts is a string representing compiler options, target is the name of
           the file to build, and source is the name of the file into which the
           example code is written.  By default, the function formats
           litre.config.compiler with its argument tuple.
        """

        # Grab one example by default
        if howmany == 'all':
            howmany = len(self.stack)

        source = '\n'.join(
            self.prefix
            + [str(x) for x in self.stack[-howmany:]]
            )

        source = reduce(lambda s, f: f(s), self.preprocessors, source)
        
        if pop:
            if pop < 0:
                pop = howmany
            del self.stack[-pop:]
            
        if len(self.stack):
            self.example = self.stack[-1]

        cpp = self._source_file_path(source_file, source_suffix)
            
        if built_file is None:
            built_file = self._output_file_path(source_file, extension)
        
        opts = ' '.join(options)
        
        includes = ' '.join(['-I%s' % d for d in self.includes])
        if not command:
            command = self.config.compiler

        if type(command) == str:
            command = lambda i, o, t, s, c = command: c % (i, o, t, s)
            
        cmd = command(includes, opts, expand_vars(built_file), expand_vars(cpp))

        if expect_error and self.config.show_expected_error_output:
            expect_error += 1


        comment_cmd = command(includes, opts, built_file, os.path.basename(cpp))
        comment = make_comment(config.comment_text(comment_cmd, expect_error))

        self._write_source(cpp, '\n'.join([comment, source]))

        #print 'wrote in', cpp
        #print 'trying command', cmd

        status, output = syscmd(cmd, expect_error)

        if status or expect_error > 1:
            print
            if expect_error and expect_error < 2:
                print 'Compilation failure expected, but none seen'
            print '------------ begin offending source ------------'
            print open(cpp).read()
            print '------------ end offending source ------------'
            
            if self.config.save_cpp:
                print 'saved in', repr(cpp)
            else:
                self._remove_source(cpp)

            sys.stdout.flush()
        else:
            print '.',
            sys.stdout.flush()
            built_handler(built_file)
                
            self._remove_source(cpp)
            
        try:
            self._unlink(built_file)
        except:
            if not expect_error:
                print 'failed to unlink', built_file
        
        return status