Class: NonPositionableExternalStream

• Inheritance
• Description
• Class protocol
  • instance creation
• Instance protocol
  • error handling
  • non homogenous reading
  • positioning
  • printing & storing
  • private
  • queries
  • reading
  • writing

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--NonPositionableExternalStream
                        |
                        +--PipeStream
                        |
                        +--Socket

Package:

stx:libbasic

Category:

Streams-External

Version:

rev: 1.61 date: 2010/03/04 15:11:43

user: stefan

file: NonPositionableExternalStream.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

This class provides common protocol for all non-positionable,
external streams. Concrete subclasses are terminal streams, pipe streams,
PrinterStreams, Sockets etc.

There are three special instances of this class, representing stdin,
stdout and stderr of the smalltalk/X process (see Unix manuals, if you
dont know what those are used for). These special streams are bound to
to globals Stdin, Stdout and Stderr at early initialization time
(see Smalltalk>>initializeStandardStreams).

The name of this class is a historical leftover - it should be called
'TTYStream' or similar.

Class protocol:

 forStderr

return a NonPositionableExternalStream object for writing to
Unixes standard error output file descriptor

 forStdin

return a NonPositionableExternalStream object for reading from
Unixes standard input file descriptor

 forStdout

return a NonPositionableExternalStream object for writing to
Unixes standard output file descriptor

 makePTYPair

return an array with two streams - the first one is the master,
the second the slave of a ptym/ptys pair.
This is much like a bidirectional pipe, but allows signals &
control chars to be passed through the connection.
This is needed to execute a shell in a view.
This is the higher level equivalent of OperatingSystem>>makePTYPair
(which returns an array of file-descriptors).

 makePipe

return an array with two streams - the first one for reading,
the second for writing.
This is the higher level equivalent of OperatingSystem>>makePipe
(which returns an array of file-descriptors).

Instance protocol:

 positionError

notify that this stream has no concept of a position

 nextBytes: count into: anObject startingAt: start

read the next count bytes into an object and return the number of
bytes read or the number of bytes read, if EOF is encountered before.
An exception is raised if the connection is broken.

Redefined here to avoid blocking of ST/X when waiting for io.
Instead only the calling thread will block

 position

catch position - there is none here

 position: aPosition

catch position - there is none here

 skip: numberToSkip

skip count bytes/characters, return the receiver.
Re-redefined since PositionableStream redefined it.

 skipThroughAll: aCollection

skip for and through the sequence given by the argument, aCollection;
return nil if not found, the receiver otherwise.
On a successful match, the next read will return elements after aCollection;
if no match was found, the receiver will be positioned at the end.
Redefined to be the same as Stream>>#skipThroughAll, to undo
the redefinition from PositionableStream

 printOn: aStream

append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

 storeOn: aStream

append a printed representation of the receiver on aStream, from
which the receiver can be reconstructed.

 handleForStderr

return a stderr handle

 handleForStdin

return a stdin handle

 handleForStdout

return a stdout handle

 initializeForStderr

setup for writing to stderr

 initializeForStdin

setup for reading stdin

 initializeForStdout

setup for writing to stdout

 reOpen

reopen the stream after an image restart.
If I am one of the standard streams, reopen is easy

 atEnd

return true, if position is at end

 current

for compatibility with Transcript - allow Transcript current,
even if redirected to the standardError

 isPositionable

return true, if the stream supports positioning (this one is not)

 size

we do not know our size

 nextOrNil

like #next, this returns the next element, if available.
If nothing is available, this does never raise a read-beyond end signal.
Instead, nil is returned immediately.

Redefined, to wait on pipes and sockets

 peekOrNil

like #peek, this returns the next element, if available.
If nothing is available, this does never raise a read-beyond end signal.
Instead, nil is returned immediately.

Redefined, to wait on pipes and sockets

 nextPutBytes: initialWriteCount from: buffer startingAt: initialOffset

redefined, to wait until stream is writable, to avoid blocking in a write