Skip to content

Commit e9444f2

Browse files
MouqMouq
committed
Modernize IO docs
1 parent fa5823f commit e9444f2

File tree

4 files changed

+166
-114
lines changed

4 files changed

+166
-114
lines changed

‎lib/IO.pod

Lines changed: 14 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,29 @@
11
=begin pod
22
3-
=TITLE class IO
3+
=TITLE role IO
44
5-
class IO::Path is Cool does IO::FileTestable { }
5+
role IO { }
66
7-
=head1 Methods
7+
The IO role provides no functionality itself, and moreso just marks if a
8+
particular object relates to input/output.
89
9-
=head2 get
10+
=head1 Operators
1011
11-
Reads a single line from the input stream (usually the Standard Input or a file).
12-
13-
Read one line from the standard input:
14-
15-
$*IN.get;
16-
17-
Read one line from a file:
18-
19-
my $fh = open 'filename';
20-
my $line = $fh.get;
21-
22-
23-
=head2 getc
24-
25-
Read a single character from the input stream.
26-
27-
=head2 eof
28-
29-
Returns L<Bool::True> if the read operations have exhausted the content of the file.
30-
31-
=head2 lines
32-
33-
=head2 read
34-
35-
=head2 write
36-
37-
=head2 seek
38-
39-
=head2 tell
40-
41-
=head2 slurp
12+
=head2 prompt
4213
43-
=head2 close
14+
sub prompt($msg)
4415
45-
Will close a previously opened filehandle.
16+
Prints C<$msg> to the standard output and waits
17+
for the user to type in something and finish with an ENTER.
18+
Returns the string typed in without the trailing newline.
4619
47-
$fh.close;
20+
my $name = prompt("Hi, what's your name? ");
4821
4922
=head2 dir
5023
51-
sub dir Cool $path = '.', Mu :$test = none('.', '..')
24+
sub dir(Cool $path = '.', Mu :$test = none('.', '..'))
5225
53-
Returns a list of L<IO::File> and L<IO::Dir> objects for the
26+
Returns a list of L<IO::File> and L<IO::Path> objects for the
5427
files and directories found in the $path. If $path is not given
5528
assumes the current directory.
5629
@@ -74,75 +47,6 @@ To include only entries with a .pl extension write:
7447
7548
dir(test => /.pl$/)
7649
77-
=head2 prompt
78-
79-
Prints out a string to the standard output and waits
80-
for the user to type in something and finish with an ENTER.
81-
Returns the string typed in without the trailing newline.
82-
83-
my $name = prompt("Hi, what's your name?");
84-
85-
=head2 File Test operators
86-
87-
-e
88-
-f Do not exist in Perl 6. See :e, :f.
89-
90-
-M Does not exist in Perl 6. See C<modified>.
91-
-A Does not exist in Perl 6. See C<accessed>.
92-
-C Does not exist in Perl 6. See C<changed>.
93-
94-
:e Exists
95-
:d Directory
96-
:f File
97-
:l Symbolic link
98-
:r Readable
99-
:w Writable
100-
:x Executable
101-
:s Size
102-
:z Zero size
103-
104-
Usage:
105-
106-
If you have a string - a path to something in the filesystem:
107-
108-
if "path/to/file".IO ~~ :e {
109-
say 'file exists';
110-
}
111-
112-
my $file = "path/to/file";
113-
if $file.IO ~~ :e {
114-
say 'file exists';
115-
}
116-
117-
If you already have an IO object in $file, either by creating one yourself,
118-
or by getting it from another subroutine, such as C<dir>,
119-
you can write this:
120-
121-
my $file = "path/to/file".IO;
122-
if $file ~~ :e {
123-
say 'file exists';
124-
}
125-
126-
There are also 3 methods for fetching the 3 timestamps of a file (inode),
127-
on Operating Systems where these are available:
128-
129-
=head2 modified
130-
131-
Timestamp when the file was last modified.
132-
133-
"path/to/file".IO.modified()
134-
135-
=head2 accessed
136-
137-
Timestamp when the file was last accessed.
138-
139-
"path/to/file".IO.accessed()
140-
141-
=head2 changed
142-
143-
Timestamp when the inode was last changed.
144-
145-
"path/to/file".IO.changed()
50+
TODO: more IO Ops
14651
14752
=end pod
148-

