<commit_before># Copyright: 2001-2006 The Perl Foundation.  All Rights Reserved.
# $Id $

=head1 NAME

docs/pdds/pddXX_io.pod - Parrot I/O

=head1 ABSTRACT

Parrot's I/O subsystem.

=head1 VERSION

$Revision $

=head1 SYNOPSIS

    open P0, "data.txt", ">"
    print P0, "sample data\n"
    close P0

    open P1, "data.txt", "<"
    S0 = read P1, 12
    P2 = getstderr
    print P2, S0
    close P1

    ...

=head1 DEFINITIONS

A "stream" allows input or output operations on a source/destination
such as a file, keyboard, or text console. Streams are also called
"filehandles", though only some of them have anything to do with files.

=head1 DESCRIPTION

This is a draft document defining Parrot's I/O subsystem, for both
streams and network I/O.

=head2 I/O Stream Opcodes

=head3 Opening and Closing Streams

=over 4

=item *

C<open> opens a stream object based on a string path. It takes an
optional string argument specifying the mode of the stream (read, write,
append, read/write, etc.) [Some discussion of the syntax of the format
strings may be relevant. Currently it uses Perl syntax, but a set of
defined constants may fit better with Parrot's general architecture.]

=item *

C<close> closes a stream object.

=back

=head3 Retrieving Existing Streams

=over 4

=item *

C<getstdin>, C<getstdout>, and C<getstderr> return a stream object for
standard input, standard output, and standard error.

=item *

C<fdopen> converts an existing and already open UNIX integer file
descriptor into a stream object. It also takes a string argument to
specify the mode.

=back

=head3 Writing to Streams

=over 4

=item *

C<print> writes an integer, float, string, or PMC value to a stream.  It
writes to standard output by default, but optionally takes a PMC
argument to select another stream to write to.

=item *

C<write> also writes to standard output and cannot select another
stream. It only accepts a PMC value to write. [Is this redundant?]

=item *

C<printerr> writes an integer, float, string, or PMC value to standard
error.

=back

=head3 Reading From Streams

=over 4

=item *

C<read> retrieves a specified number of bytes from a stream into a
string. [Note this is bytes, not codepoints.] By default it reads from
standard input, but it also takes an alternate stream object source as
an optional argument.

=item *

C<readline> retrieves a single line from a stream into a string. Calling
C<readline> flags the stream as operating in line-buffer mode (see
C<pioctl> below).  Lines are truncated at 64K.

=item *

C<peek> retrieves the next byte from a stream into a string, but doesn't
remove it from the stream. By default it reads from standard input, but
it also takes a stream object argument for an alternate source.

=back

=head3 Retrieving and Setting Stream Properties

=over 4

=item *

C<seek> sets the current file position of a stream object to an integer
byte offset from an integer starting position (0 for the start of the
file, 1 for the current position, and 2 for the end of the file). 

=item *

C<tell> retrieves the current file position of a stream object.  It also
has a 64-bit variant that returns the byte offset as two integers (one
for the first 32 bits of the 64-bit offset, and one for the second 32
bits).

=item *

C<getfd> retrieves the UNIX integer file descriptor of a stream object,
or 0 if it doesn't have an integer file descriptor. [Maybe -1 would be a
better code for "undefined", since standard input is 0.]

=item *

C<pioctl> provides low-level access to the attributes of a stream
object. It takes a stream object, an integer flag to select a command,
and a single integer argument for the command. It returns an integer
indicating the success or failure of the command.

The following constants are defined for the commands that C<pioctl> can
execute:

  0    PIOCTL_CMDRESERVED
           No documentation available.
  1    PIOCTL_CMDSETRECSEP
           Set the record separator. [This doesn't actually work at the
           moment.]
  2    PIOCTL_CMDGETRECSEP
           Get the record separator.
  3    PIOCTL_CMDSETBUFTYPE
           Set the buffer type.
  4    PIOCTL_CMDGETBUFTYPE
           Get the buffer type
  5    PIOCTL_CMDSETBUFSIZE
           Set the buffer size.
  6    PIOCTL_CMDGETBUFSIZE
           Get the buffer size.

The following constants are defined as argument/return values for the
buffer-type commands:

  0    PIOCTL_NONBUF
           Unbuffered I/O. Bytes are sent as soon as possible.
  1    PIOCTL_LINEBUF
	   Line buffered I/O. Bytes are sent when a newline is
           encountered.
  2    PIOCTL_BLKBUF
	   Fully buffered I/O. Bytes are sent when the buffer is full.
	   [Called "BLKBUF" because bytes are sent as a block, but line
	   buffering also sends them as a block, so "FULBUF" might make
           more sense.]

=back

=head2 File opcodes

=over 4

=item *

C<stat> retrieves information about a file on the filesystem. It takes a
string filename or an integer argument of a UNIX file descriptor, and an
integer flag for the type of information requested. It returns an
integer containing the requested information.  The following constants
are defined for the type of information requested (see
F<runtime/parrot/include/stat.pasm>):

  0    STAT_EXISTS
           Whether the file exists.
  1    STAT_FILESIZE<commit_msg>Some changes to the I/O PDD from comments by Leo & Nick.<commit_after># Copyright: 2001-2006 The Perl Foundation.  All Rights Reserved.
# $Id $

=head1 NAME

docs/pdds/pddXX_io.pod - Parrot I/O

=head1 ABSTRACT

Parrot's I/O subsystem.

=head1 VERSION

$Revision $

