Phobos runnable examples - ideas request

[1100110]

On 03/27/2013 04:54 PM, nazriel wrote:
[snip]
> 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.
>
> 3) The old macro approach, with wrapping examples in $(D_RUN) macro.
> Probably won't scale now due to "unittest is example" change in DDOC
> generation
>
> 4) Let's just forget about phobos having runnable examples. On the other
> hand I think there aren't much Programming Languages in which stdlib
> documentation has runnable examples. For example Go website has
> dedicated subpage with couple Examples that can be edited and then
> compiled but that's all. Nothing more. Something like main dlang.org
> website now.
>
>
> Sorry for any English related quirks :p
> Looking forward for your opinions on this and any better ideas you may
> have!
>
> Regards,
> Damian Ziemba

I'll work on 1. and see if we can't come up with something better!

The code snippets are pretty much necessary IMO.  They just need to be 
fixed.
----
int[] a = ...;
static bool greater(int a, int b)
{
     return a > b;
}
sort!(greater)(a);  // predicate as alias
sort!("a > b")(a);  // predicate as string
                     // (no ambiguity with array name)
sort(a);            // no predicate, "a < b" is implicit
----


So what about something like this then?
It's not *great*, but it actually runs now.

---- void main() {   import std.algorithm;

     int[] a = [7,5,6];

     bool greater(int a, int b)
     {
         return a > b;
     }
                     	// Here are a few different methods,
			// Please note I'm doing the same work 3 times.
     sort!(greater)(a);  // predicate as alias
     sort!("a > b")(a);  // predicate as string (no ambiguity with array 
name)
     sort(a);            // no predicate, "a < b" is implicit
     assert(isSorted(a));// Proof that it works as expected.

---- }


I was gonna come up with a short script to grab all the examples, but 
apparently github is very protective of out code, and I really don't 
wanna do html...

It'd be great if the js stuck the "void main()" and the imports in for 
us at least.