Table of Contents

6.0 Class Stream (gb)

A stream is to be understood as a data stream flowing between processes or a process and a data end connection.

Overview of the different types of data end connections, globally referred to as a file in Linux:

Notes:

The interface stream specifies which methods are implemented. A stream has these four methods, among others:

Open,
Read file,
Write file,
Close.

The Stream class is the parent class for any Gambas object that represents a stream. This means that every class that inherits from the class Stream (gb) as a base class has at least these four methods. You cannot create this (base) class. Which functionality of a Stream object you can use depends on its exact class and also on the way the object is created.

For practical work, it is thus largely irrelevant whether you write data to or read data from, for example, a regular file, a serial port or a Unix socket.Here is the list of classes that inherit from the Stream class and are described in the Gambas book:

Compress    	Chapter 28.1.1
Uncompress  	Chapter 28.1.2
Process     	Chapter 21
SerialPort  	Chapter 24.1.5
Curl        	Chapter 24 (FTPClient and HTTPClient.)
File        	Chapter 6.5
Named Pipe	Chapter 6.2.1
Socket      	Chapter 24 (TCP- and Local-Unix-Socket)
VideoDevice 	Chapter 24

6.0.1 Properties

In Gambas, a Stream is an object that inherits from the Stream class (gb) and therefore implements its properties and methods. The Stream class has these properties:

PropertyData typeDescription
Blocking BooleanReturns or sets the truth value True if the stream is blocked. If this property is set to True, reading from the stream is blocked if there is nothing to read. Writing to the stream is blocked if, for example, the internal system buffer is full.
ByteOrder IntegerReturns the byte order or sets the byte order used to read or write binary data to the stream. The property can take the following values: gb.BigEndian as “Big endian byte order” or gb.LittleEndian as “Little endian byte order”.
EndOfFileBooleanThis property signals whether the last use of LINE INPUT reached the end of the file instead of reading an entire line with an end-of-line character.
EndOfLine IntegerReturns or sets the line break separator used by the current stream. The possible values are: gb.Unix for lines separated by Chr$(10), gb.Windows for lines separated by Chr$(13) and Chr$(10), gb.Mac for lines separated by Chr$(13). The value of this property is used by LINE INPUT, PRINT and the Stream.Lines property. Note that you can read both Unix and Windows line formats with gb.Unix. But it only writes the Unix format!
Handle IntegerReturns the system file descriptor associated with the current stream.
IsTermBooleanReturns True if a stream is associated with a terminal.
Lines .Stream.LinesReturns a virtual object (type string array) with which you can read a stream line by line.
TagVariantReturns the value of the Tag property assigned to the stream or sets the value. This property of data type Variant is intended for free use by the programmer and is not used by the component.
Term.Stream.TermReturns a virtual object that can be used to manage the terminal associated with the stream. The virtual class Stream.Term (gb) has the properties Echo, FlowControl, Height, Width and Name and the method Resize. Link: http://gambaswiki.org/wiki/comp/gb/.stream.term

Table 6.0.1.1 : Properties of the Stream class

6.0.2 Methods

The Stream class has these six methods:

MethodReturn typeDescription
Begin()-Starts buffering the data written to the stream so that when the Send method is called, everything is sent at once.
Close()-Closes the stream. The method is exactly the same as the CLOSE statement.
Drop()-Deletes the data buffered since the last call of the Begin() method.
ReadLine([ Escape As String ]) StringReads a line of text from the stream, just like the LINE INPUT statement. If Escape is specified, line breaks between two escape characters are ignored. This method is very useful when reading CSV files.
Send()-Sends all data at once that has been buffered since the last call of the Begin() method.
Watch ( Mode As Integer, Watch As Boolean )-Starts or stops watching the stream file descriptor for reading or writing after it has been opened. Mode is the observation type: gb.Read to observe while reading or gb.Write to observe while writing. Watch is TRUE to enable watching and FALSE to disable watching.

Table 6.0.2.1 : Methods of the class Stream

6.0.3 Digression

6.0.3.1 Project

The project in the download area demonstrates how to use the Type property of a Stat object to determine the type of file:

B1
Figure 6.0.3.1.1: Determining the type of files

The characters -, d, l, b, c, p and s characterise the type of a file in the context of the command ls -l and displaying the output in a console.

6.0.3.2 Use file command

Also in a console, you can use the file command to quickly determine what type of file a given file is:

Regular file
-------------------------------
hans@mint-183 ~ $ file nwm.xml
nwm.xml: exported SGML document, ASCII text

Directory
-------------------------
hans@mint-183 ~/BildTon $ file Fractals
Fractals: directory

Symbolic links
---------------------------------
hans@mint-183 ~/Schreibtisch $ file Formatting_DokuWiki_Tables
Formatting_DokuWiki_Tables: symbolic link to /home/hans/DW/0_DW_Convert/librewriter2dokuwiki.gambas

Blocked devices (block devices)
--------------------------------------
hans@mint-183 ~/Schreibtisch $ file /dev/sdd1
/dev/sdd1: block special (8/49)

Character-oriented devices (char devices)
---------------------------------------
hans@mint-183 ~ $ file /dev/ttyUSB0
/dev/ttyUSB0: character special (188/0)

Data links between processes (named pipe)
-------------------------------------------------
hans@mint-183 ~ $ mknod mypipe p 	' Generate Named Pipe
hans@mint-183 ~ $ file mypipe
mypipe: fifo (named pipe)
hans@mint-183 ~ $ rm mypipe	' Delete Named Pipe

Communication endpoint (unix socket)
------------------------------------
hans@mint-183 ~ $ file /run/user/1000/unix_socket.sock
/run/user/1000/unix_socket.sock: socket

6.0.3.3 The # character

For example, the documentation states.

FLUSH [ [ # ] Stream ]

where the # sign is marked as optional. In Gambas, you can prepend the # character to the variable name of a stream object, but only for the CLOSE, READ, WRITE, SEEK, INPUT, LINE INPUT, PRINT, UNLOCK and FLUSH instructions. This does not work in function calls like LOF(…), EOF(…) or the instruction LOCK.

In a Socket_Read event, you can use the following assignment, for example:

vData = Read #Last, -4096

In Last, the Socket object is returned that triggered the Read event and from which data can be read. You should prefer the “#Last” to “Last” because “Last” alone is not seen to be a stream in this case.

Download