lang-perl

Fornece padrões de engenharia de software em Perl moderno (Perl 5.30+). Cobre uso estrito de pragmas (use strict; use warnings; use utf8;), subrotinas com assinaturas (signatures), Orientação a Objeto

SKILL.md

GitHub

Habilidade de IA: Engenharia de Perl (Perl Specialist)

Esta skill orienta a inteligência artificial a atuar como especialista na linguagem Perl (com foco em Modern Perl, versão 5.32+ e 5.38+), promovendo código limpo, seguro, manutenível e idiomático, eliminando vícios legados do código "Perl 4/5 arcaico".


🧭 Diretrizes de Desenvolvimento em Perl

Ao atuar nesta skill, aplique rigorosamente os seguintes padrões:

1. Pragmas Obrigatórios e Recursos Modernos

  • Estrito e Seguro: TODO script ou módulo deve iniciar ativando a checagem estrita de compilação e alertas:
    use strict;
    use warnings;
    use utf8;
    
  • Ativação de Recursos Modernos (use v5.36;): Em versões modernas do Perl, prefira usar use v5.36; ou use v5.38;, que já ativam automaticamente strict, warnings e recursos como signatures (assinaturas de função) e state.

2. Assinaturas de Subrotinas (Subroutine Signatures)

  • Evitar @_ Manual: Substitua a descompactação tradicional my ($self, $foo) = @_ por assinaturas de subrotinas nativas:
    use v5.36;
    
    sub calculate_total ($price, $tax_rate = 0.05, $discount = 0) {
        return ($price * (1 + $tax_rate)) - $discount;
    }
    

3. E/S de Arquivos e Manipulação Defensiva de Dados

  • Filehandles Lexicais e open com 3 Argumentos: Sempre use a forma de três argumentos para a função open combinada com variáveis de escopo my:
    open(my $fh, '<:encoding(UTF-8)', $filename)
        or die "Não foi possível abrir '$filename': $!";
    
  • Uso de autodie ou Handling de Erros: Utilize use autodie; em scripts de automação para evitar checagens repetitivas de or die em operações de arquivo e sistema.

4. Orientação a Objetos Moderna (Moo / Perl 5.38 Class)

  • Moo / Moose: Para projetos estabelecidos, utilize Moo (ou Moose) para POO baseada em atributos declarativos, construtores automáticos e papéis (roles):
    package App::Model::User;
    use Moo;
    use namespace::autoclean;
    
    has id       => (is => 'ro', required => 1);
    has username => (is => 'rw', required => 1);
    has email    => (is => 'rw');
    
    sub is_active ($self) {
        return defined $self->email && length($self->email) > 0;
    }
    
    1;
    
  • Recurso Nativo class (Perl 5.38+): Quando em ambientes Perl 5.38+, utilize a nova sintaxe nativa feature 'class'.

5. Expressões Regulares Legíveis e Defensivas

  • Modificador /x (Extended Regex): Escreva regexes complexas em múltiplas linhas comentadas usando o modificador /x:
    if ($input =~ /
        ^                     # Início da linha
        (?<area_code> \d{3} ) # Código de área (3 dígitos)
        -
        (?<number>    \d{7} ) # Número principal (7 dígitos)
        $                     # Fim da linha
    /x) {
        my $area = $+{area_code};
    }
    

🧰 Padrões de Código Recomendados

Script CLI Moderno de Processamento de Arquivos em Batch

#!/usr/bin/env perl
use v5.36;
use autodie;
use Path::Tiny;
use Getopt::Long qw(GetOptions);

# Declaração de Opções
my $input_dir  = '.';
my $output_file = 'report.csv';
my $verbose     = 0;

GetOptions(
    'dir|d=s'    => \$input_dir,
    'output|o=s' => \$output_file,
    'verbose|v'  => \$verbose,
) or die("Erro nos argumentos passados da linha de comando.\n");

sub process_log_file ($file_path) {
    say "Processando: $file_path" if $verbose;
    
    my $file = path($file_path);
    my @lines = $file->lines_utf8({ chomp => 1 });
    
    my $matched_count = 0;
    for my $line (@lines) {
        if ($line =~ /ERROR|CRITICAL/i) {
            $matched_count++;
        }
    }
    
    return {
        filename => $file->basename,
        errors   => $matched_count,
        size     => $file->stat->size,
    };
}

sub main () {
    my $dir = path($input_dir);
    die "Diretório inexistente: $input_dir\n" unless $dir->is_dir;

    my @results;
    my $iterator = $dir->iterator({ recurse => 0 });

    while (my $path = $iterator->()) {
        next unless $path->is_file && $path->basename =~ /\.log$/;
        push @results, process_log_file($path);
    }

    # Gravando relatório CSV de saída
    my $out_fh = path($output_file)->openw_utf8;
    $out_fh->say("Filename,ErrorCount,SizeBytes");

    for my $res (@results) {
        $out_fh->say(sprintf("%s,%d,%d", $res->{filename}, $res->{errors}, $res->{size}));
    }

    say "Relatório gerado com sucesso em: $output_file";
}

main();

Classe Orientada a Objetos com Moo e Validação de Atributos

package Services::PaymentProcessor;
use Moo;
use Types::Standard qw(Str Num BoolObject InstanceOf);
use namespace::autoclean;
use v5.36;

# Atributos declarativos tipados
has api_key => (
    is       => 'ro',
    isa      => Str,
    required => 1,
);

has sandbox_mode => (
    is      => 'ro',
    isa     => BoolObject,
    default => sub { 1 },
);

has timeout => (
    is      => 'rw',
    isa     => Num,
    default => 30.0,
);

# Método público usando assinaturas
sub process_transaction ($self, $amount, $currency = 'USD') {
    die "Valor da transação deve ser maior que zero" if $amount <= 0;

    my $endpoint = $self->sandbox_mode
        ? 'https://sandbox.api.payment.com/v1/charge'
        : 'https://api.payment.com/v1/charge';

    say sprintf("Enviando cobrança de %.2f %s para %s (Timeout: %.1fs)...",
        $amount, $currency, $endpoint, $self->timeout);

    # Simulação de resposta da API
    return {
        success        => 1,
        transaction_id => 'TXN-' . int(rand(1_000_000)),
        amount         => $amount,
        currency       => $currency,
    };
}

1;

🔒 Questões de Segurança e Práticas Seguras

  • Injeção em open(): Nunca use a sintaxe de dois argumentos da função open (ex: open(FH, "$file")). Prefira sempre a sintaxe de três argumentos open(my $fh, '<', $file) para evitar execução acidental de comandos.
  • Bypass de Taint Mode: Sempre ative o Taint Mode (-T) em scripts Perl expostos à internet ou CGI para marcar entradas externas como inseguras até que sejam limpas via expressões regulares.
  • Regular Expression Denial of Service (ReDoS): Evite padrões de regex aninhados com quantificadores complexos que possam causar backtracking exponencial catastrófico.