www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - "Try it now"

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
I'm quite excited about the new look of std (right now realized only by 
http://d-programming-language.org/phobos-prerelease/std_algorithm.html). 
Here's a suggestion on how we could improve it more.

Adam wrote an in-browser evaluator for D programs. These, when presented 
on the homepage with "hello, world" in them are of limited usefulness. 
However, a personalized "try it now" button present for _each_ artifact 
in an std module would be of great usefulness.

When I try some html or javascript I find it very useful to go to one of 
those sites that allow me to try some code right then and there. The key 
aspect is that the code edit field is already filled with code that is 
close to what I'm looking for, which I can then edit and try until it 
does what I want.

Similarly, it would be great if next to e.g. 
http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion 
there would be a "Try it now" button. Clicking on that button would open 
an overlay with an edit window. The edit window initially contains the 
example text:

unittest
{
   int[] a = [ 1, 2, 4, 5, 7, 9 ];
   int[] b = [ 0, 1, 2, 4, 7, 8 ];
   int[] c = [ 10 ];
   assert(setUnion(a, b).length == a.length + b.length);
   assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
   assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9, 
10][]));
}

Then the user can change, compile, and run that program, to ultimately 
close the overlay and return to the documentation.

What do you think? This would require some work in the compiler (make 
unittests documentable, make their text available to ddoc macros) and 
some work in the front end. I hope this catches the fancy of e.g. 
Walter/Don and Adam.


Andrei
Apr 13 2011
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Andrei wrote:
 Adam wrote an in-browser evaluator for D programs. These, when
 presented on the homepage with "hello, world" in them are of
 limited usefulness.
 However, a personalized "try it now" button present for _each_
 artifact in an std module would be of great usefulness.

Indeed. I actually wrote a little javascript thing for that new home page that's reusable across other ddoc or similar sites. Check it out: http://arsdnet.net/d-web-site/std_algorithm2.html Every time it sees a d_code block, the script adds a button. Hit the button, and you can edit the code and send it off to my completelyexpendable vm to compile and run it. (It's also on my not-quite-done newsreader so example code in newsgroup posts are detected and made editable. That's less perfect since it's trying to pick code out of unstructured text, but it works reasonably well.) Of course, most examples fail to actually compile... but maybe a few replacement rules for the text - automatically insert main() if it's not there, import std.all or similar at the top, replace "..." with some generic data. I think we could make the examples work with just a few lines of code. Unittests are a different story though, since their code isn't in the HTML today. If dmd did make it available though, this same script should work on it.
Apr 13 2011
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/13/11 3:54 PM, Adam D. Ruppe wrote:
 Andrei wrote:
 Adam wrote an in-browser evaluator for D programs. These, when
 presented on the homepage with "hello, world" in them are of
 limited usefulness.
 However, a personalized "try it now" button present for _each_
 artifact in an std module would be of great usefulness.

Indeed. I actually wrote a little javascript thing for that new home page that's reusable across other ddoc or similar sites. Check it out: http://arsdnet.net/d-web-site/std_algorithm2.html Every time it sees a d_code block, the script adds a button. Hit the button, and you can edit the code and send it off to my completelyexpendable vm to compile and run it. (It's also on my not-quite-done newsreader so example code in newsgroup posts are detected and made editable. That's less perfect since it's trying to pick code out of unstructured text, but it works reasonably well.) Of course, most examples fail to actually compile... but maybe a few replacement rules for the text - automatically insert main() if it's not there, import std.all or similar at the top, replace "..." with some generic data. I think we could make the examples work with just a few lines of code.

Whoa, what a coincidence we were thinking along the same lines (never saw that). To take this to pro level: * Button shold be on the same like as "Example:" and spell "Try now". Maybe a more attractive shape/icon could help too. * Once pressed, the subsequent edit should contain a "Cancel" that undoes the action. * The compilation/running results should come in a nice inline variable-height stdout after the edit window, not in a new undecorated page. I wouldn't mind some "terminal" color scheme for that stdout with e.g. green on black letters or whatnot. Anyhow, the entire edit/compile/run flow should be very very smooth. * Syntax highlighting in the editor :o)
 Unittests are a different story though, since their code isn't
 in the HTML today. If dmd did make it available though, this same
 script should work on it.

Agreed. For now it would be terrific if you could take this proof of concept full course. I'll be waiting for your diff request! Thanks, Andrei
Apr 13 2011
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu wrote:
 To take this to pro level:
 * Button shold be on the same like as "Example:" and spell "Try
 now". Maybe a more attractive shape/icon could help too.
 * Once pressed, the subsequent edit should contain a "Cancel" that
 undoes the action.
 * The compilation/running results should come in a nice inline
 variable-height stdout after the edit window

