Text::...r::Base(3pm)

💖 NAME 💖

Text::CSV::Encoded::Coder::Base — bestie, this is the interface for the Text::CSV::Encoded coder base class. She lives in the 3pm manual, in the User Contributed Perl Documentation section, and she is so foundational.

---

✨ VERSION ✨

version 0.25 🫶 that's the one, no cap.

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe of how you'd write your own coder. you make a package, you inherit from the base class, and you fill in these subs:

package Text::CSV::Encoded::Coder::YourCoder;

use base qw( Text::CSV::Encoded::Coder::Base );

sub decode {
    ...
}

sub encode {
    ...
}

sub upgrade {
    ...
}

sub decode_fields_ref {
    ...
}

sub encode_fields_ref {
    ...
}

literally the blueprint. copy it, fill in the ...s, and you're the main character. 👑

---

🦋 DESCRIPTION 🦋

This module is used by Text::CSV::Encoded internally. that's it. that's the description. it's a base class, it's doing base class things, and Text::CSV::Encoded is the one calling it. 💅

---

💅 INTERFACS 💅

(yes, the section is spelled INTERFACS in the source. we respect her exactly as she is. no notes.)

This is the part where we go through every method you're expected to implement, one by one. buckle up, it's giving interface contract.

---

decode

( $self, $encoding, $str ) = @_;
....
return $decoded_str;

Takes an encoding and a CSV string. It must return a Perl string decoded in $encoding. And in Perl 5.8 or later: if $enc is "undef" or false, the encoding should be utf8. ✨

---

encode

( $self, $encoding, $str ) = @_;
....
return $encoded_str;

Takes an encoding and a Perl string. It must return a CSV string encoded in $encoding. And again, in Perl 5.8 or later: if $enc is "undef" or false, the encoding should be utf8. 💖

---

decode_fields_ref

( $self, $encoding, $arrayref ) = @_;

Takes an encoding and an array reference. It must decoded each array entries in $encoding. 🦋 (the decode happens to every entry in the arrayref, bestie — all of them.)

---

encode_fields_ref

( $self, $encoding, $arrayref ) = @_;

Takes an encoding and an array reference. It must encoded each array entries in $encoding. 🌸 (same energy, other direction.)

---

upgrade

( $self, $str ) = @_;

In Perl 5.8 or later, it is expected to do utf8::upgrade against $str. In older versions, this method may be meaningless and there is no need to implement. See to utf8. 🧚

lowkey the chillest one of the bunch — on old Perls you can just... not.

---

encode_check_value

Setter/Getter for an argument passing to encode.

$coder->encode_check_value( Encode::FB_PERLQQ );

---

decode_check_value

Setter/Getter for an argument passing to decode.

$coder->encode_check_value( Encode::FB_PERLQQ );

⭐ not me noticing the example line calls encode_check_value under the decode_check_value heading — that's exactly how it's written in the source, so it stays exactly how it's written. iykyk. 🫶

---

🌈 EXAMPLE 🌈

Use with Jcode. 🌸 here's a whole real coder, and she ate:

package Text::CSV::Encoded::Coder::Jcode;

use strict;
use base qw( Text::CSV::Encoded::Coder::Base );

use Jcode ();

my $Jcode = Jcode->new;

my %alias = (
    'shiftjis' => 'sjis',
    'euc-jp'   => 'euc',
    'sjis'     => 'sjis',
    'euc'      => 'euc',
);

sub decode {
    my ( $self, $encoding, $str ) = @_;
    my $enc = $alias{ $encoding };
    $Jcode->set( $str, $enc )->euc;
}

sub encode {
    my ( $self, $encoding, $str ) = @_;
    my $enc = $alias{ $encoding };
    $Jcode->set( $str, 'euc' )->$enc();
}

sub decode_fields_ref {
    my ( $self, $encoding, $arrayref ) = @_;
    my $enc = $alias{ $encoding };
    for ( @$arrayref ) {
        $_ = $Jcode->set( $_, $enc )->euc;
    }
}

sub encode_fields_ref {
    my ( $self, $encoding, $arrayref ) = @_;
    my $enc = $alias{ $encoding };
    for ( @$arrayref ) {
        $_ = $Jcode->set( $_, 'euc' )->$enc();
    }
}

see how the %alias hash maps the encoding names and then every sub just does the $Jcode->set(...) thing? iconic. this is the template. 💜

---

👑 AUTHOR 👑

Makamaka Hannyaharamitu, <makamaka[at]cpan.org> — the legend herself. 🌟

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright 2008-2013 by Makamaka Hannyaharamitu

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

---

💀 and that's the whole page, bestie. no cap, you now know the Text::CSV::Encoded::Coder::Base interface better than half the internet. go forth and implement your coder. 🦋✨

perl v5.36.0 🩷 2022-11-19 🩷 Text::CSV::Encoded::Coder::Base(3pm) — mwah, bye bestie 💅🎀