NAME

src/pmc/filehandle.pmc - FileHandle PMC

DESCRIPTION

The FileHandle PMC performs I/O operations on a source or destination file.

Vtable Functions

void init()

Initializes a newly created FileHandle object.

PMC *clone()

Create a copy of the filehandle.

void mark()

Mark active filehandle data as live.

void destroy()

Free structures.

INTVAL get_bool()

Returns whether the FileHandle has reached the end of the file.

Methods

METHOD open(STRING *filename :optional, STRING *mode :optional)

Opens the file at the given filename (including path) with the given mode. The invocant is modified and becomes an open filehandle. A copy of the invocant is also returned by the method (some subclasses may create this as the primary filehandle, rather than modifying the invocant).

METHOD isatty()

METHOD close()

Close the filehandle.

METHOD is_closed()

Test if the filehandle is closed.

METHOD read(INTVAL bytes)

Read the given number of bytes from the filehandle and return them in a string.

METHOD readline()

Read a line from the filehandle and return it in a string.

METHOD readline_interactive(STRING *prompt)

Read a line from the filehandle and return it in a string.

METHOD readall(STRING *name);

Read the entire contents of a file named name into a Parrot string. On a filehandle object that isn't opened yet, the path to a file can be passed to readall and it will open a filehandle on that file, read in the contents, and close the filehandle.

  .local pmc pio
  pio = new 'FileHandle'
  $S0 = pio.'readall'('the_file')

If the filehandle is already open, then no file path should be passed. The readall method will read the contents of the file, and will not close the filehandle when finished.

  pio = open 'the_file', 'r'
  $S0 = pio.'readall'()

METHOD flush()

Flushes the filehandle.

METHOD print([INTVAL|FLOATVAL|STRING *|PMC*] value)

Print the passed in integer, number, string, or PMC to the filehandle. (Integers, numbers, and strings are auto-boxed as PMCs.)

METHOD puts(STRING *value)

Print the string to the filehandle.

METHOD buffer_type(STRING *new_type :optional)

Set or retrieve the buffering behavior for the filehandle. The argument and return value are one of the following:

unbuffered

Buffering disabled, bytes are sent as soon as possible.

line-buffered

Line buffering, bytes are sent when a record separator is encountered.

full-buffered

Full buffering, bytes are sent when the buffer is full.

METHOD buffer_size(INTVAL new_size :optional)

Set or retrieve the buffer size for the filehandle.

METHOD mode()

Retrieve the read mode string for the filehandle.

METHOD encoding(STRING *new_encoding)

Set or retrieve the encoding attribute (a string name of the selected encoding scheme) for the filehandle.

METHOD eof()

Returns true if the filehandle is at end-of-file, returns false otherwise.

METHOD get_fd()

Retrieve the integer file descriptor for the FileHandle (only available on platforms that use integer file descriptors).