NAME

  mb - Can easy script in Big5, Big5-HKSCS, GBK, Sjis(also CP932), UHC, UTF-8, ...

SYNOPSIS

  $ perl mb.pm              script_by_mbcs.pl      (auto detect encoding of script)
  $ perl mb.pm -e big5      script_by_big5.pl
  $ perl mb.pm -e big5hkscs script_by_big5hkscs.pl
  $ perl mb.pm -e eucjp     script_by_eucjp.pl
  $ perl mb.pm -e gb18030   script_by_gb18030.pl
  $ perl mb.pm -e gbk       script_by_gbk.pl
  $ perl mb.pm -e sjis      script_by_sjis.pl
  $ perl mb.pm -e sjis      script_by_cp932.pl
  $ perl mb.pm -e rfc2279   script_by_rfc2279.pl
  $ perl mb.pm -e uhc       script_by_uhc.pl
  $ perl mb.pm -e utf8      script_by_utf8.pl
  $ perl mb.pm -e wtf8      script_by_wtf8.pl

  C:\WINDOWS> perl mb.pm script.pl ??-DOS-like *wildcard* available

  MBCS quotes:
        qq/ DAMEMOJI 功声乗ソ /
         q/ DAMEMOJI 功声乗ソ /
         m/ DAMEMOJI 功声乗ソ /
         s/ DAMEMOJI 功声乗ソ / DAMEMOJI 功声乗ソ /
    split / DAMEMOJI 功声乗ソ /
        tr/ DAMEMOJI 功声乗ソ / DAMEMOJI 功声乗ソ /
         y/ DAMEMOJI 功声乗ソ / DAMEMOJI 功声乗ソ /
        qr/ DAMEMOJI 功声乗ソ /
        qw/ DAMEMOJI 功声乗ソ /
        qx/ DAMEMOJI 功声乗ソ /

  Useful MBCS subroutines:
    mb::chop(...);
    mb::chr(...);
    mb::dosglob(...);
    mb::getc(...);
    mb::length(...);
    mb::ord(...);
    mb::substr(...);
  Not so useful MBCS subroutines:
    mb::index(...);
    mb::index_byte(...);
    mb::reverse(...);
    mb::rindex(...);
    mb::rindex_byte(...);
  Subroutines that handle MBCS program:
    mb::do 'file';
    mb::eval 'string';
    mb::require 'file';
    mb::use Module;
    mb::no Module;

  MBCS special variables:
    $mb::PERL
    $mb::ORIG_PROGRAM_NAME

  Supported encodings:
    Big5
    Big5-HKSCS
    EUC-JP
    GB18030
    GBK
    Sjis(also CP932)
    UHC
    UTF-8
    WTF-8

  Supported operating systems:
    Apple Inc. Mac OS X, OS X, macOS,
    Hewlett-Packard Development Company, L.P. HP-UX,
    International Business Machines Corporation AIX,
    Microsoft Corporation Windows,
    Oracle Corporation Solaris,
    and Other Systems

  Supported perl versions:
    perl version 5.005_03 to perl 5.42

DESCRIPTION

  This software is a source code filter, a transpiler-modulino.

  Perl is said to have been able to handle Unicode since version 5.8. However,
  unlike JPerl, "Easy jobs easy" has been lost. (but we have got it again :-D)

  In Shift_JIS and similar encodings(Big5, Big5-HKSCS, GB18030, GBK, Sjis, CP932,
  UHC) have any DAMEMOJI who have metacharacters at second octet. Which characters
  are DAMEMOJI is depends on whether the enclosing delimiter is single quote or
  double quote.

  This software escapes DAMEMOJI in your script, generate a new script and
  run it.

Larry Wall-san's Way

  If you're using the utf8 pragma and you have a big headache, probably, you're
  on the wrong way. You should back to the Larry Wall Street (that is known as
  Wall street, and there are still many Perl scripts running on it today) where
  is a sign that says ver.5.00503, once.

  There is another path there. Follow that path.
  Soon, your headache will be improve.

  The "length()" described in the script always functions as "bytes::length()",
  and the "substr()" in the script always functions as "bytes::substr()".
  If you want to know the number of code points of multibyte characters contained
  in a scalar value, you have to write "mb::length()".
  If you want to execute "substr()" in code point context, you have to write
  "mb::substr()".

  Once, Larry Wall san said like this;

  "Easy jobs must be easy."

  Welcome to world of Larry Wall-san's Way!!