Got partially there. Can't spend too much time on this right now, got some work projects that need to be finished by friday. I'm pretty sure I can finish them in a day if I have to... but I don't want to have to. Anyway take a look. This is where I'll leave it until the weekend: http://arsdnet.net/d-web-site/std_algorithm2.html Changes: * added some border-radius to the buttons. (this is actually controlled in css - button.try-now {} * Changed the text. * Added cancel button. * Added boilerplate code if it can't find "int main" or "void main". As a result, several of the examples on that page actually compile and run. * Since most of them don't actually output anything, the program now detects output.length == 0 and says "Program run successfully." upon completion to give some feedback. * The output goes into an iframe above the code editor, black on green. The background is changed in css (iframe.try-now) and the foreground is changed in the javascript (due to how iframes work, it sends some desired style to the other server which spits it back out.) * Error messages are modified before being shown to the user so the filename is pretty (always "code.d" instead of sha1hash.d) and the line numbers match up, even if I add boilerplate. * Included in the boilerplate are: import std.stdio; import std.string; import std.conv; import std.algorithm; import std.range; import std.array FIXME: it should import the module you're actually looking at too! As a side note, the compile is a little slow. It caches results based on the code's hash so common examples should be fast, but if you change things, it will take a few seconds. This is by design - that VM's resources are limited on several levels to avoid a naughty program from getting out of control. Alas, to be conservative, it has to assume dmd is potentially naughty too. dmd gets a little more resources than the programs it generates, but not much. Hence, it's a little slow. But I don't think its too bad. Not done: variable height window. The iframe is always a given height. I actually think this works pretty well, but if you strongly disagree I can do some scripts to see about sizing it to it's contents, to a certain degree.
 * Syntax highlighting in the editor :o)

I'm afraid I'll have to say no here... that's a pretty enormous effort to get working well, and I hate javascript too much to spend that kind of time with it. Of course, if someone else has done it, I'm not above a little copy/paste action. If you want to try this on your private copy of the docs, it should be as simple as adding: <script src="http://arsdnet.net/d-web-site/editable_code.js"></script> somewhere in the file. Here's the CSS additions in my copy if you want them too: button.try-now { border-radius: 8px; -moz-border-radius: 8px; -webkit-border-radius: 8px; -o-border-radius: 8px; border: solid 1px #333; float: left; margin-right: 0.4em; } iframe.try-now { display: block; width: 100%; background-color: black; }
Apr 13 2011
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/13/11 5:39 PM, Adam D. Ruppe wrote:
 Andrei Alexandrescu wrote:
 To take this to pro level:
 * Button shold be on the same like as "Example:" and spell "Try
 now". Maybe a more attractive shape/icon could help too.
 * Once pressed, the subsequent edit should contain a "Cancel" that
 undoes the action.
 * The compilation/running results should come in a nice inline
 variable-height stdout after the edit window

Got partially there. Can't spend too much time on this right now, got some work projects that need to be finished by friday. I'm pretty sure I can finish them in a day if I have to... but I don't want to have to. Anyway take a look. This is where I'll leave it until the weekend: http://arsdnet.net/d-web-site/std_algorithm2.html

This is very close already! Two things if you get to work on this for the weekend: * The console window should be of variable height (to fit the text) up to some number of rows (e.g. 40), and then scroll. * The console window should be below, not above the edit window. * The "Compile & Run" button should be "Run" to enhance the feeling of instant execution. * The two buttons should be to the right of "Example:" (with some spacing) * We need to go through all examples and make sure they are compilable... :o) This is a great contribution, Adam. Thank you! Andrei
Apr 13 2011
next sibling parent Daniel Gibson <metalcaedes gmail.com> writes:
Am 14.04.2011 02:37, schrieb Andrei Alexandrescu:
 
 * The "Compile & Run" button should be "Run" to enhance the feeling of
 instant execution.

Well D *is* a compiled language. Also this is an explanation for the user why he doesn't get instant response (but has to wait two seconds or something). Cheer, - Daniel
Apr 13 2011
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
new version of javascript up:
http://arsdnet.net/d-web-site/std_algorithm2.html
Apr 17 2011
next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Adam D. Ruppe:

 new version of javascript up:
 http://arsdnet.net/d-web-site/std_algorithm2.html

