Rio Documentation

What is a Rio?

In its simplest form a Rio is a File/Directory reference. A Rio may be used to reference either files, directories, or other entities via url's. There is no requirement for the referenced item to exist in reality, since this can be ascertained later.

A Rio instance is a reference in relation to the system or container in which it resides, be it the 'RioLocalFileSystem', a remote ftp site, or a zip archive.

Once a Rio is obtained, it provides many functions for using, querying, or manipulating the item that it references and it is intended to be the main handle for using the referenced item.

Instantiating and Building Paths

The most concise method for creating a Rio is via: 1.below, the following are equivalent:

'myFile.txt' asFile

Cwd / 'myFile.txt'

Directory / 'myFile.txt'

File new:'myFile.txt' - the verbose form

Rio's may be constucted using the #/ and #, operators like so.

Cwd / 'package-cache' / 'Rio-Core' , '-kph.20' , '.mcz'.

Deconstructing the Rio Path and File Name

Given myFile := Cwd / 'myFile.3.txt'.

myFile full => '/media/hda1/squeak/myFile.3.txt'

myFile fileName => 'myFile.3.txt'

myFile parent => '/media/hda1/squeak'

myFile base => 'myFile'

myFile version => 3

myFile ext => 'txt'

myFile path => ''.

myFile full split => #('/' 'media' 'hda1' 'squeak' 'myFile.3.txt')

Adjusting the Rio Path and File Name

Given myFile := Cwd / 'myFile.3.txt'.
(#parent: and #full: will set the path relative to the default directory).

File Versions Helpers

If there exists a file, Cwd / 'temp.4.txt'. Then there are some utilities for obtaining the latest and next version file rio's.

'temp.txt' asRio latestVersion => (Rio new: 'temp.4.txt').

'temp.txt' asRio nextVersion => (Rio new: 'temp.5.txt').

A Word About Style

Rio may be used in two distinct styles. In addition to the traditional smalltalk cascading messages style, Rio supports a sentence like 'sequential' style. Whenever an example below uses the 'sequential' style for conciseness, suffice to say there is a traditional equivalent.

When a mode is set using 'cascading' style, (e.g. #setModeToRenaming) the mode flag is set on the given instance as you would expect. In contrast, when a mode is set in sequential style, a new instance is created, making the mode setting temporary for the remainer of that 'sequential sentence'. This convention applies to all modes. e.g.

sequential: myFile rename base: 'temp'. – myFile itself is untouched, the renaming mode flag is set in the myFile copy that performs #base:

File Stat

All of the typical stat information about files and directories is directly obtainable from a Rio.

myFile fileSize

myFile modificationTime returns a DateAndTime

myFile creationTime returns a DateAndTime

myFile isFile

myFile exists

myFile isDirectory

Directory Queries #select:ing

Internally the operating system provides the above stat data on entries of the parent directory. Rio implements many of its features by using one single function #select:. When #select: is performed upon a directory it traverses all of the directory entries collecting stat data. We can make use of this to perform a wide variety of directory queries.
Given myDir := Cwd / 'package-cache':

Directory Queries On Steroids aka. 'Recursive' Mode

Having explained how the world of directories, their entries and stats revolves around #select:, now is the time to announce one other little feature of #select: - it can perform its search recursively. All of the above queries become full tree searches with the addition of one little word: #recursively or #all (they are equivalent).

Copying Files - Introducing 'Binary' Mode

The basic file copying feature is implemented by a generic stream to stream copying function aPositionableStream-#copyTo:. The aim here being to eliminate many places where this, "copy from one stream to another stream via a buffer", code is duplicated. (e.g. GZReadStream-#saveContents:, GZWriteStream-compressFile: etc.) aPositionableStream-#copyTo: honours the setting of #binary mode on the input stream being copied. To make use of this Rio itself has a 'binary' mode of its own which is passed on to the streams that it uses for reading, writing and copying files.

'myFile.txt' asRio copyTo: 'yourFile.txt'

'myFile.gz' asRio binary copyTo: 'yourFile.txt.gz'

Copying Files with Compression - Introducing Adaptors and 'GZip' Mode

'GZip' mode introduces a new Rio concept, Adaptors.

An adaptor is an additional protocol which is added to Rio as needed for a given mode. 'GZip' mode adds an adaptor that wraps the standard file readStream, and writeStreams with GZipReadStream, and GZipWriteStream respectively. Readers and writers can now be created directly onto compressed streams via the same API (note the binary setting is also honoured by compressed streams). This has additional benefits since, with the generic #copyTo: scheme (described above) in place, the act of (de)compressing files now becomes:

compressing a file: myFile binary copyTo: (MyFile + '.gz') gzip.

decompressing a file: (myFile + '.gz') binary gzip copyTo: myFile

reading a gzip file: 'myFile.txt.gz' asRio gzip reader contents

The GZip adaptor also adds some convenience methods to Rio as part of its protocol enabling the following:

Adding Files to Archives - The 'Archive' Adaptor.

The 'Archive' Adaptor is a specialisation of the 'Dir' adaptor, providing the exact same interface for copying files, selections of files, and directory trees into an archive file. Selecting #zip mode, sets the 'Archive' adaptor to generate a zip archive file. The zip file is not actually written until explicitly requested via a call to #commit, or the block form #commit:

Rio at Large

Rios may be compared for equality with other Rio's, or directly with Strings. Rios may be used in many situations where you would use Strings. For example, a Rio may be included directly in a String concatentation. Rios may be passed into, and obtained from the #name attribute of a StandardFileStream. To help with legacy integration, Rios may also be passed in to many of FileDirectory's standard public methods.

Nice Code

One of the things that leads you to think that you may be doing something right is when some task which others have made look difficult, becomes simple. Here are some of my favourites.