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.

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

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.

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

On 2013-03-27 22:54, nazriel wrote:

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

RDMD already has a --main flag and DMD will soon too.

-- 
/Jacob Carlborg

I think it's too fragile to require examples inside docs to be runnable. A better way would be to expose those examples in the code (ie outside of comments). That way, they'll be guaranteed to have correct syntax, be properly syntax highlighted, and stay in sync with code.

here's a simple possibility:

----
/**
Here's a comment before
*/
version(ddocs_example) @runnable unittest{
    assert (rootName("foo") is null);
    assert (rootName("/foo") == "/");
}
version(ddocs_example) @notrunnable unittest{
    //do something not meant to be runnable here
    assert (rootName("/foo") == "/");
}
/**
Here's a comment after
*/
----

This way, DDOC can easily extract version(ddocs_example) unittest
blocks and present them as runnable examples (for the ones marked with
@runnable). dmd's unittesting would run unittest on those.

On Thu, Mar 28, 2013 at 12:18 AM, Jacob Carlborg <doob@me.com> wrote:
> On 2013-03-27 22:54, nazriel wrote:
>
>> Requesting user to edit code first, add main(){} block or fix invalid D code and then run example itself is unacceptable.
>
>
> RDMD already has a --main flag and DMD will soon too.
>
> --
> /Jacob Carlborg

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.

On 03/28/2013 07:18 AM, Jacob Carlborg wrote:
> On 2013-03-27 22:54, nazriel wrote:
>
>> Requesting user to edit code first, add main(){} block or fix invalid D
>> code and then run example itself is unacceptable.
>
> RDMD already has a --main flag and DMD will soon too.
>

Yes, DMD trunk already does that but it doesn't fully address the problem. While in cases like
----
unittest {
    assert(...);
    assert(...);
}
----

it will work fine, it will fail in such scenarios:
----
writeln("Hello world");
----

AFAIK -main flag just slaps void main(){} in dummy file.

-- 
Best regards
Damian Ziemba

On 03/28/2013 07:46 AM, Timothee Cour wrote:
> I think it's too fragile to require examples inside docs to be
> runnable. A better way would be to expose those examples in the code
> (ie outside of comments). That way, they'll be guaranteed to have
> correct syntax, be properly syntax highlighted, and stay in sync with
> code.
>
> here's a simple possibility:
>
> ----
> /**
> Here's a comment before
> */
> version(ddocs_example) @runnable unittest{
>      assert (rootName("foo") is null);
>      assert (rootName("/foo") == "/");
> }
> version(ddocs_example) @notrunnable unittest{
>      //do something not meant to be runnable here
>      assert (rootName("/foo") == "/");
> }
> /**
> Here's a comment after
> */
> ----
>
> This way, DDOC can easily extract version(ddocs_example) unittest
> blocks and present them as runnable examples (for the ones marked with
> @runnable). dmd's unittesting would run unittest on those.
>

This sounds good but won't play good with Phobos developers.
Wraping examples in DDOC macros in the past was already very controversial for them.



-- 
Best regards
Damian Ziemba

On 03/28/2013 09:53 AM, 1100110 wrote:
>
> 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.

Yeah, option 1) may work.
Although in most cases import moduleWeAreIn; isn't enough.
So I guess stabbing default pack of imports maybe necessary.

We can work out this way: Adding JS hash-map that will map Phobos modules to imports pack. Something like this:

imports["std.algorithm"] = "std.algorithm; std.file: write; std.process: shell";

What ya think? It will also allow to resolve symbol conflicts like std.stdio.write vs std.file.write

The default view of example could stay in tact (of course validity of code needs to be fixed anyways), but when you Click edit, script would
wrap example in void main() {} and append import pack I mentioned above.

However I think that option number 2) may be more scalable.
Think about like this:

By default all examples are parsed and every snippet is wrapped in void main(){}.

Script then fetches data for module we are in. Let's say: std.algorithm;

What script gets is:
- imports table - default set of imports that is appended to every snippet in module.
- special cases - snippets marked explicitly may have additional options like: don't append main() block, add additional imports to certain snippet, replace module imports table with fetched ones, add default standard input, add default standard arguments, don't make this snippet runnable etc.

Why it's better than option number 1?
Maintaining this data set is way much more easy because you don't need to edit java script file by hand, compute md5sum, make all necessary changes and then make pull request that may wait a bit in pull request queue. You just enter (for example) http://paste.dlang.org/examples
search for certain example in database, if it doesn't exist you just add it and make all changes you need. Then depending on what way we pick, request is added to queue and moderator accepts it or rejects OR it just works wiki-like, so change is visible after you submit changes.

What you think?
Anyways, if you have any questions feel free to mail me at nazriel@dzfl.pl


-- 
Best regards
Damian Ziemba

