tfwright

tfwright

Posting this in discussions because it’s more of an open question about API design/conventions, but while looking through the documentation around streams, I found myself wondering why File includes a stream! function whereas IO has stream. According to specs, both functions appear to work similarly, returning an Enumerable directly (not wrapped in a tuple), and neither mentions any error cases I noticed, so why the different name?

My impression was that there is a pretty strong convention that a ! suffix in a function should always indicate that an error could be expected in certain conditions, whereas a function without ! should never be expected to return an error, but could return either a “status tuple” (actually not sure if there’s a more technical term for {:ok, res}/{:error, res} return values) or a result more directly, which I guess would mean that IO.stream is more “correct,” since, unlike File.read!, File.stream! will not error even when the path is invalid, etc?

Mostly just curious because I am designing a stream API for one of my own modules where most of the functions return status couples, but I don’t foresee any error cases for the streaming API. Appreciate any input!

Showing Posts 1 to 2

al2o3cr

al2o3cr

File.stream! has a line that’s easy to miss in the docs:

Operating the stream can fail on open for the same reasons as File.open!/2

“Operating” is the key part - you can File.stream! things that don’t exist, and you won’t get the exception until something forces the stream.

For instance:

iex(1)> File.stream!("nosuchfile.txt")

%File.Stream{
  line_or_bytes: :line,
  modes: [:raw, :read_ahead, :binary],
  path: "nosuchfile.txt",
  raw: true
}

iex(2)> File.stream!("nosuchfile.txt") |> Enum.to_list()

** (File.Error) could not stream "nosuchfile.txt": no such file or directory
    (elixir 1.13.0) lib/file/stream.ex:83: anonymous fn/3 in Enumerable.File.Stream.reduce/3
    (elixir 1.13.0) lib/stream.ex:1517: anonymous fn/5 in Stream.resource/3
    (elixir 1.13.0) lib/enum.ex:4143: Enum.reverse/1
    (elixir 1.13.0) lib/enum.ex:3488: Enum.to_list/1

IO.stream can’t fail in any of these ways since it takes either a PID (that you’d get from calling File.open! and possibly getting an exception) or an atom (to refer to stdio), so it doesn’t get a !.

tfwright

tfwright OP

So I didn’t notice that actual line but I’m certainly familiar with the behavior that a File stream will fail when you try to iterate on it. I am less familiar with working with IO streams though so that was probably a bad assumption of mine that there were some cases that might cause an error at that point. I guess it’s just that lazy evaluation is an interesting edge case for this convention. My first reaction is that even if using the stream might create an error at a certain point, the function name should only express the possible return values, but it’s clear why that would be difficult to adhere to in this case.

Interestingly, my case involves different stream sources so it complicates even further. if a stream API might return an IO stream or a File stream, how should it be named? stream! because in certain conditions an error might be raised on iteration? :thinking:

— All posts loaded —

Where Next? Top

Trending in Discussions Top

AstonJ
The obligatory hello world thread! Who are you and where are you from? :stuck_out_tongue:
4663 61218 595
New
cblavier
Hey there, It’s been more than a year since we started using LiveView as our main UI library and building a whole library of UI componen...
515 12931 101
New
sntran
In my third year of college, around 2010, I found Erlang. A few years later, I found Elixir. I liked the ideas at once: many small proces...
New
gtcode
I’ve been tinkering with Lynx (by José) via hold_ledger. I used AI to write the code, a separate specification, the tests, and the Lean p...
New
ManuelGarcia
Hi everyone! I’m the developer of PaperForge, and I’ve been working on something alongside it that I’d like your opinion on. I’m conside...
New
AstonJ
A remark @Garrison made… ..has already inspired a thread for the technical side of reclaiming our internet, but there is of course anot...
New
bartblast
This is where the projects in the Hologram Showcase get posted: apps built with Hologram and libraries made for it. New ones go up usuall...
New

Other Trending Topics Top

ancatrusca
Frank Hunleth and Omer Kilic follow one blinking LED from Circuits.GPIO.write down to the pin, and then out to 10,000 devices in the fiel...
New
GenericJam
Edit: 2026 May 15 - This post is archived. Mob is alive!! Main docs: mob v0.7.11 — Documentation A bit of explanation for the slightly c...
261 13183 112
New
mudasobwa
I fully migrated to my own harness from Anthropic/Gemini and I think it’s time to share it. Welcome DSH, the DeepSeek Harness, fully writ...
New
OndrejValenta
(I just needed to vent somewhere and LinkedIn is full of hope, or hype, I’m not sure which exactly) AI dream has many faces, but general...
New
kip
Localize is the next generation localisation library for Elixir. Think of it as ex_cldr version 3.0. The first version will be released ...
New
jimsynz
Beam Bots (or just BB for short) is a framework for building fault-tolerant robotics applications in Elixir using familiar OTP patterns. ...
New

We're in Beta

About us Mission Statement

Options

Thread Display Mode




Thread Preview

Skip Thread Previews