I suggest to add a spinning circle for the compilation wait (see Ideone site too). Some comments on the code examples: - The second example for reduce(), the example of group() and minCount(), the third example of remove() need tuple - The example of uninitializedFill, initializeAll and schwartzSort contain dummy ... code - The filter() example gives Error: incompatible types caused by: auto small = filter!("a < 3")(arr); assert(small == [ 1, 2 ]); - Splitter() example gives another Error: incompatible types - the first and second examples of find() gives a import conflict error - The third find() example doesn't find tuple and gives a missing overload error - The example of endsWith() gives algorithm.d(3127): Error: no property 'empty' for type 'char' - findAdjacent() lacks an auto p = ... - balancedParens() gives an assert error - The example of equal() gives a approxEqual error and more - levenshteinDistance() gives Error: static assert "Bad binary function q{toupper(a) == toupper(b)}. You need to use a valid D expression using symbols a of type dchar and b of type dchar." - levenshteinDistanceAndPath() gives a algorithm.d(3975): Error: undefined identifier Range, did you mean alias Range1? - The window formatting of bringToFront() seems wrong - The second and third bringToFront() examples lack SList - The 4th and 5th examples of remove() give an assert error - The topN() example doesn't find "less" - completeSort() gives some problems, maybe it can't find assumeSorted() - makeIndex() example gives a template error - topNCopy() example gives an error, maybe it's wrong - setIntersection() example asserts statically - largestPartialIntersection() and largestPartialIntersectionWeighted() can't find Tuple Thank you for reminding me how hugely useful is the Python doctests module :-) Bye, bearophile
Apr 17 2011
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 04/17/2011 02:00 PM, bearophile wrote:
 Adam D. Ruppe:

 new version of javascript up:
 http://arsdnet.net/d-web-site/std_algorithm2.html

I suggest to add a spinning circle for the compilation wait (see Ideone site too).

Probably we're good to go without that, but it'll help once the traffic increases :o).
 Some comments on the code examples:

Since you already made a pass, I suggest you write a few pull requests on github that make examples work. Thanks, Andrei
Apr 17 2011
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
bearophile wrote:
 I suggest to add a spinning circle for the compilation wait (see
 Ideone site too).

Am I actually the only person in the world who *hates* those things? I might add it later though.
Apr 17 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 04/17/2011 02:35 PM, Adam D. Ruppe wrote:
 bearophile wrote:
 I suggest to add a spinning circle for the compilation wait (see
 Ideone site too).

Am I actually the only person in the world who *hates* those things? I might add it later though.

I think adding the text to the "Running...\n" as soon as you get the request should help. Andrei
Apr 17 2011
parent Walter Bright <newshound2 digitalmars.com> writes:
On 4/17/2011 12:36 PM, Andrei Alexandrescu wrote:
 I think adding the text to the "Running...\n" as soon as you get the request
 should help.

Or: "Please wait while the D-9000 computer boots..."
Apr 17 2011
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 04/17/2011 01:22 PM, Adam D. Ruppe wrote:
 new version of javascript up:
 http://arsdnet.net/d-web-site/std_algorithm2.html

Great. I think this looks adequate now and ready for integration into d-programming-language.org. Adam, could you please put together a pull request on github? I'd also appreciate if you sent my way a simple script that scrapes the HTML for all sample code so we can work on making them work. Thanks, Andrei
Apr 17 2011
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu wrote:
 Adam, could you please put together a pull request on github?

I've gotta figure out how that works...
 I'd also appreciate if you sent my way a simple script that scrapes
 the HTML for all sample code so we can work on making them work.

Heh, what a coincidence. I just wrote a quick one now: http://arsdnet.net/d-web-site/extractexamples.d It's cgi so you can see the output here, but it's trivial to change, very short program. Fetch my dom library here http://arsdnet.net/d-web-site/arsd/dom.d Example output: http://arsdnet.net/d-web-site/extractexamples It puts in some generic imports, an empty main, and wraps everything in unittest {}.
Apr 17 2011
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 04/17/2011 02:29 PM, Adam D. Ruppe wrote:
 Andrei Alexandrescu wrote:
 Adam, could you please put together a pull request on github?

I've gotta figure out how that works...
 I'd also appreciate if you sent my way a simple script that scrapes
 the HTML for all sample code so we can work on making them work.

Heh, what a coincidence. I just wrote a quick one now: http://arsdnet.net/d-web-site/extractexamples.d It's cgi so you can see the output here, but it's trivial to change, very short program. Fetch my dom library here http://arsdnet.net/d-web-site/arsd/dom.d Example output: http://arsdnet.net/d-web-site/extractexamples It puts in some generic imports, an empty main, and wraps everything in unittest {}.

Looking good. Hmmm, I think we should just compile code as it is, no hidden artifacts. Then that adds some syntactic noise. Not sure what the best balance is. Andrei
Apr 17 2011
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 04/17/2011 02:29 PM, Adam D. Ruppe wrote:
 Andrei Alexandrescu wrote:
 Adam, could you please put together a pull request on github?

I've gotta figure out how that works...

