S16-io.pod

Title

DRAFT: Synopsis 16: IO / User / Group

Version

Author:        Largely, the authors of the related Perl 5 docs.
Maintainer:    Larry Wall <larry@wall.org>
Contributions: Mark Stosberg <mark@summersault.com>
               Tim Nelson <wayland@wayland.id.au>
               Daniel Ruoso <daniel@ruoso.com>
Date:          12 Sep 2006
Last Modified: 23 Feb 2009
Version:       21

This is a draft document. Many of these functions will work as in Perl 5, except we're trying to rationalize everything into roles. For now you can assume most of the important functions will automatically be in the * namespace. However, with IO operations in particular, many of them are really methods on an IO handle, and if there is a corresponding global function, it's merely an exported version of the method.

IO

Overridable IO handles

In Perl 6, there are the standard IO handles, and any number of overriding inner filehandles for the same symbol.

The standard handles are our old familiar friends (with new names). Standard input changed from STDIN to $*IN, standard output changed from STDOUT to $*OUT, and standard error changed from STDERR to $*ERR. In Perl 6 these symbols represent more of a concept than a given filehandle, since the meaning is contextually determined. The process's version of these handles live in the PROCESS:: namespace, which is more global than the per-interpreter GLOBAL:: namespace.

When no explicit filehandle is used, the standard IO operators are defined in terms of the contextual variables. So the print function prints to $*OUT, while warn warns to $*ERR. The =<> term inputs from $*IN. So any given dynamic scope (interpreter, thread, function or method call) may redefine the current meaning of any of those filehandles within the dynamic scope of itself and of its called routines.

So to put it another way, when you write something like

say "Howdy, world!"

the say function looks for the current meaning of $*OUT, and takes the closest definition it can find in its callers. If none of the callers have overridden the definition, it looks in the interpreter's GLOBAL namespace. If the interpreter hasn't overridden the meaning, it takes the meaning from PROCESS. In essence, any dynamic scope in Perl 6 is allowed to do IO redirection much like a Unix shell does with its subprocesses, albeit with a different syntax:

{
        temp $*OUT = open $newfile, :w;
        foo() # all stdout goes to $newfile
}
# stdout reverts to outer scope's definition

Roles and Classes

The roles and classes that define most of the functionality for IO are defined in S32-setting-library/IO.pod. The main functions used are listed in S29 with references to S32-setting-library/IO.pod.

Users and Groups

User role

role User { has $username; # Username (some descendants(?) may want to implement a real $name) has $id; # User ID has $dir; # Home directory for files }

new

method User new($Username?, $UID?) {...}

Creates a new User object, fetching the information either by username or user ID.

write

method write() {...}

Tries to write the current User object to the user database. This may well fail.

Str

When converted to a Str, returns $username.

Num

When converted to a Num, returns $uid.

OS::Unix::User role

role OS::Unix::User does User { has $password; has $gid; has $gecos; has $shell; }

All the information is naturally fetched from the system via getpwuid, getpwnam, or the like.

Group role

role Group { has $name; has $id; has @members; }

new

method Group new(:$Name, :$ID);

write

method write();

Tries to write the group entry into the system group database.

Additions

Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 86:

'=item' outside of any '=over'

Around line 106:

You forgot a '=back' before '=head2'

Around line 126:

'=item' outside of any '=over'

Around line 136:

You forgot a '=back' before '=head1'