Parrot handles all I/O in Parrot with a set of PMCs.
FileHandle PMC takes care of reading from and writing to files and file-like streams.
Socket PMC takes care of network I/O.
open opcode opens a new filehandle.
It takes a string argument,
which is the path to the file:
.loadlib 'io_ops' # ... $P0 = open 'my/file/name.txt'
it opens the filehandle as read-only,
but an optional second string argument can specify the mode for the file.
The modes are
r for read,
w for write,
a for append,
p for pipe:These are the same as the C language read-modes,
so may be familiar.
.loadlib 'io_ops' # ... $P0 = open 'my/file/name.txt', 'a' $P0 = open 'myfile.txt', 'r'
You can combine modes; a handle that can read and write uses the mode string
A handle that can read and write but will not overwrite the existing contents uses
close opcode closes a filehandle when it's no longer needed.
Closing a filehandle doesn't destroy the object,
it only makes that filehandle object available for opening a different file.It's generally not a good idea to manually close the standard input,
or standard error filehandles,
though you can recreate them.
.loadlib 'io_ops' # ... close $P0
print $P0, 'Nobody expects'
It also has a one-argument variant that always prints to standard output:
print 'the Spanish Inquisition'
say opcode also prints to standard output,
but it appends a trailing newline to whatever it prints.
Another opcode worth mentioning is the
which prints an argument to the standard error instead of standard output:
say 'Turnip' # ... .loadlib 'io_ops' # ... printerr 'Blancmange'
readline opcodes read values from a filehandle.
read takes an integer value and returns a string with that many characters (if possible).
readline reads a line of input from a filehandle and returns the string without the trailing newline:
.loadlib 'io_ops' $S0 = read $P0, 10 $S0 = readline $P0
read opcode has a one-argument variant that reads from standard input:
.loadlib 'io_ops' # ... $S0 = read 10
getstderr opcodes fetch the filehandle objects for the standard streams: standard input,
and standard error:
.loadlib 'io_ops' # ... $P0 = getstdin # Standard input handle $P1 = getstdout # Standard output handle $P2 = getstderr # Standard error handle
Once you have the filehandle for one of the standard streams, you can use it just like any other filehandle object:
.loadlib 'io_ops' # ... $P0 = getstdout print $P0, 'hello'
This following example reads data from the file myfile.txt one line at a time using the
As it loops over the lines of the file,
it checks the boolean value of the read-only filehandle
$P0 to test whether the filehandle has reached the end of the file:
.loadlib 'io_ops' .sub 'main' $P0 = getstdout $P1 = open 'myfile.txt', 'r' loop_top: $S0 = readline $P1 print $P0, $S0 if $P1 goto loop_top close $P1 .end
The methods available on a filehandle object are mostly duplicates of the opcodes, though sometimes they provide more options. Behind the scenes many of the opcodes call the filehandle's methods anyway, so the choice between the two is more a matter of style preference than anything else.
open method opens a stream in an existing filehandle object.
It takes two optional string arguments: the name of the file to open and the open mode.
$P0 = new 'FileHandle' $P0.'open'('myfile.txt', 'r')
open opcode internally creates a new filehandle PMC and calls its
open method on it.
The opcode version is shorter to write,
but it also creates a new PMC for every call,
while the method can reopen an existing filehandle PMC with a new file.
When reopening a filehandle, Parrot will reuse the previous filename associated with the filehandle unless you provide a different filename. The same goes for the mode.
close method closes the filehandle.
This does not destroy the filehandle object; you can reopen it with the
open method later.
is_closed method checks if the filehandle is closed.
It returns true if the filehandle has been closed or was never opened,
and false if it is currently open:
$I0 = $P0.'is_closed'()
read method reads a specified number of bytes from the filehandle object and returns them in a string.
$S0 = $P0.'read'(10)
If the remaining bytes in the filehandle are fewer than the requested number of bytes, returns a string containing the remaining bytes.
readline method reads an entire line up to a newline character or the end-of-file mark from the filehandle object and returns it in a string.
$S0 = $P0.'readline'()
readline_interactive method is useful for command-line scripts.
It writes the single argument to the method as a prompt to the screen,
then reads back a line of input.
$S0 = $P0.'readline_interactive'('Please enter your name:')
readall method reads an entire file.
If the filehandle is closed,
it will open the file given by the passed in string argument,
read the entire file,
and then close the filehandle.
$S0 = $P0.'readall'('myfile.txt')
If the filehandle is already open,
readall will read the contents of the file,
and won't close the filehandle when it's finished.
Don't pass the name argument when working with a file you've already opened.
$S0 = $P0.'readall'()
mode method returns the current file access mode for the filehandle object.
$S0 = $P0.'mode'()
encoding method sets or retrieves the string encoding behavior of the filehandle.
$P0.'encoding'('utf8') $S0 = $P0.'encoding'()
See "Encodings and Charsets" in Chapter 4 for more details on the encodings supported in Parrot.
buffer_type method sets or retrieves the buffering behavior of the filehandle object.
The argument or return value is one of:
unbuffered to disable buffering,
line-buffered to read or write when the filehandle encounters a line ending,
full-buffered to read or write bytes when the buffer is full.
$P0.'buffer_type'('full-buffered') $S0 = $P0.'buffer_type'()
buffer_size method sets or retrieves the buffer size of the filehandle object.
$P0.'buffer_size'(1024) $I0 = $P0.'buffer_size'()
The buffer size set on the filehandle is only a suggestion. Parrot may allocate a larger buffer, but it will never allocate a smaller buffer.
flush method flushes the buffer if the filehandle object is working in a buffered mode.
eof method checks whether a filehandle object has reached the end of the current file.
It returns true if the filehandle is at the end of the current file and false otherwise.
$I0 = $P0.'eof'()
isatty method returns a boolean value whether the filehandle is a TTY terminal.
get_fd method returns the integer file descriptor of the current filehandle object.
Not all operating systems use integer file descriptors.
Those that don't simply return
$I0 = $P0.'get_fd'()