Oh, and I think learning git/github is a huge net gain outside of any particular project. I warmly recommend it. Andrei
Apr 17 2011
parent Adam D. Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu wrote:
 Oh, and I think learning git/github is a huge net gain outside of
 any particular project. I warmly recommend it.

Yeah, I've used git before on the command line, but never the website. I'll admit though that for my typical project, my idea of source control is commenting and/or remembering how many times to hit undo in the editor... But when I dive into this, most the change is trivial - the script and server side program do almost all the work. But I'd like to at the least fix some invalid html in std.ddoc too. Both browser scripts and my D dom module are able to figure it out anyway, but it'd be nice if the HTML was more well formed and maybe using better semantic tags/classnames.
Apr 17 2011
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 04/17/2011 01:22 PM, Adam D. Ruppe wrote:
 new version of javascript up:
 http://arsdnet.net/d-web-site/std_algorithm2.html

One more thing: make sure you solve potential cross-site scripting that may occur, and prepare for seeing a fair amount of extra traffic. In the long run we'll prepare d-programming-language.org to handle the examples itself. Thanks, Andrei
Apr 17 2011
parent Adam D. Ruppe <destructionator gmail.com> writes:
Andrei Alexandrescu wrote:
 One more thing: make sure you solve potential cross-site scripting
 that may occur

I don't think any are possible - I always escape input and output, and if something does get through, it's on a different domain so the browser's cross domain restriction will keep it from getting too bad. (Indeed, these restrictions made the auto-resize a real pain in the ass!)
 and prepare for seeing a fair amount of extra traffic.

Naturally.
Apr 17 2011
prev sibling next sibling parent reply KennyTM~ <kennytm gmail.com> writes:
On Apr 18, 11 02:22, Adam D. Ruppe wrote:
 new version of javascript up:
 http://arsdnet.net/d-web-site/std_algorithm2.html

There are some minor styling bugs. I've only tested it on Chrome 10. For Example: code blocks: 1. Press "Try Now", then "Cancel" - the code block becomes bold. 2. Click "Try Now" again - the "Cancel" is now in the other line For non-Example: code blocks: 1. The "Try Now" button appear below the code. 2. Click "Try Now" and "Cancel" moves the button above the code. ---- Also, I suggest the try-now examples should allow using a different piece of code than the one shown. For instance, the introductory code (the sort one) of the std.algorithm module clearly shows what the module does, but it absolutely useless for Try-Now. The result is "Program ran successfully.", so what? The user should be able to see how the array is sorted, how to provide a custom predicate, etc., and thus writeln's need to be placed after the 3 sorts. This can't be automated by Javascript. I like the w3schools approach (except the new window part), where the main page shows a concise example to let people understand how the feature is used, and the "Try it yourself" link provides a complete program with human-readable output.
Apr 17 2011
parent Adam D. Ruppe <destructionator gmail.com> writes:
KennyTM~ wrote:
 There are some minor styling bugs. I've only tested it on Chrome 10.

Oh, I see it too. Fixed.
Apr 17 2011
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 4/17/2011 11:22 AM, Adam D. Ruppe wrote:
 new version of javascript up:
 http://arsdnet.net/d-web-site/std_algorithm2.html

Adam, this is really awesome work! Some trivial nits: 1. The output window is offset 3 or 4 pixels to the left of the source window. 2. The source window has a 1 pixel box around it. The output window has a two pixel border on the left and top sides only. This makes it look out of place. 3. The lime-green-on-white text in the output window is a little hard to read comfortably. Perhaps a darker green? I'm running IE9 in case these issues are browser specific.
Apr 17 2011
prev sibling parent Bruno Medeiros <brunodomedeiros+spam com.gmail> writes:
On 13/04/2011 23:39, Adam D. Ruppe wrote:
 * Syntax highlighting in the editor :o)

effort to get working well, and I hate javascript too much to spend that kind of time with it. Of course, if someone else has done it, I'm not above a little copy/paste action.

Hum, this seems like the kinds of things where the new Eclipse Orion project might be interesting and useful to integrate with: http://www.eclipse.org/orion/ -- Bruno Medeiros - Software Engineer
Apr 20 2011
prev sibling parent Matthias Pleh <jens konrad.net> writes:
[..snip..]

Hey, that's so awesome, guys!
Keep up that work :)

°Matthias
Apr 13 2011
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
That is so awesome, great job Adam!

Now I *finally* have an excuse for those reports I made of examples
which don't compile (where the response was "nobody said examples
/have/ to compile, they're just demonstrations..").
Apr 13 2011
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 4/13/2011 1:54 PM, Adam D. Ruppe wrote:
 Indeed. I actually wrote a little javascript thing for that
 new home page that's reusable across other ddoc or similar
 sites. Check it out:

