libs (macros | input-output)
This RFC proposes the addition of two macros to the global prelude,
eprint! and eprintln!. These are exactly the same as print! and
println!, respectively, except that they write to standard error
instead of standard output.
An implementation already exists.
This proposal will improve the ergonomics of the Rust language for development of command-line tools and "back end" / "computational kernel" programs. Such programs need to maintain a distinction between their primary output, which will be fed to the next element in a computational "pipeline", and their status reports, which should go directly to the user. Conventionally, standard output should receive the primary output and standard error should receive status reports.
At present, writing text to standard output is very easy, using the
print(ln)! macros, but writing text to standard error is
significantly more work: compare
println!("out of cheese error: {}", 42);
writeln!(stderr(), "out of cheese error: {}", 42).unwrap();
The latter may also require the addition of use std::io::stderr
and/or use std::io::Write; to the top of the file.
Because writing to stderr is more work, and requires introduction of
more concepts, all of the tutorial documentation for the language uses
println! for error messages, which teaches bad habits.
Two macros will be added to the global prelude. eprint! is exactly
the same as print!, and eprintln! is exactly the same as
println!, except that both of them write to standard error instead
of standard output. "Standard error" is defined as "the same place
where panic! writes messages." In particular, using set_panic to
change where panic messages go will also affect eprint! and
eprintln!.
Previous discussion has converged on agreement that both these macros
will be useful, but has not arrived at a consensus about their names.
An executive decision is necessary. It is the author's opinion that
eprint! and eprintln! have the strongest case in their favor,
being (a) almost as short as print! and println!, (b) still
visibly different from them, and (c) the names chosen by several
third-party crate authors who implemented these macros themselves for
internal use.
We will need to add text to the reference manual, and especially to
the tutorials, explaining the difference between "primary output" and
"status reports", so that programmers know when to use println! and
when to use eprintln!. All of the existing examples and tutorials
should be checked over for cases where println! is being used for a
status report, and all such cases should be changed to use eprintln!
instead; similarly for print!.
The usual drawbacks of adding macros to the prelude apply. In this case, I think the most significant concern is to choose names that are unlikely to to conflict with existing library crates' exported macros. (Conversely, internal macros with the same names and semantics demonstrate that the names chosen are appropriate.)
The names eprintln! and eprint! are terse, differing only in a
single letter from println! and print!, and it's not obvious at a
glance what the leading e means. ("This is too cryptic" is the
single most frequently heard complaint from people who don't like
eprintln!.) However, once you do know what it means it is
reasonably memorable, and anyone who is already familiar with stdout
versus stderr is very likely to guess correctly what it means.
There is an increased teaching burden---but that's the wrong way to look at it. The Book and the reference manual should have been teaching the difference between "primary output" and "status reports" all along. This is something programmers already need to know in order to write programs that fit well into the larger ecosystem. Any documentation that might be a new programmer's first exposure to the concept of "standard output" has a duty to explain that there is also "standard error", and when you should use which.
It would be inappropriate to introduce printing-to-stderr macros whose behavior did not exactly parallel the existing printing-to-stdout macros; I will not discuss that possibility further.
We could provide only eprintln!, omitting the no-newline variant.
Most error messages should be one or more complete lines, so it's
not obvious that we need eprint!. However, standard error is also
the appropriate place to send progress messages, and it is common to
want to print partial lines in progress messages, as this is a natural
way to express "a time-consuming computation is running".
For example:
Particle 0 of 200: (0.512422, 0.523495, 0.481173) ( 1184 ms)
Particle 1 of 200: (0.521386, 0.543189, 0.473058) ( 1202 ms)
Particle 2 of 200: (0.498974, 0.538118, 0.488474) ( 1146 ms)
Particle 3 of 200: (0.546846, 0.565138, 0.500004) ( 1171 ms)
Particle 4 of 200: _
We could choose different names. Quite a few other possibilities have been suggested in the pre-RFC and RFC discussions; they fall into three broad classes:
error(ln)! and err(ln)! are ruled out as too likely to collide
with third-party crates. error! in particular is already taken
by the log crate.
println_err!, printlnerr!, errprintln!, and several other
variants on this theme are less terse, but also more typing. It is
the author's personal opinion that minimizing additional typing
here is a Good Thing. People do live with fprintf(stderr, ...)
in C, but on the other hand there is a lot of sloppy C out there
that sends its error messages to stdout. I want to minimize the
friction in using eprintln! once you already know what it means.
It is also highly desirable to put the distinguishing label at the beginning of the macro name, as this makes the difference stand out more when skimming code.
aprintln!, dprintln!, uprintln!, println2!, etc. are not
less cryptic than eprintln!, and the official name of standard
I/O stream 2 is "standard error", even though it's not just for
errors, so e is the best choice.
Finally, we could think of some way to improve the ergonomics of
writeln! so that we don't need the new macros at all. There are
four fundamental problems with that, though:
writeln!(stderr(), ...) is always going to be more typing than
eprintln!(...). (Again, people do live with fprintf(stderr, ...) in C, but again, minimizing usage friction is highly
desirable.)
On a similar note, use of writeln! requires use std::io::Write,
in contrast to C where #include <stdio.h> gets you both printf
and fprintf. I am not sure how often this would be the only
use of writeln! in complex programs, however.
writeln! returns a Result, which must be consumed; this is
appropriate for the intended core uses of writeln!, but means
tacking .unwrap() on the end of every use to print diagnostics
(if printing diagnostics fails, it is almost always the case that
there's nothing more sensible to do than crash).
writeln!(stderr(), ...) is unaffected by set_panic() (just as
writeln!(stdout(), ...) is unaffected by set_print()). This is
arguably a bug. On the other hand, it is also arguably the Right Thing.
See discussion above.