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