The spurt routine

Combined from primary sources listed below.

In class IO::Path ( Type/IO/Path )§

See primary docmentation in context for method spurt.

method spurt§

method spurt(IO::Path:D: $data, :$enc, :$append, :$createonly)

Opens the path for writing, and writes all of the $data into it. File will be closed afterwards. Will fail if it cannot succeed for any reason. The $data can be any Cool type or any Blob type. Arguments are as follows:

  • :$enc — character encoding of the data. Takes same values as :$enc in IO::Handle.open. Defaults to utf8. Ignored if $data is a Blob.

  • :$append — open the file in append mode, preserving existing contents, and appending data to the end of the file.

  • :$createonlyfail if the file already exists.

method spurt(IO::Path:D:)

As of the 2020.12 release of the Rakudo compiler, it is also possible to call the spurt method without any data. This will either create an empty file, or will truncate any existing file at the given path.

In Independent routines ( Type/independent-routines )§

See primary docmentation in context for sub spurt.

sub spurt§

multi spurt(IO() $path, |c)

The $path can be any object with an IO method that returns an IO::Path object. Calls IO::Path.spurt on the $path, forwarding any of the remaining arguments.

Options§

  • :enc

The encoding with which the contents will be written.

  • :append

Boolean indicating whether to append to a (potentially) existing file. If the file did not exist yet, it will be created. Defaults to False.

  • :createonly

Boolean indicating whether to fail if the file already exists. Defaults to False.

Examples§

# write directly to a file
spurt 'path/to/file', 'default text, directly written';

# write directly with a non-Unicode encoding
spurt 'path/to/latin1_file', 'latin1 text: äöüß', :enc<latin1>;

spurt 'file-that-already-exists', 'some text';           # overwrite file's contents:
spurt 'file-that-already-exists', ' new text', :append;  # append to file's contents:
say slurp 'file-that-already-exists';                    # OUTPUT: «some text new text␤»

# fail when writing to a pre-existing file
spurt 'file-that-already-exists', 'new text', :createonly;
# OUTPUT: «Failed to open file /home/camelia/file-that-already-exists: file already exists …»
multi spurt(IO() $path)

As of the 2020.12 release of the Rakudo compiler, it is also possible to call the spurt subroutine without any data. This will either create an empty file, or will truncate any existing file at the given path.

# create an empty file / truncate a file
spurt 'path/to/file';

In class IO::Handle ( Type/IO/Handle )§

See primary docmentation in context for method spurt.

method spurt§

multi method spurt(IO::Handle:D: Blob $data, :$close = False)
multi method spurt(IO::Handle:D: Cool $data, :$close = False)

Writes all of the $data into the filehandle, closing it when finished, if $close is True. For Cool $data, will use the encoding the handle is set to use (IO::Handle.open or IO::Handle.encoding).

Behavior for spurting a Cool when the handle is in binary mode or spurting a Blob when the handle is NOT in binary mode is undefined.