I think what you've done is very innovative and cool!
Apr 13 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 04/13/2011 10:54 PM, Adam D. Ruppe wrote:
 Andrei wrote:
 Adam wrote an in-browser evaluator for D programs. These, when
 presented on the homepage with "hello, world" in them are of
 limited usefulness.
 However, a personalized "try it now" button present for _each_
 artifact in an std module would be of great usefulness.

Indeed. I actually wrote a little javascript thing for that new home page that's reusable across other ddoc or similar sites. Check it out: http://arsdnet.net/d-web-site/std_algorithm2.html Every time it sees a d_code block, the script adds a button. Hit the button, and you can edit the code and send it off to my completelyexpendable vm to compile and run it. (It's also on my not-quite-done newsreader so example code in newsgroup posts are detected and made editable. That's less perfect since it's trying to pick code out of unstructured text, but it works reasonably well.) Of course, most examples fail to actually compile... but maybe a few replacement rules for the text - automatically insert main() if it's not there, import std.all or similar at the top, replace "..." with some generic data. I think we could make the examples work with just a few lines of code. Unittests are a different story though, since their code isn't in the HTML today. If dmd did make it available though, this same script should work on it.

What would be helpful, I guess, to have most examples work as is, is systematically: * put the code in a unitest block * add "void main () {}" * "import std.commonimports;" where commonimports is a to-be-defined module publicly importing common tools from std.* (there was a similar discussion about scripting in D): public import std.stdio : write, writef, writeln, writefln; public import std.string : format, join; public import std.conv : to; ... Denis -- _________________ vita es estrany spir.wikidot.com
Apr 14 2011
prev sibling parent Andrew Wiley <debio264 gmail.com> writes:
On Sun, Apr 17, 2011 at 3:01 PM, Walter Bright
<newshound2 digitalmars.com> wrote:
 On 4/17/2011 12:36 PM, Andrei Alexandrescu wrote:
 I think adding the text to the "Running...\n" as soon as you get the
 request
 should help.

Or: "Please wait while the D-9000 computer boots..."

Or "Must DESTROY John Connor!" The console background is green on black over here on the Chrome 12 dev build, so there's definitely something browser specific going on. And let me join the list of people saying this is friggin awesome. Thanks, Adam!
Apr 17 2011
prev sibling next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Andrei:

 When I try some html or javascript I find it very useful to go to one of 
 those sites that allow me to try some code right then and there. The key 
 aspect is that the code edit field is already filled with code that is 
 close to what I'm looking for, which I can then edit and try until it 
 does what I want.

Time ago Walter said that online ways to try code snippets (like the ideone and codepad sites, and the Microsoft site to try Spec#) are no good. I am glad to see you don't agree :-) As you remember the Go site has a similar window even on the home page (JavaScript required): http://golang.org/
 What do you think?

I think this is a good idea that improves the usefulness of the (now active) documentation. In my opinion it's even going to produce more bug reports for DMD/Phobos. Bye, bearophile
Apr 13 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/13/11 4:26 PM, bearophile wrote:
 Andrei:

 When I try some html or javascript I find it very useful to go to one of
 those sites that allow me to try some code right then and there. The key
 aspect is that the code edit field is already filled with code that is
 close to what I'm looking for, which I can then edit and try until it
 does what I want.

Time ago Walter said that online ways to try code snippets (like the ideone and codepad sites, and the Microsoft site to try Spec#) are no good. I am glad to see you don't agree :-) As you remember the Go site has a similar window even on the home page (JavaScript required): http://golang.org/

I just wrote that examples the likes of golang.org are poor. Andrei
Apr 13 2011
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2011-04-13 22:38, Andrei Alexandrescu wrote:
 I'm quite excited about the new look of std (right now realized only by
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html).
 Here's a suggestion on how we could improve it more.

 Adam wrote an in-browser evaluator for D programs. These, when presented
 on the homepage with "hello, world" in them are of limited usefulness.
 However, a personalized "try it now" button present for _each_ artifact
 in an std module would be of great usefulness.

 When I try some html or javascript I find it very useful to go to one of
 those sites that allow me to try some code right then and there. The key
 aspect is that the code edit field is already filled with code that is
 close to what I'm looking for, which I can then edit and try until it
 does what I want.

 Similarly, it would be great if next to e.g.
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion
 there would be a "Try it now" button. Clicking on that button would open
 an overlay with an edit window. The edit window initially contains the
 example text:

 unittest
 {
 int[] a = [ 1, 2, 4, 5, 7, 9 ];
 int[] b = [ 0, 1, 2, 4, 7, 8 ];
 int[] c = [ 10 ];
 assert(setUnion(a, b).length == a.length + b.length);
 assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
 assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9,
 10][]));
 }

 Then the user can change, compile, and run that program, to ultimately
 close the overlay and return to the documentation.

 What do you think? This would require some work in the compiler (make
 unittests documentable, make their text available to ddoc macros) and
 some work in the front end. I hope this catches the fancy of e.g.
 Walter/Don and Adam.


 Andrei

