Documentation for routine
words assembled from the following types:
method words(Supply: --> Supply)
Creates a supply that will emit the characters coming in word for word from a supply that's usually created by some asynchronous I/O operation.
my = Supply.from-list("Hello Word!".comb);my = .words;.tap(); # OUTPUT: «Hello␤Word!␤»
multi method words(Str: )multi method words(Str:)
Returns a list of non-whitespace bits, i.e. the same as a call to
$input.comb( / \S+ /, $limit ) would.
say "a\nb\n".words.perl; # OUTPUT: «("a", "b").Seq␤»say "hello world".words.perl; # OUTPUT: «("hello", "world").Seq␤»say "foo:bar".words.perl; # OUTPUT: «("foo:bar",).Seq␤»say "foo:bar\tbaz".words.perl; # OUTPUT: «("foo:bar", "baz").Seq␤»
It can also be used as a subroutine, turning the first argument into the invocant.
$limit is optional, but if it is provided (and not equal to
Inf), it will return only the first
say words("I will be very brief here", 2); # OUTPUT: «(I will)␤»
method words(Cool: |c)
say <The quick brown fox>.words.join('|'); # OUTPUT: «The|quick|brown|fox␤»say <The quick brown fox>.words(2).join('|'); # OUTPUT: «The|quick␤»
Cool is the base class for many other classes, and some of them, like Match, can be converted to a string. This is what happens in this case:
say ( "easy come, easy goes" ~~ m:g/(ea\w+)/).words(Inf);# OUTPUT: «(easy easy)␤»say words( "easy come, easy goes" ~~ m:g/(ea\w+)/ , ∞);# OUTPUT: «(easy easy)␤»
The example above illustrates two of the ways
words can be invoked, with the first argument turned into invocant by its signature. Of course,
Inf is the default value of the second argument, so in both cases (and forms) it can be simply omitted.
Only whitespace (including no-break space) counts as word boundaries
say <Flying on a Boeing 747>.words.join('|'); # OUTPUT: «Flying|on|a|Boeing|747␤»
In this case, "Boeing 747" includes a (visible only in the source) no-break space;
words still splits the (resulting)
Str on it, even if the original array only had 4 elements:
say <Flying on a Boeing 747>.join('|'); # OUTPUT: «Flying|on|a|Boeing 747␤»
Str.words for more examples and ways to invoke it.
method words(IO::CatHandle: = Inf, : --> Seq)
IO::Handle.words (including the caveat about more data read than needed to make some number of words). Note that a boundary between source handles is considered to be word boundary.
(my = 'foo'.IO).spurt: 'foo bar';(my = 'bar'.IO).spurt: 'meow';IO::CatHandle.new(, ).words.perl.say;# OUTPUT: «("foo", "bar", "meow").Seq␤»
False, fully-consumed handles are still going to be closed.
method words(IO::Path: : = True, : = 'utf8', : = ["\x0A", "\r\n"], |c --> Seq)
Opens the invocant and returns its words.
The behavior is equivalent to opening the file specified by the invocant, forwarding the
:$nl-in arguments to
IO::Handle.open, then calling
IO::Handle.words on that handle, forwarding any of the remaining arguments to that method, and returning the resultant Seq.
NOTE: words are lazily read. The handle used under the hood is not closed until the returned Seq is fully reified, and this could lead to leaking open filehandles. It is possible to avoid leaking open filehandles using the
$limit argument to cut down the
Seq of words to be generated.
my := bag 'my-file.txt'.IO.words;say "Most common words: ", .sort(-*.value).head: 5;
multi sub words(IO::Handle = , = Inf, : --> Seq)multi method words(IO::Handle: = Inf, : --> Seq)
Str.words, separates the handle's stream on contiguous chunks of whitespace (as defined by Unicode) and returns a Seq of the resultant "words." Takes an optional
$limit argument that can be a non-negative Int,
Inf, or Whatever (which is interpreted to mean
Inf), to indicate only up-to
$limit words must be returned. If Bool
:$close named argument is set to
True, will automatically close the handle when the returned Seq is exhausted. Subroutine form defaults to
$*ARGFILES, if no handle is provided.
Attempting to call this method when the handle is in binary mode will result in
X::IO::BinaryMode exception being thrown.
my := bag .words;say "Most common words: ", .sort(-*.value).head: 5;
NOTE: implementations may read more data than necessary when a call to
.words is made. That is,
$handle.words(2) may read more data than two "words" worth of data and subsequent calls to read methods might not read from the place right after the two fetched words. After a call to
.words, the file position should be treated as undefined.