I/O
Parrot handles all I/O in Parrot with a set of PMCs.
The FileHandle PMC takes care of reading from and writing to files and file-like streams.
The Socket PMC takes care of network I/O.
FileHandle Opcodes
The open opcode opens a new filehandle.
It takes a string argument,
which is the path to the file:
$P0 = open 'my/file/name.txt'
By default,
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,
and p for pipe:These are the same as the C language read-modes,
so may be familiar.
$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 rw.
A handle that can read and write but will not overwrite the existing contents uses ra instead.
The 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,
standard output,
or standard error filehandles,
though you can recreate them.
close $P0
The print opcode prints a string argument or the string form of an integer,
number,
or PMC to a filehandle:
print $P0, 'Nobody expects'
It also has a one-argument variant that always prints to standard output:
print 'the Spanish Inquisition'
The say opcode also prints to standard output,
but it appends a trailing newline to whatever it prints.
Another opcode worth mentioning is the printerr opcode,
which prints an argument to the standard error instead of standard output:
say 'Turnip' printerr 'Blancmange'
The read and 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:
$S0 = read $P0, 10 $S0 = readline $P0
The read opcode has a one-argument variant that reads from standard input:
$S0 = read 10
The getstdin,
getstdout,
and getstderr opcodes fetch the filehandle objects for the standard streams: standard input,
standard output,
and standard error:
$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:
$P0 = getstdout print $P0, 'hello'
This following example reads data from the file myfile.txt one line at a time using the readline opcode.
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:
.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
FileHandle Methods
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
The 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')
The 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
The close method closes the filehandle.
This does not destroy the filehandle object; you can reopen it with the open method later.
$P0.'close'()
is_closed
The 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'()
The print method prints a given value to the filehandle.
The argument can be an integer,
number,
string,
or PMC.
$P0.'print'('Hello!')
puts
The puts method is similar to print,
but it only takes a string argument.
$P0.'puts'('Hello!')
read
The 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
The 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
The 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
The 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
The mode method returns the current file access mode for the filehandle object.
$S0 = $P0.'mode'()
encoding
The 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
The 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,
or full-buffered to read or write bytes when the buffer is full.
$P0.'buffer_type'('full-buffered')
$S0 = $P0.'buffer_type'()
buffer_size
The 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
The flush method flushes the buffer if the filehandle object is working in a buffered mode.
$P0.'flush'()
eof
The 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
The isatty method returns a boolean value whether the filehandle is a TTY terminal.
$P0.'isatty'()
get_fd
The 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 -1.
$I0 = $P0.'get_fd'()