# perldoc > PerlIO::via

---
type: CommandReference
command: PerlIO::via
mode: perldoc
section: ""
source: perldoc
---

## Quick Reference

- `use PerlIO::via::Layer; open($fh,"<:via(Layer)",...)` — open a file with a custom PerlIO layer implemented in Perl
- `use PerlIO::via::Hex; open($fh,">:via(Hex)","foo.hex")` — output hex dump of bytes
- `use PerlIO::via::Hex; open($fh,"<:via(Hex)","foo.hex")` — read hex dump back into bytes
- `use PerlIO::via::StripHTML; open(my $fh, "<:via(StripHTML)", "index.html")` — strip HTML tags on read

## Name

PerlIO::via - Helper class for PerlIO layers implemented in perl

## Synopsis

perl
use PerlIO::via::Layer;
open($fh,"<:via(Layer)",...);

use Some::Other::Package;
open($fh,">:via(Some::Other::Package)",...);
## Description

The `PerlIO::via` module allows you to develop PerlIO layers in Perl without C/XS. Layers are typically created in the `PerlIO::via::` namespace so they can be used without full qualification. Example modules include `PerlIO::via::QuotedPrint`, `PerlIO::via::StripHTML`, and `PerlIO::via::Base64`. The layer is specified with `:via(ModuleName)` in the open mode.

## Expected Methods

To implement a PerlIO layer, provide some of the following subroutines. `$fh` is a reference to the layer below, passed last if not at bottom.

- `$class->PUSHED([$mode,[$fh]])` — Mandatory. Returns an object/class or -1 on failure. Called before open.
- `$obj->POPPED([$fh])` — Optional. Called when layer is removed.
- `$obj->UTF8($belowFlag,[$fh])` — Optional. Called after PUSHED. Return true if layer expects UTF-8 data.
- `$obj->OPEN($path,$mode,[$fh])` — Optional. Called for normal opens after push.
- `$obj->BINMODE([$fh])` — Optional. Called on binmode or `:raw`. Return 0 success, -1 error, undef to pop.
- `$obj->FDOPEN($fd,[$fh])` — Optional. Called for opens with numeric file descriptor.
- `$obj->SYSOPEN($path,$imode,$perm,[$fh])` — Optional. Called for sysopen style opens.
- `$obj->FILENO($fh)` — Optional. Returns Unix file descriptor or -1. Default: `fileno($fh)`.
- `$obj->READ($buffer,$len,$fh)` — Optional. Returns number of octets placed in $buffer. Default uses FILL.
- `$obj->WRITE($buffer,$fh)` — Returns number of octets written.
- `$obj->FILL($fh)` — Optional. Returns a string to buffer. Must provide READ or reject reading in PUSHED if not provided.
- `$obj->CLOSE($fh)` — Optional. Return 0 success, -1 error.
- `$obj->SEEK($posn,$whence,$fh)` — Optional. Return 0 success, -1 error. Default fails.
- `$obj->TELL($fh)` — Optional. Returns file position.
- `$obj->UNREAD($buffer,$fh)` — Optional. Returns number of octets saved for future FILL/READ. Default pushes to temporary layer above.
- `$obj->FLUSH($fh)` — Flush buffered write data. Return 0 success, -1 error.
- `$obj->SETLINEBUF($fh)` — Optional. No return.
- `$obj->CLEARERR($fh)` — Optional. No return.
- `$obj->ERROR($fh)` — Optional. Returns error state. Default no error.
- `$obj->EOF($fh)` — Optional. Returns end-of-file state. Default based on FILL/READ.

## Examples

### Example – a Hexadecimal Handle

Module `PerlIO::via::Hex`:

perl
package PerlIO::via::Hex;

sub PUSHED
{
    my ($class, $mode, $fh) = @_;
    my $buf = '';
    return bless \$buf, $class;
}

sub FILL
{
    my ($obj, $fh) = @_;
    my $line = <$fh>;
    return (defined $line) ? pack("H*", $line) : undef;
}

sub WRITE
{
    my ($obj, $buf, $fh) = @_;
    $$obj .= unpack("H*", $buf);
    return length($buf);
}

sub FLUSH
{
    my ($obj, $fh) = @_;
    print $fh $$obj or return -1;
    $$obj = '';
    return 0;
}

1;
Usage – output hex dump:

perl
use PerlIO::via::Hex;
open(my $fh, ">:via(Hex)", "foo.hex");
Usage – read hex dump back:

perl
use PerlIO::via::Hex;
open(my $fh, "<:via(Hex)", "foo.hex");