Skip to content
This repository
Browse code

chdir, get, lines

also remove more crazy stuff, and warn about the unreviewd stuff
  • Loading branch information...
commit ce9cbc72f5980253f688e0f834730ef6eda52a9f 1 parent 8082097
Moritz Lenz authored July 06, 2012

Showing 1 changed file with 43 additions and 362 deletions. Show diff stats Hide diff stats

  1. 405  S32-setting-library/IO.pod
405  S32-setting-library/IO.pod
Source Rendered
@@ -158,6 +158,13 @@ file.
158 158
 The routine will also C<fail> with the corresponding exception if there was any
159 159
 other error in opening, writing, or closing.
160 160
 
  161
+=item chdir
  162
+
  163
+    multi sub chdir(Str:D)
  164
+    multi sub chdir(IO::Path::D)
  165
+
  166
+Changes the current working directory to the new value. Fails on error.
  167
+
161 168
 =back
162 169
 
163 170
 =head1 IO Types
@@ -179,12 +186,26 @@ writing like a file.
179 186
 
180 187
 =over 4
181 188
 
  189
+=item get
  190
+
  191
+    method get() returns Str:D
  192
+
  193
+Reads and returns one line from the handle. Uses C<input-line-separator>
  194
+to determine where a line ends.
  195
+
  196
+=item lines
  197
+
  198
+    method lines($limit = Inf)
  199
+
  200
+Returns a lazy list of lines read via the C<get> method, limited to C<$limit>
  201
+lines.
  202
+
182 203
 =item getc
183 204
 X<getc>
184 205
 
185 206
     method getc (IO::Handle:D: Int $chars = 1 --> Str)
186 207
 
187  
-See below for details.
  208
+Reads C<$chars> and returns them
188 209
 
189 210
 =item print
190 211
 X<print>
@@ -426,12 +447,7 @@ Everything below this point hasn't been reviewed properly
426 447
 
427 448
 =head2 IO::Socket
428 449
 