=head1 SYNOPSIS

    open P0, "data.txt", ">"
    print P0, "sample data\n"
    close P0

    open P1, "data.txt", "<"
    S0 = read P1, 12
    P2 = getstderr
    print P2, S0
    close P1

    ...

=head1 DEFINITIONS

A "stream" allows input or output operations on a source/destination
such as a file, keyboard, or text console. Streams are also called
"filehandles", though only some of them have anything to do with files.

=head1 DESCRIPTION

This is a draft document defining Parrot's I/O subsystem, for both
streams and network I/O.

=head2 I/O Stream Opcodes

=head3 Opening and Closing Streams

=over 4

=item *

C<open> opens a stream object based on a string path. It takes an
optional string argument specifying the mode of the stream (read, write,
append, read/write, etc.) [Some discussion of the syntax of the format
strings may be relevant. Currently it uses Perl syntax, but a set of
defined constants may fit better with Parrot's general architecture.]

=item *

C<close> closes a stream object.

=back

=head3 Retrieving Existing Streams

=over 4

=item *

C<getstdin>, C<getstdout>, and C<getstderr> return a stream object for
standard input, standard output, and standard error.

=item *

C<fdopen> converts an existing and already open UNIX integer file
descriptor into a stream object. It also takes a string argument to
specify the mode.

=back

=head3 Writing to Streams

=over 4

=item *

C<print> writes an integer, float, string, or PMC value to a stream.  It
writes to standard output by default, but optionally takes a PMC
argument to select another stream to write to.

=item *

C<printerr> writes an integer, float, string, or PMC value to standard
error.

=back

=head3 Reading From Streams

=over 4

=item *

C<read> retrieves a specified number of bytes from a stream into a
string. [Note this is bytes, not codepoints.] By default it reads from
standard input, but it also takes an alternate stream object source as
an optional argument.

=item *

C<readline> retrieves a single line from a stream into a string. Calling
C<readline> flags the stream as operating in line-buffer mode (see
C<pioctl> below).  Lines are truncated at 64K.

=item *

C<peek> retrieves the next byte from a stream into a string, but doesn't
remove it from the stream. By default it reads from standard input, but
it also takes a stream object argument for an alternate source.

=back

=head3 Retrieving and Setting Stream Properties

=over 4

=item *

C<seek> sets the current file position of a stream object to an integer
byte offset from an integer starting position (0 for the start of the
file, 1 for the current position, and 2 for the end of the file). It
also has a 64-bit variant that sets the byte offset by two integer
arguments (one for the first 32 bits of the 64-bit offset, and one for
the second 32 bits). [The two-register emulation for 64-bit integers may
be deprecated in the future.]

=item *

C<tell> retrieves the current file position of a stream object.  It also
has a 64-bit variant that returns the byte offset as two integers (one
for the first 32 bits of the 64-bit offset, and one for the second 32
bits). [The two-register emulation for 64-bit integers may be deprecated
in the future.]

=item *

C<getfd> retrieves the UNIX integer file descriptor of a stream object,
or 0 if it doesn't have an integer file descriptor. [Maybe -1 would be a
better code for "undefined", since standard input is 0.]

=item *

C<pioctl> provides low-level access to the attributes of a stream
object. It takes a stream object, an integer flag to select a command,
and a single integer argument for the command. It returns an integer
indicating the success or failure of the command.

The following constants are defined for the commands that C<pioctl> can
execute:

  0    PIOCTL_CMDRESERVED
           No documentation available.
  1    PIOCTL_CMDSETRECSEP
           Set the record separator. [This doesn't actually work at the
           moment.]
  2    PIOCTL_CMDGETRECSEP
           Get the record separator.
  3    PIOCTL_CMDSETBUFTYPE
           Set the buffer type.
  4    PIOCTL_CMDGETBUFTYPE
           Get the buffer type
  5    PIOCTL_CMDSETBUFSIZE
           Set the buffer size.
  6    PIOCTL_CMDGETBUFSIZE
           Get the buffer size.

The following constants are defined as argument/return values for the
buffer-type commands:

  0    PIOCTL_NONBUF
           Unbuffered I/O. Bytes are sent as soon as possible.
  1    PIOCTL_LINEBUF
	   Line buffered I/O. Bytes are sent when a newline is
           encountered.
  2    PIOCTL_BLKBUF
	   Fully buffered I/O. Bytes are sent when the buffer is full.
	   [Called "BLKBUF" because bytes are sent as a block, but line
	   buffering also sends them as a block, so "FULBUF" might make
           more sense.]

=back

=head3 Deprecated opcodes

=over

=item *

C<write> prints to standard output but it cannot select another stream.
It only accepts a PMC value to write. This is redundant with the
C<print> opcode, so it will be deprecated.

=back

=head2 File opcodes

=over 4

=item *

C<stat> retrieves information about a file on the filesystem. It takes a
string filename or an integer argument of a UNIX file descriptor, and an
integer flag for the type of information requested. It returns an
integer containing the requested information.  The following constants
are defined for the type of information requested (see
F<runtime/parrot/include/stat.pasm>):

  0    STAT_EXISTS
           Whether the file exists.
  1    STAT_FILESIZE
{'fraction_non_alphanumeric': 0.05381850853548967, 'fraction_numerical': 0.013207547169811321, 'mean_word_length': 3.4030854430379747, 'pattern_counts': {'":': 0, '<': 48, '<?xml version=': 0, '>': 48, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4009928', 'n_tokens_mistral': 3375, 'n_tokens_neox': 3240, 'n_words': 1663}