1POD2::PT::POD2::Base(3)User Contributed Perl DocumentatioPnOD2::PT::POD2::Base(3)
2
6 POD2::Base~[pt] - Módulo básico para traduções de documentação Perl
7
9 use POD2::Base;
10 $pod2 = POD2::Base->new({ lang => 'EO' });
11 @dirs = $pod2->pod_dirs;
13 $re = $pod2->search_perlfunc_re;
14
16 Este código é uma abstração do código em POD2::IT e POD2::FR, módulos
17 que pertencem aos projetos italiano e francês de tradução dos
18 documentos que acompanham o interpretador Perl.
19 Com o pacote de tradução já instalado, a documentação traduzida pode
21 ser acessada através do comando:
22 $ perldoc POD2::<lang>::<podname>
24 (onde <lang> é uma abreviação para linguagem como IT, FR, TLH, etc.)
26 Isto funciona seguramente até para as versões antigas do perldoc. Não é
28 muito conveniente mas sempre funciona.
29 Para incrementar o suporte para leitura destes documentos traduzidos, o
31 programa perldoc (desde a versão 3.14_01) foi atualizado para encontrar
32 PODs traduzidos assim:
33 $ perldoc -L IT <podpage>
35 $ perldoc -L FR -f <function>
36 $ perldoc -L TLH -q <FAQregex>
37 (Nota: Este suporte foi distribuído junto da versão 5.10.0 do
39 interpretador Perl recentemente disponilizado no CPAN.)
40 O objetivo desta classe é prover uma base mínima para ajudar o
42 "perldoc" e os autores de projetos de tradução a fazerem seu trabalho.
43
45 Se você quer escrever um pacote de tradução (e tem algumas necessidades
46 de personalização), seu trabalho pode ser diminuído se você criar uma
47 subclasse de "POD2::Base".
48 Por exemplo, um exemplo mínimo é ilustrado abaixo.
50 package POD2::TLH; # Klingon
52 use POD2::Base;
54 our @ISA = qw( POD2::Base );
55 sub search_perlfunc_re { # ajuda 'perldoc -f' a funcionar
57 return 'Klingon Listing of Perl Functions';
58 }
59 1;
61 E então
63 $ perldoc -L tlh perlintro
65 vai lhe apresentar a introdução de Perl na linguagem Klingon (desde que
67 um arquivo POD2/TLH/perlintro.pod tenha sido distribuído junto com
68 POD2/TLH.pm) e
69 $ perldoc -L tlh -f pack
71 vai encontrar a documentação em Klingon de "pack" (se
73 POD2/TLH/perlfunc.pod foi disponibilizado também).
74
76 Este módulo foi projetado como uma classe OO com uma API bem pequena.
77 new
79 $pod2 = POD2::Base->new(\%args);
80 $pod2 = POD2::ANY->new();
81 O constructor. A criação de uma instância pode se fazer de modo
83 similar a:
84 $pod2 = POD2::Base->new({ lang => 'tlh' });
86 onde as opções suportadas são:
88 • "lang"
90 Especifica o código da linguagem em que estamos interessados.
92 Este parâmetro é obrigatório, mas pode ser extraído do nome da
93 subclasse, como explicado mais abaixo.
94 • "inc"
96 Este parâmetro é usado para substituir a lista de diretórios
98 para as bibliotecas Perl onde procuram-se os documentos POD (ou
99 seja, @INC). Na maior parte do tempo, você não vai querer mexer
100 com isto. Este parâmetro é mais útil para debugging e testes.
101 Espera-se um array ref.
103 Se "POD2::ANY" é uma subclasse de "POD2::Base", o construtor
105 herdado funcionará sem argumentos extraindo 'ANY' do nome do pacote
106 e usando-o como o código da linguagem desejada.
107 Note que o uso de "inc" no construtor congela a lista de diretórios
109 vasculhados pela instância "POD2::Base". Se não é usado, o conteúdo
110 atualizado de @INC é usado em cada chamada de "pod_dirs" (de tal
111 forma que mudanças dinâmicas no path para as bibliotecas Perl são
112 percebidas). É isto que queríamos dizer com "Na maior parte do
113 tempo, você não vai querer mexer com isto."
114 pod_dirs
116 @dirs = $pod2->pod_dirs;
117 @dirs = $pod2->pod_dirs(\%options);
118 Usado por "Pod::Perldoc" para descobrir onde procurar por PODs
120 traduzidos.
121 O comportamento padrão de "POD2::Base" é encontrar cada diretório
123 POD2/<lang>/ sob os diretórios de bibliotecas Perl (@INC) ou na
124 lista dada como o argumento "inc" no construtor.
125 As opções suportadas são:
127 • "test"
129 Por default, o retorno de "pod_dirs" não inclui diretórios POD
131 que não existem (testados com "-d"). Se um valor falso
132 explícito é dado para esta opção (por exemplo, "test => 0"),
133 este teste não é feito e "pod_dirs" inclui todos candidatos
134 POD2/<lang>/ abaixo dos diretórios de bibliotecas. (Útil para
135 o debugging deste módulo, mas sem outros usos práticos além
136 deste.)
137 search_perlfunc_re
139 $re = $pod2->search_perlfunc_re;
140 Para implementar "perldoc -f <function>" o código atual de
142 "Pod::Perldoc" usa um string fixo "Alphabetical Listing of Perl
143 Functions" ou o retorno deste método (em uma regex) para pular a
144 introdução e alcançar a listagem das funções builtin. Então um
145 pacote de tradução com a correspondente tradução de perlfunc.pod
146 deve definir este método para fazer "perldoc -L <lang> -f
147 <function>" funcionar corretamente.
148 Há outros métodos documentados abaixo. Entretanto, eles provavelmente
150 serão tornados obsoletos em versões futuras quando forem projetados e
151 implementados métodos mais gerais de encontrar e mostrar os metadados
152 sobre os PODs traduzidos.
153 pod_info
155 $hashref = $pod2->pod_info;
156 Usado pelo próprio "POD2::Base" e seus ancestrais "POD2::IT" e
158 "POD2::FR". O retorno contém alguns metadados sobre os PODs
159 traduzidos usados pelos métodos "print_pod" e "print_pods".
160 Ao fazer subclasses seguindo o padrão de "POD2::IT" e "POD2::FR",
162 você deve redefinir este método com a informação atual sobre quais
163 traduções POD o pacote atual está disponibilizando.
164 print_pods
166 $pod2->print_pods;
167 Mostra (via "print") todos PODs traduzidos e a versão
169 correspondente de Perl dos arquivos originais.
170 print_pod
172 $pod2->print_pod(@pages);
173 $pod2->print_pod(); # usa @ARGV
174 Mostra a versão de Perl correspondente dos arquivos originais
176 associados aos PODs passados como argumentos.
177
179 POD2::TLH
180 Uma versão mais completa de "POD2::TLH" pode-se parecer com isto:
181 package POD2::TLH; # Klingon
183 use POD2::Base;
185 our @ISA = qw( POD2::Base );
186 sub search_perlfunc_re {
188 return 'Klingon Listing of Perl Functions';
189 }
190 sub pod_info {
192 return { perlintro => '5.8.8' };
193 }
194 1;
196 E você pode experimentar:
198 use POD2::TLH;
200 my $pod2 = 'POD2::TLH';
201 $pod2->print_pods();
202 $pod2->print_pod('pod_foo', 'pod_baz', ...);
203 OS ARQUIVOS INSTALADOS
205 Se você quer descobrir quais arquivos PODs de uma dada linguagem que
206 estão instalados junto com seu interpretador Perl, você pode usar um
207 código similar a este.
208 use File::Find;
210 use POD2::Base;
211 my $pod2 = POD2::Base->new({ lang => $lang });
213 my @files;
215 find sub { push @files, $File::Find::name } if -f },
216 $pod2->pod_dirs;
217 print "$_\n" for @files;
218 Na distribuição "POD2-Base", é incluído um script eg/list.pl com uma
220 versão estendida deste código.
221 As regras para encontrar POD em arquivos .pod, .pm e outros pertencem
223 ao módulo Pod::Perldoc. Assim "POD2::Base" não tenta repetir esta
224 funcionalidade aqui.
225
227 Enrico Sorcinelli <bepi at perl.it> (pelo código original em POD2::IT)
228 Adriano Ferreira <ferreira at cpan.org>
230
232 POD2::IT, POD2::FR, POD2::LT, POD2::CN, perldoc, perl.
233 A versão original deste documento: POD2::Base.
235 (O propósito desta tradução é servir como um primeiro teste para
237 experimentar o suporte dos vários modules Pod e sites Perl aos PODs
238 traduzidos.)
239 (This translation was supplied as a front test against the support of
241 the many Pod modules and Perl sites on translated PODs.)
242
244 Copyright (C) 2004-2006 Perl.it / Perl Mongers Italia
245 This library is free software; you can redistribute it and/or modify it
247 under the same terms as Perl itself.
248perl v5.34.0 2022-01-21 POD2::PT::POD2::Base(3)