STREAM.ICN

NAME
SYNOPSIS
DESCRIPTION
RETURNS
PORTABILITY
SEE ALSO
BUGS AND LIMITATIONS
AUTHOR

NAME

Stream--Constructor for sequential access class wrappers for co-expressions, files, and lists

SYNOPSIS

  # construct subclass of Stream_Abstract
  procedure Stream( device, mode, other[ ] )

  # base class for StreamC, Streamf, StreamL
  class Stream_Abstract
    method Close( )          # &fail
    method Data( )           # &fail
    method Flush( )          # &fail
    method Get( )            # &fail
    method Pull( )           # &fail
    method Push( )           # &fail
    method Put( )            # &fail
    method Select( )         # &fail
    method Type( )           # &fail

 # sequential access class for co-expression
  class StreamC : Stream_Abstract
    method Close( )          # null?
    method Data( )           # co-expression
    method Flush( )          # null
    method Get( value )      # any
    method Put( values[ ] )  # list?
    method Select( )         # null?
    method Type( )           # string

 # sequential access class for file
  class Streamf : Stream_Abstract
    method Close( )          # file|integer|null?
    method Data( )           # file|null
    method Flush( )          # file?
    method Get( )            # string?
    method Put( values[ ] )  # list?
    method Select( timeout ) # null?
    method Type( )           # string

 # sequential access class for list
  class StreamL : Stream_Abstract
    method Close( )          # null
    method Data( )           # list
    method Flush( )          # null
    method Get( )            # any?
    method Pull( )           # any?
    method Push( values[ ] ) # list?
    method Put( values[ ] )  # list?
    method Select( )         # integer?
    method Type( )           # string

DESCRIPTION

For an extended introduction to Stream.icn and ideas about how to apply it, please see [Eschenlauer, 2006].

Constructor (Factory)

The Stream( ) procedure constructs instances of the StreamC, Streamf, and StreamL classes to provide a common interface to exchange data with co−expressions, files, and lists, respectively.

The "returns" section below explains how the arguments determine the class of the object produced.

Interface

The StreamC, Streamf, and StreamL classes all implement the following methods:

Close

Closes f, cofails C, or replaces L with an empty list.

Data

Produces the list, file, or co-expression managed by StreamC, Streamf, and StreamL.

Flush

Produces result of flush(f), or &null.

Get

Produces a value; can transmit a value to C

Pull

Produces a value (for StreamL only)

Push

Produces a list as long as number of args (for StreamL only)

Put

Produces a list as long as number of args

Select

Produces &null if Get may produce a value

Type

Produces "list" | "file" | "co-expression"

Activation of Producers and Consumers

When a producer coexpression uses StreamC object to transmit values to a consumer coexpression that receives them using another StreamC object, the values transmitted will be the same regardless of whether the producer or the consumer was activated first.

RETURNS

The class produced by the constructor function Stream( ) depends on the arguments supplied:

Stream(C,"r"|"w")

produces an instance of StreamC encapsulating co-expression C.

Note that under shell.icn( 1 ):
− A producer task should use the "w" filemode when creating a StreamC instance to manage communication with a consumer task.
− A consumer task should use the "r" filemode to when creating a StreamC instance to communicate with a producer task.
− A client task should use the "w" filemode when creating a StreamC instance to manage communication with a service task.

Stream(f)

produces an instance of Streamf encapsulating file f

Stream(s,args[ ])

produces an instance of Streamf where [s] ||| args is the argument list passed to the open( ) function

Stream(L)

produces an instance of StreamL encapsulating list L

Stream(StreamL)

produces an instance of StreamL encapsulating the list encapsulated by the StreamL-typed argument

PORTABILITY

Stream.icn is compatible with Unicon but not Icon since Icon does not support classes. Stream.icn is not Idol-compatible.

SEE ALSO

Eschenlauer, Arthur C., 2006. "A Unicon Shell", The Generator, Vol. 2, No. 2, pp 3-32.

  http://www.unicon.org/generator/v2n2.pdf

shell.icn( 1 )

BUGS AND LIMITATIONS

Streamf has been extensively tested only with disk files; databases, network connections, etc., have not been tested much if at all.

AUTHOR

Art Eschenlauer

Stream.icn is in the public domain. The freedom of its content is protected by the Lesser GNU public license, version 2.1, February 1999,

  http://www.gnu.org/licenses/lgpl.html

which means you are granted permission to use this in any way that does not limit others’ freedom to use it.