/ 
File-Raw-Base64-0.02
/ File::Raw::Base64

NAME

File::Raw::Base64 - Base64 plugin for File::Raw

VERSION

Version 0.02

SYNOPSIS

Loading the module registers two plugins (base64 and base64url) with File::Raw. Opt in per-call:

use File::Raw::Base64;
use File::Raw qw(import);   # installs file_slurp / file_spew / ...

# Decode a base64-encoded blob into bytes.
my $bytes = file_slurp("token.b64", plugin => 'base64');

# Encode bytes into base64 text.
file_spew("blob.b64", $payload, plugin => 'base64', wrap => 64);

# PEM mode: strip BEGIN/END headers on read, wrap with them on write.
my $der = file_slurp("cert.pem", plugin => 'base64', pem => 1);

file_spew("cert.pem", $der,
    plugin    => 'base64',
    pem       => 1,
    pem_label => 'CERTIFICATE',
    wrap      => 64,
);

# URL-safe alphabet (- and _ instead of + and /).
my $bytes = file_slurp("jwt.txt", plugin => 'base64url', padding => 0);

OPTIONS

Both plugins accept the same keys.

wrap

Encode-only. Insert a line terminator after every wrap output characters. 0 (default) emits a single line. 64 matches PEM, 76 matches MIME (RFC 2045).

urlsafe

Switch to the URL-safe alphabet (- and _ instead of + and /). The base64url plugin sets this automatically; passing urlsafe => 0 on a base64url call would force the standard alphabet.

padding

Encode-only. 1 (default) appends = to align the output to a multiple of four characters. 0 strips trailing padding (handy for JWT, where padding is conventionally omitted). Decoders are always tolerant of missing padding.

pem

1 turns on PEM envelope handling. On encode, the output is wrapped in -----BEGIN $pem_label----- / -----END $pem_label----- lines. On decode, those lines are located and stripped before the body is decoded; whitespace inside the body is ignored regardless of strict. BEGIN and END labels must match or decode croaks.

pem_label

Encode-only. Label used in the BEGIN/END markers. Default DATA. Common real-world values: CERTIFICATE, PRIVATE KEY, PUBLIC KEY, RSA PRIVATE KEY.

strict

Decode-only. 1 rejects any byte outside the active alphabet (with an error message naming the byte offset). Default 0 silently skips non-alphabet bytes - matching MIME::Base64::decode_base64.

eol

Encode-only. Line terminator emitted when wrap or pem is on. Default "\n". Pass "\r\n" for CRLF output. One or two bytes only.

PLUGIN BEHAVIOUR

The two registered plugins differ only in their seeded default alphabet:

  • base64 - RFC 4648 section 4 alphabet (A-Z a-z 0-9 + /).

  • base64url - RFC 4648 section 5 alphabet (A-Z a-z 0-9 - _).

WRITE and READ phases are wired; STREAM and RECORD are not - base64 decoding is naturally chunk-aligned but the in-memory call covers the common case at one syscall through File::Raw, which is the point.

Combine with other File::Raw plugins via plugin chains (plugin => ['base64', 'csv']) once File::Raw 0.11 lands chain support.

SEE ALSO

File::Raw, MIME::Base64.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)