Documentation for routine words

Documentation for routine words, assembled from the following types:

class Cool

From Cool

(Cool) method words

Defined as:

method words(Int() $limit)

Coerces the invocant to Str, and returns a list of words that make up the string (and if $limit is supplied, only the first $limit words).

say 'The quick brown fox'.words.join('|');      # OUTPUT: «The|quick|brown|fox␤» 
say 'The quick brown fox'.words(2).join('|');   # OUTPUT: «The|quick␤» 

Only whitespace counts as word boundaries

say "isn't, can't".words.join('|');             # OUTPUT: «isn't,|can't␤» 

class Str

From Str

(Str) routine words

multi sub    words(Str:D $input$limit = Inf --> Positional)
multi method words(Str:D $input: $limit = Inf --> Positional)

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

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.

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

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 behaviour 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: the words are ready lazily and the handle used under the hood won't get closed until the returned Seq is fully reified, so ensure it is, or you'll be leaking open file handles. (TIP: use the $limit argument)

my %dict := bag 'my-file.txt'.IO.words;
say "Most common words: "%dict.sort(-*.value).head: 5;

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