focal (3) POD2::PT::POD2::Base.3pm.gz
NOME
POD2::Base~[pt] - Módulo básico para traduções de documentação Perl
SINOPSE
use POD2::Base;
$pod2 = POD2::Base->new({ lang => 'EO' });
@dirs = $pod2->pod_dirs;
$re = $pod2->search_perlfunc_re;
DESCRIÇÃO
Este código é uma abstração do código em POD2::IT e POD2::FR, módulos que pertencem aos projetos italiano
e francês de tradução dos documentos que acompanham o interpretador Perl.
Com o pacote de tradução já instalado, a documentação traduzida pode ser acessada através do comando:
$ perldoc POD2::<lang>::<podname>
(onde <lang> é uma abreviação para linguagem como IT, FR, TLH, etc.)
Isto funciona seguramente até para as versões antigas do perldoc. Não é muito conveniente mas sempre
funciona.
Para incrementar o suporte para leitura destes documentos traduzidos, o programa perldoc (desde a versão
3.14_01) foi atualizado para encontrar PODs traduzidos assim:
$ perldoc -L IT <podpage>
$ perldoc -L FR -f <function>
$ perldoc -L TLH -q <FAQregex>
(Nota: Este suporte foi distribuído junto da versão 5.10.0 do interpretador Perl recentemente
disponilizado no CPAN.)
O objetivo desta classe é prover uma base mínima para ajudar o "perldoc" e os autores de projetos de
tradução a fazerem seu trabalho.
SUBCLASSES
Se você quer escrever um pacote de tradução (e tem algumas necessidades de personalização), seu trabalho
pode ser diminuído se você criar uma subclasse de "POD2::Base".
Por exemplo, um exemplo mínimo é ilustrado abaixo.
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re { # ajuda 'perldoc -f' a funcionar
return 'Klingon Listing of Perl Functions';
}
1;
E então
$ perldoc -L tlh perlintro
vai lhe apresentar a introdução de Perl na linguagem Klingon (desde que um arquivo POD2/TLH/perlintro.pod
tenha sido distribuído junto com POD2/TLH.pm) e
$ perldoc -L tlh -f pack
vai encontrar a documentação em Klingon de "pack" (se POD2/TLH/perlfunc.pod foi disponibilizado também).
MÉTODOS
Este módulo foi projetado como uma classe OO com uma API bem pequena.
new
$pod2 = POD2::Base->new(\%args);
$pod2 = POD2::ANY->new();
O constructor. A criação de uma instância pode se fazer de modo similar a:
$pod2 = POD2::Base->new({ lang => 'tlh' });
onde as opções suportadas são:
• "lang"
Especifica o código da linguagem em que estamos interessados. Este parâmetro é obrigatório, mas
pode ser extraído do nome da subclasse, como explicado mais abaixo.
• "inc"
Este parâmetro é usado para substituir a lista de diretórios para as bibliotecas Perl onde
procuram-se os documentos POD (ou seja, @INC). Na maior parte do tempo, você não vai querer mexer
com isto. Este parâmetro é mais útil para debugging e testes.
Espera-se um array ref.
Se "POD2::ANY" é uma subclasse de "POD2::Base", o construtor herdado funcionará sem argumentos
extraindo 'ANY' do nome do pacote e usando-o como o código da linguagem desejada.
Note que o uso de "inc" no construtor congela a lista de diretórios vasculhados pela instância
"POD2::Base". Se não é usado, o conteúdo atualizado de @INC é usado em cada chamada de "pod_dirs" (de
tal forma que mudanças dinâmicas no path para as bibliotecas Perl são percebidas). É isto que
queríamos dizer com "Na maior parte do tempo, você não vai querer mexer com isto."
pod_dirs
@dirs = $pod2->pod_dirs;
@dirs = $pod2->pod_dirs(\%options);
Usado por "Pod::Perldoc" para descobrir onde procurar por PODs traduzidos.
O comportamento padrão de "POD2::Base" é encontrar cada diretório POD2/<lang>/ sob os diretórios de
bibliotecas Perl (@INC) ou na lista dada como o argumento "inc" no construtor.
As opções suportadas são:
• "test"
Por default, o retorno de "pod_dirs" não inclui diretórios POD que não existem (testados com
"-d"). Se um valor falso explícito é dado para esta opção (por exemplo, "test => 0"), este teste
não é feito e "pod_dirs" inclui todos candidatos POD2/<lang>/ abaixo dos diretórios de
bibliotecas. (Útil para o debugging deste módulo, mas sem outros usos práticos além deste.)
search_perlfunc_re
$re = $pod2->search_perlfunc_re;
Para implementar "perldoc -f <function>" o código atual de "Pod::Perldoc" usa um string fixo
"Alphabetical Listing of Perl Functions" ou o retorno deste método (em uma regex) para pular a
introdução e alcançar a listagem das funções builtin. Então um pacote de tradução com a
correspondente tradução de perlfunc.pod deve definir este método para fazer "perldoc -L <lang> -f
<function>" funcionar corretamente.
Há outros métodos documentados abaixo. Entretanto, eles provavelmente serão tornados obsoletos em versões
futuras quando forem projetados e implementados métodos mais gerais de encontrar e mostrar os metadados
sobre os PODs traduzidos.
pod_info
$hashref = $pod2->pod_info;
Usado pelo próprio "POD2::Base" e seus ancestrais "POD2::IT" e "POD2::FR". O retorno contém alguns
metadados sobre os PODs traduzidos usados pelos métodos "print_pod" e "print_pods".
Ao fazer subclasses seguindo o padrão de "POD2::IT" e "POD2::FR", você deve redefinir este método com
a informação atual sobre quais traduções POD o pacote atual está disponibilizando.
print_pods
$pod2->print_pods;
Mostra (via "print") todos PODs traduzidos e a versão correspondente de Perl dos arquivos originais.
print_pod
$pod2->print_pod(@pages);
$pod2->print_pod(); # usa @ARGV
Mostra a versão de Perl correspondente dos arquivos originais associados aos PODs passados como
argumentos.
EXEMPLOS
POD2::TLH
Uma versão mais completa de "POD2::TLH" pode-se parecer com isto:
package POD2::TLH; # Klingon
use POD2::Base;
our @ISA = qw( POD2::Base );
sub search_perlfunc_re {
return 'Klingon Listing of Perl Functions';
}
sub pod_info {
return { perlintro => '5.8.8' };
}
1;
E você pode experimentar:
use POD2::TLH;
my $pod2 = 'POD2::TLH';
$pod2->print_pods();
$pod2->print_pod('pod_foo', 'pod_baz', ...);
OS ARQUIVOS INSTALADOS
Se você quer descobrir quais arquivos PODs de uma dada linguagem que estão instalados junto com seu
interpretador Perl, você pode usar um código similar a este.
use File::Find;
use POD2::Base;
my $pod2 = POD2::Base->new({ lang => $lang });
my @files;
find sub { push @files, $File::Find::name } if -f },
$pod2->pod_dirs;
print "$_\n" for @files;
Na distribuição "POD2-Base", é incluído um script eg/list.pl com uma versão estendida deste código.
As regras para encontrar POD em arquivos .pod, .pm e outros pertencem ao módulo Pod::Perldoc. Assim
"POD2::Base" não tenta repetir esta funcionalidade aqui.
AUTORES
Enrico Sorcinelli <bepi at perl.it> (pelo código original em POD2::IT)
Adriano Ferreira <ferreira at cpan.org>
VEJA TAMBÉM
POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
A versão original deste documento: POD2::Base.
(O propósito desta tradução é servir como um primeiro teste para experimentar o suporte dos vários
modules Pod e sites Perl aos PODs traduzidos.)
(This translation was supplied as a front test against the support of the many Pod modules and Perl sites
on translated PODs.)
COPYRIGHT E LICENÇA
Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.