Stream tutorial broken

[bruce-ricard]

Here is what I see on https://ocaml.org/learn/tutorials/streams.html

# let line_stream_of_channel channel =
    Stream.from
      (fun _ ->
         try Some (input_line channel) with End_of_file -> None);;
File "", line 1:
Error: Reference to undefined global `Stdlib__stream'

# let lines = line_stream_of_string "hello\nworld";;
Error: Unbound value line_stream_of_string
# Stream.peek lines;;
Error: Unbound value lines
# Stream.peek lines;;
Error: Unbound value lines
# Stream.junk lines;;
Error: Unbound value lines
# Stream.peek lines;;
Error: Unbound value lines
# Stream.junk lines;;
Error: Unbound value lines
# Stream.peek lines;;
Error: Unbound value lines

[Chris00]

Thanks for reporting. I know the tutorials about deprecated modules (and those using camlp4) should be modified to incorporate verbatim the output of commands. I'll work on this ASAP.

[bruce-ricard]

I often argue that world facing documentation, especially tutorials, are some of the most important things to get right. We might have lost people to the ocaml community already because they think we are a joke after looking at this doc. That also seems like something that shouldn't take too long to fix, although I don't know :).

[pveber]

It seems the page is still there, although not reachable anymore from the tutorial page. If there's an interest, I could translate it to Seq, but I'm not sure it's worth the trouble if there are no longer term plans.

[dbuenzli]

I could translate it to Seq

Please don't. Seq is the wrong thing to use for dealing with ressources. Sample code doing the wrong things is unproductive for newcomers.

[pveber]

Gasp, I didn't expect you'd be eavesdropping here ;). More seriously, I understand and share your concerns (at least what I've read from you on the inclusion of Seq in the standard library). Ideally, this tutorial should be replaced by another one on more advisable techniques for streaming algorithms, including beginner-friendly solutions. In any case, leaving it in that state is really not that great, so maybe it should be simply removed?

[dbuenzli]

Gasp, I didn't expect you'd be eavesdropping here ;)

🕴

so maybe it should be simply removed?

I think that's the best course of action. Stream has been on the verge of being deprecated for the last past… 6 years. Mentioning it to newcomers seems not to be the best use of their time.

[benjub]

Please don't. Seq is the wrong thing to use

Maybe it would be more useful to tell what the right thing to use is ? As a newcomer, I found https://ocaml.org/learn/tutorials/stream_expressions.html through a duckduckgo search last week, and it seemed to answer perfectly my problem. (I am writing a small lexer that reads a text file as a Stream of characters and returns a Stream of tokens.) What should be used instead of Stream ? (I did not find a clear answer in the thread about deprecation you linked to.) Thanks in advance.

[pveber]

I think there are much better alternatives nowadays, for example you can have a look at angstrom, or menhir for more complex parsers and better error messages in case of syntax errors.

[shonfeder]

I found this issue while I was coming to report the breakage in the tutorial. If I can get clear guidance on what we want to do with this page, I should be able to put some energy into making it happen. I agree with @bruce-ricard that keeping this kind of official stuff in good working order is important, and I'm happy to do what I can to help it stay in order.

I suggest we make the make smallest, and least controversial change to get this fixed up, whether that be removing the page or fixing the compilation errors.

Who is the decider in this realm?

[johnwhitington]

What is the policy on the removal of pages which are unlinked? There seem to be plenty in the source. I would be happy to produce a PR to remove them from the repository if that is what is wanted.

[mseri]

What if we keep the tutorial, translating it to use Seq, just to show how can one do the same with what is in the standard library, and then use this as an opportunity to refer people to re (in place of Str), iter and odis-labs/streaming (instead of Seq), menhir and armstrong (for parsing) with a mention of their relevance and in which case is worth using them?