--- name: "POD2::PT::POD2::Base" section: "3pm" platform: "linux" package: "libpod2-base-perl" version: "0.043-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/POD2::PT::POD2::Base" --- # POD2::PT::POD2::Base(3pm) ## 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:::: ``` (onde \ é 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 $ perldoc -L FR -f $ perldoc -L TLH -q ``` (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/\/* 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/\/* 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 "` 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 -f "` 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 \ (pelo código original em POD2::IT) Adriano Ferreira \ ## 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.