---
name: "Test2::Harness::Util::File"
section: "3pm"
platform: "linux"
package: "libtest2-harness-perl"
version: "1.000158-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::Harness::Util::File"
---

# Test2::Harness::Util::File(3pm)

Utility class for manipulating a file.

## NAME

Test2::Harness::Util::File - Utility class for manipulating a file.

## DESCRIPTION

This is a utility class for file operations. This also serves as a base class for several file helpers.

## SYNOPSIS

```
    use Test2::Harness::Util::File;
    my $f = Test2::Harness::Util::File->new(name => '/path/to/file');
    $f->write($content);
    my $fh = $f->open_file('<');
    # Read, throw exception if it cannot read
    my $content = $f->read();
    # Try to read, but do not throw an exception if it cannot be read.
    my $content_or_undef = $f->maybe_read();
    my $line1 = $f->read_line();
    my $line2 = $f->read_line();
    ...
```

## ATTRIBUTES

- $filename = $f-\>name;

  Get the filename. Must also be provided during construction.

- $bool = $f-\>done;

  True if **read\_line()** has read every line.

## METHODS

- $decoded = $f-\>decode($encoded)

  This is a no-op, it returns the argument unchanged. This is called by `"read"` and `"read_line"`. Subclasses can override this if the file contains encoded data.

- $encoded = $f-\>encode($decoded)

  This is a no-op, it returns the argument unchanged. This is called by `"write"`. Subclasses can override this if the file contains encoded data.

- $bool = $f-\>**exists()**

  Check if the file exists

- $content = $f-\>**maybe\_read()**

  This will read the file if it can and return the content (all lines joined together as a single string). If the file cannot be read, or does not exist this will return undef.

- $fh = $f-\>**open\_file()**

  - $fh = $f-\>open\_file($mode)

  Open a handle to the file. If no `$mode` is provided `'<'` is used.

- $content = $f-\>**read()**

  This will read the file if it can and return the content (all lines joined together as a single string). If the file cannot be read, or does not exist this will throw an exception.

- $line = $f-\>**read\_line()**

  Read a single line from the file, subsequent calls will read the next line and so on until the end of the file is reached. Reset with the `reset()` method.

- $f-\>**reset()**

  Reset the internal line iterator used by `read_line()`.

- $f-\>write($content)

  This is an atomic-write. First `$content` will be written to a temporary file using `'>'` mode. Then the temporary file will be renamed to the desired file name. Under the hood this uses `write_file_atomic()` from Test2::Harness::Util.

## SOURCE

The source code repository for Test2-Harness can be found at *http://github.com/Test-More/Test2-Harness/*.

## MAINTAINERS

- Chad Granum \<exodist@cpan.org\>

  ## AUTHORS

- Chad Granum \<exodist@cpan.org\>

  ## COPYRIGHT

Copyright 2020 Chad Granum \<exodist7@gmail.com\>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See *http://dev.perl.org/licenses/*