Jo�o Abecasis <[EMAIL PROTECTED]> writes:
> David Abrahams wrote:
>> Joel de Guzman <[EMAIL PROTECTED]> writes:
>>> I'd also want to know the objectives of the system
>> The main objective was to get some automated testing for the code
>> examples in our book. Really, that's all! ;-)
>>
>>>and how it addresses that. Oh sure, it's a literate programming
>>>system, but I do not see the connection with that and having the
>>> ability to preprocess
>> Well, we have code examples that show the Boost PP lib. We need to
>> be
>> able to test that they do what we thought.
>>
>>>or check for specific strings in the output,
>>
>> We have examples whose correctness can only be tested well by
>> verifying that they produce a particular output on stdio. Standard
>> code testing stuff. Only this time, most of the code and all the
>> instructions about what to do with it are embedded in the source text
>> of the book.
>
> Well, here's a very rudimentary and not very thought out proposal that
> may get us started on the processing of doc-related-code...
>
> [process command args]
>
> ... content ...
>
> [endprocess]
>
> The 'process' directive shall execute 'command' passing it the specified
> 'args' as command line arguments. The content of the process directive
> will be used as standard input for the command.
>
> 'command' shall be a platform and toolset independent command (I'm
> imagining some promiscuity between bjam and quickbook here... perhaps
> quickbook can invoke bjam for these steps).
>
> 'args' may include names of external files (this includes collector's
> with a file name) and names of collectors.
>
> Both stdout and stderr of the invoked command may be made available for
> inclusion in the docs in an as yet unspecified manner (proposals
> welcome!) or may be output to quickbook's stdout/stderr also in an as
> yet unspecified manner.
>
> There might also be interest in redirecting stdout/stderr through
> another processing step.
>
> Would something like this (but actually working and with a nice syntax
> ;) ) do?
My experience tells me it's not flexible enough. My litre code really
exploits the flexibility I get with Python. It's not uncommon to need
to make arbitrary substitutions within the example's text before
testing it, not least to deal with <your identifier here>-type
substitutable elements and places where "..." appears to indicate
omitted code. Actually the "..." items are automatically turned into
"/* ... */" by a preprocessing function that we plug in, again
possible because of Python flexibility. But it also records where
they are in the text, so we can tell it to replace the Nth
substitutable or ellipsis element with specific text. Here's another
typical example from chapter 4 of the book:
.. @ def holder_test(expect_error = False):
stack[:0] = holder
example.append("""
int a[4];
holder<int(&)[4]> x(a);
holder<int> y(a[0]);
holder<int[4]> z(a);
""")
compile('all', expect_error = expect_error)
holder_test(expect_error = not 'mwcc' in config.compiler)
This defines a function that
- prepends the contents of a list of previously-collected snippets
(holder) to the stack (a collector singleton)
- appends the given test code to the current (last) example
- compiles everything in the stack together in one translation unit,
with whether an error should be expected determined by an
argument.
Then we invoke the function, expecting an error unless we're testing
with metrowerks (I forget the reason this was needed, but it was). Of
course, we wouldn't define the function if it weren't going to be
reused; we have a sequence of many examples that can be tested with
the same logic, so we use it on each one. expect_error is only ever
true for this first example; none of the others pass an argument.
I could go on with many more such examples, some even more elaborate,
but I think it should be clear from this that the kinds of textual and
logical manipulations an author will need to expressively test all
kinds of examples probably can't be anticipated by the writers of the
quickbook tool. It's better to just bind in a nice dynamic language
so people can do what they need.
Here are some other snippets:
.. @for i,e in enumerate(stack):
if str(e).strip().endswith('>'):
e.wrap('typedef ', '::type t%d;' % i)
e.replace('compare =', '')
else:
e.wrap('''
namespace n%d {
typedef t%d i;
typedef mpl::begin<seq>::type j;
enum { test =
''' % (i, i-1)
, '''
};
BOOST_STATIC_ASSERT(test);
}
''')
stack[0].prepend('''
typedef mpl::vector_c<int, 2, 3, 5, 7> seq;
typedef mpl::int_<4> T;
typedef mpl::less<_,_> compare;
''')
compile('all')
.. @for e in stack: e.wrap('typedef',';')
compile('all')
.. @import tempfile, os
open(os.path.join(tempfile.gettempdir(),'tiny_size_spec.hpp'), 'w'
).write(str(example))
ignore() # The example is in a file now; drop it.
vertical_options = ['-I'+tempfile.gettempdir(), '-c']
compile('all', options = vertical_options, pop = 1)
Then later:
.. @compile('all', options = vertical_options + ['-DTINY_MAX_SIZE=8'])
--
Dave Abrahams
Boost Consulting
www.boost-consulting.com
-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
