Initial Commit
This commit is contained in:
Riley Schneider
481
database/perl/vendor/lib/POD2/DE/local/lib.pod
vendored
Normal file
481
database/perl/vendor/lib/POD2/DE/local/lib.pod
vendored
Normal file
@@ -0,0 +1,481 @@
|
||||
=encoding utf8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
local::lib~[de] - Erschaffen und benutzen von Perl Modulen in einem lokalen lib/ Verzeichnis mit PERL5LIB
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
Im Code -
|
||||
|
||||
use local::lib; # Benutzt das Verzeichnis ~/perl5 zum anlegen des lokalen lib/ Verzeichnisses
|
||||
|
||||
use local::lib '~/foo'; # das selbe, aber mit ~/foo
|
||||
|
||||
# Oder...
|
||||
use FindBin;
|
||||
use local::lib "$FindBin::Bin/../support"; # Applikationsspezifische Sammlung von Modulen
|
||||
|
||||
Von der Shell -
|
||||
|
||||
# Installiert LWP und alle notwendigen Abhängigkeiten in das '~/perl5' Verzeichnis
|
||||
perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
|
||||
|
||||
# Gibt die Shell Kommandos aus um die Umgebung vorzubereiten
|
||||
$ perl -Mlocal::lib
|
||||
export PERL_MB_OPT='--install_base /home/username/perl5'
|
||||
export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
|
||||
export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
|
||||
export PATH="/home/username/perl5/bin:$PATH"
|
||||
|
||||
=head2 Die Bootstrapping Methode
|
||||
|
||||
Ein typischer Weg um local::lib zu benutzen ist die sogenannte "Bootstrapping" Methode.
|
||||
Diese Methode wird benutzt wenn noch kein local::lib auf dem System installiert ist.
|
||||
In diesem Fall kannst du einfach local::lib direkt in deinem Home-Verzeichnis installieren.
|
||||
|
||||
Selbst wenn du administrative Rechte hast, ist es wichtig das die Umgebungsvariablen von
|
||||
Schritt 4 in deinem Shell Startup Skript gesetzt werden. Ohne diesen Schritt werden die
|
||||
Module von CPAN weiterhin im System installiert und auch Perl Skripte die du startest
|
||||
würden das von local::lib erstellte lib/ Verzeichnis nicht nutzen.
|
||||
|
||||
Standardmäßig installiert sich local::lib in ~/perl5.
|
||||
|
||||
Windows Benutzern müssen ausserdem dies hier lesen:
|
||||
L</Unterschiede bei Benutzung dieses Module mit Win32>.
|
||||
|
||||
1. Lade das Tar-Archiv von CPAN runter (Suche nach "Download" auf der CPAN Seite von
|
||||
local::lib) und entpacke es in einem beliebigem Verzeichnis. Um das obige Problem zu
|
||||
vermeiden, sollte man dies als normaler User tun und nicht als root oder Administrator.
|
||||
|
||||
2. Starte in dem entstandenen Verzeichnis folgenden Befehl:
|
||||
|
||||
perl Makefile.PL --bootstrap
|
||||
|
||||
Wenn das System dir vorschlägt gewisse Dinge eigenständig zu konfigurieren ist es in
|
||||
fast allen Fällen vollkommen in Ordnung einfach "yes" zu antworten.
|
||||
|
||||
Falls du local::lib nicht in das Standard Verzeichnis installieren willst, musst du
|
||||
dieses Verzeichnis als Parameter angeben:
|
||||
|
||||
perl Makefile.PL --bootstrap=~/foo
|
||||
|
||||
3. Danach folgenden Befehl starten: (local::lib erwartet make auf dem System)
|
||||
|
||||
make test && make install
|
||||
|
||||
4. Nun müssen wir die benötigten Umgebungsvariablen, damit Perl unser neu generiertes
|
||||
lib/ Verzeichnis benutzt. Wenn du bash oder eine andere Bourne Shell benutzt, kannst
|
||||
du es über diesen Weg zu deinem Shell Startup Skript hinzufügen:
|
||||
|
||||
echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
|
||||
|
||||
Wenn du C Shell benutzt, du kannst das gleiche hiermit erreichen:
|
||||
|
||||
/bin/csh
|
||||
echo $SHELL
|
||||
/bin/csh
|
||||
perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
|
||||
|
||||
Wenn du beim bootstrappen ein anderes Verzeichnis benutzt als das Standardverzeichnis,
|
||||
dann musst du dieses Verzeichnis als Parameter beim Laden des Modules local::lib angeben:
|
||||
|
||||
echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
|
||||
|
||||
Nachdem diese Änderungen in deinem Shell Startup Skript gemacht wurden, ist es nun wichtig
|
||||
das diese Umgebungsvariablen auch gesetzt sind in deiner aktuellen Umgebung. In Bourne
|
||||
Shells macht man dies z.B. mit C<. ~/.bashrc>, und in C Shell würde man es mit:
|
||||
C<source ~/.cshrc> mit.
|
||||
|
||||
Wenn du eine sehr langsames System hast, oder du unter drakonischen Regulierungen des
|
||||
Plattenplatz leben musst, kann man die automatische Generierung der manpages vom POD
|
||||
bei der Installation des Moduls deaktivieren beim bootstrapping mit dem C<--no-manpages>
|
||||
Parameter:
|
||||
|
||||
perl Makefile.PL --bootstrap --no-manpages
|
||||
|
||||
Um zu vermeiden das man mehrere bootstraps macht um z.B. für verschiedene Applikationen
|
||||
eigene local::lib Installationen zu nutzen, kann man eine dieser Umgebungen benutzen
|
||||
um einfach in beliebigen anderen Verzeichnis Module zu installieren und somit weitere
|
||||
eigenständige lib/ Umgebungen zu bekommen:
|
||||
|
||||
cd ~/mydir1
|
||||
perl -Mlocal::lib=./
|
||||
eval $(perl -Mlocal::lib=./) ### Um die Umgebungsvariablen für die
|
||||
### aktuelle Shell zusetzen
|
||||
|
||||
printenv ### Hier kannst du sehen das ~/mydir1
|
||||
### in der PERL5LIB Umgebungsvariable
|
||||
### steht
|
||||
|
||||
perl -MCPAN -e install ... ### welche Module auch immer ...
|
||||
cd ../mydir2
|
||||
|
||||
... WIEDERHOLEN ...
|
||||
|
||||
Für mehrere Umgebungen in dieser Form brauch man eine Modifikation in der
|
||||
Benutzung von C<< use FindBin >> in dem "Im Code" Beispiel oben.
|
||||
Wenn du sowas machst, und du hast damit z.B. Perl Module nach C<<
|
||||
~/mydir1/lib >> installiert und du hast ein Script in C<<
|
||||
~/mydir1/scripts/myscript.pl >>, du musst dort angeben das die Module
|
||||
die es braucht im Verzeichnis C<< ~/mydir1/lib >> liegen.
|
||||
|
||||
In C<< ~/mydir1/scripts/myscript.pl >> steht dann:
|
||||
|
||||
use strict;
|
||||
use warnings;
|
||||
use local::lib "$FindBin::Bin/.."; ### zeigt auf ~/mydir1 und local::lib
|
||||
### findet dort lib
|
||||
use lib "$FindBin::Bin/../lib"; ### zeigt auf ~/mydir1/lib
|
||||
|
||||
Setze das vor jeden BEGIN { ... } Block der die Module braucht die du
|
||||
installiert hast.
|
||||
|
||||
=head2 Unterschiede bei Benutzung dieses Module mit Win32
|
||||
|
||||
Um die nötigen Umgebungsvariablen für diese Variablen in der derzeitigen
|
||||
Sitzung mit C<CMD.EXE> zu setzen, kann man folgendes kommando nutzen:
|
||||
|
||||
C:\>perl -Mlocal::lib
|
||||
set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
|
||||
set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
|
||||
set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
|
||||
set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
|
||||
|
||||
### Um die Umgebungsvariablen für diese Shell alleine zu setzen
|
||||
C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
|
||||
### anstelle von $(perl -Mlocal::lib=./) in bash.
|
||||
|
||||
Wenn du willst das die Umgebungsvariablen dauerhaft gesetzt sind, musst du diese
|
||||
in Systemsteuerung / System dauerhaft selber eintragen oder
|
||||
L<App::local::lib::Win32Helper> benutzen.
|
||||
|
||||
Die "~" wird übersetzt zu dem Benutzer Profil Verzeichnis (das Verzeichnis was
|
||||
beim User als "Dokumente und Einstellungen" bekannt ist unter Windows XP und
|
||||
vorher oder das "Benutzer" Verzeichnis bei Windows Vista und später), solange
|
||||
$ENV{HOME} nicht gesetzt ist. Das Verzeichnis wird hierbei zu dem korrekten
|
||||
Kurznamen umgewandelt, und muss daher definitiv existieren, und wird um die
|
||||
nötigen Unterverzeichnise erweitert.
|
||||
|
||||
=head1 GRUNDPRINZIP
|
||||
|
||||
Die Version von den Perl Paketen die man benötigt für spezifische Aufgaben sind
|
||||
sehr häufig nicht die richtigen oder korrekten Versionen auf dem System
|
||||
vorinstalliert. Ein Updaten von diesen Modulen ist in vielen Fällen einfach
|
||||
nicht möglich weil die nötigen Rechte fehlen. Ausserdem ist es generell nicht
|
||||
gut eigenständig die Versionen der Module auf dem System auszutauschen, weil
|
||||
natürlich der Rest des Systems genau die Version erwartet die von der
|
||||
Systemverwaltung auch installiert wurde.
|
||||
|
||||
local::lib löst dieses Problem, es erlaubt dir dein komplett eigenes Verzeichnis
|
||||
für deine CPAN Module zu haben und bist so nicht genötigt die Module vom
|
||||
System zu nutzen oder andersrum andere User nicht mit individuellen
|
||||
Modulwünschen zu Überarbeitung ihres Codes zu zwingen, weil bestimmte Module
|
||||
zentral für alle auf neuere Version upgedatet werden. Die Installation findet
|
||||
hierbei dann z.B. im Home Verzeichnis statt. Es werden nur Umgebungsvariablen
|
||||
gesetzt die das installierte Perl dazu bewegen die im Homeverzeichnis
|
||||
installierten Module zu benutzen, zusätzlich und vorgezogen zu denen auf dem
|
||||
System.
|
||||
|
||||
Daher muss man sich wenn man ein Paket System benutzt, wie z.b. Debian, garnicht
|
||||
mehr Sorgen machen, irgendwas auf dem System zu verletzten nur durch die
|
||||
Installation von Perl Modulen.
|
||||
|
||||
=head1 BESCHREIBUNG
|
||||
|
||||
Dieses Modul bietet eine schnelle und legitime Art und Weise ein sogenanntes
|
||||
bootstrapping zu machen um in einem User Homeverzeichnis eine Sammlung von
|
||||
Modulen zu installieren. Es erstellt auch die nötigen Umgebungsvariablen
|
||||
die benötigt werden um diese Module zu nutzen, passend zu der Shell die der
|
||||
User in der Umgebungsvariable C<SHELL> angegeben hat, um dann direkt passend
|
||||
in die entsprechenden Konfigurationsdateien der Shell einfügt zu werden.
|
||||
|
||||
Weitergehend ist local::lib in der Lage Module zu nutzen die nicht im
|
||||
standardmäßigen C<@INC> Pfad von Perl enthalten sind. Das macht es einfacher
|
||||
für bestimmte Applikationen ein bestimmtes Set von Modulen zu installieren
|
||||
ohne die anderen Module auf dem System in irgendeiner Art anzufassen.
|
||||
Damit es z.B. auch sicherer Module zu installieren die vom Maintainer noch
|
||||
nicht als Release verfügbar sind.
|
||||
|
||||
Beim Import setzt local::lib die folgenden Umgebungsvariablen zu den
|
||||
nötigen Werten:
|
||||
|
||||
=over 4
|
||||
|
||||
=item PERL_MB_OPT
|
||||
|
||||
=item PERL_MM_OPT
|
||||
|
||||
=item PERL5LIB
|
||||
|
||||
=item PATH
|
||||
|
||||
Am PATH wird natürlich angehangen, und nicht ersetzt.
|
||||
|
||||
=back
|
||||
|
||||
Diese Werte sind dann verfügbar für jeden Code der danach importiert wurde.
|
||||
|
||||
=head1 ERSTELLEN EINES EIGENSTÄNDIGE SAMMLUNG VON MODULEN
|
||||
|
||||
Mit L<lib::core::only> besteht eine Möglichkeit dieses zutun, aber beachte das
|
||||
hier eine Menge von Fallstricken und Problemen existieren, und man sollte
|
||||
immer darauf achten das man auf einem Perl aufbaut was sowenig wie möglich
|
||||
verändert wurde (d.h. site und vendor Verzeichnis so leer wie möglich).
|
||||
|
||||
=head1 METHODEN
|
||||
|
||||
=head2 ensure_dir_structure_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $path
|
||||
|
||||
=item Rückgabewert: Keiner
|
||||
|
||||
=back
|
||||
|
||||
Versucht den angegebenen Pfad anzulegen, mit allen nötigen drüberliegenden
|
||||
Verzeichnissen. Im Fehlerfall wird eine Exception geworfen.
|
||||
|
||||
=head2 print_environment_vars_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: Keiner
|
||||
|
||||
=back
|
||||
|
||||
Gibt die Umgebungsvariablen aus, die benötigt werden um den angegebenen Pfad
|
||||
als Basis Verzeichnis zu nutzen.
|
||||
|
||||
=head2 build_environment_vars_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad, $interpolate
|
||||
|
||||
=item Rückgabewert: \%umgebungs_variablen
|
||||
|
||||
=back
|
||||
|
||||
Gibt ein Hash zurück mit den Variablen die nötig sind in den Umgebungsvariablen
|
||||
um eine Installation in dem gegebenen Pfad zu benutzen.
|
||||
|
||||
=head2 setup_env_hash_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: Keiner
|
||||
|
||||
=back
|
||||
|
||||
Setzt die C<%ENV> Einträge basierend auf dem Aufruf von
|
||||
L</build_environment_vars_for>.
|
||||
|
||||
=head2 install_base_perl_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $module_installations_pfad
|
||||
|
||||
=back
|
||||
|
||||
Gibt den Pfad zurück der benutzt wird um Perl Module zu installieren bei
|
||||
dem gegebenen Pfad als Basis. Prinzipiell wird nur C<lib> und C<perl5> als
|
||||
Pfadelemente angehangen.
|
||||
|
||||
=head2 install_base_arch_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $architektur_module_installations_pfad
|
||||
|
||||
=back
|
||||
|
||||
Gibt den Pfad zurück der benutzt wird um die Architektur-abhängigen Perl
|
||||
Module zu installieren basirend auf dem angegebenen Pfad als Basis. Basierend
|
||||
auf dem was L</install_base_perl_path> zurückgibt, and appends the value of
|
||||
C<$Config{archname}>.asis.
|
||||
|
||||
=head2 install_base_bin_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $ausfuehrbare_programme_installations_pfad
|
||||
|
||||
=back
|
||||
|
||||
Gibt den Pfad zurück, wo ausführbare Programme installiert werden, basierend
|
||||
auf der Basis des angegebenen Pfad. Basierend auf L</install_base_perl_path>
|
||||
Rückgabewert, hängt diese Methode noch C<bin> an.
|
||||
|
||||
=head2 resolve_empty_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $basis_pfad
|
||||
|
||||
=back
|
||||
|
||||
Erstellt und gibt zurück den Pfad der benutzt wird als Basis zur Installation
|
||||
der Module. Standardmäßig dies ist C<~/perl5>.
|
||||
|
||||
=head2 resolve_home_path( $path )
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $home
|
||||
|
||||
=back
|
||||
|
||||
Versucht das Home Verzeichnis vom aktullen User zu finden. Wenn C<File::HomeDir>
|
||||
installiert ist, für dieses benutzt dafür. Es wird eine Exception geworfen, wenn
|
||||
kein Home Verzeichnis ermittelt werden konnte.
|
||||
|
||||
=head2 resolve_relative_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $absoluter_pfad
|
||||
|
||||
=back
|
||||
|
||||
Macht aus dem angegebenen Pfad einen absoluten Pfad.
|
||||
|
||||
=head2 resolve_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Parameter: $pfad
|
||||
|
||||
=item Rückgabewert: $absoluter_pfad
|
||||
|
||||
=back
|
||||
|
||||
Hierbei wird der Pfad durch die folgende Methoden gegeben, wobei der Rückgabewert
|
||||
der ersten an die nächste weitergeben wird, um die Umgebung zu konfigurieren
|
||||
für die lokale Bibliotheks Installation: L</resolve_empty_path>,
|
||||
L</resolve_home_path>, L</resolve_relative_path>.
|
||||
Der daraus resultierende Pfad wird zu L</resolve_empty_path> übergeben, dessen
|
||||
Resultat dann weitergegeben wird an L</resolve_home_path>, wessen Resultat dann
|
||||
weitergegeben wird an L</resolve_relative_path>. Dieses Resultat wird dann final
|
||||
an L</resolve_path> übergeben, welches dann den Rückgabewert stellt.
|
||||
|
||||
=head1 EINE WARNUNG VOR UNINST=1
|
||||
|
||||
Wenn man local::lib in Kombination mit "make install UNINST=1" benutzt, muss
|
||||
man vorsichtig sein über die Tatsache das der Prozess über die Neuinstallation
|
||||
eine nicht ausreichende Sicherheit hat bezüglich wo er nun installieren muss.
|
||||
Hierdurch mann es passieren das beim deinstallieren eines Modul u.U. das
|
||||
globale Modul deinstalliert wird (wenn die Rechte vorhanden sind) aber die
|
||||
neue Version nur in der lokalen Version installiert ist. Es ist hier also sehr
|
||||
wichtig das man "make install UNINST=1" und local::lib nur gleichzeitig
|
||||
benutzt wenn man sehr sicher darüber ist welche Konsequenzen einem
|
||||
entgegenkommen.
|
||||
|
||||
=head1 EINSCHRÄNKUNGEN
|
||||
|
||||
Die Werkzeuge von perl, die benutzt werden um die Pakete zu installieren
|
||||
(die sogenannte toolchain), sind leider nicht in der Lage sauber mit
|
||||
Verzeichnissen umzugehen die Leerzeichen enthalten und können daher local::lib
|
||||
nicht direkt in ein solches Verzeichnis installieren. Was du machen kannst
|
||||
ist B<nach> der Installation von local::lib und der Module die du in deiner
|
||||
local::lib haben willst, das gesamte Verzeichnis dahin zu bewegen. local::lib
|
||||
kann mit dem Verzeichnis mit Leerzeichen umgehen. Bitte aufpassen das natürlich
|
||||
eine weitere Installation oder ein Erneuern von Paketen mit dem CPAN Programm
|
||||
nicht mehr möglich ist.
|
||||
|
||||
Die Shell Erkennung ist sehr primitiv. Derzeit ist es so das alles was "csh"
|
||||
im Namen hat auch als C Shell eingeordnet wird, und alles andere wird als
|
||||
Bourne Shell betrachet, ausser auf Win32 Systemen. Wenn die C<SHELL> Variable
|
||||
nicht gesetzt ist, eine Bourne Shell wird angenommen.
|
||||
|
||||
Bootstrap ist leider ein Hack, und wird auf jedenfall CPAN.pm benutzen für
|
||||
ExtUtils::MakeMaker, auch wenn CPANPLUS installiert ist.
|
||||
|
||||
Es setzt definitiv PERL5LIB, PERL_MM_OPT und PERL_MB_OPT neu und vernichtet
|
||||
jeden Wert der vorher gesetzt war.
|
||||
|
||||
Es sollte vielleicht eine automatische Korrektur der CPAN Config machen, wenn
|
||||
das nicht schon gemacht wurde.
|
||||
|
||||
"Patches Welcome" - Patches sind immer willkommen beim Autor oder den anderen
|
||||
Mitwirkenden.
|
||||
|
||||
Auf Win32 Systemen werden die Umgebungsvariablen nicht direkt in die Registrierung
|
||||
geschrieben damit sie auch nach dem Neustarten erhalten bleiben.
|
||||
|
||||
=head1 FEHLERANALYSE
|
||||
|
||||
Wenn du local::lib konfiguriert hast CPAN Module in deinem Home Verzeichnis
|
||||
zu installieren, und du danach versuchst mit C<cpan -i Foo::Bar> ein Modul
|
||||
zu installieren, und dabei einen Fehler bekommst, wie: C<Warning: You do not
|
||||
have permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
|
||||
/usr/lib64/perl5/5.8.8/Foo/Bar.pm> und in der installationsausgabe steht
|
||||
irgendwo ein Fehler der sagt C<'INSTALL_BASE' is not a known MakeMaker parameter
|
||||
name>, dann hast du aus irgendeinem Grund dein neue Version von ExtUtils::MakeMaker
|
||||
verloren.
|
||||
|
||||
Um dies zu korrigieren, einfach nochmal die bootstrapping Methode laufen lassen,
|
||||
wie oben beschrieben.
|
||||
|
||||
Dann starte C<rm -r ~/.cpan/build/Foo-Bar*>
|
||||
|
||||
Abschliessend dann nochmal mit C<cpan -i Foo::Bar> installieren und die Probleme
|
||||
sollten verschwunden sein.
|
||||
|
||||
=head1 UMGEBUNGSVARIABLEN
|
||||
|
||||
=over 4
|
||||
|
||||
=item SHELL
|
||||
|
||||
=item COMSPEC
|
||||
|
||||
local::lib schaut in die C<SHELL> Umgebungsvariable um die korrekten Kommandos
|
||||
zu der Shell Konfiguration hinzuzufügen.
|
||||
|
||||
Auf Win32 Systemen, C<COMSPEC> wird auch analysiert.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SUPPORT
|
||||
|
||||
IRC:
|
||||
|
||||
Wir sind im Channel #local-lib auf dem Server irc.perl.org.
|
||||
|
||||
=head1 AUTOR DER ÜBERSETZUNG
|
||||
|
||||
Torsten Raudssus <torsten@raudssus.de> http://www.raudssus.de/
|
||||
|
||||
=head1 URHEBERRECHT
|
||||
|
||||
Copyright (c) 2007 - 2010 von den local::lib L<local::lib/"AUTHOR">
|
||||
und L<local::lib/"CONTRIBUTORS"> aufgelistet in L<local::lib|local::lib>.
|
||||
|
||||
=head1 LIZENZ
|
||||
|
||||
Diese Sammlung ist freie Software und kann unter der selben Lizenz verbreitet
|
||||
werden wie Perl selber.
|
||||
|
||||
=cut
|
||||
|
||||
1;
|
||||
560
database/perl/vendor/lib/POD2/JA/MIME/Charset.pod
vendored
Normal file
560
database/perl/vendor/lib/POD2/JA/MIME/Charset.pod
vendored
Normal file
@@ -0,0 +1,560 @@
|
||||
=encoding utf-8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
MIME::Charset~[ja] - MIME のためのキャラクタセット情報
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
use MIME::Charset:
|
||||
|
||||
$charset = MIME::Charset->new("euc-jp");
|
||||
|
||||
キャラクタセット情報の取得:
|
||||
|
||||
$benc = $charset->body_encoding; # 例 "Q"
|
||||
$cset = $charset->as_string; # 例 "US-ASCII"
|
||||
$henc = $charset->header_encoding; # 例 "S"
|
||||
$cset = $charset->output_charset; # 例 "ISO-2022-JP"
|
||||
|
||||
テキストデータの変換:
|
||||
|
||||
($text, $charset, $encoding) =
|
||||
$charset->header_encode(
|
||||
"\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
|
||||
"\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
|
||||
Charset => 'euc-jp');
|
||||
# ...例えば (<変換ずみ文字列>, "ISO-2022-JP", "B") を返す。
|
||||
|
||||
($text, $charset, $encoding) =
|
||||
$charset->body_encode(
|
||||
"Collectioneur path\xe9tiquement ",
|
||||
Charset => 'latin1');
|
||||
# ...例えば (<元の文字列>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
|
||||
|
||||
$len = $charset->encoded_header_len(
|
||||
"Perl\xe8\xa8\x80\xe8\xaa\x9e",
|
||||
Charset => "utf-8",
|
||||
Encoding => "b");
|
||||
# ...例えば 28 を返す。
|
||||
|
||||
モジュール既定値の操作:
|
||||
|
||||
MIME::Charset::alias("csEUCKR", "euc-kr");
|
||||
MIME::Charset::default("iso-8859-1");
|
||||
MIME::Charset::fallback("us-ascii");
|
||||
|
||||
非OO関数 (近い将来に廃止):
|
||||
|
||||
use MIME::Charset qw(:info);
|
||||
|
||||
$benc = body_encoding("iso-8859-2"); # "Q"
|
||||
$cset = canonical_charset("ANSI X3.4-1968"); # "US-ASCII"
|
||||
$henc = header_encoding("utf-8"); # "S"
|
||||
$cset = output_charset("shift_jis"); # "ISO-2022-JP"
|
||||
|
||||
use MIME::Charset qw(:trans);
|
||||
|
||||
($text, $charset, $encoding) =
|
||||
header_encode(
|
||||
"\xc9\xc2\xc5\xaa\xc0\xde\xc3\xef\xc5\xaa".
|
||||
"\xc7\xd1\xca\xaa\xbd\xd0\xce\xcf\xb4\xef",
|
||||
"euc-jp");
|
||||
# ...(<変換されたテキスト>, "ISO-2022-JP", "B") を返す。
|
||||
|
||||
($text, $charset, $encoding) =
|
||||
body_encode(
|
||||
"Collectioneur path\xe9tiquement ".
|
||||
"\xe9clectique de d\xe9chets",
|
||||
"latin1");
|
||||
# ...(<元のテキスト>, "ISO-8859-1", "QUOTED-PRINTABLE") を返す。
|
||||
|
||||
$len = encoded_header_len(
|
||||
"Perl\xe8\xa8\x80\xe8\xaa\x9e", "b", "utf-8"); # 28
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
MIME::Charset は、インターネット上での MIME
|
||||
メッセージに用いるキャラクタセットの情報を提供する。
|
||||
|
||||
=head2 定義
|
||||
|
||||
B<キャラクタセット> とは、MIME での ``character set'' のことで、
|
||||
オクテットの列を文字の列に変換する方法を指す。
|
||||
これは、ISO/IEC における ``符号化文字集合'' (CCS) と
|
||||
``文字符号化法'' (CES) の両方の概念を包含する。
|
||||
|
||||
B<エンコーディング> とは、MIME でのそれのことで、
|
||||
メッセージ本体やメッセージヘッダ本体を印字可能な
|
||||
US-ASCII 文字の列として表現する方法を指す。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=head2 コンストラクタ
|
||||
|
||||
=over
|
||||
|
||||
=item $charset = MIME::Charset->new([CHARSET [, OPTS]])
|
||||
|
||||
キャラクタセットオブジェクトを作成して返す。
|
||||
|
||||
OPTS には次の対を指定できる。
|
||||
B<NOTE>:
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
変換を行わないので、次のオプションは効果を持たない。
|
||||
|
||||
=over 4
|
||||
|
||||
=item Mapping => MAPTYPE
|
||||
|
||||
キャラクタセット名に対して実際に使うマッピングの拡張をするかどうか。
|
||||
C<"EXTENDED"> は拡張マッピングを使う。
|
||||
C<"STANDARD"> は標準化されている厳密なマッピングを使う。
|
||||
既定は C<"EXTENDED">。
|
||||
|
||||
=back
|
||||
|
||||
=cut
|
||||
|
||||
=back
|
||||
|
||||
=head2 キャラクタセット情報の取得
|
||||
|
||||
=over
|
||||
|
||||
=item $charset->body_encoding
|
||||
|
||||
=item body_encoding CHARSET
|
||||
|
||||
CHARSET のメッセージ本体で推奨される伝送エンコーディングを取得する。
|
||||
|
||||
返値は C<"B"> (BASE64)、C<"Q"> (QUOTED-PRINTABLE)、C<"S"> (どちらか短いほう)、
|
||||
C<undef> (伝送エンコードしなくてよい --- 7BIT か 8BIT)
|
||||
のいずれか。これはメッセージヘッダのエンコーディングとは違うこともある。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->as_string
|
||||
|
||||
=item canonical_charset CHARSET
|
||||
|
||||
キャラクタセットの正規の名前を取得する。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->decoder
|
||||
|
||||
キャラクタセットを Unicode に復号するのに使う
|
||||
L<"Encode::Encoding"> オブジェクトを返す。
|
||||
キャラクタセットが指定されていなかったか、当モジュールの知らないキャラクタセットであった場合は、undef 値を返す。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->dup
|
||||
|
||||
キャラクタセットオブジェクトを複写する。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->encoder([CHARSET])
|
||||
|
||||
インターネット上の MIME
|
||||
メッセージで使うことを推奨される互換キャラクタセットで符号化するのに使う
|
||||
L<"Encode::Encoding"> オブジェクトを返す。
|
||||
|
||||
CHARSET 引数を指定した場合、$charset オブジェクトの符号化器
|
||||
(および出力キャラクタセット名) を、CHARSET のそれに置き換える。
|
||||
つまり、$charset オブジェクトは元のキャラクタセットから新たな
|
||||
CHARSET への変換器となる。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->header_encoding
|
||||
|
||||
=item header_encoding CHARSET
|
||||
|
||||
CHARSET のメッセージヘッダで推奨されるエンコーディング法を取得する。
|
||||
|
||||
返値は C<"B">、C<"Q">、C<"S"> (どちらか短くなるほう)、
|
||||
C<undef> (エンコードしなくてよい)
|
||||
のいずれか。これはメッセージ本体のエンコーディングとは違うこともある。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->output_charset
|
||||
|
||||
=item output_charset CHARSET
|
||||
|
||||
指定した CHARSET と互換で、インターネット上の
|
||||
MIME メッセージで使うことを推奨されるキャラクタセット名を
|
||||
(当モジュールが知っていれば) 取得する。
|
||||
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
この関数は単に L<"canonical_charset"> の結果を返す。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=back
|
||||
|
||||
=head2 テキストデータの変換
|
||||
|
||||
=over
|
||||
|
||||
=item $charset->body_encode(STRING [, OPTS])
|
||||
|
||||
=item body_encode STRING, CHARSET [, OPTS]
|
||||
|
||||
STRING を (必要なら) 変換したデータと、
|
||||
メッセージ本体で推奨される伝送エンコーディングを取得する。
|
||||
CHARSET は STRING を符号化しているキャラクタセット。
|
||||
|
||||
OPTS には以下の対を指定できる。
|
||||
B<NOTE>:
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
変換を行わないので、以下のオプションは効果を持たない。
|
||||
|
||||
=over 4
|
||||
|
||||
=item Detect7bit => YESNO
|
||||
|
||||
CHARSET がないとき、7ビットのキャラクタセットを自動認識しようとする。
|
||||
既定は C<"YES">。
|
||||
|
||||
=item Replacement => REPLACEMENT
|
||||
|
||||
エラー処理法の指定。L<"エラー処理"> 参照。
|
||||
|
||||
=back
|
||||
|
||||
3要素のリスト (I<変換ずみの文字列>, I<出力のキャラクタセット>,
|
||||
I<伝送エンコーディング>) が返る。
|
||||
I<伝送エンコーディング> は C<"BASE64">、C<"QUOTED-PRINTABLE">、
|
||||
C<"7BIT">、C<"8BIT"> のいずれか。I<出力のキャラクタセット> が決定できず、
|
||||
I<変換ずみの文字列> が ASCII以外のバイトを含むときは、
|
||||
I<出力のキャラクタセット> は C<undef>、I<伝送エンコーディング> は C<"BASE64">
|
||||
となる。
|
||||
I<出力のキャラクタセット> が C<"US-ASCII">
|
||||
となるのは、文字列が ASCII以外のバイトを含まないときに限る。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->decode(STRING [,CHECK])
|
||||
|
||||
STRING を Unicode 文字列に復号する。
|
||||
|
||||
B<NOTE>:
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
この機能を実行すると死ぬ。
|
||||
|
||||
=cut
|
||||
|
||||
=item detect_7bit_charset STRING
|
||||
|
||||
文字列 STRING を符号化している7 ビットキャラクタセットを推測する。
|
||||
STRING が8ビットのバイトを含むときは C<undef> を返す。
|
||||
そうでないとき、キャラクタセットが不明なら初期キャラクタセットを返す。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->encode(STRING [, CHECK])
|
||||
|
||||
STRING (Unicode 文字列または普通の文字列) を、
|
||||
元のキャラクタセットと互換でインターネット上の
|
||||
MIME メッセージで使うことを推奨されるキャラクタセットを
|
||||
(当モジュールが知っていれば) 使って、符号化する。
|
||||
元のキャラクタセットと互換キャラクタセットが同じでも、
|
||||
文字列を Unicode に復号してから符号化することに注意。
|
||||
|
||||
B<NOTE>:
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
この機能を実行すると死ぬ。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->encoded_header_len(STRING [, ENCODING])
|
||||
|
||||
=item encoded_header_len STRING, ENCODING, CHARSET
|
||||
|
||||
STRING をメッセージヘッダとしてエンコードしたときの長さ
|
||||
(行折りはしないとして) を取得する。
|
||||
|
||||
ENCODING は C<"B">、C<"Q">、C<"S">
|
||||
(C<"B"> と C<"Q"> のうち短くなるほう) のいずれか。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->header_encode(STRING [, OPTS])
|
||||
|
||||
=item header_encode STRING, CHARSET [, OPTS]
|
||||
|
||||
STRING を (必要なら) 変換したデータと、
|
||||
メッセージヘッダで推奨されるエンコーディング法を取得する。
|
||||
CHARSET は STRING を符号化しているキャラクタセット。
|
||||
|
||||
OPTS には以下の対を指定できる。
|
||||
B<NOTE>:
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
変換を行わないので、以下のオプションは効果を持たない。
|
||||
|
||||
=over 4
|
||||
|
||||
=item Detect7bit => YESNO
|
||||
|
||||
CHARSET がないとき、7ビットのキャラクタセットを自動認識しようとする。
|
||||
既定は C<"YES">。
|
||||
|
||||
=item Replacement => REPLACEMENT
|
||||
|
||||
エラー処理法の指定。L<"エラー処理"> 参照。
|
||||
|
||||
=back
|
||||
|
||||
3要素のリスト (I<変換ずみの文字列>, I<出力のキャラクタセット>,
|
||||
I<エンコーディング法>) が返る。
|
||||
I<エンコーディング法> は C<"B">、C<"Q">、C<undef> (エンコードしなくてよい)
|
||||
のいずれか。
|
||||
I<出力のキャラクタセット> が決定できず、I<変換ずみの文字列>
|
||||
が ASCII以外のバイトを含むときは、I<出力のキャラクタセット> は C<"8BIT">
|
||||
(これはキャラクタセットの名前ではI<なく>、符号化が不可能なデータを表す特殊値)
|
||||
で I<エンコーディング法> は C<undef> (エンコードするべきではない) となる。
|
||||
I<出力のキャラクタセット> が C<"US-ASCII">
|
||||
となるのは、文字列が ASCII以外のバイトを含まないときに限る。
|
||||
|
||||
=cut
|
||||
|
||||
=item $charset->undecode(STRING [,CHECK])
|
||||
|
||||
Unicode 文字列 string を、
|
||||
$charset の入力キャラクタセットを使って文字列に変換する。
|
||||
これは C<$charset-E<gt>decoder-E<gt>encode()> と同等である。
|
||||
|
||||
B<NOTE>:
|
||||
Unicode/マルチバイト対応が有効になっていないとき (L<"USE_ENCODE"> 参照) は、
|
||||
この機能を実行すると死ぬ。
|
||||
|
||||
=cut
|
||||
|
||||
=back
|
||||
|
||||
=head2 モジュール既定値の操作
|
||||
|
||||
=over
|
||||
|
||||
=item alias ALIAS [, CHARSET]
|
||||
|
||||
L<"canonical_charset"> で正規名を決定するためのキャラクタセットの別名を取得/設定する。
|
||||
|
||||
CHARSET があって偽でないとき、ALIAS が CHARSET の別名に登録される。
|
||||
さもなければ、別名に変更はない。いずれの場合でも、
|
||||
現在 ALIAS が登録されているキャラクタセットを返す。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=item default [CHARSET]
|
||||
|
||||
既定キャラクタセットを取得/設定する。
|
||||
|
||||
B<既定キャラクタセット>とは、
|
||||
当モジュールで、処理のためのキャラクタセットが不明なときに用いるキャラクタセット。
|
||||
当モジュールを利用するモジュールでは、
|
||||
処理のためのキャラクタセットが不明なときや暗黙の既定値が必要なとき、
|
||||
このキャラクタセットを使うことを推奨する。
|
||||
これは既定では C<"US-ASCII">。
|
||||
|
||||
CHARSET があって偽でなければ、それを既定キャラクタセットに設定する。
|
||||
さもなければ、既定キャラクタセットは変わらない。いずれの場合でも、
|
||||
現在の既定キャラクタセットを返す。
|
||||
|
||||
B<NOTE>: 既定キャラクタセットは変更するI<べきではない>。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=item fallback [CHARSET]
|
||||
|
||||
予備キャラクタセットを取得/設定する。
|
||||
|
||||
B<予備キャラクタセット>とは、
|
||||
当モジュールで、指定されたキャラクタセットでの変換が失敗し、
|
||||
エラー処理法に C<"FALLBACK"> が指定されていたときに用いるキャラクタセット。
|
||||
当モジュールを利用するモジュールでは、
|
||||
キャラクタセット変換が失敗するときに最終手段としてこのキャラクタセットを使ってもよい。
|
||||
これは既定では C<"UTF-8">。
|
||||
|
||||
CHARSET があって偽でなければ、それを予備キャラクタセットに設定する。
|
||||
CHARSET が C<"NONE"> であれば、予備キャラクタセットを未定にする。
|
||||
さもなければ、予備キャラクタセットは変わらない。いずれの場合でも、
|
||||
現在の予備キャラクタセットを返す。
|
||||
|
||||
B<NOTE>: 予備キャラクタセットに C<"US-ASCII"> を指定する価値はI<ある>。
|
||||
変換の結果は、キャラクタセット情報がないときも可読となる。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=item recommended CHARSET [, HEADERENC, BODYENC [, ENCCHARSET]]
|
||||
|
||||
キャラクタセットの特性を取得/設定する。
|
||||
|
||||
必須でない引数があってそのどれかが偽でなければ、
|
||||
その引数で CHARSET の特性を設定する。さもなければ、特性は変わらない。
|
||||
いずれの場合でも、CHARSET の現在の特性を 3 要素のリスト
|
||||
(HEADERENC, BODYENC, ENCCHARSET) として返す。
|
||||
|
||||
HEADERENC はメッセージヘッダで推奨されるエンコーディング法。
|
||||
C<"B">、C<"Q">、C<"S"> (どちらか短くなるほう)、
|
||||
C<undef> (エンコードしなくてよい) を指定できる。
|
||||
|
||||
BODYENC はメッセージ本体で推奨される伝送エンコーディング。
|
||||
C<"B">、C<"Q">、C<"S"> (どちらか短くなるほう)、C<undef> (伝送エンコードしなくてよい) を指定できる。
|
||||
|
||||
ENCCHARSET は、指定した CHARSET と互換で、インターネット上の
|
||||
MIME メッセージで使うことを推奨されるキャラクタセット名。
|
||||
変換が必要ない (または当モジュールが適当なキャラクタセットを知らない) ときは、
|
||||
ENCCHARSET は C<undef>。
|
||||
|
||||
B<NOTE>: この関数の今後の版では、ほかにも必須でない引数をとれるようになるかもしれない
|
||||
(たとえば、文字幅、行分割の挙動などについての属性)。
|
||||
そのため、返値の形式も変わるかもしれない。個々の特性を取得するには
|
||||
L<"header_encoding">、L<"body_encoding">、L<"output_charset"> を使ってほしい。
|
||||
|
||||
|
||||
=cut
|
||||
|
||||
=back
|
||||
|
||||
=head2 定数
|
||||
|
||||
=over
|
||||
|
||||
=item USE_ENCODE
|
||||
|
||||
Unicode/マルチバイト対応フラグ。
|
||||
Unicode とマルチバイトへの対応が有効になっているときは、空でない文字列が設定されている。
|
||||
現在、このフラグは Perl 5.7.3 以降で空でなく、それより以前の Perl では空の文字列。
|
||||
|
||||
=back
|
||||
|
||||
=head2 エラー処理
|
||||
|
||||
L<"body_encode"> と L<"header_encode"> の
|
||||
C<Replacement> オプションには以下のものを指定できる:
|
||||
|
||||
=over
|
||||
|
||||
=item C<"DEFAULT">
|
||||
|
||||
不正な文字を置き換え文字で置き換える。
|
||||
UCM に基づく符号化器を持つキャラクタセットでは <subchar> を使うことがある。
|
||||
|
||||
=item C<"FALLBACK">
|
||||
|
||||
I<予備キャラクタセット> を使って C<"DEFAULT"> 方式をやってみる
|
||||
(L<"fallback"> 参照)。
|
||||
予備キャラクタセットが未定で変換がエラーを起こしたときは、
|
||||
コードはエラーメッセージを出力して死ぬ。
|
||||
|
||||
=item C<"CROAK">
|
||||
|
||||
コードはエラーメッセージを出力してすぐ死ぬ。
|
||||
したがって、本当にエラーで死なせたくなければ
|
||||
eval{} で致命的エラーを受け止めなければいけない。
|
||||
C<"STRICT"> でも同じ。
|
||||
|
||||
=item C<"PERLQQ">
|
||||
|
||||
=item C<"HTMLCREF">
|
||||
|
||||
=item C<"XMLCREF">
|
||||
|
||||
L<Encode> モジュールで定義している
|
||||
C<FB_PERLQQ>、C<FB_HTMLCREF>、C<FB_XMLCREF>
|
||||
の方式を使う。
|
||||
|
||||
=item 数値
|
||||
|
||||
数値を指定することもできる。
|
||||
詳細は L<Encode/Handling Malformed Data> を見てほしい。
|
||||
|
||||
=back
|
||||
|
||||
エラー処理法が指定されないか、上記以外のエラー処理法が指定されたときは、
|
||||
C<"DEFAULT"> とみなす。
|
||||
|
||||
=head2 設定ファイル
|
||||
|
||||
オプションのパラメタの組み込み既定値は、設定ファイル
|
||||
F<MIME/Charset/Defaults.pm> で変更することができる。
|
||||
詳しくは F<MIME/Charset/Defaults.pm.sample> を読んでほしい。
|
||||
|
||||
=head1 VERSION
|
||||
|
||||
$VERSION 変数を見てほしい。
|
||||
|
||||
このモジュールの開発版が
|
||||
L<http://hatuka.nezumi.nu/repos/MIME-Charset/> にある。
|
||||
|
||||
=head2 非互換な変更
|
||||
|
||||
=over 4
|
||||
|
||||
=item 1.001
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
new() メソッドは CHARSET 引数を指定しなくてもオブジェクトを返すようになった。
|
||||
|
||||
=back
|
||||
|
||||
=item 1.005
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
encoded-word に含まれる文字種を RFC 2047 の 5 (3) 節のとおりにした。
|
||||
encoded_header_len() メソッドの返値も変わる。
|
||||
|
||||
=back
|
||||
|
||||
=item 1.008.2
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
body_encoding() メソッドも C<"S"> を返せるようになった。
|
||||
|
||||
=item *
|
||||
|
||||
body_encode() メソッドの UTF-8 に対する返値のエンコーディング要素は、
|
||||
これまでのリリースでは C<"BASE64"> に固定だったが、C<"QUOTED-PRINTABLE"> になることがある。
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
Multipurpose Internet Mail Extensions (MIME).
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright (C) 2006-2017 Hatuka*nezumi - IKEDA Soji.
|
||||
This program is free software; you can redistribute it and/or modify it
|
||||
under the same terms as Perl itself.
|
||||
|
||||
|
||||
=cut
|
||||
190
database/perl/vendor/lib/POD2/JA/Text/LineFold.pod
vendored
Normal file
190
database/perl/vendor/lib/POD2/JA/Text/LineFold.pod
vendored
Normal file
@@ -0,0 +1,190 @@
|
||||
use utf8;
|
||||
|
||||
=encoding utf-8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Text::LineFold~[ja] - プレインテキストの行折り
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
use Text::LineFold;
|
||||
$lf = Text::LineFold->new();
|
||||
|
||||
# 行折りする
|
||||
$folded = $lf->fold($string, 'PLAIN');
|
||||
$indented = $lf->fold(' ' x 8, ' ' x 4, $string);
|
||||
|
||||
# 行折りを戻す
|
||||
$unfolded = $lf->unfold($string, 'FIXED');
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Text::LineFold は、プレインテキストの行折りをしたり行折りを戻したりする。
|
||||
電子メールメッセージを主眼に置いており、RFC 3676 の flowed 形式にも対応する。
|
||||
|
||||
|
||||
=head2 公開インタフェース
|
||||
|
||||
=over 4
|
||||
|
||||
=item new ([KEY => VALUE, ...])
|
||||
|
||||
I<コンストラクタ>。
|
||||
KEY => VALUE の対については config メソッドを参照。
|
||||
|
||||
=item $self->config (KEY)
|
||||
|
||||
=item $self->config ([KEY => VAL, ...])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
設定を取得または更新する。以下の KEY => VALUE 対を指定できる。
|
||||
|
||||
=over 4
|
||||
|
||||
=item Charset => CHARSET
|
||||
|
||||
入力文字列を符号化しているキャラクタセット。
|
||||
文字列または L<MIME::Charset~[ja]> オブジェクト。
|
||||
初期値は C<"UTF-8">。
|
||||
|
||||
=item Language => LANGUAGE
|
||||
|
||||
Charset オプションとともに、言語/地域の文脈を決めるのに使える。
|
||||
初期値は C<"XX">。
|
||||
L<Unicode::LineBreak~[ja]/Context> オプションも参照。
|
||||
|
||||
=item Newline => STRING
|
||||
|
||||
改行の文字列。
|
||||
初期値は C<"\n">。
|
||||
|
||||
=item OutputCharset => CHARSET
|
||||
|
||||
fold()/unfold() の結果を符号化するキャラクタセット。
|
||||
文字列または L<MIME::Charset~[ja]> オブジェクト。
|
||||
特殊値 C<"_UNICODE_"> を指定すると、結果は Unicode 文字列となる。
|
||||
初期値は Charset オプションの値。
|
||||
|
||||
=item TabSize => NUMBER
|
||||
|
||||
タブストップの桁数。
|
||||
0 を指定すると、タブストップを無視する。
|
||||
初期値は 8。
|
||||
|
||||
=item BreakIndent
|
||||
|
||||
=item CharMax
|
||||
|
||||
=item ColMax
|
||||
|
||||
=item ColMin
|
||||
|
||||
=item ComplexBreaking
|
||||
|
||||
=item EAWidth
|
||||
|
||||
=item HangulAsAL
|
||||
|
||||
=item LBClass
|
||||
|
||||
=item LegacyCM
|
||||
|
||||
=item Prep
|
||||
|
||||
=item Urgent
|
||||
|
||||
L<Unicode::LineBreak~[ja]/オプション> を参照。
|
||||
|
||||
=back
|
||||
|
||||
=item $self->fold (STRING, [METHOD])
|
||||
|
||||
=item $self->fold (INITIAL_TAB, SUBSEQUENT_TAB, STRING, ...)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
文字列 STRING を行折りする。
|
||||
行末の余分な空白文字や水平タブ文字を除去し、
|
||||
改行の文字列を Newline オプションで指定したものに置き換え、
|
||||
テキスト末尾に改行がなければ追加する。
|
||||
水平タブ文字は TabSize オプションによる幅のタブストップと見なす。
|
||||
|
||||
ひとつめの形式では、METHOD 引数に以下のオプションを指定できる。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<"FIXED">
|
||||
|
||||
C<"E<gt>"> で始まる行は行折りしない。
|
||||
段落は空行で分かたれる。
|
||||
|
||||
=item C<"FLOWED">
|
||||
|
||||
RFC 3676 で定義される C<"Format=Flowed; DelSp=Yes"> 形式。
|
||||
|
||||
=item C<"PLAIN">
|
||||
|
||||
初期の方法。すべての行を行折りする。
|
||||
|
||||
=back
|
||||
|
||||
ふたつめの形式は、L<Text::Wrap/wrap()> に似ている。
|
||||
すべての行を行折りする。段落の先頭には INITIAL_TAB を、ほかの行の先頭には SUBSEQUENT_TAB を挿入する。
|
||||
|
||||
=item $self->unfold (STRING, METHOD)
|
||||
|
||||
文字列 STRING の行折りされた段落をつなぎ直してそれを返す。
|
||||
|
||||
METHOD 引数には以下のオプションを指定できる。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<"FIXED">
|
||||
|
||||
初期の方法。
|
||||
C<"E<gt>"> で始まる行はつなぎ直さない。
|
||||
空行を段落の区切りとみなす。
|
||||
|
||||
=item C<"FLOWED">
|
||||
|
||||
RFC 3676 で定義される C<"Format=Flowed; DelSp=Yes"> 形式をつなぎ直す。
|
||||
|
||||
=item C<"FLOWEDSP">
|
||||
|
||||
RFC 3676 で定義される C<"Format=Flowed; DelSp=No"> 形式をつなぎ直す。
|
||||
|
||||
=begin comment
|
||||
|
||||
=item C<"OBSFLOWED">
|
||||
|
||||
RFC 2646 (廃止) で定義される C<"Format=Flowed"> 形式をできるだけうまくつなぎ直す。
|
||||
|
||||
=end comment
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
バグやバグのような動作は開発者に教えてください。
|
||||
|
||||
CPAN Request Tracker:
|
||||
L<http://rt.cpan.org/Public/Dist/Display.html?Name=Unicode-LineBreak>.
|
||||
|
||||
=head1 VERSION
|
||||
|
||||
$VERSION 変数を見てほしい。
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<Unicode::LineBreak~[ja]>,
|
||||
L<Text::Wrap>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Copyright (C) 2009-2012 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify it
|
||||
under the same terms as Perl itself.
|
||||
294
database/perl/vendor/lib/POD2/JA/Unicode/GCString.pod
vendored
Normal file
294
database/perl/vendor/lib/POD2/JA/Unicode/GCString.pod
vendored
Normal file
@@ -0,0 +1,294 @@
|
||||
=encoding utf-8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Unicode::GCString~[ja] - UAX #29 書記素クラスタの列としての文字列
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
use Unicode::GCString;
|
||||
$gcstring = Unicode::GCString->new($string);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Unicode::GCString はUnicode文字列を、Unicode標準附属書29 [UAX #29] で定義される「拡張書記素クラスタ」〔extended grapheme cluster〕の列として扱う。
|
||||
|
||||
B<書記素クラスタ>〔grapheme cluster〕は、Unicode文字の列で、ひとつのB<書記素基底>〔grapheme base〕と、付加的なB<書記素エキステンダ>〔grapheme extender〕および/またはB<「前置」文字>〔“prepend” character〕から成る。これは人が「文字」とみなすものに近い。
|
||||
|
||||
=head2 公開インタフェース
|
||||
|
||||
=head3 コンストラクタ
|
||||
|
||||
=over 4
|
||||
|
||||
=item new (STRING, [KEY => VALUE, ...])
|
||||
|
||||
=item new (STRING, [LINEBREAK])
|
||||
|
||||
I<コンストラクタ>。
|
||||
Unicode文字列 STRING から新たに書記素クラスタ文字列
|
||||
(Unicode::GCString オブジェクト) を作る。
|
||||
|
||||
KEY => VALUE の対については L<Unicode::LineBreak~[ja]/オプション>を参照。
|
||||
第二の形式では、
|
||||
L<Unicode::LineBreak~[ja]> オブジェクト LINEBREAK で分節の仕様を決定する。
|
||||
|
||||
B<注>:
|
||||
最初の形式はリリース 2012.10 で導入された。
|
||||
|
||||
=item copy
|
||||
|
||||
I<コピーコンストラクタ>。
|
||||
書記素クラスタ文字列の複製を作る。
|
||||
新たな文字列では、次の位置は先頭になる。
|
||||
|
||||
=back
|
||||
|
||||
=head3 長さ
|
||||
|
||||
=over 4
|
||||
|
||||
=item chars
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
書記素クラスタ文字列に含まれるUnicode文字の数、つまりUnicode文字列としての長さを返す。
|
||||
|
||||
=item columns
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
組み込みの文字データベースで決定される書記素クラスタ文字列の桁数を返す。
|
||||
詳しくは L<Unicode::LineBreak~[ja]/DESCRIPTION> を参照。
|
||||
|
||||
=item length
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
書記素クラスタ文字列に含まれる書記素クラスタの数を返す。
|
||||
|
||||
=back
|
||||
|
||||
=head3 文字列としての操作
|
||||
|
||||
=over 4
|
||||
|
||||
=item as_string
|
||||
|
||||
=item C<">OBJECTC<">
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
書記素クラスタ文字列を明示的にUnicode文字列に変換する。
|
||||
|
||||
=item cmp (STRING)
|
||||
|
||||
=item STRING C<cmp> STRING
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
文字列を比較する。特に風変わりなところはない。
|
||||
文字列のどちらかがUnicode文字列でもよい。
|
||||
|
||||
=item concat (STRING)
|
||||
|
||||
=item STRING C<.> STRING
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
書記素クラスタ文字列を結合する。
|
||||
STRING のどちらかがUnicode文字列でもよい。
|
||||
結果の文字列の桁数 (columns() を参照) や書記素クラスタの数 (length() を参照) は、ふたつの文字列のそれの和になるとはかぎらないことに注意。
|
||||
新たな文字列では、次の位置は左辺の文字列にセットされていた位置になる。
|
||||
|
||||
=item join ([STRING, ...])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
STRING を、書記素クラスタ文字列をはさんでつなげる。
|
||||
STRING のうちに Unicode文字列があってもよい。
|
||||
|
||||
=item substr (OFFSET, [LENGTH, [REPLACEMENT]])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
書記素クラスタ文字列の部分文字列を返す。
|
||||
OFFSET と LENGTH は書記素クラスタで数える。
|
||||
REPLACEMENT を指定すると、部分文字列をそれで置き換える。
|
||||
REPLACEMENT は Unicode文字列でもよい。
|
||||
|
||||
Note:
|
||||
このメソッドは組み込み関数 substr() と異なり、左辺値を返すことはない。
|
||||
|
||||
=back
|
||||
|
||||
=head3 書記素クラスタの列としての操作
|
||||
|
||||
=over 4
|
||||
|
||||
=item as_array
|
||||
|
||||
=item C<@{>OBJECTC<}>
|
||||
|
||||
=item as_arrayref
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
書記素クラスタ文字列を、書記素クラスタの情報の配列に変換する。
|
||||
|
||||
=item eos
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
現在の位置が書記素クラスタ文字列の最後かどうか調べる。
|
||||
|
||||
=item item ([OFFSET])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
OFFSET番めの書記素クラスタを返す。
|
||||
OFFSET を指定しないと、次の位置の書記素クラスタの情報を返す。
|
||||
|
||||
=item next
|
||||
|
||||
=item C<E<lt>>OBJECTC<E<gt>>
|
||||
|
||||
I<インスタンスメソッド>、反復的。
|
||||
次の位置の書記素クラスタを返し、次の位置をひとつ進める。
|
||||
|
||||
=item pos ([OFFSET])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
OFFSET を指定した場合は、次の位置をそれにする。
|
||||
書記素クラスタ文字列の次の位置を返す。
|
||||
|
||||
=back
|
||||
|
||||
=begin comment
|
||||
|
||||
=head4 廃止予定のメソッド
|
||||
|
||||
=over 4
|
||||
|
||||
=item flag ([OFFSET, [VALUE]])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
OFFSET番めの書記素クラスタのフラグ値を取得、設定する。
|
||||
OFFSET を指定しないと、次の位置の書記素クラスタのフラグ値を返す。
|
||||
フラグ値は 255 を超えない非負整数で、はじめは 0。
|
||||
|
||||
定義ずみのフラグには次のものがある。
|
||||
|
||||
=over 4
|
||||
|
||||
=item Unicode::LineBreak::ALLOW_BEFORE
|
||||
|
||||
この書記素クラスタの直前で行分割を許す。
|
||||
|
||||
=item Unicode::LineBreak::PROHIBIT_BEFORE
|
||||
|
||||
この書記素クラスタの直前での行分割を禁ずる。
|
||||
|
||||
=back
|
||||
|
||||
=item lbclass ([OFFSET])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
OFFSET番めの書記素クラスタの最初の文字の行分割クラス
|
||||
(L<Unicode::LineBreak~[ja]> 参照) を返す。
|
||||
OFFSET を指定しないと、次の位置の書記素クラスタの情報を返す。
|
||||
|
||||
B<注>:
|
||||
lbc() を使ってほしい。
|
||||
|
||||
=item lbclass_ext ([OFFSET])
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
OFFSET番めの書記素クラスタの最後の書記素エキステンダの行分割クラス
|
||||
(L<Unicode::LineBreak> 参照) を返す。
|
||||
書記素エキステンダがないか、またはクラスが CM の場合は、lbclass() の値を返す。
|
||||
|
||||
B<注>:
|
||||
lbcext() を使ってほしい。
|
||||
|
||||
=back
|
||||
|
||||
=end comment
|
||||
|
||||
=head3 その他
|
||||
|
||||
=over 4
|
||||
|
||||
=item lbc
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
最初の書記素クラスタの最初の文字の行分割クラス
|
||||
(L<Unicode::LineBreak~[ja]> 参照) を返す。
|
||||
|
||||
=item lbcext
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
最後の書記素クラスタの最後の書記素エキステンダの行分割クラス
|
||||
(L<Unicode::LineBreak~[ja]> 参照) を返す。
|
||||
書記素エキステンダがないか、またはクラスが CM の場合は、
|
||||
最後の書記素基底の行分割クラスを返す。
|
||||
|
||||
=back
|
||||
|
||||
=head1 CAVEATS
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
書記素クラスタを「書記素」と呼ぶべきではない (ラリーはそう呼ぶが)。
|
||||
|
||||
=item *
|
||||
|
||||
Perl の 5.10.1 版あたりでは、Unicode::GCString オブジェクトから Unicode 文字列への暗黙の変換が C<"utf8_mg_pos_cache_update"> キャッシュを混乱させることがある。
|
||||
|
||||
たとえば、つぎのように
|
||||
|
||||
$sub = substr($gcstring, $i, $j);
|
||||
|
||||
するかわりに、つぎのようにするとよい。
|
||||
|
||||
$sub = substr("$gcstring", $i, $j);
|
||||
|
||||
$sub = substr($gcstring->as_string, $i, $j);
|
||||
|
||||
=item *
|
||||
|
||||
このモジュールでは「初期の」書記素クラスタ境界判別アルゴリズムを実装している。
|
||||
手直し〔tailoring〕の機構にはまだ対応していない。
|
||||
|
||||
=back
|
||||
|
||||
=head1 VERSION
|
||||
|
||||
$VERSION 変数を参照してほしい。
|
||||
|
||||
=head2 非互換な変更
|
||||
|
||||
=over 4
|
||||
|
||||
=item 2013.10
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
new() メソッドは非Unicode文字列を引数に取れるようになった。
|
||||
その場合、文字列をiso-8859-1 (Latin 1) キャラクタセットで復号する。
|
||||
以前のリリースでは、このメソッドに非Unicodeを入力すると死ぬようになっていた。
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
[UAX #29]
|
||||
Mark Davis (ed.) (2009-2013).
|
||||
I<Unicode Standard Annex #29: Unicode Text Segmentation>, Revisions 15-23.
|
||||
L<http://www.unicode.org/reports/tr29/>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright (C) 2009-2013 Hatuka*nezumi - IKEDA Soji.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify it
|
||||
under the same terms as Perl itself.
|
||||
917
database/perl/vendor/lib/POD2/JA/Unicode/LineBreak.pod
vendored
Normal file
917
database/perl/vendor/lib/POD2/JA/Unicode/LineBreak.pod
vendored
Normal file
@@ -0,0 +1,917 @@
|
||||
=encoding utf-8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Unicode::LineBreak~[ja] - UAX #14 Unicode 行分割アルゴリズム
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
use Unicode::LineBreak;
|
||||
$lb = Unicode::LineBreak->new();
|
||||
$broken = $lb->break($string);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Unicode::LineBreak は、Unicode 標準の附属書14 [UAX #14] で述べる Unicode 行分割アルゴリズムを実行する。
|
||||
分割位置を決定する際に、附属書11 [UAX #11] で定義される East_Asian_Width 参考特性も考慮する。
|
||||
|
||||
=head2 用語
|
||||
|
||||
便宜的に以下の用語を使う。
|
||||
|
||||
B<強制分割>〔mandatory break〕は、基本規則で定められており、周囲の文字に関係なく義務的に実行される行分割動作。
|
||||
B<任意分割>は、基本規則で認められており、ユーザが実行すると決めた場合に行われる行分割動作。
|
||||
[UAX #14] で定義される任意分割にはB<直接分割>〔direct break〕とB<間接分割>〔indirect break〕とがある。
|
||||
|
||||
B<音素文字的な文字>〔alphabetic characters〕は、通常、他の文字が分割の機会を与えないかぎり、文字同士の間で行分割できない文字。
|
||||
B<表語文字的な文字>〔ideographic characters〕は、通常、その前後で行分割できる文字。
|
||||
[UAX #14] では音素文字的な文字のほとんどを AL に、表語文字的な文字のほとんどを ID に分類している
|
||||
(これらの用語は文字学の観点からすれば不正確である)。
|
||||
若干の用字系では、個々の文字からは分割位置が明確にならないため、辞書による発見的方法を用いる。
|
||||
|
||||
文字列のB<桁数>は、文字列に含まれる文字の数と等しいとはかぎらない。
|
||||
個々の文字はB<広い>〔wide〕か、B<狭い>〔narrow〕か、前進を伴わない〔nonspacing〕かのいずれかであり、各々 2 桁、1 桁、0 桁を占める。
|
||||
若干の文字は、使われる文脈によって広くも狭くもなり得る。
|
||||
カスタマイズによって、文字はより多様な幅を持ちうる。
|
||||
|
||||
=head1 PUBLIC INTERFACE
|
||||
|
||||
=head2 行の分割
|
||||
|
||||
=over 4
|
||||
|
||||
=item new ([KEY => VALUE, ...])
|
||||
|
||||
I<コンストラクタ>。
|
||||
KEY => VALUE の対については L</オプション> を参照。
|
||||
|
||||
=item break (STRING)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
Unicode 文字列 STRING を分割し、それを返す。
|
||||
配列コンテクストでは、結果の各行の配列を返す。
|
||||
|
||||
=item break_partial (STRING)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
break() と同じだが、文字列を少しずつ追加して入力する場合。
|
||||
入力が完了したことを示すには、STRING 引数に C<undef> を与える。
|
||||
|
||||
=item config (KEY)
|
||||
|
||||
=item config (KEY => VALUE, ...)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
設定を取得または変更する。
|
||||
KEY => VALUE の対については L</オプション> を参照。
|
||||
|
||||
=item copy
|
||||
|
||||
I<コピーコンストラクタ>。
|
||||
オブジェクトインスタンスの複製をつくる。
|
||||
|
||||
=begin comment
|
||||
|
||||
=item reset
|
||||
|
||||
I<Undocumented>.
|
||||
|
||||
=end comment
|
||||
|
||||
=back
|
||||
|
||||
=head2 情報の取得
|
||||
|
||||
=over 4
|
||||
|
||||
=item breakingRule (BEFORESTR, AFTERSTR)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
文字列 BEFORESTR と AFTERSTR の間での行分割動作を得る。
|
||||
返値については L</定数> を参照。
|
||||
|
||||
B<注>:
|
||||
このメソッドは、行分割のおおまかな動作を表す値を返すにすぎない。
|
||||
実際のテキストを行折りするには、break() 等のメソッドを使ってほしい。
|
||||
|
||||
=item context ([Charset => CHARSET], [Language => LANGUAGE])
|
||||
|
||||
I<関数>。
|
||||
キャラクタセット CHARSET および言語コード LANGUAGE から、それを使う言語/地域の文脈を得る。
|
||||
|
||||
=back
|
||||
|
||||
=begin comment
|
||||
|
||||
=head3 廃止予定のメソッド
|
||||
|
||||
=over 4
|
||||
|
||||
=item lbrule (BEFORE, AFTER)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
分類 BEFORE と分類 AFTER の間での行分割動作を得る。
|
||||
返値については L</定数> を参照。
|
||||
|
||||
B<注>:
|
||||
このメソッドは、行分割のおおまかな動作を表す値を返すにすぎない。
|
||||
|
||||
B<注>:
|
||||
breakingRule() を使ってほしい。
|
||||
|
||||
=item strsize (LEN, PRE, SPC, STR)
|
||||
|
||||
I<インスタンスメソッド>。
|
||||
[UAX #11] で定義された文字幅に基づいて、Unicode 文字列 PRE.SPC.STR のI<桁数>を算出する。
|
||||
|
||||
B<注>:
|
||||
L<Unicode::GCString/columns> を使ってほしい。
|
||||
|
||||
=back
|
||||
|
||||
=end comment
|
||||
|
||||
=head2 オプション
|
||||
|
||||
L</new>、L</config> の両メソッドには以下の対を指定できる。
|
||||
桁数の算出 ([B<E>])、書記素クラスタ分節 ([B<G>])
|
||||
(L<Unicode::GCString~[ja]> も参照)、行分割動作 ([B<L>])
|
||||
に影響するものがある。
|
||||
|
||||
=over 4
|
||||
|
||||
=item BreakIndent => C<"YES"> | C<"NO">
|
||||
|
||||
[B<L>]
|
||||
行頭の SPACE の並び (インデント) の後では常に分割を許す。
|
||||
[UAX #14] は SPACE のこのような用法を考慮していない。
|
||||
初期値は C<"YES">。
|
||||
|
||||
B<注>:
|
||||
このオプションはリリース 1.011 で導入された。
|
||||
|
||||
=item CharMax => NUMBER
|
||||
|
||||
[B<L>]
|
||||
行に含みうる最大の文字数。行末の空白文字と改行の文字列を除く。
|
||||
文字数は一般に行の長さを表さないことに注意。
|
||||
初期値は C<998>。
|
||||
C<0> にはできない。
|
||||
|
||||
=item ColMin => NUMBER
|
||||
|
||||
[B<L>]
|
||||
任意分割された行の、改行の文字列と行末の空白文字を含めない最小桁数。
|
||||
初期値は C<0>。
|
||||
|
||||
=item ColMax => NUMBER
|
||||
|
||||
[B<L>]
|
||||
行の、改行の文字列と行末の空白文字を含めない最大桁数。つまり、行の最大長。
|
||||
初期値は C<76>。
|
||||
|
||||
=back
|
||||
|
||||
L</Urgent> オプションおよび L</ユーザ定義の行分割動作> も参照。
|
||||
|
||||
=over 4
|
||||
|
||||
|
||||
=item ComplexBreaking => C<"YES"> | C<"NO">
|
||||
|
||||
[B<L>]
|
||||
東南アジアの複雑な文脈で、発見的な行折りを行う。
|
||||
初期値は、東南アジアの表記体系での単語分節が有効なら C<"YES">。
|
||||
|
||||
=item Context => CONTEXT
|
||||
|
||||
[B<E>][B<L>]
|
||||
言語/地域の文脈を指定する。
|
||||
現在使える文脈は C<"EASTASIAN"> か C<"NONEASTASIAN">。
|
||||
初期の文脈は C<"NONEASTASIAN">。
|
||||
|
||||
C<"EASTASIAN"> 文脈では、East_Asian_Width 特性が曖昧 (A)
|
||||
であれば「広い」文字とみなし、行分割特性が AI であれば表語文字的 (ID)
|
||||
とみなす。
|
||||
|
||||
C<"NONEASTASIAN"> 文脈では、East_Asian_Width 特性が曖昧 (A)
|
||||
であれば「狭い」文字とみなし、行分割特性が AI であれば音素文字的 (AL)
|
||||
とみなす。
|
||||
|
||||
=item EAWidth => C<[> ORD C<=E<gt>> PROPERTY C<]>
|
||||
|
||||
=item EAWidth => C<undef>
|
||||
|
||||
[B<E>]
|
||||
個々の文字の East_Asian_Width 特性を手直しする。
|
||||
ORD は文字の UCS インデクス値か、それらの配列への参照。
|
||||
PROPERTY は East_Asian_Width 特性値か拡張値のいずれか (L</定数> を参照)。
|
||||
このオプションは複数回指定できる。
|
||||
C<undef> を指定すると、それまでの手直しをすべて取り消す。
|
||||
|
||||
初期値では、East_Asian_width 特性の手直しはしない。
|
||||
L</文字の特性の手直し> も参照。
|
||||
|
||||
=item Format => METHOD
|
||||
|
||||
[B<L>]
|
||||
分割した行を整形する方法を指定する。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<"SIMPLE">
|
||||
|
||||
初期の方法。
|
||||
任意分割の位置に改行を挿入するだけ。
|
||||
|
||||
=item C<"NEWLINE">
|
||||
|
||||
L</Newline> オプションで指定したもので改行を置き換える。
|
||||
改行の前とテキスト終端の空白文字を除去する。
|
||||
テキスト終端に改行がなければ追加する。
|
||||
|
||||
=item C<"TRIM">
|
||||
|
||||
任意分割の位置に改行を挿入する。
|
||||
改行の前の空白文字を除去する。
|
||||
|
||||
=item C<undef>
|
||||
|
||||
なにもしない (改行の挿入も)。
|
||||
|
||||
=item サブルーチンへの参照
|
||||
|
||||
L</行の整形> を参照。
|
||||
|
||||
=back
|
||||
|
||||
=item HangulAsAL => C<"YES"> | C<"NO">
|
||||
|
||||
[B<L>]
|
||||
ハングル音節とハングル連結チャモ〔conjoining jamo〕を音素文字的な文字 (AL) と扱う。
|
||||
初期値は C<"NO">。
|
||||
|
||||
=item LBClass => C<[> ORD C<=E<gt>> CLASS C<]>
|
||||
|
||||
=item LBClass => C<undef>
|
||||
|
||||
[B<G>][B<L>]
|
||||
個々の文字の行分割特性 (分類) を手直しする。
|
||||
ORD は文字の UCS インデクス値か、それらの配列への参照。
|
||||
CLASS は行分割特性値のいずれか (L</定数> を参照)。
|
||||
このオプションは複数回指定できる。
|
||||
C<undef> を指定すると、それまでの手直しをすべて取り消す。
|
||||
|
||||
初期値では、行分割特性の手直しはしない。
|
||||
L</文字の特性の手直し> も参照。
|
||||
|
||||
=item LegacyCM => C<"YES"> | C<"NO">
|
||||
|
||||
[B<G>][B<L>]
|
||||
前に空白文字がついた結合文字を単独の結合文字 (ID) と扱う。
|
||||
Unicode 5.0 版からは、空白文字のこのような使いかたは推奨されない。
|
||||
初期値は C<"YES">。
|
||||
|
||||
=item Newline => STRING
|
||||
|
||||
[B<L>]
|
||||
改行の文字列とする Unicode 文字列。
|
||||
初期値は C<"\n">。
|
||||
|
||||
=item Prep => METHOD
|
||||
|
||||
[B<L>]
|
||||
ユーザ定義の行分割動作を追加する。
|
||||
このオプションは複数回指定できる。
|
||||
METHOD には以下のものを指定できる。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<"NONBREAKURI">
|
||||
|
||||
URI を分割しない。
|
||||
|
||||
=item C<"BREAKURI">
|
||||
|
||||
URI を、印刷物に適した規則で分割する。
|
||||
詳しくは [CMOS] の 6.17 節と 17.11 節を参照。
|
||||
|
||||
=item C<[> REGEX, SUBREF C<]>
|
||||
|
||||
正規表現 REGEX にマッチする文字列を、SUBREF で参照されるサブルーチンで分割する。
|
||||
詳細は L</ユーザ定義の行分割動作> を参照。
|
||||
|
||||
=item C<undef>
|
||||
|
||||
それまでに追加した動作をすべて取り消す。
|
||||
|
||||
=back
|
||||
|
||||
=item Sizing => METHOD
|
||||
|
||||
[B<L>]
|
||||
文字列の長さを算出する方法を指定する。
|
||||
以下のオプションが使える。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<"UAX11">
|
||||
|
||||
初期の方法。
|
||||
組み込みの文字データベースによって文字の桁数を算出する。
|
||||
|
||||
=item C<undef>
|
||||
|
||||
文字列に含まれる書記素クラスタ (L<Unicode::GCString> 参照) の数を返す。
|
||||
|
||||
=item サブルーチンへの参照
|
||||
|
||||
L</文字列長の算出> を参照。
|
||||
|
||||
=back
|
||||
|
||||
L</ColMax>、L</ColMin>、L</EAWidth> オプションも参照。
|
||||
|
||||
=item Urgent => METHOD
|
||||
|
||||
[B<L>]
|
||||
長すぎる行の扱いかたを指定する。
|
||||
以下のオプションが使える。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<"CROAK">
|
||||
|
||||
エラーメッセージを出力して死ぬ。
|
||||
|
||||
=item C<"FORCE">
|
||||
|
||||
長すぎる文字列を無理やり分割する。
|
||||
|
||||
=item C<undef>
|
||||
|
||||
初期の方法。
|
||||
長すぎる文字列も分割しない。
|
||||
|
||||
=item サブルーチンへの参照
|
||||
|
||||
L</ユーザ定義の行分割動作> を参照。
|
||||
|
||||
=back
|
||||
|
||||
=item ViramaAsJoiner => C<"YES"> | C<"NO">
|
||||
|
||||
[B<G>]
|
||||
ヴィラーマ記号 (ヒンディ語では「ハラント」、クメール文字での「脚」)
|
||||
とそれに続く字とを分離しない。
|
||||
初期値は C<"YES">。
|
||||
B<注>:
|
||||
このオプションはリリース 2011.001_29 で導入された。
|
||||
以前のリリースでは C<"NO"> に固定であった。
|
||||
これは、[UAX #29] で定義する「初期の」書記素クラスタには含まれない仕様である。
|
||||
|
||||
=back
|
||||
|
||||
=begin comment
|
||||
|
||||
=head3 旧式なオプション
|
||||
|
||||
=over 4
|
||||
|
||||
=item TailorEA => C<[> ORD C<=E<gt>> PROPERTY, ... C<]>
|
||||
|
||||
L</EAWidth> の旧式な形式。
|
||||
|
||||
=item TailorLB => C<[> ORD C<=E<gt>> CLASS, ... C<]>
|
||||
|
||||
L</LBClass> の旧式な形式。
|
||||
|
||||
=item UserBreaking => C<[>METHOD, ...C<]>
|
||||
|
||||
L</Prep> の旧式な形式。
|
||||
|
||||
=back
|
||||
|
||||
=end comment
|
||||
|
||||
=head2 定数
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<EA_Na>, C<EA_N>, C<EA_A>, C<EA_W>, C<EA_H>, C<EA_F>
|
||||
|
||||
[UAX #11] で定義される 6 つの East_Asian_Width 特性値。
|
||||
狭 (Na)、中立 (N)、曖昧 (A)、広 (W)、半角 (H)、全角 (F)。
|
||||
|
||||
=item C<EA_Z>
|
||||
|
||||
前進を伴わない文字の East_Asian_Width 特性の値。
|
||||
|
||||
B<注>:
|
||||
この「前進を伴わない」値は当モジュールによる拡張であり、
|
||||
[UAX #11] の一部ではない。
|
||||
|
||||
=begin comment
|
||||
|
||||
C<EA_ZA> and C<EA_ZW>: Undocumented.
|
||||
|
||||
以前のリリースには C<EA_Z> しかなく、C<EA_ZA> と C<EA_ZW> は
|
||||
リリース 2012.10 で追加された。
|
||||
|
||||
=end comment
|
||||
|
||||
=item C<LB_BK>, C<LB_CR>, C<LB_LF>, C<LB_NL>, C<LB_SP>, C<LB_OP>, C<LB_CL>, C<LB_CP>, C<LB_QU>, C<LB_GL>, C<LB_NS>, C<LB_EX>, C<LB_SY>, C<LB_IS>, C<LB_PR>, C<LB_PO>, C<LB_NU>, C<LB_AL>, C<LB_HL>, C<LB_ID>, C<LB_IN>, C<LB_HY>, C<LB_BA>, C<LB_BB>, C<LB_B2>, C<LB_CB>, C<LB_ZW>, C<LB_CM>, C<LB_WJ>, C<LB_H2>, C<LB_H3>, C<LB_JL>, C<LB_JV>, C<LB_JT>, C<LB_SG>, C<LB_AI>, C<LB_CJ>, C<LB_SA>, C<LB_XX>, C<LB_RI>
|
||||
|
||||
[UAX #14] で定義される 40 の行分割特性値 (分類)。
|
||||
|
||||
B<注>:
|
||||
特性値 CP はUnicode 5.2.0版で導入された。
|
||||
特性値 HL と CJ はUnicode 6.1.0版で導入された。
|
||||
特性値 RI は Unicode 6.2.0版で導入された。
|
||||
|
||||
=item C<MANDATORY>, C<DIRECT>, C<INDIRECT>, C<PROHIBITED>
|
||||
|
||||
行分割動作を表す 4 つの値。
|
||||
強制分割。直接分割も間接分割も認める。間接分割を認めるが直接分割は禁ずる。分割を禁ずる。
|
||||
|
||||
=item C<Unicode::LineBreak::SouthEastAsian::supported>
|
||||
|
||||
東南アジアの表記体系のための単語分節機能が有効かどうかを示すフラグ。
|
||||
この機能が有効になっていれば、空でない文字列。
|
||||
そうでなければ C<undef>。
|
||||
|
||||
B<注>: 現リリースでは現代タイ語のタイ文字にのみ対応している。
|
||||
|
||||
=item C<UNICODE_VERSION>
|
||||
|
||||
このモジュールが参照する Unicode 標準の版を示す文字列。
|
||||
|
||||
=back
|
||||
|
||||
=head1 CUSTOMIZATION
|
||||
|
||||
=head2 行の整形
|
||||
|
||||
L</Format> オプションにサブルーチンへの参照を指定する場合、そのサブルーチンは 3 つの引数を取らなければならない。
|
||||
|
||||
$修正後 = &サブルーチン(SELF, EVENT, STR);
|
||||
|
||||
SELF は Unicode::LineBreak オブジェクト、EVENT はサブルーチンが呼ばれた文脈を表す文字列、STR は分割位置の前または後の Unicode 文字列の断片。
|
||||
|
||||
EVENT |駆動の契機 |STR
|
||||
-----------------------------------------------------------------
|
||||
"sot" |テキスト先頭 |最初の行の断片
|
||||
"sop" |強制分割の後 |次の行の断片
|
||||
"sol" |任意分割の後 |続きの行の断片
|
||||
"" |分割の直前 |行全体 (終端の空白文字を除く)
|
||||
"eol" |任意分割 |分割位置の前の空白文字
|
||||
"eop" |強制分割 |改行とその前の空白文字
|
||||
"eot" |テキスト終端 |テキスト終端の空白文字 (と改行)
|
||||
-----------------------------------------------------------------
|
||||
|
||||
サブルーチンは、テキストの断片を修正して返さなければならない。なにも修正しなかったことを示すには、C<undef> を返せばよい。
|
||||
なお、C<"sot">、C<"sop">、C<"sol"> の文脈での修正はその後の分割位置の決定に影響するが、ほかの文脈での修正は影響しない。
|
||||
|
||||
B<注意>:
|
||||
文字列の引数は実際には書記素クラスタ列である。
|
||||
L<Unicode::GCString~[ja]> 参照。
|
||||
|
||||
たとえば次のコードは、行末の空白を取り除いて行折りをする。
|
||||
|
||||
sub fmt {
|
||||
if ($_[1] =~ /^eo/) {
|
||||
return "\n";
|
||||
}
|
||||
return undef;
|
||||
}
|
||||
my $lb = Unicode::LineBreak->new(Format => \&fmt);
|
||||
$output = $lb->break($text);
|
||||
|
||||
=head2 ユーザ定義の行分割動作
|
||||
|
||||
任意分割によって生じる行が CharMax、ColMax、ColMin のいずれかの制限を超えると見込まれるときは、引き続く文字列に対してB<緊急分割>を実行できる。
|
||||
L</Urgent> オプションにサブルーチンへの参照を指定する場合、そのサブルーチンは 2 つの引数を取らなければならない。
|
||||
|
||||
@分割後 = &サブルーチン(SELF, STR);
|
||||
|
||||
SELF は Unicode::LineBreak オブジェクト、STR は分割すべき Unicode 文字列。
|
||||
|
||||
サブルーチンは、文字列 STR を分割した結果の配列を返さなければならない。
|
||||
|
||||
B<注意>:
|
||||
文字列の引数は実際には書記素クラスタ列である。
|
||||
L<Unicode::GCString~[ja]> 参照。
|
||||
|
||||
たとえば次のコードは、若干の化学物質 (チチンのような) の名称にハイフンを挿入し、行折りできるようにする。
|
||||
|
||||
sub hyphenize {
|
||||
return map {$_ =~ s/yl$/yl-/; $_} split /(\w+?yl(?=\w))/, $_[1];
|
||||
}
|
||||
my $lb = Unicode::LineBreak->new(Urgent => \&hyphenize);
|
||||
$output = $lb->break("Methionylthreonylthreonylglutaminylarginyl...");
|
||||
|
||||
L</Prep> オプションに [REGEX, SUBREF] の配列参照を指定する場合、サブルーチンは 2 つの引数を取らなければならない。
|
||||
|
||||
@分割後 = &サブルーチン(SELF, STR);
|
||||
|
||||
SELF は Unicode::LineBreak オブジェクト、STR は REGEX にマッチする分割すべき Unicode 文字列。
|
||||
|
||||
サブルーチンは、文字列 STR を分割した結果の配列を返さなければならない。
|
||||
|
||||
たとえば次のコードは、HTTP URL を [CMOS] の規則を用いて分割する。
|
||||
|
||||
my $url = qr{http://[\x21-\x7E]+}i;
|
||||
sub breakurl {
|
||||
my $self = shift;
|
||||
my $str = shift;
|
||||
return split m{(?<=[/]) (?=[^/]) |
|
||||
(?<=[^-.]) (?=[-~.,_?\#%=&]) |
|
||||
(?<=[=&]) (?=.)}x, $str;
|
||||
}
|
||||
my $lb = Unicode::LineBreak->new(Prep => [$url, \&breakurl]);
|
||||
$output = $lb->break($string);
|
||||
|
||||
=head3 状態の保存
|
||||
|
||||
Unicode::LineBreak オブジェクトはハッシュ参照としてふるまう。
|
||||
任意の要素を、オブジェクトの存在期間中保存できる。
|
||||
|
||||
たとえば次のコードは、段落を空行で分ける。
|
||||
|
||||
sub paraformat {
|
||||
my $self = shift;
|
||||
my $action = shift;
|
||||
my $str = shift;
|
||||
|
||||
if ($action eq 'sot' or $action eq 'sop') {
|
||||
$self->{'line'} = '';
|
||||
} elsif ($action eq '') {
|
||||
$self->{'line'} = $str;
|
||||
} elsif ($action eq 'eol') {
|
||||
return "\n";
|
||||
} elsif ($action eq 'eop') {
|
||||
if (length $self->{'line'}) {
|
||||
return "\n\n";
|
||||
} else {
|
||||
return "\n";
|
||||
}
|
||||
} elsif ($action eq 'eot') {
|
||||
return "\n";
|
||||
}
|
||||
return undef;
|
||||
}
|
||||
my $lb = Unicode::LineBreak->new(Format => \¶format);
|
||||
$output = $lb->break($string);
|
||||
|
||||
=head2 文字列長の算出
|
||||
|
||||
L</Sizing> オプションにサブルーチンへの参照を指定する場合、そのサブルーチンは 5 つの引数を取らなければならない。
|
||||
|
||||
$桁数 = &サブルーチン(SELF, LEN, PRE, SPC, STR);
|
||||
|
||||
SELF は Unicode::LineBreak オブジェクト、LEN は先行する文字列の長さ、PRE は先行する Unicode 文字列、SPC は追加される空白文字、STR は処理する Unicode 文字列。
|
||||
|
||||
サブルーチンは C<PRE.SPC.STR> の桁数を算出して返さなければならない。
|
||||
桁数は整数でなくてもよい。桁数の単位は随意に選べるが、L</ColMin> オプションおよび L</ColMax> オプションのそれと一致させなければならない。
|
||||
|
||||
B<注意>:
|
||||
文字列の引数は実際には書記素クラスタ列である。
|
||||
L<Unicode::GCString~[ja]> 参照。
|
||||
|
||||
たとえば次のコードは、行に 8 桁ごとのタブストップがあるものとして処理する。
|
||||
|
||||
sub tabbedsizing {
|
||||
my ($self, $cols, $pre, $spc, $str) = @_;
|
||||
|
||||
my $spcstr = $spc.$str;
|
||||
while ($spcstr->lbc == LB_SP) {
|
||||
my $c = $spcstr->item(0);
|
||||
if ($c eq "\t") {
|
||||
$cols += 8 - $cols % 8;
|
||||
} else {
|
||||
$cols += $c->columns;
|
||||
}
|
||||
$spcstr = $spcstr->substr(1);
|
||||
}
|
||||
$cols += $spcstr->columns;
|
||||
return $cols;
|
||||
};
|
||||
my $lb = Unicode::LineBreak->new(LBClass => [ord("\t") => LB_SP],
|
||||
Sizing => \&tabbedsizing);
|
||||
$output = $lb->break($string);
|
||||
|
||||
=head2 文字の特性の手直し
|
||||
|
||||
L</LBClass> オプションおよび L</EAWidth> オプションで個々の文字の行分割特性 (分類) や East_Asian_Width 特性を手直しできる。その際に便利な定数をいくつか定義してある。
|
||||
|
||||
=head3 行分割特性
|
||||
|
||||
=head4 仮名などの行頭禁則文字
|
||||
|
||||
初期値では、若干の仮名や仮名に準ずるものを行頭禁則文字 (NS または CJ) と扱う。
|
||||
以下の対を L<LBClass> オプションに指定すれば、これらの文字を通常の表語文字的な文字 (ID) と扱える。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<KANA_NONSTARTERS() =E<gt> LB_ID>
|
||||
|
||||
下記の文字すべて。
|
||||
|
||||
=item C<IDEOGRAPHIC_ITERATION_MARKS() =E<gt> LB_ID>
|
||||
|
||||
表語文字的な繰り返し記号。
|
||||
U+3005 繰返し記号、U+303B ゆすり点、U+309D 平仮名繰返し記号、U+309E 平仮名繰返し記号 (濁点)、U+30FD 片仮名繰返し記号、U+30FE 片仮名繰返し記号 (濁点)。
|
||||
|
||||
注。仮名ではないものもある。
|
||||
|
||||
=item C<KANA_SMALL_LETTERS() =E<gt> LB_ID>
|
||||
|
||||
=item C<KANA_PROLONGED_SOUND_MARKS() =E<gt> LB_ID>
|
||||
|
||||
小書き仮名。
|
||||
小書き平仮名 U+3041 ぁ, U+3043 ぃ, U+3045 ぅ, U+3047 ぇ, U+3049 ぉ, U+3063 っ, U+3083 ゃ, U+3085 ゅ, U+3087 ょ, U+308E ゎ, U+3095 E<0x3095>, U+3096 E<0x3096>。
|
||||
小書き片仮名 U+30A1 ァ, U+30A3 ィ, U+30A5 ゥ, U+30A7 ェ, U+30A9 ォ, U+30C3 ッ, U+30E3 ャ, U+30E5 ュ, U+30E7 ョ, U+30EE ヮ, U+30F5 ヵ, U+30F6 ヶ。
|
||||
片仮名表音拡張 U+31F0 E<0x31F0> - U+31FF E<0x31FF>。
|
||||
小書き片仮名 (代替名称) U+FF67 E<0xFF67> - U+FF6F E<0xFF6F>。
|
||||
|
||||
長音記号。
|
||||
U+30FC 長音記号、U+FF70 長音記号 (代替名称)。
|
||||
|
||||
注。これらの文字は行頭禁則文字と扱われることも、通常の表語文字的な文字と扱われることもある。[JIS X 4051] 6.1.1、[JLREQ] 3.1.7 や [UAX14] を参照。
|
||||
|
||||
注。U+3095 E<0x3095>, U+3096 E<0x3096>, U+30F5 ヵ, U+30F6 ヶ は仮名ではないとされる。
|
||||
|
||||
=item C<MASU_MARK() =E<gt> LB_ID>
|
||||
|
||||
U+303C ます記号。
|
||||
|
||||
注。この文字は仮名ではないが、通常 C<"ます"> や C<"マス"> の略記として用いられる。
|
||||
|
||||
注。この文字は [UAX #14] では行頭禁則文字 (NS) に分類されるが、[JIS X 4051] や [JLREQ] では文字クラス (13) や cl-19 (ID に相当) に分類される。
|
||||
|
||||
=back
|
||||
|
||||
=head4 曖昧な引用符
|
||||
|
||||
初期値では、若干の記号を曖昧な引用符 (QU) と扱う。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<BACKWARD_QUOTES() =E<gt> LB_OP, FORWARD_QUOTES() =E<gt> LB_CL>
|
||||
|
||||
ある言語 (オランダ語、英語、イタリア語、ポルトガル語、スペイン語、トルコ語、
|
||||
および東アジアの多くの言語) では、開き記号に 9 が回転した形状の引用符
|
||||
(E<0x2018> E<0x201C>) を、閉じ記号に 9 の形状の引用符
|
||||
(E<0x2019> E<0x201D>) を用いる。
|
||||
|
||||
=item C<FORWARD_QUOTES() =E<gt> LB_OP, BACKWARD_QUOTES() =E<gt> LB_CL>
|
||||
|
||||
ほかの言語 (チェコ語、ドイツ語、スロヴァク語) では、9 の形状の引用符
|
||||
(E<0x2019> E<0x201D>) を開き記号に、9 が回転した形状の引用符
|
||||
(E<0x2018> E<0x201C>) を閉じ記号に用いる。
|
||||
|
||||
=item C<BACKWARD_GUILLEMETS() =E<gt> LB_OP, FORWARD_GUILLEMETS() =E<gt> LB_CL>
|
||||
|
||||
フランス語、ギリシャ語、ロシア語などでは、左向きのギュメ
|
||||
(E<0x00AB> E<0x2039>) を開き記号に、右向きのギュメ
|
||||
(E<0x00BB> E<0x203A>) を閉じ記号に用いる。
|
||||
|
||||
=item C<FORWARD_GUILLEMETS() =E<gt> LB_OP, BACKWARD_GUILLEMETS() =E<gt> LB_CL>
|
||||
|
||||
ドイツ語やスロヴァク語では、右向きのギュメ (E<0x00BB> E<0x203A>)
|
||||
を開き記号に、左向きのギュメ (E<0x00AB> E<0x2039>) を閉じ記号に用いる。
|
||||
|
||||
=back
|
||||
|
||||
デーン語、フィン語、ノルウェー語、スウェーデン語では、9 の形状の引用符や
|
||||
右向きのギュメ (E<0x2019> E<0x201D> E<0x00BB> E<0x203A>)
|
||||
を開き記号にも閉じ記号にも用いる。
|
||||
|
||||
=head4 和字間隔
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<IDEOGRAPHIC_SPACE() =E<gt> LB_BA>
|
||||
|
||||
U+3000 和字間隔が行頭に来ないようにする。
|
||||
これが初期の挙動である。
|
||||
|
||||
=item C<IDEOGRAPHIC_SPACE() =E<gt> LB_ID>
|
||||
|
||||
和字間隔が行頭に来ることがある。
|
||||
Unicode 6.2以前はこれが初期の挙動であった。
|
||||
|
||||
=item C<IDEOGRAPHIC_SPACE() =E<gt> LB_SP>
|
||||
|
||||
和字間隔が行頭に来ず、行末でははみ出すようにする。
|
||||
|
||||
=back
|
||||
|
||||
=head3 East_Asian_Width 特性
|
||||
|
||||
ラテン、ギリシア、キリルの各用字系では、特定の文字が曖昧 (A) の East_Asian_Width 特性を持っている。このため、こういった文字は C<"EASTASIAN"> 文脈で広い文字と扱われる。
|
||||
C<EAWidth =E<gt> [ AMBIGUOUS_>*C<() =E<gt> EA_N ]> と指定することで、そのような文字を常に狭い文字と扱う。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<AMBIGUOUS_ALPHABETICS() =E<gt> EA_N>
|
||||
|
||||
下記の文字すべてを East_Asian_Width 特性 N (中立) の文字と扱う。
|
||||
|
||||
=item C<AMBIGUOUS_CYRILLIC() =E<gt> EA_N>
|
||||
|
||||
=item C<AMBIGUOUS_GREEK() =E<gt> EA_N>
|
||||
|
||||
=item C<AMBIGUOUS_LATIN() =E<gt> EA_N>
|
||||
|
||||
曖昧 (A) の幅を持つキリル、ギリシア、ラテン用字系の文字を中立 (N) の文字と扱う。
|
||||
|
||||
=back
|
||||
|
||||
いっぽう、東アジアの符号化文字集合に対する多くの実装でたびたび広い文字に描画されてきたにもかかわらず、Unicode 標準では全角 (F) の互換文字を持つがゆえに狭い (Na) 文字とされている文字が若干ある。L<EAWidth> オプションに以下のように指定することで、これらの文字を C<"EASTASIAN"> 文脈で広い文字と扱える。
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<QUESTIONABLE_NARROW_SIGNS() =E<gt> EA_A>
|
||||
|
||||
U+00A2 セント記号、U+00A3 ポンド記号、U+00A5 円記号 (または元記号)、U+00A6 破断線、U+00AC 否定、U+00AF マクロン。
|
||||
|
||||
=back
|
||||
|
||||
=head2 設定ファイル
|
||||
|
||||
L</new> メソッドおよび L</config> メソッドのオプション引数の組み込み初期値は、 設定ファイルで上書きできる。
|
||||
F<Unicode/LineBreak/Defaults.pm>。
|
||||
詳細は F<Unicode/LineBreak/Defaults.pm.sample> を読んでほしい。
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
バグやバグのような動作は、開発者に教えてください。
|
||||
|
||||
CPAN Request Tracker:
|
||||
L<http://rt.cpan.org/Public/Dist/Display.html?Name=Unicode-LineBreak>.
|
||||
|
||||
=head1 VERSION
|
||||
|
||||
$VERSION 変数を参照してほしい。
|
||||
|
||||
=head2 非互換な変更
|
||||
|
||||
=over 4
|
||||
|
||||
=item 2012.06
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
eawidth() メソッドを廃止した。
|
||||
代わりに L<Unicode::GCString/columns> が使えるかもしれない。
|
||||
|
||||
=item *
|
||||
|
||||
lbclass() メソッドを廃止した。
|
||||
L<Unicode::GCString/lbc> や L<Unicode::GCString/lbcext>
|
||||
を使ってほしい。
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=head2 標準への適合性
|
||||
|
||||
このモジュールで用いている文字の特性値は、Unicode 標準 8.0.0版による。
|
||||
|
||||
このモジュールでは、実装水準 UAX14-C2 を実装しているつもり。
|
||||
|
||||
=head1 IMPLEMENTATION NOTES
|
||||
|
||||
=over 4
|
||||
|
||||
=item *
|
||||
|
||||
一部の表語文字的な文字を NS として扱うか ID として扱うかを選べる。
|
||||
|
||||
=item *
|
||||
|
||||
ハングル音節およびハングル連結チャモを ID として扱うか AL として扱うかを選べる。
|
||||
|
||||
=item *
|
||||
|
||||
AI に分類される文字を AL と ID のどちらに解決するかを選べる。
|
||||
|
||||
=item *
|
||||
|
||||
CB に分類される文字は解決しない。
|
||||
|
||||
=item *
|
||||
|
||||
CJ に分類される文字は常に NS に解決する。より柔軟な手直しの機構が提供される。
|
||||
|
||||
=item *
|
||||
|
||||
東南アジアの表記体系の単語分節に対応しない場合は、
|
||||
SA に分類される文字は AL に解決する。
|
||||
ただし、Grapheme_Cluster_Break 特性の値が Extend か SpacingMark である文字は CM に解決する。
|
||||
|
||||
=item *
|
||||
|
||||
SG や XX に分類される文字は AL に解決する。
|
||||
|
||||
=item *
|
||||
|
||||
以下の UCS の範囲にあるコードポイントは、文字が割り当てられていなくても決まった特性値を持つ。
|
||||
|
||||
範囲 | UAX #14 | UAX #11 | 説明
|
||||
-------------------------------------------------------------
|
||||
U+20A0..U+20CF | PR [*1] | N [*2] | 通貨記号
|
||||
U+3400..U+4DBF | ID | W | CJK漢字
|
||||
U+4E00..U+9FFF | ID | W | CJK漢字
|
||||
U+D800..U+DFFF | AL (SG) | N | サロゲート
|
||||
U+E000..U+F8FF | AL (XX) | F か N (A) | 私用領域
|
||||
U+F900..U+FAFF | ID | W | CJK漢字
|
||||
U+20000..U+2FFFD | ID | W | CJK漢字
|
||||
U+30000..U+3FFFD | ID | W | 古漢字
|
||||
U+F0000..U+FFFFD | AL (XX) | F か N (A) | 私用領域
|
||||
U+100000..U+10FFFD | AL (XX) | F か N (A) | 私用領域
|
||||
その他未割り当て | AL (XX) | N | 未割り当て、
|
||||
| | | 予約、非文字
|
||||
-------------------------------------------------------------
|
||||
[*1] U+20A7 ペセタ記号 (PO)、U+20B6 トゥール・リーヴル記号
|
||||
(PO)、U+20BB スカンディナヴィア・マルク記号 (PO)、U+20BE
|
||||
ラリ記号 (PO) を除く。
|
||||
[*2] U+20A9 ウォン記号 (H)、U+20AC ユーロ記号 (F か N (A)) を
|
||||
除く。
|
||||
|
||||
=item *
|
||||
|
||||
一般カテゴリ特性が Mn、Me、Cc、Cf、Zl、Zp のいずれかである文字は、前進を伴わない文字とみなす。
|
||||
|
||||
=back
|
||||
|
||||
=head1 REFERENCES
|
||||
|
||||
=over 4
|
||||
|
||||
=item [CMOS]
|
||||
|
||||
I<The Chicago Manual of Style>, 15th edition.
|
||||
University of Chicago Press, 2003.
|
||||
|
||||
=item [JIS X 4051]
|
||||
|
||||
JIS X 4051:2004
|
||||
I<日本語文書の組版方法>.
|
||||
日本規格協会, 2004.
|
||||
|
||||
=item [JLREQ]
|
||||
|
||||
阿南康宏他.
|
||||
I<日本語組版処理の要件>,
|
||||
W3C 技術ノート 2012年4月3日.
|
||||
L<http://www.w3.org/TR/2012/NOTE-jlreq-20120403/ja/>.
|
||||
|
||||
=begin comment
|
||||
|
||||
=item [Kubota]
|
||||
|
||||
久保田智広 (2001-2002).
|
||||
文字幅問題, I<Unicode (ユニコード) と中日韓 (CJK) エンコーディングとの相互運用の問題>.
|
||||
L<http://web.archive.org/web/people.debian.org/~kubota/unicode-symbols-width2.html.ja>.
|
||||
|
||||
=end comment
|
||||
|
||||
=item [UAX #11]
|
||||
|
||||
A. Freytag (ed.) (2008-2009).
|
||||
I<Unicode Standard Annex #11: East Asian Width>, Revisions 17-19.
|
||||
L<http://unicode.org/reports/tr11/>.
|
||||
|
||||
=item [UAX #14]
|
||||
|
||||
A. Freytag and A. Heninger (eds.) (2008-2015).
|
||||
I<Unicode Standard Annex #14: Unicode Line Breaking Algorithm>, Revisions 22-35.
|
||||
L<http://unicode.org/reports/tr14/>.
|
||||
|
||||
=item [UAX #29]
|
||||
|
||||
Mark Davis (ed.) (2009-2013).
|
||||
I<Unicode Standard Annex #29: Unicode Text Segmentation>, Revisions 15-23.
|
||||
L<http://www.unicode.org/reports/tr29/>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<Text::LineFold~[ja]>,
|
||||
L<Text::Wrap>,
|
||||
L<Unicode::GCString~[ja]>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Copyright (C) 2009-2018 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify it
|
||||
under the same terms as Perl itself.
|
||||
|
||||
=cut
|
||||
468
database/perl/vendor/lib/POD2/PT_BR/local/lib.pod
vendored
Normal file
468
database/perl/vendor/lib/POD2/PT_BR/local/lib.pod
vendored
Normal file
@@ -0,0 +1,468 @@
|
||||
=encoding utf8
|
||||
|
||||
=head1 NAME
|
||||
|
||||
local::lib~[pt_br] - crie e use um diretório lib/ local para módulos perl com PERL5LIB
|
||||
|
||||
=head1 SINOPSE
|
||||
|
||||
No código -
|
||||
|
||||
use local::lib; # configura um lib local em ~/perl5
|
||||
|
||||
use local::lib '~/foo'; # idem, mas ~/foo
|
||||
|
||||
# Ou...
|
||||
use FindBin;
|
||||
use local::lib "$FindBin::Bin/../suporte"; # bibliotecas de suporte locais à aplicação
|
||||
|
||||
Pela linha de comando (shell) -
|
||||
|
||||
# Instala o LWP e suas dependências não encontradas no diretório '~/perl5'
|
||||
perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
|
||||
|
||||
# Apenas exibe alguns comandos úteis para a shell
|
||||
$ perl -Mlocal::lib
|
||||
export PERL_MB_OPT='--install_base /home/username/perl5'
|
||||
export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
|
||||
export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
|
||||
export PATH="/home/username/perl5/bin:$PATH"
|
||||
|
||||
=head2 A técnica de 'bootstrapping'
|
||||
|
||||
Uma forma comum de instalar o local::lib é usando o que é conhecido como
|
||||
técnica de "bootstrapping". É uma boa abordagem caso seu administrador de
|
||||
sistemas não tenha instalado o local::lib. Nesse caso, você precisará
|
||||
instalar o local::lib em seu diretório de usuário.
|
||||
|
||||
Caso você tenha privilégios de administrador, ainda assim deverá
|
||||
configurar suas variáveis de ambiente, como discutido no passo 4, abaixo.
|
||||
Sem elas, você ainda instalará módulos no CPAN do sistema e seus scripts
|
||||
Perl não utilizarão o caminho para o lib/ que você definiu com o local::lib.
|
||||
|
||||
Por padrão, o local::lib instala os módulos do CPAN e a si próprio em ~/perl5.
|
||||
|
||||
Usuários do Windows devem ler L</Diferenças ao usar esse módulo em Win32>.
|
||||
|
||||
1. Baixe e descompacte o local::lib do CPAN (procure por "Download" na página
|
||||
do CPAN sobre o local::lib). Faça isso como um usuário comum, não como root
|
||||
ou administrador. Descompacte o arquivo em seu diretório de usuário ou em
|
||||
qualquer outro local conveniente.
|
||||
|
||||
2. Execute isso:
|
||||
|
||||
perl Makefile.PL --bootstrap
|
||||
|
||||
Caso o sistema pergunte se deve configurar tudo que puder automaticamente,
|
||||
você provavelmente deve responder que sim (yes).
|
||||
|
||||
Para instalar o local::lib em um diretório que não o padrão, você precisará
|
||||
especificá-lo ao chamar o bootstrap, da seguinte forma:
|
||||
|
||||
perl Makefile.PL --bootstrap=~/foo
|
||||
|
||||
3. Execute isso: (local::lib assume que você possui o comando 'make'
|
||||
instalado em seu sistema)
|
||||
|
||||
make test && make install
|
||||
|
||||
4. Agora precisamos configurar as variáveis de ambiente apropriadas para
|
||||
que o Perl use nosso recém-criado diretório lib/. Caso esteja usando bash
|
||||
ou outra shell Bourne, você pode fazer isso adicionando a seguinte linha
|
||||
em seu script de inicialização da shell:
|
||||
|
||||
echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
|
||||
|
||||
Caso esteja usando a shell C, pode fazer da seguinte forma:
|
||||
|
||||
/bin/csh
|
||||
echo $SHELL
|
||||
/bin/csh
|
||||
perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
|
||||
|
||||
Caso tenha passado para o bootstrap um diretório que não o padrão, você
|
||||
precisará indicá-lo na chamada ao local::lib, dessa forma:
|
||||
|
||||
echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
|
||||
|
||||
Após atualizar seu arquivo de configuração da shell, certifique-se de
|
||||
processá-lo novamente para obter as modificações em sua shell atual.
|
||||
Shells Bourne usam C<. ~/.bashrc> para isso, enquanto shells C
|
||||
usam C<source ~/.cshrc>.
|
||||
|
||||
Se estiver em uma máquina lenta ou operando com grandes limitações de
|
||||
espaço em disco, você pode desativar a geração automática de manpages a
|
||||
partir do POD ao instalar módulos. Para isso, basta passar o argumento
|
||||
C<--no-manpages> durante o bootstrap:
|
||||
|
||||
perl Makefile.PL --bootstrap --no-manpages
|
||||
|
||||
Para evitar ter que fazer vários bootstraps para vários ambientes de
|
||||
módulos Perl na mesma conta de usuário - por exemplo se você usa o
|
||||
local::lib para desenvolver diferentes aplicativos independentes -
|
||||
você pode utilizar uma única instalação bootstrap do local::lib para
|
||||
instalar módulos em diretórios diferentes da seguinte forma:
|
||||
|
||||
cd ~/meudir1
|
||||
perl -Mlocal::lib=./
|
||||
eval $(perl -Mlocal::lib=./) ### Para configurar o ambiente apenas nessa shell
|
||||
printenv ### Veja que o ~/meudir1 está na PERL5LIB
|
||||
perl -MCPAN -e install ... ### Os módulos que quiser
|
||||
cd ../meudir2
|
||||
... REPITA ...
|
||||
|
||||
Para múltiplos ambientes destinados a múltiplos aplicativos, você pode
|
||||
precisar incluir uma versão modificada das instruções de C<< use FindBin >>
|
||||
no exemplo "No código" acima. Caso tenha feito algo como o que foi descrito
|
||||
acima, terá um conjunto de módulos Perl em C<< ~/meudir1/lib >>. Caso
|
||||
tenha um script em C<< ~/meudir1/scripts/meuscript.pl >>, você precisará
|
||||
indicar a ele onde encontrar os módulos que instalou para ele
|
||||
em C<< ~/meudir1/lib >>.
|
||||
|
||||
Em C<< ~/meudir1/scripts/meuscript.pl >>:
|
||||
|
||||
use strict;
|
||||
use warnings;
|
||||
use local::lib "$FindBin::Bin/.."; ### aponta para ~/meudir1 e o local::lib acha o lib/
|
||||
use lib "$FindBin::Bin/../lib"; ### aponta para ~/meudir1/lib
|
||||
|
||||
Coloque isso antes de qualquer bloco BEGIN { ... } que precise dos módulos instalados.
|
||||
|
||||
=head2 Diferenças ao usar esse módulo em Win32
|
||||
|
||||
Para configurar as variáveis de ambiente apropriadas para sua sessão atual
|
||||
do C<CMD.exe>, você pode fazer assim:
|
||||
|
||||
C:\>perl -Mlocal::lib
|
||||
set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
|
||||
set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
|
||||
set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
|
||||
set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
|
||||
|
||||
### Para configurar o ambiente apenas dessa shell
|
||||
C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
|
||||
### em vez de $(perl -Mlocal::lib=./)
|
||||
|
||||
Caso queira que as configurações do ambiente persistam, você precisará
|
||||
adicioná-las em Painel de Controle -> Sistema, ou usar o L<App::local::lib::Win32Helper>.
|
||||
|
||||
O "~" é transformado no diretório do perfil do usuário (o diretório com o
|
||||
nome do usuário dentro de "Documents and Settings" (Windows XP ou anterior)
|
||||
ou "Usuários" (Windows Vista e mais recentes)) a menos que $ENV{HOME} exista.
|
||||
Após isso, o nome do diretório é encurtado e os subdiretórios são criados
|
||||
(o que significa que o diretório deve existir).
|
||||
|
||||
=head1 MOTIVAÇÃO
|
||||
|
||||
A versão de um pacote Perl na sua máquina nem sempre é a que você precisa.
|
||||
Obviamente, a melhor coisa a fazer seria atualizá-la para a versão desejada.
|
||||
No entanto, você pode estar em uma situação que o impede de fazer isso.
|
||||
Talvez você não tenha privilégios de administrador do sistema; ou talvez
|
||||
esteja usando um sistema de gerenciamento de pacotes como o do Debian,
|
||||
e ainda não exista um pacote disponível na versão desejada.
|
||||
|
||||
local::lib resolve esse problema possibilitando a criação de seu próprio
|
||||
diretório de pacotes Perl obtidos do CPAN (em sistemas multi-usuário, isso
|
||||
normalmente fica dentro do diretório de seu usuário). A instalação do Perl
|
||||
no sistema permanece inalterada; você simplesmente chama o Perl com opções
|
||||
especiais para que ele use os pacotes em seu diretório local em vez dos
|
||||
pacotes do sistema. O local::lib organiza as coisas para que versões dos
|
||||
pacotes Perl instalados localmente tenham precedência sobre as do sistema.
|
||||
|
||||
Caso esteja usando um sistema de gerenciamento de pacote (como em sistemas
|
||||
Debian), não precisará se preocupar com conflitos entre o Debian e o CPAN.
|
||||
Sua versão local dos pacotes será instalada em um diretório completamente
|
||||
diferente das versões instaladas pelo gerenciador de pacotes do sistema.
|
||||
|
||||
=head1 DESCRIÇÃO
|
||||
|
||||
Este módulo oferece uma forma rápida e conveniente para criar um repositório
|
||||
de módulos locais ao usuário, dentro do diretório do mesmo. Ele também monta
|
||||
e exibe para o usuário uma lista de variáveis de ambiente utilizando a
|
||||
sintaxe da shell atual do usuário (conforme especificado pela variável
|
||||
de ambiente C<SHELL>), pronta para ser adicionada diretamente no arquivo
|
||||
de configuração da shell.
|
||||
|
||||
Generalizando, o local::lib permite a criação e uso de um diretório contendo
|
||||
módulos Perl fora do C<@INC> do Perl. Isso facilita a produção de aplicações
|
||||
com uma versão específica de determinado módulo, ou coleção de módulos.
|
||||
Também é útil quando o mantenedor de um módulo não aplicou determinado patch
|
||||
que você precisa para seu aplicativo.
|
||||
|
||||
Durante o C<import>, o local::lib define valores apropriados para as
|
||||
seguintes variáveis de ambiente:
|
||||
|
||||
=over 4
|
||||
|
||||
=item PERL_MB_OPT
|
||||
|
||||
=item PERL_MM_OPT
|
||||
|
||||
=item PERL5LIB
|
||||
|
||||
=item PATH
|
||||
|
||||
valores serão anexados ao PATH, em vez de substituí-lo.
|
||||
|
||||
=back
|
||||
|
||||
Esses valores são então disponibilizados para referência por qualquer
|
||||
outro código após o C<import>.
|
||||
|
||||
=head1 CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS
|
||||
|
||||
Veja L<lib::core::only|lib::core::only> para uma maneira de fazer isso - mas
|
||||
note que há uma série de ressalvas na abordagem, e a melhor forma é sempre
|
||||
fazer o 'build' contra uma versão limpa do perl (i.e. com 'site' e 'vendor'
|
||||
o mais vazios possível).
|
||||
|
||||
=head1 MÉTODOS
|
||||
|
||||
=head2 ensure_dir_structure_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: Nenhum
|
||||
|
||||
=back
|
||||
|
||||
Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso de falha.
|
||||
|
||||
=head2 print_environment_vars_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: Nenhum
|
||||
|
||||
=back
|
||||
|
||||
Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas
|
||||
para utilizar o caminho fornecido como diretório base.
|
||||
|
||||
=head2 build_environment_vars_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio, $interpolar
|
||||
|
||||
=item Valor de Retorno: %variaveis_de_ambiente
|
||||
|
||||
=back
|
||||
|
||||
Retorna hash contendo as variáveis de ambiente listadas acima, devidamente
|
||||
ajustadas para utilizar o caminho fornecido como diretório base.
|
||||
|
||||
=head2 setup_env_hash_for
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: Nenhum
|
||||
|
||||
=back
|
||||
|
||||
Constrói as chaves no C<%ENV> para o caminho fornecido, chamando
|
||||
C<build_environment_vars_for>.
|
||||
|
||||
=head2 install_base_perl_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_base_de_instalacao
|
||||
|
||||
=back
|
||||
|
||||
Retorna um caminho de diretório indicando onde instalar os módulos Perl
|
||||
para essa instalação local de bibliotecas. Adiciona os diretórios C<lib>
|
||||
e C<perl5> ao final do caminho fornecido.
|
||||
|
||||
=head2 install_base_arch_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_base_de_instalacao_arch
|
||||
|
||||
=back
|
||||
|
||||
Retorna um caminho de diretório indicando onde instalar os módulos Perl
|
||||
de arquiteturas específicas para essa instalação local de bibliotecas.
|
||||
Baseia-se no valor de retorno do método L</install_base_perl_path>,
|
||||
adicionando o valor de C<$Config{archname}>.
|
||||
|
||||
=head2 install_base_bin_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_base_de_instalacao_bin
|
||||
|
||||
=back
|
||||
|
||||
Retorna um caminho de diretório indicando onde instalar programas executáveis
|
||||
para essa instalação local de bibliotecas. Baseia-se no valor de retorno do
|
||||
método L</install_base_perl_path>, adicionando o diretório C<bin>.
|
||||
|
||||
=head2 resolve_empty_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_base_de_instalacao
|
||||
|
||||
=back
|
||||
|
||||
Cria e retorna o caminho de diretório raiz em que a instalação local de
|
||||
módulos deve ser feita. O padrão é C<~/perl5>.
|
||||
|
||||
=head2 resolve_home_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_para_home
|
||||
|
||||
=back
|
||||
|
||||
Procura pelo diretório padrão (home) do usuário. Caso esteja instalado,
|
||||
utiliza o C<File::HomeDir> para isso. Gera uma exceção caso não encontre
|
||||
resultado definitivo.
|
||||
|
||||
=head2 resolve_relative_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_absoluto
|
||||
|
||||
=back
|
||||
|
||||
Transforma o caminho fornecido em um caminho absoluto.
|
||||
|
||||
=head2 resolve_path
|
||||
|
||||
=over 4
|
||||
|
||||
=item Argumentos: $caminho_do_diretorio
|
||||
|
||||
=item Valor de Retorno: $caminho_absoluto
|
||||
|
||||
=back
|
||||
|
||||
Invoca os seguintes métodos em sequência, passando o resultado do método
|
||||
anterior para o seguinte, na tentativa de descobrir onde configurar o
|
||||
ambiente para a instalação local de bibliotecas: L</resolve_empty_path>,
|
||||
L</resolve_home_path>, L</resolve_relative_path>. Passa o caminho de
|
||||
diretório fornecido para L</resolve_empty_path> que retorna um resultado
|
||||
que é passado para L</resolve_home_path>, que então tem seu resultado
|
||||
passado para L</resolve_relative_path>. O resultado dessa chamada final
|
||||
é então retornado pelo L</resolve_path>.
|
||||
|
||||
=head1 UM AVISO SOBRE UNINST=1
|
||||
|
||||
Tenha cuidado ao usar o local::lib em conjunto com "make install UNINST=1".
|
||||
A idéia dessa opção é desinstalar a versão anterior de um módulo antes de
|
||||
instalar a mais recente. No entanto ela não possui uma verificação de
|
||||
segurança de que a versão antiga e a nova referem-se ao mesmo diretório.
|
||||
Usada em combinação com o local::lib, você pode potencialmente apagar uma
|
||||
versão globalmente acessível de um módulo e instalar a versão mais nova
|
||||
no diretório local. Apenas utilize "make install UNINST=1" junto com o
|
||||
local::lib se você entende essas possíveis consequências.
|
||||
|
||||
=head1 LIMITAÇÕES
|
||||
|
||||
As ferramentas auxiliares do perl não conseguem lidar com nomes de
|
||||
diretórios contendo espaços, então não é possível fazer seu bootstrap
|
||||
do local::lib em um diretório com espaços. O que você pode fazer é mover
|
||||
seu local::lib para um diretório com espaços B<após> ter instalado todos
|
||||
os módulos dentro dele. Mas esteja ciente que você não poderá atualizar
|
||||
ou instalar outros módulos do CPAN nesse diretório local após a mudança.
|
||||
|
||||
A detecção da shell é relativamente básica. Neste momento, qualquer coisa
|
||||
com csh no nome será tratada como a C shell ou compatível, e todo o resto
|
||||
será tratado como Bourne, exceto em sistemas Win32. Caso a variável de
|
||||
ambiente C<SHELL> não esteja disponível, assumiremos tratar-se de uma
|
||||
shell compatível com a Bourne.
|
||||
|
||||
A técnica de bootstrap é um hack e usará o CPAN.pm para o ExtUtils::MakeMaker
|
||||
mesmo que você tenha o CPANPLUS instalado.
|
||||
|
||||
Destrói qualquer valor pré-existente nas variáveis de ambiente PERL5LIB,
|
||||
PERL_MM_OPT e PERL_MB_OPT.
|
||||
|
||||
Provavelmente deveria auto-configurar o CPAN caso isso ainda não tenha
|
||||
sido feito.
|
||||
|
||||
Correções (patches) são muito bem-vindos para quaisquer dos itens acima.
|
||||
|
||||
Em sistemas Win32, não há uma forma de escrever no registro as variáveis
|
||||
de ambiente criadas, para que elas persistam a uma reinicialização.
|
||||
|
||||
=head1 SOLUÇÃO DE PROBLEMAS
|
||||
|
||||
Se você configurou o local::lib para instalar módulos do CPAN em algum lugar
|
||||
do seu 'home', e mais tarde tentou instalar um módulo fazendo C<cpan -i
|
||||
Foo::Bar>, mas ele falhou com um erro como: C<Warning: You do not have
|
||||
permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
|
||||
/usr/lib64/perl5/5.8.8/Foo/Bar.pm> e em algum lugar no seu log de instalação
|
||||
houver um erro dizendo C<'INSTALL_BASE' is not a known MakeMaker parameter
|
||||
name>, então você de alguma forma perdeu seu ExtUtils::MakeMaker atualizado.
|
||||
|
||||
Para remediar a situação, execute novamente o procedimento de bootstrap
|
||||
descrito acima.
|
||||
|
||||
Então, execute C<rm -r ~/.cpan/build/Foo-Bar*>
|
||||
|
||||
Finalmente, execute novamente o C<cpan -i Foo::Bar> e ele deve instalar
|
||||
sem problemas.
|
||||
|
||||
=head1 AMBIENTE
|
||||
|
||||
=over 4
|
||||
|
||||
=item SHELL
|
||||
|
||||
=item COMSPEC
|
||||
|
||||
O local::lib procura pela variável de ambiente C<SHELL> do usuário ao
|
||||
processar e exibir os comandos a serem adicionados no arquivo de
|
||||
configuração da shell.
|
||||
|
||||
Em sistemas Win32, C<COMSPEC> também será examinado.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SUPORTE
|
||||
|
||||
IRC:
|
||||
|
||||
Acesse #local-lib em irc.perl.org.
|
||||
|
||||
=head1 AUTOR DA TRADUÇÃO
|
||||
|
||||
Breno G. de Oliveira, C<< <garu at cpan.org> >>, após ter perdido uma aposta
|
||||
para o L<Getty|http://search.cpan.org/~getty/> durante a Copa de 2010.
|
||||
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright (c) 2007 - 2010 L<local::lib/"AUTHOR">
|
||||
e L<local::lib/"CONTRIBUTORS"> do local::lib como listados em L<local::lib>.
|
||||
|
||||
=head1 LICENÇA
|
||||
|
||||
Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos
|
||||
do perl.
|
||||
|
||||
Reference in New Issue
Block a user