On Fri, 28 Aug 2020, ToddAndMargo via perl6-users wrote:
> https://docs.raku.org/type/IO::Path#method_lines
>
> (IO::Path) method lines
>
> Defined as:
>
> method lines(IO::Path:D: :$chomp = True, :$enc = 'utf8', :$nl-in =
> ["\x0A", "\r\n"], |c --> Seq:D)
>
> Opens the invocant and returns its lines.
>
> The behavior is equivalent to opening the file specified
> by the invocant, forwarding the :$chomp, :$enc,
> and :$nl-in arguments to IO::Handle.open, then calling
> IO::Handle.lines on that handle, forwarding any of the
> remaining arguments to that method, and returning the
> resultant Seq.
>
> And if I am not pushing it, what is `|c`?
>
> [...]
> I do not understand
The description of this method says that it shall do two things:
- open the invocant path (IIRC you like to use the phrase
"what is fed into it" instead of "invocant") which returns
an IO::Handle,
- then call the lines method on this IO::Handle, resulting
in a sequence of lines (Seq in Raku), and it should return
this same Seq value.
The lines method on an IO::Path does the same as the lines method on an
IO::Handle, except that it has to open the path before to get a handle.
The arguments to the IO::Path.lines method therefore split into two groups:
- :$chomp, :$enc, :$nl-in which are passed on to the open call
in the first bullet point above,
- all the remaining arguments, whatever they are, are *captured*
by the syntax |c and will be forwarded to the IO::Handle.lines
call in the second bullet point above.
The |c is a so-called capture parameter [1]. It is used in a signature
(what you stubbornly call "cryptogram") when a method wants to inspect
some (or none) of the arguments it got but keep all the others in a
black box, named c here. The capture black box allows forwarding these
extra arguments to some other call. The point is that the IO::Path.lines
method does not need to know which arguments the target IO::Handle.lines
method accepts. It only needs to take everything in and pass it on.
It follows that you read about the meaning of the individual arguments or
which arguments it makes sense to pass to IO::Path.lines in the documentation
pages for the IO::Handle.open and IO::Handle.lines methods, which are linked
to in the text. Really, everything that IO::Path.lines does is redistribute
its arguments to two other method calls.
The documentation of lines does not tell you that |c is a capture parameter,
but it described what it is used for with the slide-in
[...] forwarding any of the remaining arguments to that method [...]
in the paragraph you quoted. The connection of that slide-in with the
"|c thing" is a matter of text comprehension.
Best,
Tobias
[1] https://docs.raku.org/type/Signature#Capture_parameters
--
"There's an old saying: Don't change anything... ever!" -- Mr. Monk
