Documentation for routine words assembled from the following types:

class Supply

From Supply

(Supply) method words

method words(Supply:D: --> Supply:D)

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 $s = Supply.from-list("Hello Word!".comb);
my $ws = $s.words;
$ws.tap(&say);           # OUTPUT: «Hello␤Word!␤»

class Str

From Str

(Str) routine words

multi method words(Str:D: $limit)
multi method words(Str:D:)

Returns a list of non-whitespace bits, i.e. the same as a call to $input.comb( / \S+ /, $limit ) would.

Examples:

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 $limit words.

say words("I will be very brief here", 2); # OUTPUT: «(I will)␤»

class Cool

From Cool

(Cool) method words

Defined as:

method words(Cool:D: |c)

Coerces the invocant (or first argument, if it is called as a subroutine) to Str, and returns a list of words that make up the string. Check Str.words for additional arguments and its meaning.

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␤»

Please see Str.words for more examples and ways to invoke it.

class IO::CatHandle

From IO::CatHandle

(IO::CatHandle) method words

Defined as:

method words(IO::CatHandle:D: $limit = Inf, :$close --> Seq:D)

Same as 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 $f1 = 'foo'.IO).spurt: 'foo bar';
(my $f2 = 'bar'.IO).spurt: 'meow';
IO::CatHandle.new($f1, $f2).words.perl.say;
# OUTPUT: «("foo", "bar", "meow").Seq␤» 

Note: if :$close is False, fully-consumed handles are still going to be closed.

class IO::Path

From IO::Path

(IO::Path) method words

Defined as:

method words(IO::Path:D: :$chomp = True, :$enc = 'utf8', :$nl-in = ["\x0A", "\r\n"], |c --> Seq:D)

Opens the invocant and returns its words.

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.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 %dict := bag 'my-file.txt'.IO.words;
say "Most common words: ", %dict.sort(-*.value).head: 5;

class IO::Handle

From IO::Handle

(IO::Handle) routine words

Defined as:

multi sub words(IO::Handle:D $fh = $*ARGFILES, $limit = Inf, :$close --> Seq:D)
multi method words(IO::Handle:D: $limit = Inf, :$close --> Seq:D)

Similar to 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 %dict := bag $*IN.words;
say "Most common words: ", %dict.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.