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_integer_keyed_int(INTVAL key)

Shortcut to get the value of some attributes. For internal usage only, subject to change without notice.

void set_integer_keyed_int(INTVAL key, INTVAL value)

Shortcut to set the value of some attributes For internal usage only, subject to change without notice.

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()

Returns a boolean value indicating whether SELF is a console/tty.

METHOD is_closed()

Test if the filehandle is closed.

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 exit_status()

If this is a pipe, return the exit status of the child process.

METHOD tell()

Get the file position of the stream. 2 INTVALs are returned. The first is the position. The second is the position shifted down by 32 bits to handle overflows on 32-bit systems.

METHOD seek(INTVAL whence, INTVAL offs, INTVAL offs_overflow)

Set the file position to an offset specified by offs (and optionally offs_overflow). whence determines from where in the file the offset is taken.

 Whence Value      Meaning
 0                 Seek from the beginning of the file
 1                 Seek from the current position
 2                 Seek from the end of the file

offs_overflow is optional and is used to handle offsets higher than 2Gb on 32bit systems.

METHOD peek()

Returns the next byte from the stream, but does not remove it.