THREE WAYS TO RUN

  A script reaches multibyte codepoint semantics in one of three ways.
  They are additive; pick the one that fits.

    -----------------------------------------------------------------------
    way            how to invoke         transpiles            perl
    -----------------------------------------------------------------------
    1 filter       use mb;               the whole file        5.8 and later
    2 modulino     perl mb.pm script.pl  the whole script      5.005_03+
    3 runtime      use mb qw(*mb utf8);  only where you call   5.005_03+
                                         mb::qr / mb::valid /
                                         mb::split / $mb{...}
    -----------------------------------------------------------------------

  Use the filter for a fresh script on a modern perl with plain-looking
  source.  Use the modulino when you must support perl 5.005_03 / 5.6 (no
  source filter there), run a single file as "perl mb.pm script.pl", or need
  <DATA> (a __DATA__/__END__ script is run through a child interpreter).  Use
  the runtime interface to keep ordinary octet Perl and add codepoint behaviour
  only at the few spots that need it.

STRICT VS LENIENT

  After mb::set_script_encoding('utf8') (or 'sjis', 'eucjp', ...), mb defines
  one "character" STRICTLY as: a well-formed multi-byte sequence of that
  encoding, OR a single US-ASCII byte. A stray octet is not a character.

    mb::set_script_encoding('utf8');
    mb::length("A\x85B");    # 1  (0x85 is a stray byte; the walk halts)

    mb::set_script_encoding('sjis');
    mb::length("A\x85B");    # 2  (under sjis 0x85 is a legal lead byte)

  So "strict" means strict with respect to the current encoding. The codepoint
  character classes are strict too: "\S" matches a well-formed sequence or a
  US-ASCII byte, so a lone stray octet matches neither "\s" nor "\S".
  mb::valid() is the explicit predicate built on this same strict unit (1 if
  the whole string is well-formed, 0 otherwise).

  The one deliberate lenient exception, and only on the filter/modulino paths,
  is the dot ".": a transpiled "." also matches any single octet so it never
  gets stuck on binary data. The runtime interface (mb::qr) keeps even "."
  strict.

  "Lenient" otherwise just means the octet view: plain "length"/"substr" count
  bytes, and a script that calls mb::set_script_encoding() itself is passed
  through the filter unchanged so it keeps managing octets on its own. Choose
  the codepoint (strict) model for text work and to detect malformed input;
  choose the octet (lenient) model for binary-safe I/O and byte-exact
  pass-through; or use mb::valid() as the gate where octets become trusted text.

INSTALLATION

  perl mb.pm install

  or

  perl Makefile.PL
  make
  make test
  make install

PERL 5.42 AND source::encoding

  Perl 5.42 introduces the source::encoding pragma and automatically enables
  ASCII-only source checking for scripts that use v5.41 and later.

  mb transpiles most program tokens into US-ASCII, but intentionally keeps
  comments and POD as-is.  Those may contain multibyte characters.

  Therefore, when mb runs as a command and writes a transpiled .oo.* file,
  it inserts a defensive BEGIN block that disables source::encoding checking
  when the pragma exists:

    BEGIN { eval { require source::encoding; source::encoding->unimport; 1 } }

  This block is harmless on Perl 5.005_03 through 5.41, where the pragma
  does not exist.

AUTHOR

  INABA Hitoshi <ina.cpan@gmail.com>

  This software was made referring to software and the document that the
  following hackers or persons had made. I am thankful to all persons.

    Larry Wall, Perl
    http://www.perl.org/

LICENSE AND COPYRIGHT

  This software is free software; you can redistribute it and/or
  modify it under the same terms as Perl itself.
  See L<perlartistic>.

SEE ALSO

  https://metacpan.org/author/INA
  http://backpan.cpantesters.org/authors/id/I/IN/INA/
  https://metacpan.org/release/Jacode4e-RoundTrip
  https://metacpan.org/release/Jacode4e
  https://metacpan.org/release/Jacode
