OsReadPipeStream
Description
A read pipe stream is a pipe stream that reads data off the receiving side of the pipe. This stream is used to read streaming data from processes via os pipes in a blocking or non-blocking fashion.
Auto Fill
All read pipe streams support the concept of 'auto-fill' which is a policy to try and read as much data from the operating system pipes into the buffers. Users should not set that directly in <OsReadPipeStream>, but rather from #autoFill methods or setting the OsProcessStarter>>tuneForDeadlockAvoidance policy.
Blocking API
This stream conforms to the majority of the smalltalk stream apis. Most of these will be considered blocking operations meaning that these methods can block the calling process. @see the methods in category IPC-API (Blocking)
Non-Blocking API
This stream also includes many non-blocking calls that will tend to retrieve that information that is available at the time of the call, but not block waiting for more. @see the methods in category IPC-API (Non-Blocking)
Class Methods
None
Instance Methods
atEnd
  NON-BLOCKING
     Answer true if the pipe is at EOF, false otherwise.
     Note: The pipe is constantly being filled and drained,
     so keep in mind that atEnd may answer true in one
     invocation, and then answer false in a subsequent invocation
     because the pipe was filled up.

     Answers:
        <Boolean>
autoFill
  Answer true if this buffer should try and keep itself full during the process lifecycle, false
     if it fills only indirectly based on a request for more data than is in the buffer.

     There are events (i.e. a write is about to be performed to stdin) that will trigger the
     buffer to fill up in order to prevent well-known deadlock situations.

     Answers:
        <Boolean>
autoFill:
  Set a <Boolean> indicating if this buffer should try and keep itself full during the process lifecycle (true),
     or if it fills only indirectly based on a request for more data than is in the buffer (false).

     Arguments:
        aBoolean - <Boolean>
available
  NON-BLOCKING
     Return the number of bytes available to be read.
     This is the the bufferred data + data in pipe
     Subclasses determine if this is interpreted as available
     for reading or writing

     Answers:
        <Integer> num bytes available in the pipe
availableInPipe
  NON-BLOCKING
     Return the number of bytes available in the pipe.
     Subclasses determine if this is interpreted as available
     for reading or writing

     Answers:
        <Integer> num bytes available in the pipe
fill
  NON-Blocking: Preemptively attempt to fill the pipe buffer

     Answers:
        <Integer> number of bytes filled
isBytes:
  If true, adjust the buffers to store bytes.
     If false, adjust the buffers to store chars.
     Inform the @stream

     Arguments:
        aBoolean - <Boolean>
next
  BLOCKING
     Answer the next element in the pipe.
     Block until an element becomes available in the pipe.
     If the other side of the pipe closes, then a nil will be
     returned meaning End Of Pipe

     Answers:
        <Integer | Character> next element
     Raises:
        <ExCLDTIndexOutOfRange>
        <OsProcessException>
next:
  BLOCKING
     Answer a collection containing the next @anInteger elements from the pipe.
     The caller will block until all @anInteger elements are available or End Of Pipe
     because the write end of the pipe was closed.
     If @anInteger < 1, an empty collection is answered

     Arguments:
        anInteger - <Integer>
     Answers:
        <ByteArray | String>
     Raises:
        <OsProcessException>
next:into:
  BLOCKING
     Insert the next @anInteger elements from the pipe into @aByteCollection starting at 1.
     The caller will block until all @anInteger elements are available or End Of Pipe because the
     write end of the pipe was closed.
     If @anInteger < 1, an empty collection is answered.
     An exception is raised if < anInteger elements are avaiable in this stream.

     Arguments:
        anInteger - <Integer>
        aByteCollection - <ByteArray | String>
     Answers:
        <ByteArray | String> aByteCollection
     Raises:
        <OsProcessException>
next:into:startingAt:
  BLOCKING
     Insert the next @anInteger elements from the pipe into @aByteCollection starting at the 1-based @initialPosition
     The caller will block until all @anInteger elements are available or End Of Pipe because the write end of the pipe
     was closed.
     If @anInteger < 1, an empty collection is answered.
     An exception is raised if < anInteger elements are avaiable in this stream.

     Arguments:
        anInteger - <Integer>
        aByteCollection - <ByteArray | String>
        initialPosition - <Integer>
     Answers:
        <ByteArray | String> aByteCollection
     Raises:
        <ExCLDTIndexOutOfRange>
        <OsProcessException>