This is looking better and better each time. One thing I still don't like is the cheat sheet, I think it looks cluttered. I think it's just too much text in most of the rows. The text in the Set operations looks good. I would also prefer more vertical space in some of the examples. I think the first example for the "reduce" function looks good but I find the example for the "filter" function harder to read because there's no empty newlines. -- /Jacob Carlborg
Apr 14 2011
next sibling parent reply spir <denis.spir gmail.com> writes:
On 04/14/2011 11:30 AM, Jacob Carlborg wrote:
 On 2011-04-13 22:38, Andrei Alexandrescu wrote:
 I'm quite excited about the new look of std (right now realized only by
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html).
 Here's a suggestion on how we could improve it more.

 Adam wrote an in-browser evaluator for D programs. These, when presented
 on the homepage with "hello, world" in them are of limited usefulness.
 However, a personalized "try it now" button present for _each_ artifact
 in an std module would be of great usefulness.

 When I try some html or javascript I find it very useful to go to one of
 those sites that allow me to try some code right then and there. The key
 aspect is that the code edit field is already filled with code that is
 close to what I'm looking for, which I can then edit and try until it
 does what I want.

 Similarly, it would be great if next to e.g.
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion
 there would be a "Try it now" button. Clicking on that button would open
 an overlay with an edit window. The edit window initially contains the
 example text:

 unittest
 {
 int[] a = [ 1, 2, 4, 5, 7, 9 ];
 int[] b = [ 0, 1, 2, 4, 7, 8 ];
 int[] c = [ 10 ];
 assert(setUnion(a, b).length == a.length + b.length);
 assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
 assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9,
 10][]));
 }

 Then the user can change, compile, and run that program, to ultimately
 close the overlay and return to the documentation.

 What do you think? This would require some work in the compiler (make
 unittests documentable, make their text available to ddoc macros) and
 some work in the front end. I hope this catches the fancy of e.g.
 Walter/Don and Adam.


 Andrei

This is looking better and better each time. One thing I still don't like is the cheat sheet, I think it looks cluttered. I think it's just too much text in most of the rows.

Agreed. May I suggest an easy (and imo sensible) doc guideline, which would also allow automatising cheat sheet generation? 1. The top line of each doc block defines the *purpose* of the given piece of code (meaning for a func either what value it computes, or what action it performs). 2. This line is taken as is by a cheat sheet generator. Examples: PI /** The value of pi. ... */ struct Circle /** Representation of a circle, as defined by radius & position of center. ... */ size_t indexOf (E elem) // method of some collection type /** Index of first occurrence of elem in collection --else throws IndexError. ... */ void_t erase (E elem) // ditto /** Erase all occurrences of elem in collection. ... */ Denis -- _________________ vita es estrany spir.wikidot.com
Apr 14 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/14/11 6:49 AM, spir wrote:
 On 04/14/2011 11:30 AM, Jacob Carlborg wrote:
 On 2011-04-13 22:38, Andrei Alexandrescu wrote:
 I'm quite excited about the new look of std (right now realized only by
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html).
 Here's a suggestion on how we could improve it more.

 Adam wrote an in-browser evaluator for D programs. These, when presented
 on the homepage with "hello, world" in them are of limited usefulness.
 However, a personalized "try it now" button present for _each_ artifact
 in an std module would be of great usefulness.

 When I try some html or javascript I find it very useful to go to one of
 those sites that allow me to try some code right then and there. The key
 aspect is that the code edit field is already filled with code that is
 close to what I'm looking for, which I can then edit and try until it
 does what I want.

 Similarly, it would be great if next to e.g.
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion

 there would be a "Try it now" button. Clicking on that button would open
 an overlay with an edit window. The edit window initially contains the
 example text:

 unittest
 {
 int[] a = [ 1, 2, 4, 5, 7, 9 ];
 int[] b = [ 0, 1, 2, 4, 7, 8 ];
 int[] c = [ 10 ];
 assert(setUnion(a, b).length == a.length + b.length);
 assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
 assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9,
 10][]));
 }

 Then the user can change, compile, and run that program, to ultimately
 close the overlay and return to the documentation.

 What do you think? This would require some work in the compiler (make
 unittests documentable, make their text available to ddoc macros) and
 some work in the front end. I hope this catches the fancy of e.g.
 Walter/Don and Adam.


 Andrei