On 03/28/2013 12:09 PM, nazriel wrote:
> On 03/28/2013 09:53 AM, 1100110 wrote:
>>
>> 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.
>
> Yeah, option 1) may work.
> Although in most cases import moduleWeAreIn; isn't enough.
> So I guess stabbing default pack of imports maybe necessary.
>
> We can work out this way: Adding JS hash-map that will map Phobos
> modules to imports pack. Something like this:
>
> imports["std.algorithm"] = "std.algorithm; std.file: write; std.process:
> shell";
>
> What ya think? It will also allow to resolve symbol conflicts like
> std.stdio.write vs std.file.write
>
> The default view of example could stay in tact (of course validity of
> code needs to be fixed anyways), but when you Click edit, script would
> wrap example in void main() {} and append import pack I mentioned above.
>
> However I think that option number 2) may be more scalable.
> Think about like this:
>
> By default all examples are parsed and every snippet is wrapped in void
> main(){}.
>
> Script then fetches data for module we are in. Let's say: std.algorithm;
>
> What script gets is:
> - imports table - default set of imports that is appended to every
> snippet in module.
> - special cases - snippets marked explicitly may have additional options
> like: don't append main() block, add additional imports to certain
> snippet, replace module imports table with fetched ones, add default
> standard input, add default standard arguments, don't make this snippet
> runnable etc.
>
> Why it's better than option number 1?
> Maintaining this data set is way much more easy because you don't need
> to edit java script file by hand, compute md5sum, make all necessary
> changes and then make pull request that may wait a bit in pull request
> queue. You just enter (for example) http://paste.dlang.org/examples
> search for certain example in database, if it doesn't exist you just add
> it and make all changes you need. Then depending on what way we pick,
> request is added to queue and moderator accepts it or rejects OR it just
> works wiki-like, so change is visible after you submit changes.
>
> What you think?
> Anyways, if you have any questions feel free to mail me at nazriel@dzfl.pl
>
>

I think you may have hit upon something with part #2.

Stick with the script idea real quick. But make it slightly more generic. How many times have you wished you had a small code example for the immediate thing you want?

I was trying to sell D to my friend, and Bam!  readf's non-obvious blocking behaviour hit me!  So imagine a little script that sits in front of a github repo.(or whatever, the first place to look is API + rosetta code probably.)  You give it the name of a module, or a function, or just straight text with what you want.
It gives you code that it knows imports *and uses* that code.

I can't figure out what's up with readf?  I I now have more than enough public domain examples that (hopefullu..) I'll immediately see the problem.

So, extending that a little further, what if it's a script that can tell what you're looking for that can make specific offers, such as the official documentation.


That would definitely be a worthy project for D-Programming-Language/Tools, IMO.



The script could always sit in front of some website like dpaste, but what if it didn't have to?

That's one thing that's always bothered me, we aspired to that kind of ease of use(rdmd --man, for example) but it was never *quite* good enough to be impressed by.  Or really use, personally.

Imagine it.


$ rdmd --search std.algorithm cartesianproduct
======================================================================
auto N = sequence!"n"(0); 	  // the range of natural numbers
auto N2 = cartesianProduct(N, N);

// the range of all pairs of natural numbers 	
// Various arbitrary number pairs can be found
// in the range in finite time.

assert(canFind(N2, tuple(0, 0)));
assert(canFind(N2, tuple(123, 321)));
assert(canFind(N2, tuple(11, 35)));
assert(canFind(N2, tuple(279, 172)));
======================================================================
More? [Y/n]

$ rdmd --search println
=======================================================================
/// Read until end of file
import std.stdio;

int main() {
	string buf;
	while ((buf = stdin.readln()) !is null)
		write(buf);
	return 0;
}
========================================================================
More? [Y/n]


Best of both worlds!  It should have a full website UI for searching and even editing. Even if rdmd rejects it, that is something that simply must happen!

Am Wed, 27 Mar 2013 22:54:21 +0100
schrieb "nazriel" <spam@dzfl.pl>:

> Greetings.
> 
> I would like to finish Phobos runnable examples case. But I need help in picking one strategy for implementation details.
> 

With the recent unittest-as-example changes I'd say make runnable
examples work with those and promote writing examples as unittests. This
way you know for sure that examples compile. AFAIK there's currently
no way to disambiguate such an example from a handwritten one, but you
could file an enhancement request for that. I'm sure Andrej Mitrovic
would implement that quickly. (We'd just need a DDOC_CHECKED_EXAMPLE
macro to wrap the example).

On Thu, Mar 28, 2013 at 07:25:07PM +0100, Johannes Pfau wrote:
> Am Wed, 27 Mar 2013 22:54:21 +0100
> schrieb "nazriel" <spam@dzfl.pl>:
> 
> > Greetings.
> > 
> > I would like to finish Phobos runnable examples case. But I need help in picking one strategy for implementation details.
> > 
> 
> With the recent unittest-as-example changes I'd say make runnable
> examples work with those and promote writing examples as unittests. This
> way you know for sure that examples compile. AFAIK there's currently
> no way to disambiguate such an example from a handwritten one, but you
> could file an enhancement request for that. I'm sure Andrej Mitrovic
> would implement that quickly. (We'd just need a DDOC_CHECKED_EXAMPLE
> macro to wrap the example).

The unittest examples are already running; so all we need to do to make it independently compilable is to wrap the code inside a unittest block, insert an empty main, and it should work.

Imports may be handled by including code from version(unittest) blocks. I'm not so sure about this, though. IMO, other than the implicit import of the current module, all code examples should always display all imports explicitly so that copy-n-pasting the code into a unittest block will automatically work, no matter what.


T

-- 
There are two ways to write error-free programs; only the third one works.