nextInto:
  BLOCKING
     Insert the next @aByteCollection size number of elements from the pipe into @aByteCollection starting at 1
     The caller will block until @abyteCollection size of elements are available or End Of Pipe because the
     write end of the pipe was closed.
     If @anInteger < 1, an empty collection is answered.
     An exception is raised if < anInteger elements are avaiable in this stream.

     Arguments:
        aByteCollection - <ByteArray | String>
     Answers:
        <ByteArray | String> aByteCollection
     Raises:
        <OsProcessException>
nextLine
  BLOCKING
     Answer the elements between the current position and the next lineDelimiter. 
     The caller will block until the next lineDelimiter is reached or End Of Pipe because
     the write end of the pipe was closed.

    If #shouldSearchForAllStandardDelimiters answers false 
    (likely, the user has specified an explicit line delimiter via #lineDelimiter:)
    then we ONLY search for that delimiter. However, if it answers true
    (likely the stream current delimiter is the default one), then we try to look
    for any of the standard delimiters: Cr, Lf, and CrLf. This is useful when we are
    reading streams that could have been written on different platforms.

    Answers:
        <ByteArray | String>
peek
  NON-BLOCKING
     Answer the next byte or char from the pipe without
     removing it

     Answers:
        <Integer | Character>
position
  Answer the virtual stream position.
     The position can be determined by asking the buffers how many
     bytes have they consumed

     Answers:
        <Integer>
skip:
  BLOCKING
     Read and discard @anInteger number of elements from the pipe.
     The caller will block until all @anInteger elements are skipped or End Of Pipe because the
     write end of the pipe was closed.
     Fail if the number of elements in the pipe < @anInteger

     Arguments:
        anInteger - <Integer>
skipTo:
  BLOCKING
     Read and discard elements just past the occurrence of @aByteOrChar.
     The caller will block until @aByteOrChar is found or End Of Pipe because the
     write end of the pipe was closed.

     Arguments:
        aByteOrChar - <Integer | Character>
     Answers:
        <Boolean> true if found, false otherwise
skipToAll:
  BLOCKING
     Read and discard elements just past the occurrence of @aByteCollection.
     The caller will block until all occurrences in @aByteCollection are found
     or End Of Pipe because the write end of the pipe was closed.

     Arguments:
        aByteColletion - <ByteArray | String>
skipToAny:
  BLOCKING
     Read and discard elements beyond the next occurrence
     of an element that exists in @aSequentialCollection or if none,
     to the end of stream.
     The caller will block until any occurrences in @aByteCollection are found
     or End Of Pipe because the write end of the pipe was closed.
     Answer true if an element in @aSequentialCollection
     occurred, else answer false.

     Arguments:
        aSequentialCollection - <aSequentialCollection>
     Answers:
        <Boolean>
tryNext
  NON-BLOCKING
     Answer the next element in the pipe.
     Answer nil if the pipe is at the end.

     Answers:
        <Integer | Character> next element
        <UndefinedObject> no more elements
tryNext:
  NON-BLOCKING
     Answer a collection containing UP TO @anInteger number of elements
     read from the pipe.
     If @anInteger < 1 or no more elements remain in this pipe, an empty collection is answered

     Note: The try API does not raise an exception if there is < @anInteger number of
     elements remaining.

     Arguments:
        anInteger - <Integer>
     Answers:
        <ByteArray | String>
tryNext:into:
  NON-BLOCKING
     Insert UP TO the next @anInteger elements from the pipe into @aByteCollection starting at 1

     Note: The try API does not raise an exception if there is < @anInteger number of
     elements remaining.  It also answers the actual number of elements inserted

     Arguments:
        anInteger - <Integer>
        aByteCollection - <ByteArray | String>
     Answers:
        <Integer> 0 if anInteger is 0
                      -1 if at end of stream
                      <n> actual number of elements inserted
tryNext:into:startingAt:
  NON-BLOCKING
     Insert UP TO the next @anInteger elements from the pipe into @aByteCollection starting at the 1-based @initialPosition

     Note: The try API does not raise an exception if there is < @anInteger number of
     elements remaining.  It also answers the actual number of elements inserted

     Arguments:
        anInteger - <Integer> number of elements to insert
        aByteCollection - <ByteArray | String> collection to insert into
        initialPosition - <Integer> 1-based index to start inserting into @aByteCollection
     Answers:
        <Integer> 0 if anInteger is 0
                      -1 if at end of stream
                      <n> actual number of elements inserted
tryNextAvailable
  NON-BLOCKING
     Answer the available bytes
     This includes the bytes in the internal buffers, as well
     as the bytes in the pipe at the time the #available call was made.

     Answers:
        <ByteArray | String>
tryNextInto:
  NON-BLOCKING
     Insert UP TO the next @aByteCollection size number of elements into @aByteCollection starting at 1
     Change the state of this stream such that these elements will no
     longer be accessible.

     Note: The try API does not raise an exception if there is < @anInteger number of
     elements remaining.  It also answers the actual number of elements inserted

     Arguments:
        anInteger - <Integer>
     Answers:
        <Integer> 0 if anInteger is 0
                      -1 if at end of stream
                      <n> actual number of elements inserted
trySkip:
  NON-BLOCKING
     Attempt to read and discard @anInteger number of elements from the pipe.
     If the end of pipe is reached first, then answer the number of bytes actually skipped

     Arguments:
        anInteger - <Integer>
     Answers:
        <Integer> number actually skipped
trySkipTo:
  NON-BLOCKING
     Attempt to read and discard elements just past the occurrence of @aByteOrChar.
     Answer true if it was found, false if it was never found and the end of
     pipe was reached during this invocation.

     Arguments:
        aByteOrChar - <Integer | Character>
     Answers:
        <Boolean>
trySkipToAll:
  NON-BLOCKING
     Attempt to read and discard elements just past the occurrence of @aByteCollection.

     Arguments:
        aByteColletion - <ByteArray | String>
trySkipToAny:
  NON-BLOCKING
     Attempt to read and discard elements beyond the next occurrence
     of an element that exists in @aSequentialCollection or if none,
     to the end of stream.  Answer true if an element in @aSequentialCollection
     occurred, else answer false.

     Arguments:
        aSequentialCollection - <aSequentialCollection>
     Answers:
        <Boolean>
tryUpTo:
  NON-BLOCKING
     Answers a collection of all of the objects in the pipe
     beginning from the current position up to, but not including,
     @aByteOrChar

     Arguments:
        aByteOrChar - <Integer | Character>
     Answers:
        <ByteArray or String>
tryUpToAll:
  NON-BLOCKING
     Answers a collection of all of the objects in the pipe
     beginning from the current position up to, but not including,
     @aByteCollection

     Arguments:
        aByteColletion - <ByteArray | String>
     Answers:
        <ByteArray or String>
tryUpToAny:
  NON-BLOCKING
     Answers a collection of all of the objects in the pipe up to, but not including, the next occurrence
     of the element that exists in @aSequenceableCollection.  If the element that exists in @aSequenceableCollection
     is not found and the end of the pipe is encountered, an ordered collection of the objects read is returned.

     Arguments:
        aSequentialCollection - <aSequentialCollection>
     Answers:
        <SequenceableCollection>
upTo:
  BLOCKING
     Answers a collection of all of the objects in the pipe
     beginning from the current position up to, but not including,
     @aByteOrChar.
     The caller will block until @aByteOrChar is found
     or End Of Pipe because the write end of the pipe was closed.

     Arguments:
        aByteOrChar - <Integer | Character>
     Answers:
        <ByteArray or String>
upToAll:
  BLOCKING
     Answers a collection of all of the objects in the pipe
     beginning from the current position up to, but not including,
     @aByteCollection
     The caller will block until all occurrences in @aByteCollection are found
     or End Of Pipe because the write end of the pipe was closed.

     Arguments:
        aByteColletion - <ByteArray | String>
     Answers:
        <ByteArray or String>
upToAny:
  BLOCKING
     Answers a collection of all of the objects in the pipe up to, but not including, the next occurrence
     of the element that exists in @aSequenceableCollection.  If the element that exists in @aSequenceableCollection
     is not found and the end of the pipe is encountered, an ordered collection of the objects read is returned.
     The caller will block until any occurrences in @aByteCollection are found
     or End Of Pipe because the write end of the pipe was closed.

     Arguments:
        aSequentialCollection - <aSequentialCollection>
     Answers:
        <SequenceableCollection>
upToEnd
  NON-BLOCKING
     Answer a collection containing UP TO the maximum number of elements read from the pipe.
     If there are no more bytes available to be read, then an empty collection is answered.

     Since a <ByteArray> or <String> is being answered, the maximum number of elements is restricted
     to be the largest index for a byte-shaped object.

     Note: This method involves grabbing all remaining bytes IN THE READ PIPE, not
     necessarily all remaining bytes the external program will ever generate.

     Answers:
        <ByteArray | String>
Last modified date: 07/07/2022