This is looking better and better each time. One thing I still don't like is the cheat sheet, I think it looks cluttered. I think it's just too much text in most of the rows.

Agreed. May I suggest an easy (and imo sensible) doc guideline, which would also allow automatising cheat sheet generation? 1. The top line of each doc block defines the *purpose* of the given piece of code (meaning for a func either what value it computes, or what action it performs). 2. This line is taken as is by a cheat sheet generator. Examples: PI /** The value of pi. ... */ struct Circle /** Representation of a circle, as defined by radius & position of center. ... */ size_t indexOf (E elem) // method of some collection type /** Index of first occurrence of elem in collection --else throws IndexError. ... */ void_t erase (E elem) // ditto /** Erase all occurrences of elem in collection. ... */ Denis

I prefer the cheat sheet contain code snippets. They are very terse and eloquent. Andrei
Apr 14 2011
prev sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
If you remove asserts then we're forced to run the examples every time
we want to remind ourselves of what the code does. With assert it's
obvious what the code does.

And besides, why discourage newbies from learning about assert?
Looking at examples with write's could make them think it's a standard
way of debugging code. "Just print all the values, and then check them
one by one to see that they're valid". Let them learn about asserts
and unittests.

Another thing is that I believe most newcomers to D are C/C++
programmers. If we show them how easy it is to check code for
validity, they might start thinking that using asserts and unittests
isn't such a bad thing after all. If you ask an average C++ programmer
whether they use asserts and unittests they'll probably say "No,
because it's too difficult to set up and run them, and I'm too lazy".
Heck, every other day someone comes up with a brand new unittest C++
_library_, and people are completely uninterested.

IMO we shouldn't be hiding D's top features just because they might
look foreign at first.
Apr 14 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 04/13/2011 10:38 PM, Andrei Alexandrescu wrote:
 Similarly, it would be great if next to e.g.
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion
 there would be a "Try it now" button. Clicking on that button would open an
 overlay with an edit window. The edit window initially contains the example
text:

 unittest
 {
    int[] a = [ 1, 2, 4, 5, 7, 9 ];
    int[] b = [ 0, 1, 2, 4, 7, 8 ];
    int[] c = [ 10 ];
    assert(setUnion(a, b).length == a.length + b.length);
    assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
    assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9,
10][]));
 }

 Then the user can change, compile, and run that program, to ultimately close
 the overlay and return to the documentation.

I recently started to realise a side-effect of the unittest feature is to provide D with "free code blocks", where one can just put any piece of code; code that could go on a module's top-level in a dynamic language. Typically, this allows clean trials. Eg, does '/' perform euclidean division or true division, on integers / reals? import std.stdio : writeln; unittest { writeln("ints"); writeln(2/2); writeln(3/2); } unittest { writeln("reals"); writeln(2.0/2); writeln(3.0/2); } void main () {} Sure, one can use main() for this. But unittest blocks are cleaner and allow structuration. In the same vein, unittests can be cleanly used to *demonstrate* language behaviour; for instance in tutorials, when showing issues like on D-leran, or for... bug reports. Denis -- _________________ vita es estrany spir.wikidot.com
Apr 14 2011
prev sibling next sibling parent spir <denis.spir gmail.com> writes:
On 04/14/2011 04:21 PM, Andrei Alexandrescu wrote:
 On 4/14/11 6:49 AM, spir wrote:
 On 04/14/2011 11:30 AM, Jacob Carlborg wrote:
 On 2011-04-13 22:38, Andrei Alexandrescu wrote:
 I'm quite excited about the new look of std (right now realized only by
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html).
 Here's a suggestion on how we could improve it more.

 Adam wrote an in-browser evaluator for D programs. These, when presented
 on the homepage with "hello, world" in them are of limited usefulness.
 However, a personalized "try it now" button present for _each_ artifact
 in an std module would be of great usefulness.

 When I try some html or javascript I find it very useful to go to one of
 those sites that allow me to try some code right then and there. The key
 aspect is that the code edit field is already filled with code that is
 close to what I'm looking for, which I can then edit and try until it
 does what I want.

 Similarly, it would be great if next to e.g.
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion


 there would be a "Try it now" button. Clicking on that button would open
 an overlay with an edit window. The edit window initially contains the
 example text:

 unittest
 {
 int[] a = [ 1, 2, 4, 5, 7, 9 ];
 int[] b = [ 0, 1, 2, 4, 7, 8 ];
 int[] c = [ 10 ];
 assert(setUnion(a, b).length == a.length + b.length);
 assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
 assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9,
 10][]));
 }

 Then the user can change, compile, and run that program, to ultimately
 close the overlay and return to the documentation.

 What do you think? This would require some work in the compiler (make
 unittests documentable, make their text available to ddoc macros) and
 some work in the front end. I hope this catches the fancy of e.g.
 Walter/Don and Adam.


 Andrei

