lib/io
The new input-output system of SmartEiffel.
->See description

 

DIRECTORY
 Tools for file-system directory handling.
 High-level facade for class BASIC_DIRECTORY.

FILE_TOOLS
 This expanded class gather tools relatives to files such as
 file comparison, file renaming, file deletion, file size, file
 permissions...

 Note this is a facilities class. Files are referenced with
 their names (as STRINGs). Consider using functions available in
 TEXT_FILE_READ if you are already connected to the file.

FILTER
 A filter is something connected to another stream. It allows to add behaviour (e.g. compression, encryption
 and any other codings)

 There are two kinds of filters:
 + input filters (see FILTER_INPUT_STREAM)
 + output filters (see FILTER_OUTPUT_STREAM)

*** Note that currently FILTER is inserted (not inherited) by FILTER_INPUT_STREAM and FILTER_OUTPUT_STREAM
 (due to limitations of the new Eiffel way, or bugs of the compiler, I don't know)

FILTER_INPUT_STREAM
 A filtered input stream.

FILTER_OUTPUT_STREAM
 A filtered output stream.

INPUT_STREAM
 An input stream is a flow of characters that can be read from some source (be it an Eiffel object or an
 external object)

 Input stream usage is available in tutorial/io and SmartEiffel FAQ.

OUTPUT_STREAM
 An output stream is a flow of characters that can be written to some destination (be it an Eiffel object or
 an external object)

STANDARD_STREAMS
 Thanks to this `standard_streams' singleton object, you can redirect `io', `std_input', `std_output' as
 well as `std_error'. (See also examples from our tutorial/io directory.)

STREAM
 A stream of characters.

 There are two kinds of streams:
 + input streams (see INPUT_STREAM)
 + output_streams (see OUTPUT_STREAM)

 Streams can:
 + be connected (e.g. to some system object)
 + be used ot read or write characters, only if they are connected
 + be filtered (see FILTER)

*** Note that currently STREAM is inserted (not inherited) by INPUT_STREAM and OUTPUT_STREAM (due to
 limitations of the new Eiffel way, or bugs of the compiler, I don't know)

TERMINAL_INPUT_OUTPUT_STREAM
 A stream that is at the same time an input stream and an output stream.

TERMINAL_INPUT_STREAM
 A "terminal" input stream is an input stream connected to a "real" character flow. There are many kinds of
 "real" data flows:
  + a file
  + a string
  + a virtual flow, such as a null-provider
  + . . .

TERMINAL_OUTPUT_STREAM
 A "terminal" output stream is an output stream connected to a "real" character flow. There are many kinds
 of "real" data flows:
  + a file
  + a string
  + a virtual flow, such as a null-provider
  + . . .


 

Cluster lib/io description

The new input-output system of SmartEiffel.

Usage

When creating streams, one should procede as follows:

  1. Create a terminal stream: that's the "back-end", i.e. where the bytes really come from and/or go to. Such a back-end may be either connected to an OS-related resource (such as a file, a standard stream, or a socket --well, the latter, one day it'll come), or an Eiffel resource (such as a string);
  2. Create zero or more filters, connected one to another using the connect_to feature of filter streams;
  3. Let clients only use the front-end filter. Any intermediary filter, and the terminal stream, will refuse to be used directly when they are attached to a filter.

Taken together, interconnected filters and terminal make a filtered stream; one reads and/or writes from one side of the "pipe", while the terminal reads/writes at the other side.

Architecture

First of all, input and output streams have symmetrical hierarchies. They also have a common ancestor (Note: this ancestor is currently inserted, not inherited).

Those classes are split in two hierarchies: on the one hand, filters, on the other hand, terminals.

Filtered streams are in fact a double-linked objects: each filter points to an underlying stream (be it another filter or a terminal) while each stream points to a filter. The "stream-to-filter" back-link is used for assertions, to ensure one does not bypass filters.

Filters

Filters are stuck in front of a stream (be it another filter or a terminal). They provide extra functionality: compression, buffers, and so on.

Note: you cannot directly use streams that are connected to a filter; use that filter instead.

Terminals

Terminals are back-end bytes readers and/or writers. There are many such terminals: files, sockets, strings and so on. There are even the equivalent of the good ol' Unix /dev/null device, which eats bytes and provides zeroes.

There are three kinds of terminal streams: TERMINAL_INPUT_STREAM, TERMINAL_OUTPUT_STREAM, and TERMINAL_INPUT_OUTPUT_STREAM

Note that there are only terminal input-output streams. Filters do not have this notion: you use either an input or an output stream, even if the underlying resource has input-output capabilities.

Standard streams

The class STANDARD_STREAMS provides access to the standard streams. GENERAL provides an access to a STANDARD_STREAMS once object, along with shortcuts to the most used features: the standard streams std_input, std_output, std_error, and the most used io which is but a centralized access to the former two.

STANDARD_STREAMS provides features to dynamically change standard streams. It allows to:

Also available in this cluster

Apart from the Streams and Filters system, the io cluster also provides: