add example for std.stdio.stdin

[WalterBright]

Also removes some unnecessary trailing whitespace.

[dnadlinger]

Are documented unit tests restricted to functions right now? If not, this should probably be one to prevent bit-rot.

[dnadlinger]

On second thought, why add this example only for stdin? It uses stdout as well, and really is not specific to either of them. Maybe just briefly discuss the fact that stdin/stdout/stderr are just Files in best C/UNIX tradition in the module header documentation, and also add this as an introductory example?

[WalterBright]

A useful example for stdin really needs to be a whole program, not a function.

I struggled to create this program a couple years ago - it covers a number of unclear, implied how-to-use-it aspects of ranges. It does belong in std.stdio, as it illustrates basic use of stdio functions and how they fit together. Putting it under stdin is as good a place as any, as it is the most likely place a new user of stdio will look.

[dnadlinger]

I don't disagree with that. If you want to leave it in the stdin docs, fine with me. It just seemed to me that it would be useful as an example for stdout or any other File I/O just as well. But you are right, users will (or won't) find it either way.

However, please do make it a documented unittest. I just checked and we handle them correctly for non-function symbols as well. If you just copy your whole example code into a unittest block (including the main declaration), then it won't actually be run and the DDoc output will look just the same, yet we can be sure it will continue to compile. We've had enough issues with our doc examples in the past, at least in my opinion.

[WalterBright]

ok

[dnadlinger]

Uh, this somehow seems to crash DMD. Sorry for the hassle.

[WalterBright]

It doesn't crash dmd, it errors with an admonition to use std.algorithm.sort.

I put it back the way it was.

[PetarKirov]

Nitpick: Put brace on separate line and put dots at the beginning of each line:

void main()
{
    stdin                         // read from stdin
      .byLine(KeepTerminator.yes) // a line at a time
      .map!(a => a.idup)          // byLine() reuses its buffer, so copy the lines
      .array                      // convert to array of lines
      .sort                       // sort the lines
      .copy(                      // copy output of .sort to an OutputRange
          stdout.lockingTextWriter());   // the OutputRange
}

I think this is a more established formatting convention for method chaining.
Examples:
D: http://ddili.org/ders/d.en/ufcs.html (see the example at the bottom of the page).
C#: http://visualstudiomagazine.com/Articles/2013/04/10/Essential-Reactive-Extensions.aspx?Page=2
Java: http://www.oracle.com/technetwork/articles/java/ma14-java-se-8-streams-2177646.html

[WalterBright]

I put the { on the same line as main() because vertical space is a bit important now that people view web pages on small screens.

[mihails-strasuns]

This doesn't help much on small screens and make snippets look awkward on normal screen. Also horizontal space is much more important as mobile devices are optimized for vertical scrolling.

[dnadlinger]

Oh, sorry, I was waiting for a C++ project that doesn't use -Werror to compile when I wrote my post and naturally assumed the warning was only informational. That being said, I'd argue that having example code that generates warnings isn't a good idea.

[WalterBright]

I've incorporated all requests. Please pull - Phobos doc desperately needs more examples.

[dnadlinger]

Auto-merge toggled on

[dnadlinger]

Thanks. Although I didn't insist on it here, I think that generally most people would argue that separating out mass white space changes into their own commits is a good idea.

[WalterBright]

Thank you. The whitespace changes came about because I run all code through a filter program, detab and tolf, that converts tabs to spaces, removes trailing whitespace, and ensures consistent LF line endings. I encourage everyone to do the same.

[bearophile]

In modern D it's better to write ".map!idup" instead of ".map!(a => a.idup)".

[andralex]

noice