This is looking better and better each time. One thing I still don't like is the cheat sheet, I think it looks cluttered. I think it's just too much text in most of the rows.

Agreed. May I suggest an easy (and imo sensible) doc guideline, which would also allow automatising cheat sheet generation? 1. The top line of each doc block defines the *purpose* of the given piece of code (meaning for a func either what value it computes, or what action it performs). 2. This line is taken as is by a cheat sheet generator. Examples: PI /** The value of pi. ... */ struct Circle /** Representation of a circle, as defined by radius & position of center. ... */ size_t indexOf (E elem) // method of some collection type /** Index of first occurrence of elem in collection --else throws IndexError. ... */ void_t erase (E elem) // ditto /** Erase all occurrences of elem in collection. ... */ Denis

I prefer the cheat sheet contain code snippets. They are very terse and eloquent. Andrei

Right. Sounds sensible. Denis -- _________________ vita es estrany spir.wikidot.com
Apr 14 2011
prev sibling parent reply Gerrit Wichert <gwichert yahoo.com> writes:
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Am 13.04.2011 22:38, schrieb Andrei Alexandrescu:
 I'm quite excited about the new look of std (right now realized only 
 by 
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html). 

I just had a look and stumbled over the short description of group: <http://d-programming-language.org/phobos-prerelease/std_algorithm.html#group> group([5, 2, 2, 3, 3]) returns a range containing the tuples tuple(5, 1), tuple(5, 1), tuple(2, 2), and tuple(3, 2). there seems to be one 'touple(5, 1)' too much.
Apr 14 2011
parent reply David Nadlinger <see klickverbot.at> writes:
On 4/14/11 9:38 PM, Gerrit Wichert wrote:
 Am 13.04.2011 22:38, schrieb Andrei Alexandrescu:
 I'm quite excited about the new look of std (right now realized only
 by
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html).

I just had a look and stumbled over the short description of group: <http://d-programming-language.org/phobos-prerelease/std_algorithm.html#group> group([5, 2, 2, 3, 3]) returns a range containing the tuples tuple(5, 1), tuple(5, 1), tuple(2, 2), and tuple(3, 2). there seems to be one 'touple(5, 1)' too much.

This is already fixed in Git, but Andrei apparently didn't get around to update the build on the website – thanks anyway. David
Apr 14 2011
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/14/11 3:00 PM, David Nadlinger wrote:
 On 4/14/11 9:38 PM, Gerrit Wichert wrote:
 Am 13.04.2011 22:38, schrieb Andrei Alexandrescu:
 I'm quite excited about the new look of std (right now realized only
 by
 http://d-programming-language.org/phobos-prerelease/std_algorithm.html).

I just had a look and stumbled over the short description of group: <http://d-programming-language.org/phobos-prerelease/std_algorithm.html#group> group([5, 2, 2, 3, 3]) returns a range containing the tuples tuple(5, 1), tuple(5, 1), tuple(2, 2), and tuple(3, 2). there seems to be one 'touple(5, 1)' too much.

This is already fixed in Git, but Andrei apparently didn't get around to update the build on the website – thanks anyway. David

BTW there is a proposal to change group to yield a range of ranges instead of a range of tuples. Do you folks estimate this could cause significant harm to existing code? Thanks, Andrei
Apr 14 2011
parent reply bearophile <bearophileHUGS lycos.com> writes:
Andrei:

 BTW there is a proposal to change group to yield a range of ranges 
 instead of a range of tuples.
 
 Do you folks estimate this could cause significant harm to existing code?

This proposal makes group closer to the semantics of the Python itertools.groupby. This change doesn't harm my code significantly. But in my Python code most times I use groupby I have to convert the inner generator (the inner range) in something eager. So for me the current behaviour of group is OK. What are the reasons to change it? Bye, bearophile
Apr 14 2011
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 4/14/11 3:31 PM, bearophile wrote:
 Andrei:

 BTW there is a proposal to change group to yield a range of ranges
 instead of a range of tuples.

 Do you folks estimate this could cause significant harm to existing code?

This proposal makes group closer to the semantics of the Python itertools.groupby. This change doesn't harm my code significantly. But in my Python code most times I use groupby I have to convert the inner generator (the inner range) in something eager. So for me the current behaviour of group is OK. What are the reasons to change it? Bye, bearophile

The reasons for changing is that often you have groups in which elements are not identical, but instead in the same equivalence class. So you want not only their number - you want to take a look at the actual items. (Consider e.g. grouping some strings by their length.) Andrei
Apr 14 2011