13.3 Output Ports🔗ℹ

An output port is a port specifically for output, and an output string port writes to a byte string.

The stdout form is a shorthand for Port.Output.current(), and the stderr form is a shorthand for Port.Output.current_error().

The Port.Output.using form is analogous to Port.Input.using, but for setting the current output port while evaluating the body sequence. When the ~file variant is used, an ~exists option before the body sequence indicates how to handle the case that a file with the indicated path exists, the same as the ~exists argument to Port.Output.open_file.

• #'error — throws Exn.Fail.Filesystem.Exists if the file exists.

• #'replace — remove the old file, if it exists, and write a new one.

• #'truncate — remove all old data, if the file exists.

• #'must_truncate — remove all old data in an existing file; if the file does not exist, the Exn.Fail.Filesystem exception is thrown.

• #'truncate_replace — try #'truncate; if it fails (perhaps due to file permissions), try #'replace.

• #'update — open an existing file without truncating it; if the file does not exist, the Exn.Fail.Filesystem exception is thrown.

• #'can_update — open an existing file without truncating it, or create the file if it does not exist.

• #'append — append to the end of the file, whether it already exists or not; on Windows, #'append is equivalent to #'update, except that the file is not required to exist, and the file position is immediately set to the end of the file after opening it.

Port.Output.open_string does the same as Port.Output.open_bytes, but can be used to clarify the intention together with Port.Output.get_string.

Port.Output.String.get_string is like Port.Output.String.get_bytes, but returns a string converted from the byte string instead.

Writing to out may block, depending on the backing device. If wait is #'all, then all bytes are written, but not necessarily flushed (see Port.Output.flush), and the result is end-start. If wait is #'one, then writing will block until at least one byte is written and immediately flushed, and the result is the number of bytes written. If wait is #'none, then writing never blocks, and the result is the number of bytes written and immediately flushed. If wait is #'enable_break, then writing blocks in the same way as for #'one, but asynchronous break exceptions are enabled during the wait; in that case, if breaks are disabled before the call to Port.Output.write_bytes either some bytes will be written or a break exception will be thrown, but not both.