429  
-    role IO::Socket
430  
-        does IO::Closeable
431  
-        does IO::Readable
432  
-        does IO::Writeable
433  
-        does IO::Streamable
434  
-    {
  450
+    role IO::Socket {
435 451
         has %.options;
436 452
         has Bool $.Listener;
437 453
         ...
@@ -501,26 +517,14 @@ Implements the IO::Writeable interface by doing  a I<send(2)>.
501 517
 
502 518
 =back
503 519
 
504  
-=head2 IO::Handle
505  
-
506  
-This role indicates that this object actually represents an open file
507  
-descriptor in the os level.
508  
-
509  
-=over
510  
-
511  
-=item method int fileno()
512  
-
513  
-File descriptors are always native integers, conforming to C89.
514  
-
515  
-=back
516  
-
517  
-=head1 Classes
518  
-
519  
-=head2 IO::File
520  
-
521  
-This does file input and output.
  520
+=head2 IO::Socket::INET
522 521
 
523  
-    class IO::File does IO::Streamable {
  522
+    class IO::Socket::INET does IO::Socket {
  523
+        has Str $.proto = 'TCP';
  524
+        has Str $.host;
  525
+        has Int $.port;
  526
+        has Str $.localhost;
  527
+        has Int $.localport;
524 528
         ...
525 529
     }
526 530
 
@@ -528,326 +532,34 @@ This does file input and output.
528 532
 
529 533
 =item new
530 534
 
531  
-    method new(
532  
-        Path :$Path,
533  
-        :$fd
534  
-        Bool :$NoOpen,
535  
-        :$Writeable,
536  
-        :$Readable
537  
-    );
538  
-
539  
-The C<Path> and C<fd> options are mutually exclusive.  
540  
-
541  
-C<NoOpen> is passed to C<IO::Streamable.new()>
542  
-
543  
-Examples:
544  
-
545  
-    # Read, no interpolation
546  
-    $fobj = IO::File.new(Path => qp{/path/to/file});
547  
-
548  
-    # Write, interpolation
549  
-    $fobj = IO::File.new(
550  
-        Path => p:qq{$filename},
551  
-        Writeable => 1
552  
-    );
553  
-
554  
-    # Read using file descriptor
555  
-    $fobj = IO::File.new(fd => $fd);
556  
-
557  
-This final example associates an C<IO> object with an already-open file descriptor,
558  
-presumably passed in from the parent process.
559  
-
560  
-=item open()
561  
-
562  
-This function opens a file that had the C<NoOpen> option passed to the C<new> method.
563  
-
564  
-=item IO.truncate
565  
-
566  
-=item IO.fcntl
  535
+    multi method new(:$host!, :$port, *%attributes) { ... }
  536
+    multi method new(:$localhost!, :$localport, :$listen! *%attributes) { ... }
567 537
 
568  
-Available only as a handle method.
  538
+Creates a new socket and opens it.
569 539
 
570 540
 =back
571 541
 
572  
-=head2 IO::Directory
  542
+=head2 IO::Handle
573 543
 
574  
-    role IO::Directory does IO::Streamable {
575  
-        ...
576  
-    }
  544
+This role indicates that this object actually represents an open file
  545
+descriptor in the os level.
577 546
 
578 547
 =over
579 548
 
580  
-=item open
581  
-
582  
-    $dir.open(
583  
-        Str  :$enc = "Unicode",
584  
-    );
585  
-
586  
-Opens a directory for processing, if the C<new> method was passed the C<NoOpen> option.
587  
-Makes the directory looks like
588  
-a list of autochomped lines, so just use ordinary C<IO> operators after the open.
589  
-
590  
-=back
591  
-
592  
-=head2 IO::FileSystems
593  
-
594  
-This represents the file systems mounted on the current machine (i.e. accessible via a 
595  
-filesystem path).  
596  
-
597  
-    class IO::FileSystems {
598  
-        has Str $.illegal-chars; # i.e. /\x0
599  
-        has Int $.max-path;
600  
-        has Int $.max-path-element;
601  
-    ...
602  
-    }
603  
-
604  
-=over 4
605  
-
606  
-=item chdir FILENAME
607  
-X<chdir> X<cd>
608  
-
609  
-=item chdir
610  
-
611  
-Changes the current working directory to the one specified by FILENAME.
612  
-If it succeeds it returns true, otherwise it returns C<Failure> and
613  
-sets C<$!> (errno).  Note, though, that chdir affects only the system 
614  
-directory; most things in Perl 6 that need a current directory depend
615  
-on their thread's copy of $*CWD, so you probably want to set $*CWD
616  
-instead of using chdir().  
617  
-
618  
-
619  
-=item glob
620  
-
621  
-Returns C<Path> objects.  Path.Encoding is set to $?ENC unless the 
622  
-Encoding parameter is passed in (see Path for further discussion of
623  
-encoding).  
  549
+=item method int fileno()
624 550
 
625  
-=item rename
  551
+File descriptors are always native integers, conforming to C89.
626 552
 
627 553
 =back
628 554
 
629  
-=head2 Path
630  
-
631  
-The "Path" role covers both the path to the file, and the file metadata.  They
632  
-are usually created with the qp{/path/to/file} syntax.  It could be a directory,
633  
-file, link, or something else OS-specific.  
634  
-
635  
-    role Path does Str does Array {
636  
-        has Str $.Type;
637  
-        has Str @.Elements;
638  
-        has Str $.Encoding;
639  
-        has Buf $.Binary;
640  
-        has IO::ACL @.ACLs;
641  
-        has %.times;
642  
-    ...
643  
-    }
644  
-
645  
-C<$.Type> can be C<File>, C<Directory>, C<Link>, or C<Other>.  See 
646  
-C<.create()> method documentation for how it is set.  
647  
-
648  
-The C<@.Elements> array is a list of Str that contain the path elements, but
649  
-all are checked before being pushed onto the array.  Note that @.Elements
650  
-can not be accessed unless $.Encoding is defined.  
651  
-
652  
-The C<%.times> has keys that can be e.g. C<ctime>, C<Modification>, and 
653  
-C<Access> (and maybe others on other operating systems), and the values are 
654  
-all C<Instant> objects.
655  
-
656  
-When a Path is used as a Str, it allows some operations, so that it can 
657  
-be concatenated easily with other strings.  When used as an Array, it 
658  
-acts as an array of path elements.  
659  
-
660  
-=head3 Methods
661  
-
662  
-=over 4
663  
-
664  
-=item new
665  
-
666  
-While new Path objects will normally be created with the qp{/path/to/file} 
667  
-syntax, there are also OO-related alternatives.  
668  
-
669  
-This is called automatically on object creation.
670  
-
671  
-    multi method new(
672  
-        Stringy :$Path,
673  
-        Str :@PathElements,
674  
-        Str :$Encoding,
675 555
 
676  
-        Str :@Constraints, 
677  
-        Str :$Protocol,
  556
+=head1 Conjectural Stuff
678 557
 
679  
-        Str :$Target,
680  
-        Str :$LinkType,
681  
-        Str :$Type,
682  
-    );
  558
+Everything below this point should be considered as mere ideas for
  559
+future evolution, not as things that a compiler write should implement
  560
+unquestioningly.
683 561
 
684  
-Path and PathElements are mutually exclusive.  
685  
-
686  
-If the $Encoding parameter is not defined, then, if Path is a Buf, 
687  
-the $.Encoding attribute remains undefined, otherwise it is set to 
688  
-$?ENC.  There are
689  
-a number of features that don't work without the encoding being set.  
690  
-
691  
-$Constraints determines whether the $Path and $Target strings should be
692  
-assumed to be Unix-style, Windows-style, or something else.  
693  
-
694  
-If the Type option is not passed in, the Path.Type attribute is initialised 
695  
-as follows:
696  
-
697  
-    Value        Condition
698  
-    =====        =========
699  
-    Directory    $Path ends in a separator (i.e. /)
700  
-    Link         $Target is specified
701  
-    Other        $Protocol is specified
702  
-    Undefined    All other cases
703  
-
704  
-If the $.Type attribute is read (which will happen in a number of cases,
705  
-including when you read $.Target and $.LinkType), but is still undefined, 
706  
-then an attempt is 
707  
-made to determine what its type should be from the filesystem.  If no 
708  
-answers are found using this method, then it defaults to "File".  
709  
-
710  
-The C<Target> and C<LinkType> options are only relevant for links that have
711  
-not been created yet, or are to be overwritten; in all other cases, 
712  
-they will be determined from the filesystem.  If Target is not specified,
713  
-this Path is assumed not to be a link.  If LinkType is not specified, 
714  
-then the default is used (symbolic, on a Unix system).  
715  
-
716  
-Examples:
717  
-
718  
-    # These three do the same thing (on a Unix machine)
719  
-    $path = qp{/home/wayland};
720  
-    $path = Path.new(PathElements => ['home', 'wayland']);
721  
-    $path = Path.new(Constraints => ['Unix'], Path => qp{/home/wayland});
722  
-    $path = Path.new(Path => qp{/home/wayland});
723  
-
724  
-    # This creates a symlink from /home/wayland/m to /home/wayland/Music
725  
-    $path = Path.new(
726  
-        Path => qp{/home/wayland/m},
727  
-        Target => qp{/home/wayland/Music},
728  
-    );
729  
-
730  
-=item path
731  
-
732  
-method path( --> Str);
733  
-
734  
-Returns @.elements concatenated together for use as a string.  Usually this 
735  
-is the path that it was originally created with.  
736  
-
737  
-=item canonpath
738  
-
739  
-    method canonpath( --> Str);
740  
-
741  
-No physical check on the filesystem, but a logical cleanup of a path.
742  
-
743  
-=item realpath
744  
-
745  
-    method realpath( --> Str);
746  
-
747  
-Gets the real path to the object, resolving softlinks/shortcuts, etc
748  
-
749  
-=item resolvepath
750  
-
751  
-    method resolvepath(Str :@Types --> Str);
752  
-
753  
-@Types can contain "real" and "canon", in any order, and the
754  
-method will run realpath and canonpath in the order specified.
755  
-
756  
-=item ACCEPTS
757  
-
758  
-    multi method ACCEPTS(Path $filename);
759  
-
760  
-Test whether the specified filename is the same file as this file.  On a 
761  
-Unix system, this would presumably be done by comparing inode numbers or 
762  
-something.  
763  
-
764  
-=item create
765  
-X<mkdir> X<md> X<directory, create> X<touch>
766  
-
767  
-    method create(
768  
-        Bool :$Recursive,
769  
-        Bool :$Truncate,
770  
-    )
771  
-
772  
-Creates/touches the specified path.  In the case of a link or a directory, no 
773  
-parameters are required.  If a file doesn't exist, then no parameters are 
774  
-required.  If the path already exists, then an exception is thrown, unless
775  
-the file is an ordinary file or a link, and $Truncate is true.  
776  
-
777  
-The $Recursive option specifies that any necessary parent directories should
778  
-also be created.  
779  
-
780  
-=item touch
781  
-
782  
-Update timestamps on a file.  
783  
-
784  
-=item delete
785  
-
786  
-X<rmdir> X<rd> X<directory, remove>
787  
-
788  
-    method delete(Bool :$Recursive --> Int);
789  
-
790  
-This deletes the C<Path> from the filesystem.  If the node has children, it 
791  
-throws an error unless the C<Recursive> option is specified.  It returns the 
792  
-number of nodes deleted, and may throw an exception.  
793  
-
794  
-=item get
795  
-
796  
-    multi get () 
797  
-
798  
-Returns the next line from $*ARGFILES.  (Note that other C<get> functions
799  
-and methods are operations on any iterator, not just an IO handle.)
800  
-
801  
-=item lines
802  
-
803  
-    method lines ($handle:
804  
-        Any  $limit = *,
805  
-        Bool :$bin = False,
806  
-        Str  :$enc = "Unicode",
807  
-        Any  :$nl = "\n",
808  
-        Bool :$chomp = True,
809  
-        --> List
810  
-    )
811  
-
812  
-    multi lines (IO $fh = $*ARGFILES,
813  
-        Any  $limit = *,
814  
-        Bool :$bin = False,
815  
-        Str  :$enc = "Unicode",
816  
-        Any  :$nl = "\n",
817  
-        Bool :$chomp = True,
818  
-        --> List
819  
-    )
820  
-
821  
-    # See also Str.lines and lines(Str)
822  
-
823  
-Returns some or all the lines of a file or entries in a directory
824  
-as a C<List> regardless of context.
825  
-See also C<slurp>.  Note that lists are lazy by default, but you
826  
-can always ask for C<eager lines>.  Note that the limit semantics cannot be
827  
-duplicated by subscripting, since
828  
-
829  
-    $fh.lines[^5]
830  
-
831  
-reads all the lines before the subscript gives you the first five,
832  
-whereas
833  
-
834  
-    $fh.lines(5)
835  
-
836  
-reads only five lines from the handle.  Note that
837  
-
838  
-    $fh.lines(1)
839  
-
840  
-is equivalent to
841  
-
842  
-    $fh.get
843  
-
844  
-If fewer lines are available than the limit, it is not an error;
845  
-you just get the number of lines available.
846  
-
847  
-
848  
-=back
849  
-
850  
-=head3 Other things
  562
+=head1 Other things
851 563
 
852 564
 =over 4
853 565
 
@@ -919,27 +631,6 @@ done with groups too.  Works on Unix, at least.
919 631
 The C<$.owningObject> attribute of C<ACL> shows what the ACL is set on.  On a
920 632
 Windows system, this can be a parent directory, as permissions are inherited.
921 633
 
922  
-=head2 IO::Socket::INET
923  
-
924  
-    class IO::Socket::INET does IO::Socket {
925  
-        has Str $.proto = 'TCP';
926  
-        has Str $.host;
927  
-        has Int $.port;
928  
-        has Str $.localhost;
929  
-        has Int $.localport;
930  
-        ...
931  
-    }
932  
-
933  
-=over
934  
-
935  
-=item new
936  
-
937  
-    multi method new(:$host!, :$port, *%attributes) { ... }
938  
-    multi method new(:$localhost!, :$localport, :$listen! *%attributes) { ... }
939  
-
940  
-Creates a new socket and opens it.
941  
-
942  
-=back
943 634
 
944 635
 =head2 IO::Pipe
945 636
 
@@ -1206,16 +897,6 @@ Gone, see C<Path.times>.
1206 897
 
1207 898
 =back
1208 899
 
1209  
-=head1 Additions
1210  
-
1211  
-Please post errors and feedback to perl6-language.  If you are making
1212  
-a general laundry list, please separate messages by topic.
1213  
-
1214  
-=head1 Conjectural stuff
1215  
-
1216  
-Old methods are moved here if it's not clear how they fit into the current
1217  
-picture. If nobody comes up with a good solution, they are removed.
1218  
-
1219 900
 =head2 IO::Buffered
1220 901
 
1221 902
 Indicates that this object performs buffering. The management of the

0 notes on commit ce9cbc7

Please sign in to comment.
Something went wrong with that request. Please try again.