1# Copyright (C) 2002-2004, 2012 Elizabeth Mattijsen.  All rights reserved.
2# Copyright (C) 2015 Steve Hay.  All rights reserved.
3
4# This module is free software; you can redistribute it and/or modify it under
5# the same terms as Perl itself, i.e. under the terms of either the GNU General
6# Public License or the Artistic License, as specified in the F<LICENCE> file.
7
8package PerlIO::via::QuotedPrint;
9
10use 5.008001;
11
12# be as strict as possible
13use strict;
14
15our $VERSION = '0.09';
16
17# modules that we need
18use MIME::QuotedPrint (); # no need to pollute this namespace
19
20# satisfy -require-
211;
22
23#-------------------------------------------------------------------------------
24#
25# Standard Perl features
26#
27#-------------------------------------------------------------------------------
28#  IN: 1 class to bless with
29#      2 mode string (ignored)
30#      3 file handle of PerlIO layer below (ignored)
31# OUT: 1 blessed object
32
33sub PUSHED { bless \*PUSHED,$_[0] } #PUSHED
34
35#-------------------------------------------------------------------------------
36#  IN: 1 instantiated object (ignored)
37#      2 handle to read from
38# OUT: 1 decoded string
39
40sub FILL {
41
42    # decode and return
43    my $line= readline( $_[1] );
44    return ( defined $line )
45      ? MIME::QuotedPrint::decode_qp($line)
46      : undef;
47} #FILL
48
49#-------------------------------------------------------------------------------
50#  IN: 1 instantiated object (ignored)
51#      2 buffer to be written
52#      3 handle to write to
53# OUT: 1 number of bytes written
54
55sub WRITE {
56
57    # encode and write to handle: indicate result
58    return ( print { $_[2] } MIME::QuotedPrint::encode_qp( $_[1] ) )
59      ? length( $_[1] )
60      : -1;
61} #WRITE
62
63#-------------------------------------------------------------------------------
64
65__END__
66
67=head1 NAME
68
69PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings
70
71=head1 SYNOPSIS
72
73    use PerlIO::via::QuotedPrint;
74
75    open(my $in, '<:via(QuotedPrint)', 'file.qp') or
76        die "Can't open file.qp for reading: $!\n";
77
78    open(my $out, '>:via(QuotedPrint)', 'file.qp') or
79        die "Can't open file.qp for writing: $!\n";
80
81=head1 DESCRIPTION
82
83This module implements a PerlIO layer that works on files encoded in the
84quoted-printable format.  It will decode from quoted-printable while reading
85from a handle, and it will encode as quoted-printable while writing to a handle.
86
87=head1 EXPORTS
88
89I<None>.
90
91=head1 KNOWN BUGS
92
93I<None>.
94
95=head1 FEEDBACK
96
97Patches, bug reports, suggestions or any other feedback is welcome.
98
99Patches can be sent as GitHub pull requests at
100L<https://github.com/steve-m-hay/PerlIO-via-QuotedPrint/pulls>.
101
102Bug reports and suggestions can be made on the CPAN Request Tracker at
103L<https://rt.cpan.org/Public/Bug/Report.html?Queue=PerlIO-via-QuotedPrint>.
104
105Currently active requests on the CPAN Request Tracker can be viewed at
106L<https://rt.cpan.org/Public/Dist/Display.html?Status=Active;Queue=PerlIO-via-QuotedPrint>.
107
108Please test this distribution.  See CPAN Testers Reports at
109L<https://www.cpantesters.org/> for details of how to get involved.
110
111Previous test results on CPAN Testers Reports can be viewed at
112L<https://www.cpantesters.org/distro/P/PerlIO-via-QuotedPrint.html>.
113
114Please rate this distribution on CPAN Ratings at
115L<https://cpanratings.perl.org/rate/?distribution=PerlIO-via-QuotedPrint>.
116
117=head1 SEE ALSO
118
119L<PerlIO::via>,
120L<MIME::QuotedPrint>.
121
122=head1 ACKNOWLEDGEMENTS
123
124Based on an example in the standard library module MIME::QuotedPrint in Perl
125(version 5.8.0).
126
127=head1 AVAILABILITY
128
129The latest version of this module is available from CPAN (see
130L<perlmodlib/"CPAN"> for details) at
131
132L<https://metacpan.org/release/PerlIO-via-QuotedPrint> or
133
134L<https://www.cpan.org/authors/id/S/SH/SHAY/> or
135
136L<https://www.cpan.org/modules/by-module/PerlIO/>.
137
138The latest source code is available from GitHub at
139L<https://github.com/steve-m-hay/PerlIO-via-QuotedPrint>.
140
141=head1 INSTALLATION
142
143See the F<INSTALL> file.
144
145=head1 AUTHOR
146
147Elizabeth Mattijsen E<lt>L<liz@dijkmat.nl|mailto:liz@dijkmat.nl>E<gt>.
148
149Steve Hay E<lt>L<shay@cpan.org|mailto:shay@cpan.org>E<gt> is now maintaining
150PerlIO::via::QuotedPrint as of version 0.08.
151
152=head1 COPYRIGHT
153
154Copyright (C) 2002-2004, 2012 Elizabeth Mattijsen.  All rights reserved.
155
156Copyright (C) 2015, 2020 Steve Hay.  All rights reserved.
157
158=head1 LICENCE
159
160This module is free software; you can redistribute it and/or modify it under
161the same terms as Perl itself, i.e. under the terms of either the GNU General
162Public License or the Artistic License, as specified in the F<LICENCE> file.
163
164=head1 VERSION
165
166Version 0.09
167
168=head1 DATE
169
17008 Dec 2020
171
172=head1 HISTORY
173
174See the F<Changes> file.
175
176=cut
177