Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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.