I'd like to note that FileDescriptors are not reserved unices. I know
Windows also has them (though they aren't commonly used), and quite
possibly others too.
Also, IO::Socket.close() is not an alternative for a shutdown()
method. They do subtly different things. IO::Socket should support
both IMHO.
Regards,
Leon
On Wed, Feb 18, 2009 at 4:30 AM, <pugs-comm...@feather.perl6.nl> wrote:
> Author: wayland
> Date: 2009-02-18 04:30:33 +0100 (Wed, 18 Feb 2009)
> New Revision: 25371
>
> Modified:
> docs/Perl6/Spec/S16-io.pod
> Log:
> S16: Redid things in terms of trees, at least somewhat.
>
>
> Modified: docs/Perl6/Spec/S16-io.pod
> ===================================================================
> --- docs/Perl6/Spec/S16-io.pod 2009-02-17 21:05:38 UTC (rev 25370)
> +++ docs/Perl6/Spec/S16-io.pod 2009-02-18 03:30:33 UTC (rev 25371)
> @@ -204,21 +204,6 @@
> the $.locale, or the undefined value at end of file, or if there was
> an error (in the latter case C<$!> is set).
>
> -=item our List multi method lines (IO $handle:) is export;
> -
> -=item our List multi lines (Str $filename);
> -
> -Returns all the lines of a file as a (lazy) List regardless of context.
> -See also C<slurp>.
> -
> -=item our Item multi method slurp (IO $handle: *%opts) is export;
> -
> -=item our Item multi slurp (Str $filename, *%opts);
> -
> -Slurps the entire file into a Str or Buf regardless of context.
> -(See also C<lines>.) Whether a Str or Buf is returned depends on
> -the options.
> -
> =back
>
> =head2 IO::Writeable::Encoded
> @@ -314,19 +299,6 @@
>
> =back
>
> -=head2 IO::FileDescriptor
> -
> -This role indicates that this object actually represents an open file
> -descriptor in the os level.
> -
> -=over
> -
> -=item method int fileno()
> -
> -File descriptors are always native integers, conforming to C89.
> -
> -=back
> -
> =head2 IO::Closeable
>
> This role indicates that this object can be closed.
> @@ -350,26 +322,17 @@
>
> =head2 IO::Socket
>
> -role IO::Socket {
> +role IO::Socket {
> + has %.options;
> ...
> }
>
> +Accessing the %.options would on Unix be done with getsockopt/setsockopt.
> +
> =over
>
> -=item socket
> +=item pair
>
> -=item IO.setsockopt
> -
> -=item IO.shutdown
> -
> -(should IO::Socket.close() call shutdown, instead of having a different
> name?)
> -
> -=item IO.accept
> -
> -=item IO.bind
> -
> -=item Socket.pair
> -
> our List of IO method pair(Int $domain, Int $type, Int $protocol)
>
> A wrapper for socketpair(2), returns a pair of IO objects representing the
> @@ -381,18 +344,89 @@
>
> =back
>
> -=head1 Filehandles, files, and directories
> +=head2 IO::Listening
>
> -=over 4
> +=item open
>
> -=item IO.fcntl
> + method open()
>
> -Available only as a handle method.
> + Does a bind() and a listen().
>
> -=item IO.ioctl
> +=item accept
>
> -Available only as a handle method.
> + method IO::Socket accept()
>
> +=head2 Tree Roles and Classes
> +
> +To support the filesystem, it is also useful to define some generic tree
> roles, which
> +could equally well be used for XML or LDAP as well as filesystem
> representation. However,
> +while the roles are generic, the comments and documentation in this section
> refers
> +specifically to filesystems.
> +
> +=head3 Tree::Name
> +
> + class Tree::Name {
> + has $.namespace;
> + has $.prefix;
> +
> + # Call this for stringifying
> + method fullname()
> + }
> +
> + fullname for XML does "$namespace:$prefix"
> +
> +=head3 Tree::Node
> +
> +This should be an ancestor role to filesystems, their elements, their
> attributes, and the
> +like.
> +
> + role Tree::Node does Array {
> + has Tree::Name $.name; # would usually be File or Directory on a
> filesystem
> + has $.ownerNode; # This is the IO::FileSystem
> + has $.rootNode; This is the root of the filesystem
> + has $.parent; # Another Tree::Node
> + has @.children handles <Array List Container>; # This is all the
> child notes
> + has $.path is ro; # Accessor does a getpath
> + has $.depth is ro; # depth from $ownerNode
> +
> + method infix:<===>(...)
> + method infix:<==>(...)
> + multi method *infix:</>(Tree::Node @nodes: Matcher $test);
> + multi method postfix:<//>(Tree::Node @parents: Matcher $test);
> + method path(Str $.quitcriteria); # This allows the path call to quit
> eg. when it
> + # gets to the filesystem root, instead of the overall root
> + }
> +
> +Array operations on this are entirely capable of moving files and
> directories,
> +
> +=head3 Tree
> +
> + role Tree does Tree::Node {
> + has Tree::Node $root; # The root directory
> + has Tree::Node $cwn; # The current working directory (node)
> + }
> +
> +=head3 Tree::Element
> +
> + role Tree::Element does Tree::Node {
> + has %.attributes; # This is all the attributes, including Name
> + has Str $!defaultattributename;
> + method postcircumfix:<{ }>($selector, $node(s)); # Accesses stuff in
> %attributes
> + method pathelement();
> + }
> +
> +=head3 Tree::Attribute
> +
> + role Tree::Attribute does Tree::Node {
> + has $.value;
> +
> + method pathelement();
> + }
> +
> +=head1 Filehandles, files, and directories
> +
> +=over 4
> +
> =item IO.name
>
> The C<.name> method returns the name of the file/socket/uri the handle
> @@ -442,40 +476,37 @@
>
> =item IO.truncate
>
> +=item IO.fcntl
> +
> +Available only as a handle method.
> +
> =back
>
> =head2 IO::FileSystem
>
> This reads directories, deletes filesystem entries, creates links, and the
> like.
>
> -class IO::FileSystem does IO::Streamable {
> - has IO::FileSystemEntry $.cwd; # Current working directory
> - has IO::FileSystemEntry $.basepath; # The Unix mount point, or
> Windows drive letter, or whatever
> - has Str $.type; # ext3, ntfs, vfat, reiserfs, etc
> +class IO::FileSystem does IO::Streamable does Tree {
> + has Str $.fstype; # ext3, ntfs, vfat, reiserfs, etc
> has Str $.illegal_chars; # ie. /\x0
> has Int $.max_path;
> ...
> }
>
> +It inherits $cwn and $root from Tree.
> +
> =over 4
>
> =item glob
>
> -Returns FileSystemEntry objects
> +Returns FSNode objects
>
> =item find
>
> -Returns FileSystemEntry objects
> +Returns FSNode objects
>
> =item link
>
> -=item lstat
> -
> -Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates
> -to true, and additional file tests may be performed on the value. If
> -the stat fails, all subsequent tests on the stat buffer also evaluate
> -to false.
> -
> =item mkdir
>
> =item IO::Dir::open EXPR
> @@ -518,11 +549,10 @@
>
> =back
>
> -=head2 IO::FilesystemEntry
> +=head2 IO::FSNode
>
> -class IO::FileSystemEntry {
> - has Str $path;
> - has IO::FileSystemEntryACL @.acls;
> +class IO::FSNode does Tree::Node {
> + has Array of IO::FSNodeACL @.ACLs;
> ...
> }
>
> @@ -621,100 +651,33 @@
> if $filename.TEST(:e,:x) {...}
>
>
> -=item chown
> -
> - our Int multi chown ($uid = -1, $gid = -1, *...@files)
> -
> -Changes the owner (and group) of a list of files. The first
> -two elements of the list must be the numeric uid and gid, in
> -that order. A value of -1 in either position is interpreted by
> -most systems to leave that value unchanged. Returns the number
> -of files successfully changed.
> -
> - $count = chown $uid, $gid, 'foo', 'bar';
> - chown $uid, $gid, @filenames;
> -
> -On systems that support C<fchown>, you might pass file handles
> -among the files. On systems that don't support C<fchown>, passing
> -file handles produces a fatal error at run time.
> -
> -Here's an example that looks up nonnumeric uids in the passwd
> -file:
> -
> - $user = prompt "User: ";
> - $pattern = prompt "Files: ";
> -
> - ($login,$pass,$uid,$gid) = getpwnam($user)
> - or die "$user not in passwd file";
> -
> - @ary = glob($pattern); # expand filenames
> - chown $uid, $gid, @ary;
> -
> -On most systems, you are not allowed to change the ownership of
> -the file unless you're the superuser, although you should be
> -able to change the group to any of your secondary groups. On
> -insecure systems, these restrictions may be relaxed, but this
> -is not a portable assumption. On POSIX systems, you can detect
> -this condition this way:
> -
> - use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
> - $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
> -
> -=item chmod LIST
> -X<chmod> X<permission> X<mode>
> -
> -Changes the permissions of a list of files. The first element of the
> -list must be the numerical mode, which should probably be an octal
> -number, and which definitely should I<not> be a string of octal digits:
> -C<0o644> is okay, C<0644> is not. Returns the number of files
> -successfully changed.
> -
> - $cnt = chmod 0o755, 'foo', 'bar';
> - chmod 0o755, @executables;
> - $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to --w----r-T
> - $mode = '0o644'; chmod $mode, 'foo'; # this is better
> - $mode = 0o644; chmod $mode, 'foo'; # this is best
> -
> -=item stat
> -
> -=item IO.stat
> -
> -Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates
> -to true, and additional file tests may be performed on the value. If
> -the stat fails, all subsequent tests on the stat buffer also evaluate
> -to false.
> -
> =item realpath
>
> method Str realpath();
>
> Gets the real path to the object, resolving softlinks/shortcuts, etc
>
> -=item parent
> +=item === operator
>
> - method IO::FileSystemEntry parent();
> + method infix:<===>(Str $filename);
>
> -=item isSameFile
> -
> - method isSameFile(Str $filename);
> -
> Test whether the specified filename is the same file as this file. On a
> Unix system,
> this would presumably be done by comparing inode numbers or something.
>
> =back
>
> -=head2 IO::FileSystemEntryACL
> +=head2 IO::FSNodeACL
>
> This is a basic abstraction; for better control, use the operating-system
> specific
> -interfaces [not designed yet], over which this is a thin veneer.
> +interfaces, over which this is a thin veneer.
>
> -class IO::FileSystemEntryACL {
> +class IO::FSNodeACL {
> has Str $.type; # "User", "Group", "Everyone", ???
> has Str $.id; # username or groupname; unused for $type eq
> "Everyone"
> has %.permissions;
> # Unsupported values may (or may not) throw
> # UnsupportedPermission when set or read
> - has IO::FileSystemEntry $.owningObject;
> + has IO::FSNode $.owningObject;
> ...
> }
>
> @@ -734,7 +697,8 @@
>
> =item Executeable
>
> -Supported on most Unix systems, anyway
> +Supported on most Unix systems, anyway. Windows should be able to guess
> when this is
> +read, and throw an exception if written to.
>
> =item Default
>
> @@ -743,9 +707,40 @@
>
> =back
>
> -The $.owningObject attribute of FileSystemEntryACL shows what the ACL is set
> on. On a
> +The $.owningObject attribute of FSNodeACL shows what the ACL is set on. On a
> Windows system, this can be a parent directory, as permissions are inherited.
>
> +=head2 IO::FileNode
> +
> + role IO::FileNode does IO::FSNode {
> +...
> + }
> +
> +=over
> +
> +=item our List multi method lines (IO $handle:) is export;
> +
> +=item our List multi lines (Str $filename);
> +
> +Returns all the lines of a file as a (lazy) List regardless of context.
> +See also C<slurp>.
> +
> +=item our Item multi method slurp (IO $handle: *%opts) is export;
> +
> +=item our Item multi slurp (Str $filename, *%opts);
> +
> +Slurps the entire file into a Str or Buf regardless of context.
> +(See also C<lines>.) Whether a Str or Buf is returned depends on
> +the options.
> +
> +=back
> +
> +=head2 IO::DirectoryNode
> +
> + role IO::DirectoryNode does IO::FSNode {
> +...
> + }
> +
> =head2 IO::Socket::TCP
>
> class IO::Socket::TCP does IO::Socket does IO::Streamable {
> @@ -762,12 +757,25 @@
>
> =item has $.LocalPort
>
> -=item method Bool open($Listen?);
> +=item init
>
> -If $Listen is 2, it does a listen(), but no connect().
> -If $Listen is any other true value, it does a connect() and a listen().
> -If $Listen is false, it does a connect(), but no listen().
> + method Bool init(
> + $RemoteHost, $RemotePort,
> + $LocalHost?, $LocalPort?,
> + $Blocking?,
> + $NoOpen?
> + );
>
> +The creation of the object will also open the connection, unless NoOpen is
> specified.
> +
> +=item open
> +
> + method open()
> +
> +If it's not an IO::Listening, it does a connect().
> +
> +It's intended for the case where the creation of the object didn't do one.
> +
> =item method Int read($buf is rw, Int $length)
>
> Does a recv().
> @@ -782,25 +790,6 @@
>
> =back
>
> -=head2 IO::POSIX
> -
> -Indicates that this object can perform standard posix IO
> -operations. It implies IO::Readable and IO::Writeable.
> -
> -=over
> -
> -=item method IO dup()
> -
> -=item has Bool $.blocking is rw
> -
> -=item method Bool flock(:$r,:$w)
> -
> -=item method Bool funlock()
> -
> -=item ...
> -
> -=back
> -
> =head2 IO::Pipe
>
> class IO::Pipe does IO::Streamable {
> @@ -860,12 +849,124 @@
>
> =back
>
> +=head1 OS-specific classes
> +
> +=head2 Unix
> +
> +=head2 IO::FileDescriptor
> +
> +This role indicates that this object actually represents an open file
> +descriptor in the os level.
> +
> +=over
> +
> +=item method int fileno()
> +
> +File descriptors are always native integers, conforming to C89.
> +
> +=back
> +
> +=head2 IO::FSNode::Unix
> +
> +=item chown
> +
> + our Int multi chown ($uid = -1, $gid = -1, *...@files)
> +
> +Changes the owner (and group) of a list of files. The first
> +two elements of the list must be the numeric uid and gid, in
> +that order. A value of -1 in either position is interpreted by
> +most systems to leave that value unchanged. Returns the number
> +of files successfully changed.
> +
> + $count = chown $uid, $gid, 'foo', 'bar';
> + chown $uid, $gid, @filenames;
> +
> +On systems that support C<fchown>, you might pass file handles
> +among the files. On systems that don't support C<fchown>, passing
> +file handles produces a fatal error at run time.
> +
> +Here's an example that looks up nonnumeric uids in the passwd
> +file:
> +
> + $user = prompt "User: ";
> + $pattern = prompt "Files: ";
> +
> + ($login,$pass,$uid,$gid) = getpwnam($user)
> + or die "$user not in passwd file";
> +
> + @ary = glob($pattern); # expand filenames
> + chown $uid, $gid, @ary;
> +
> +On most systems, you are not allowed to change the ownership of
> +the file unless you're the superuser, although you should be
> +able to change the group to any of your secondary groups. On
> +insecure systems, these restrictions may be relaxed, but this
> +is not a portable assumption. On POSIX systems, you can detect
> +this condition this way:
> +
> + use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
> + $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
> +
> +=item chmod LIST
> +X<chmod> X<permission> X<mode>
> +
> +Changes the permissions of a list of files. The first element of the
> +list must be the numerical mode, which should probably be an octal
> +number, and which definitely should I<not> be a string of octal digits:
> +C<0o644> is okay, C<0644> is not. Returns the number of files
> +successfully changed.
> +
> + $cnt = chmod 0o755, 'foo', 'bar';
> + chmod 0o755, @executables;
> + $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to --w----r-T
> + $mode = '0o644'; chmod $mode, 'foo'; # this is better
> + $mode = 0o644; chmod $mode, 'foo'; # this is best
> +
> +=item lstat
> +
> +Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates
> +to true, and additional file tests may be performed on the value. If
> +the stat fails, all subsequent tests on the stat buffer also evaluate
> +to false.
> +
> +=item stat
> +
> +=item IO.stat
> +
> +Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates
> +to true, and additional file tests may be performed on the value. If
> +the stat fails, all subsequent tests on the stat buffer also evaluate
> +to false.
> +
> +=head2 IO::POSIX
> +
> +Indicates that this object can perform standard posix IO
> +operations. It implies IO::Readable and IO::Writeable.
> +
> +=over
> +
> +=item method IO dup()
> +
> +=item has Bool $.blocking is rw
> +
> +=item method Bool flock(:$r,:$w)
> +
> +=item method Bool funlock()
> +
> +=item ...
> +
> +=back
> +
> =head1 Unfiled
>
> =over 4
>
> =item IO.fileno
>
> +=item IO.ioctl
> +
> +Available only as a handle method.
> +
> =item alarm
>
> =item prompt
> @@ -874,12 +975,8 @@
>
> =item Str.readpipe
>
> -=item IO.sysread
> -
> =item IO.sysseek
>
> -=item IO.syswrite
> -
> =back
>
> =head1 Removed functions
> @@ -898,10 +995,22 @@
>
> Gone. (Note: for subsecond sleep, just use sleep with a fractional
> argument.)
>
> +=item IO.shutdown()
> +
> +Gone, see IO::Socket.close()
> +
> =item socketpair
>
> Gone, see Socket.pair
>
> +=item IO.sysread
> +
> +Gone, see IO::Readable.read()
> +
> +=item IO.syswrite
> +
> +Gone, see IO::Writeable.read()
> +
> =back
>
> =head1 Additions
>
>
