Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

chdir, get, lines

also remove more crazy stuff, and warn about the unreviewd stuff
  • Loading branch information...
commit ce9cbc72f5980253f688e0f834730ef6eda52a9f 1 parent 8082097
@moritz moritz authored
Showing with 43 additions and 362 deletions.
  1. +43 −362 S32-setting-library/IO.pod
View
405 S32-setting-library/IO.pod
@@ -158,6 +158,13 @@ file.
The routine will also C<fail> with the corresponding exception if there was any
other error in opening, writing, or closing.
+=item chdir
+
+ multi sub chdir(Str:D)
+ multi sub chdir(IO::Path::D)
+
+Changes the current working directory to the new value. Fails on error.
+
=back
=head1 IO Types
@@ -179,12 +186,26 @@ writing like a file.
=over 4
+=item get
+
+ method get() returns Str:D
+
+Reads and returns one line from the handle. Uses C<input-line-separator>
+to determine where a line ends.
+
+=item lines
+
+ method lines($limit = Inf)
+
+Returns a lazy list of lines read via the C<get> method, limited to C<$limit>
+lines.
+
=item getc
X<getc>
method getc (IO::Handle:D: Int $chars = 1 --> Str)
-See below for details.
+Reads C<$chars> and returns them
=item print
X<print>
@@ -426,12 +447,7 @@ Everything below this point hasn't been reviewed properly
=head2 IO::Socket
- role IO::Socket
- does IO::Closeable
- does IO::Readable
- does IO::Writeable
- does IO::Streamable
- {
+ role IO::Socket {
has %.options;
has Bool $.Listener;
...
@@ -501,26 +517,14 @@ Implements the IO::Writeable interface by doing a I<send(2)>.
=back
-=head2 IO::Handle
-
-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
-
-=head1 Classes
-
-=head2 IO::File
-
-This does file input and output.
+=head2 IO::Socket::INET
- class IO::File does IO::Streamable {
+ class IO::Socket::INET does IO::Socket {
+ has Str $.proto = 'TCP';
+ has Str $.host;
+ has Int $.port;
+ has Str $.localhost;
+ has Int $.localport;
...
}
@@ -528,326 +532,34 @@ This does file input and output.
=item new
- method new(
- Path :$Path,
- :$fd
- Bool :$NoOpen,
- :$Writeable,
- :$Readable
- );
-
-The C<Path> and C<fd> options are mutually exclusive.
-
-C<NoOpen> is passed to C<IO::Streamable.new()>
-
-Examples:
-
- # Read, no interpolation
- $fobj = IO::File.new(Path => qp{/path/to/file});
-
- # Write, interpolation
- $fobj = IO::File.new(
- Path => p:qq{$filename},
- Writeable => 1
- );
-
- # Read using file descriptor
- $fobj = IO::File.new(fd => $fd);
-
-This final example associates an C<IO> object with an already-open file descriptor,
-presumably passed in from the parent process.
-
-=item open()
-
-This function opens a file that had the C<NoOpen> option passed to the C<new> method.
-
-=item IO.truncate
-
-=item IO.fcntl
+ multi method new(:$host!, :$port, *%attributes) { ... }
+ multi method new(:$localhost!, :$localport, :$listen! *%attributes) { ... }
-Available only as a handle method.
+Creates a new socket and opens it.
=back
-=head2 IO::Directory
+=head2 IO::Handle
- role IO::Directory does IO::Streamable {
- ...
- }
+This role indicates that this object actually represents an open file
+descriptor in the os level.
=over
-=item open
-
- $dir.open(
- Str :$enc = "Unicode",
- );
-
-Opens a directory for processing, if the C<new> method was passed the C<NoOpen> option.
-Makes the directory looks like
-a list of autochomped lines, so just use ordinary C<IO> operators after the open.
-
-=back
-
-=head2 IO::FileSystems
-
-This represents the file systems mounted on the current machine (i.e. accessible via a
-filesystem path).
-
- class IO::FileSystems {
- has Str $.illegal-chars; # i.e. /\x0
- has Int $.max-path;
- has Int $.max-path-element;
- ...
- }
-
-=over 4
-
-=item chdir FILENAME
-X<chdir> X<cd>
-
-=item chdir
-
-Changes the current working directory to the one specified by FILENAME.
-If it succeeds it returns true, otherwise it returns C<Failure> and
-sets C<$!> (errno). Note, though, that chdir affects only the system
-directory; most things in Perl 6 that need a current directory depend
-on their thread's copy of $*CWD, so you probably want to set $*CWD
-instead of using chdir().
-
-
-=item glob
-
-Returns C<Path> objects. Path.Encoding is set to $?ENC unless the
-Encoding parameter is passed in (see Path for further discussion of
-encoding).
+=item method int fileno()
-=item rename
+File descriptors are always native integers, conforming to C89.
=back
-=head2 Path
-
-The "Path" role covers both the path to the file, and the file metadata. They
-are usually created with the qp{/path/to/file} syntax. It could be a directory,
-file, link, or something else OS-specific.
-
- role Path does Str does Array {
- has Str $.Type;
- has Str @.Elements;
- has Str $.Encoding;
- has Buf $.Binary;
- has IO::ACL @.ACLs;
- has %.times;
- ...
- }
-
-C<$.Type> can be C<File>, C<Directory>, C<Link>, or C<Other>. See
-C<.create()> method documentation for how it is set.
-
-The C<@.Elements> array is a list of Str that contain the path elements, but
-all are checked before being pushed onto the array. Note that @.Elements
-can not be accessed unless $.Encoding is defined.
-
-The C<%.times> has keys that can be e.g. C<ctime>, C<Modification>, and
-C<Access> (and maybe others on other operating systems), and the values are
-all C<Instant> objects.
-
-When a Path is used as a Str, it allows some operations, so that it can
-be concatenated easily with other strings. When used as an Array, it
-acts as an array of path elements.
-
-=head3 Methods
-
-=over 4
-
-=item new
-
-While new Path objects will normally be created with the qp{/path/to/file}
-syntax, there are also OO-related alternatives.
-
-This is called automatically on object creation.
-
- multi method new(
- Stringy :$Path,
- Str :@PathElements,
- Str :$Encoding,
- Str :@Constraints,
- Str :$Protocol,
+=head1 Conjectural Stuff
- Str :$Target,
- Str :$LinkType,
- Str :$Type,
- );
+Everything below this point should be considered as mere ideas for
+future evolution, not as things that a compiler write should implement
+unquestioningly.
-Path and PathElements are mutually exclusive.
-
-If the $Encoding parameter is not defined, then, if Path is a Buf,
-the $.Encoding attribute remains undefined, otherwise it is set to
-$?ENC. There are
-a number of features that don't work without the encoding being set.
-
-$Constraints determines whether the $Path and $Target strings should be
-assumed to be Unix-style, Windows-style, or something else.
-
-If the Type option is not passed in, the Path.Type attribute is initialised
-as follows:
-
- Value Condition
- ===== =========
- Directory $Path ends in a separator (i.e. /)
- Link $Target is specified
- Other $Protocol is specified
- Undefined All other cases
-
-If the $.Type attribute is read (which will happen in a number of cases,
-including when you read $.Target and $.LinkType), but is still undefined,
-then an attempt is
-made to determine what its type should be from the filesystem. If no
-answers are found using this method, then it defaults to "File".
-
-The C<Target> and C<LinkType> options are only relevant for links that have
-not been created yet, or are to be overwritten; in all other cases,
-they will be determined from the filesystem. If Target is not specified,
-this Path is assumed not to be a link. If LinkType is not specified,
-then the default is used (symbolic, on a Unix system).
-
-Examples:
-
- # These three do the same thing (on a Unix machine)
- $path = qp{/home/wayland};
- $path = Path.new(PathElements => ['home', 'wayland']);
- $path = Path.new(Constraints => ['Unix'], Path => qp{/home/wayland});
- $path = Path.new(Path => qp{/home/wayland});
-
- # This creates a symlink from /home/wayland/m to /home/wayland/Music
- $path = Path.new(
- Path => qp{/home/wayland/m},
- Target => qp{/home/wayland/Music},
- );
-
-=item path
-
-method path( --> Str);
-
-Returns @.elements concatenated together for use as a string. Usually this
-is the path that it was originally created with.
-
-=item canonpath
-
- method canonpath( --> Str);
-
-No physical check on the filesystem, but a logical cleanup of a path.
-
-=item realpath
-
- method realpath( --> Str);
-
-Gets the real path to the object, resolving softlinks/shortcuts, etc
-
-=item resolvepath
-
- method resolvepath(Str :@Types --> Str);
-
-@Types can contain "real" and "canon", in any order, and the
-method will run realpath and canonpath in the order specified.
-
-=item ACCEPTS
-
- multi method ACCEPTS(Path $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.
-
-=item create
-X<mkdir> X<md> X<directory, create> X<touch>
-
- method create(
- Bool :$Recursive,
- Bool :$Truncate,
- )
-
-Creates/touches the specified path. In the case of a link or a directory, no
-parameters are required. If a file doesn't exist, then no parameters are
-required. If the path already exists, then an exception is thrown, unless
-the file is an ordinary file or a link, and $Truncate is true.
-
-The $Recursive option specifies that any necessary parent directories should
-also be created.
-
-=item touch
-
-Update timestamps on a file.
-
-=item delete
-
-X<rmdir> X<rd> X<directory, remove>
-
- method delete(Bool :$Recursive --> Int);
-
-This deletes the C<Path> from the filesystem. If the node has children, it
-throws an error unless the C<Recursive> option is specified. It returns the
-number of nodes deleted, and may throw an exception.
-
-=item get
-
- multi get ()
-
-Returns the next line from $*ARGFILES. (Note that other C<get> functions
-and methods are operations on any iterator, not just an IO handle.)
-
-=item lines
-
- method lines ($handle:
- Any $limit = *,
- Bool :$bin = False,
- Str :$enc = "Unicode",
- Any :$nl = "\n",
- Bool :$chomp = True,
- --> List
- )
-
- multi lines (IO $fh = $*ARGFILES,
- Any $limit = *,
- Bool :$bin = False,
- Str :$enc = "Unicode",
- Any :$nl = "\n",
- Bool :$chomp = True,
- --> List
- )
-
- # See also Str.lines and lines(Str)
-
-Returns some or all the lines of a file or entries in a directory
-as a C<List> regardless of context.
-See also C<slurp>. Note that lists are lazy by default, but you
-can always ask for C<eager lines>. Note that the limit semantics cannot be
-duplicated by subscripting, since
-
- $fh.lines[^5]
-
-reads all the lines before the subscript gives you the first five,
-whereas
-
- $fh.lines(5)
-
-reads only five lines from the handle. Note that
-
- $fh.lines(1)
-
-is equivalent to
-
- $fh.get
-
-If fewer lines are available than the limit, it is not an error;
-you just get the number of lines available.
-
-
-=back
-
-=head3 Other things
+=head1 Other things
=over 4
@@ -919,27 +631,6 @@ done with groups too. Works on Unix, at least.
The C<$.owningObject> attribute of C<ACL> shows what the ACL is set on. On a
Windows system, this can be a parent directory, as permissions are inherited.
-=head2 IO::Socket::INET
-
- class IO::Socket::INET does IO::Socket {
- has Str $.proto = 'TCP';
- has Str $.host;
- has Int $.port;
- has Str $.localhost;
- has Int $.localport;
- ...
- }
-
-=over
-
-=item new
-
- multi method new(:$host!, :$port, *%attributes) { ... }
- multi method new(:$localhost!, :$localport, :$listen! *%attributes) { ... }
-
-Creates a new socket and opens it.
-
-=back
=head2 IO::Pipe
@@ -1206,16 +897,6 @@ Gone, see C<Path.times>.
=back
-=head1 Additions
-
-Please post errors and feedback to perl6-language. If you are making
-a general laundry list, please separate messages by topic.
-
-=head1 Conjectural stuff
-
-Old methods are moved here if it's not clear how they fit into the current
-picture. If nobody comes up with a good solution, they are removed.
-
=head2 IO::Buffered
Indicates that this object performs buffering. The management of the
Please sign in to comment.
Something went wrong with that request. Please try again.