fix: add encoding parameter to PPI::Document->new

[toddr-bot]

Summary

PPI::Document->new($filename) reads files as raw bytes with no encoding support, making it impossible to correctly parse UTF-8 encoded Perl source files containing non-ASCII characters. This adds an encoding parameter so users can specify the file encoding:

my $doc = PPI::Document->new($filename, encoding => 'UTF-8');

Fixes #22

Changes

• PPI::Util::_slurp() accepts optional encoding parameter, applies :encoding() layer via binmode when specified
• PPI::Document->new() handles the encoding attribute by slurping with the specified encoding and passing the decoded string to the lexer
• New PPI::Document->encoding() accessor returns the encoding the document was created with
• PPI::Document->save() applies the document's encoding when writing, so round-trip load/save preserves the correct byte representation on disk
• PPI::Document::_setattr() stores the encoding attribute
• Fully backward compatible: existing code without the encoding parameter is completely unchanged

Test plan

• New test file t/30_encoding.t with 15 tests covering:
  • Loading UTF-8 files with encoding => 'UTF-8' and verifying character-level (not byte-level) token content
  • PPI::Document::File encoding passthrough
  • Wide characters in string literals
  • Round-trip: load with encoding, save, verify bytes on disk match original
  • encoding accessor method
  • Backward compatibility without encoding parameter
• Full test suite passes (70 files, 53,106 tests, zero failures)

---

Generated by Kōan /fix

---

Quality Report

Changes: 3 files changed, 206 insertions(+), 4 deletions(-)

Code scan: clean

Tests: skipped

Branch hygiene: clean

Generated by Kōan post-mission quality pipeline