Phobos runnable examples - ideas request

[Andrei Alexandrescu]

On 3/27/13 5:54 PM, nazriel wrote:
> Greetings.
>
> I would like to finish Phobos runnable examples case. But I need help in
> picking one strategy for implementation details.
>
> Current state of things is rather bad.
> Apart from the fact that lots of examples are not valid examples per se
>
> (first example in std.algorithm:
> ---
> int[] a = ...;
> static bool greater(int a, int b)
> ---
> )
>
> lots of examples have got outdated assertions in the unittest blocks etc.

Thanks for doing this. Incorrect examples are a liability. Examples with 
unspecified portions (ellipsis) are occasionally useful but at best 
should work if e.g. the ellipsis is eliminated. For TDPL I have a 
preprocessor that eliminates (from all examples) lines consisting of 
ellipses and whitespace only before collecting them for compilation.

> Requesting user to edit code first, add main(){} block or fix invalid D
> code and then run example itself is unacceptable.

Agreed.

> Snippets at main dlang.org website work well because all examples are
> valid D code which compiles out of box. While phobos examples are just
> taken out of context.
>
> The options I've gathered so far:
> 1) Make all examples valid D code by hand. Make JavaScript assume that
> all code examples in Phobos documentation should be wrapped in void
> main() {} blocks. Add default set of includes + the module we are on.
> Explicitly mark examples that are full programs (ie. std.concurrency
> ones) and don't append void main() {} blocks to them. Code should be
> already wrapped in main(){} block after clicking Edit button. Append all
> special cases where default stdin and stdargs are needed like it is done
> on main webpage ( http://dlang.org/js/run.js and
> http://dlang.org/js/run-main-website.js )
>
> 2) Make JavaScript assume that all code examples in Phobos documentation
> should be wrapped in void main() {} blocks. Create subpage with
> wiki-like database where special cases would be added and script could
> fetch data from it.
> For example adding default stdin and stdargs arguments and special
> includes.

I kept those that I prefer. How about this 1.5: assume everything should 
be wrapped in void main(){}, EXCEPT if the first like is "#!/bin/env 
rdmd", in which case it's considered a complete script.

One note - scoped imports inside functions still have issues, I assume 
you'll discover some bugs.


Works?

Andrei