‎lib/IO/FileTestable.pod

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
=begin pod
2+
3+
=TITLE role IO::FileTestable
4+
5+
role IO::FileTestable does IO { }
6+
7+
=head1 Methods
8+
9+
=head2 File Test operators
10+
11+
-e
12+
-f Do not exist in Perl 6. See :e, :f.
13+
14+
-M Does not exist in Perl 6. See C<modified>.
15+
-A Does not exist in Perl 6. See C<accessed>.
16+
-C Does not exist in Perl 6. See C<changed>.
17+
18+
:e Exists
19+
:d Directory
20+
:f File
21+
:l Symbolic link
22+
:r Readable
23+
:w Writable
24+
:x Executable
25+
:s Size
26+
:z Zero size
27+
28+
Usage:
29+
30+
If you have a string - a path to something in the filesystem:
31+
32+
if "path/to/file".IO ~~ :e {
33+
say 'file exists';
34+
}
35+
36+
my $file = "path/to/file";
37+
if $file.IO ~~ :e {
38+
say 'file exists';
39+
}
40+
41+
If you already have an IO object in $file, either by creating one yourself,
42+
or by getting it from another subroutine, such as C<dir>,
43+
you can write this:
44+
45+
my $file = "path/to/file".IO;
46+
if $file ~~ :e {
47+
say 'file exists';
48+
}
49+
50+
There are also 3 methods for fetching the 3 timestamps of a file (inode),
51+
on Operating Systems where these are available:
52+
53+
=head2 modified
54+
55+
Timestamp when the file was last modified.
56+
57+
"path/to/file".IO.modified()
58+
59+
=head2 accessed
60+
61+
Timestamp when the file was last accessed.
62+
63+
"path/to/file".IO.accessed()
64+
65+
=head2 changed
66+
67+
Timestamp when the inode was last changed.
68+
69+
"path/to/file".IO.changed()
70+
71+
=end pod
72+

‎lib/IO/Handle.pod

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
=begin pod
2+
3+
=TITLE class IO::Handle
4+
5+
class IO::Handle does IO::FileTestable { }
6+
7+
=head1 Methods
8+
9+
=head2 get
10+
11+
Reads a single line from the input stream (usually the Standard Input or a file).
12+
13+
Read one line from the standard input:
14+
15+
$*IN.get;
16+
17+
Read one line from a file:
18+
19+
my $fh = open 'filename';
20+
my $line = $fh.get;
21+
22+
23+
=head2 getc
24+
25+
Read a single character from the input stream.
26+
27+
=head2 eof
28+
29+
Returns L<Bool::True> if the read operations have exhausted the content of the file.
30+
31+
=head2 lines
32+
33+
method lines($limit = Inf)
34+
35+
Return a lazy list of the file's lines read via L<get>, limited to C<$limit> lines.
36+
37+
=for code :allow<B>
38+
my @data;
39+
my $data-file = open 'readings.csv'
40+
for B<$data-file.lines> -> $line {
41+
@data.push($line.split(','))
42+
}
43+
44+
=head2 read
45+
46+
method read(IO::Handle:D: Cool:D $bytes as Int --> Buf)
47+
48+
Binary reading; reads and returns C<$bytes> bytes from the handle
49+
50+
=head2 write
51+
52+
method write(IO::Handle:D: Blob:D $buf)
53+
54+
Binary writing; writes C<$buf> to the filehandle.
55+
56+
=head2 seek
57+
58+
=head2 tell
59+
60+
=head2 slurp
61+
62+
=head2 spurt
63+
64+
=head2 close
65+
66+
Will close a previously opened filehandle.
67+
68+
$fh.close;
69+
70+
=end pod
71+

‎type-graph.txt

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -108,11 +108,16 @@ class Duration is Cool does Real
108108
class Instant is Cool does Real
109109

110110
# IO
111-
role IO::FileTestable
112-
class IO does IO::FileTestable
111+
role IO
112+
role IO::FileTestable does IO
113+
class IO::Handle does IO::FileTestable
113114
class IO::Path is Cool does IO::FileTestable
114-
class IO::ArgFiles is IO
115-
role IO::Socket
115+
class IO::Path::Unix is IO::Path
116+
class IO::Path::Win32 is IO::Path
117+
class IO::Path::Cygwin is IO::Path
118+
class IO::Path::QNX is IO::Path
119+
class IO::ArgFiles is IO::Handle
120+
role IO::Socket does IO
116121
class IO::Socket::INET does IO::Socket
117122

118123
# Pod

0 commit comments

Comments
 (0)