REBOL 3 Concepts: Ports: Opening a Port

Pending Revision

This document was written for R2 and has yet to be revised for R3.

The Open Function

The open function initializes access to a port according to specified parameters. The function can be supplied with a filename, a URL, or an object. In addition, there are several refinements that will affect the open operation or the access to the port's data.

The simplest method of using open is to provide it with a filename or URL as its argument. In the example below, a file port is opened:

fp: open %file.txt

The fp variable refers to the port. If the port did not open, an error will occur. If necessary, the error can be caught with the try function.

By default the file is opened as buffered. This means that the file is accessed and modified in memory and changes to the file are not written out until the port is closed or updated.

For files, the open function will automatically create the file if it does not already exist.

close open %somefile.txt
if exists? %somefile.txt [print "somefile exists"]
somefile exists

The /new refinement can be used to overwrite an existing file.

write %somefile.txt "text in some file"
print read %somefile.txt
text in some file

close insert open/new %somefile.txt "new data"
print read %somefile.txt
new data

Once a port is open, the series operations such as copy, insert, remove, clear, first, next, and length? can be used to access and change the contents the port.

Open Refinements

The open function accepts a number of refinements that can be used to modify its operation:

/binary	port data is binary
/string	port data is text, translate all line terminators
/with	specify an alternate line termination
/lines	handle data a line at a time or as a block of lines
/direct	do not buffer the port
/new	create or recreate the target of the port
/read	open for read only operation
/write	open for write only operation
/no-wait	do not wait for data
/skip	skip part of the data
/allow	specify protection attributes of files
/custom	allow special refinements