peruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7c3d9d50d299d8c07b711e9dc07d689676750015c59489fe118916956d39dae
+  data.tar.gz: 9593822800bebfab84aa02c90e1d7892c3f025e4c782ed2c1f860ddb55aed4fa
+SHA512:
+  metadata.gz: b316119852f0a061ac46b578952b3c10c5cd51de7310ed1a68e8528582f73bc5b034ba5d9eb113e0f6eff7093b8c3416875f8fabba30704a3c0102bc7b18e7a1
+  data.tar.gz: 8daeab8accd567dde3db0fddbfdb594657c184f09e34f06fdf772768f86e6f258376cdd978f9ec84dbc44385e8b218d4e92bd7a67bed9d34cadb4c6289be86ec

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  Exclude:
+    - "lib/peruby/parser/grammar.rb"
+    - "tmp/**/*"
+    - "vendor/**/*"
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/AbcSize:
+  Max: 30
+  Exclude:
+    - "test/**/*"
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ModuleLength:
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+Lint/MissingSuper:
+  Exclude:
+    - "lib/peruby/op/**/*.rb"

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-08-30
+
+- Implement the L4 interpreter pipeline, value model, contexts, and aliases.
+- Add regexes, references, file I/O, OO dispatch, modules, phases, and selected
+  core modules.
+- Add Perl-compatible CLI processing, diagnostics, oracle tests, compatibility
+  reports, and benchmarks.
+- Add lambda-composed execution with a tree-interpreter fallback.
+- Complete process, signal, diamond I/O, packing, module-loading, and overload behavior.
+- Match the system Perl on all 615 scripts in the oracle corpus.
+
+Peruby follows semantic versioning. Until 1.0, minor releases may expand or
+correct Perl semantics; patch releases remain backward-compatible bug fixes.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,51 @@
+# Peruby
+
+Peruby is a Perl 5 interpreter written in pure Ruby. It runs a practical L4
+subset: procedural Perl, regexes, references, file I/O, objects, `use` /
+`require`, compile phases, and selected core modules. It does not invoke a Perl
+binary at runtime.
+
+## Installation
+
+Peruby requires Ruby 3.2 or newer.
+
+```sh
+gem install peruby
+peruby --version
+```
+
+From a checkout, use `bundle exec bin/peruby`.
+
+## Usage
+
+```sh
+peruby script.pl arg1 arg2
+peruby -e 'print "hello\n";'
+peruby -n -l -a -F: -e 'print $F[0];' data.txt
+peruby -MList::Util=sum -e 'print sum(1, 2, 3);'
+```
+
+Supported command switches include `-e`, `-E`, `-c`, `-I`, `-n`, `-p`, `-l`,
+`-a`, `-F`, `-0`, `-M`, `-m`, and `-s`. Debugging switches include
+`--dump-tokens`, `--dump-ast`, `--dump-ops`, `--trace-ops`, and
+`--interpreter=tree`. Set `PERUBY_DEBUG=lexer,parser` for both front-end traces.
+
+The exact measured scope is in [the compatibility report](doc/COMPAT.md), and
+known differences are listed in [INCOMPATIBILITIES.md](doc/INCOMPATIBILITIES.md).
+Pure-Perl CPAN compatibility is ongoing L5 work rather than a current promise.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake oracle
+bundle exec rake bench
+```
+
+See [CONTRIBUTING.md](doc/CONTRIBUTING.md), [DESIGN.md](doc/DESIGN.md), and the
+[roadmap](doc/ROADMAP.md).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'open3'
+require 'rake/testtask'
+
+GRAMMAR_Y = 'lib/peruby/parser/grammar.y'
+GRAMMAR_RB = 'lib/peruby/parser/grammar.rb'
+GRAMMAR_OUTPUT = 'tmp/grammar.output'
+
+desc 'Generate the parser'
+task :parser do
+  mkdir_p 'tmp'
+  sh 'racc', '-F', '-o', GRAMMAR_RB, '-v', '-O', GRAMMAR_OUTPUT, GRAMMAR_Y
+end
+
+namespace :grammar do
+  desc 'Check that the generated grammar has no undocumented conflicts'
+  task check: :parser do
+    ruby 'tools/conflict_check.rb', GRAMMAR_OUTPUT
+  end
+end
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << 'test'
+  task.pattern = 'test/**/*_test.rb'
+end
+
+desc 'Run Perl TAP tests with peruby'
+task :t do
+  files = Dir['t/*.t']
+  tests = files.sum do |file|
+    stdout, stderr, status = Open3.capture3('bin/peruby', '-I', 't/lib', file)
+    print stdout
+    warn stderr unless stderr.empty?
+    planned = stdout.lines.filter_map { |line| line[/^1\.\.(\d+)/, 1]&.to_i }.last
+    passed = stdout.lines.count { |line| line.match?(/^ok \d+/) }
+    failed = stdout.lines.any? { |line| line.match?(/^not ok \d+/) }
+    raise "#{file}: invalid or failing TAP" unless status.success? && planned == passed && !failed
+
+    passed
+  end
+  puts "#{files.length} file(s), #{tests} test(s), all successful"
+end
+
+desc 'Compare oracle scripts with perl'
+task :oracle do
+  ruby 'tools/oracle_runner.rb'
+end
+
+namespace :oracle do
+  desc 'Record oracle results from perl'
+  task :record do
+    ruby 'tools/oracle_runner.rb', '--record'
+  end
+end
+
+namespace :compat do
+  desc 'Report compatibility for the migrated perl op tests'
+  task :perl do
+    ruby 'tools/compat_report.rb'
+  end
+
+  desc 'Report compatibility for unpacked CPAN distributions'
+  task :cpan do
+    ruby 'tools/cpan_report.rb', *ENV.fetch('DISTS', '').split
+  end
+end
+
+desc 'Run RuboCop'
+task :rubocop do
+  sh 'rubocop', '--cache', 'false'
+end
+
+desc 'Compare peruby and perl benchmark timings'
+task :bench do
+  ruby 'tools/benchmark.rb'
+end
+
+namespace :bench do
+  desc 'Measure compiled execution without process startup'
+  task :execution do
+    ruby 'tools/execution_benchmark.rb'
+  end
+end
+
+desc 'Count interpreter method calls for one benchmark'
+task :profile do
+  ruby 'tools/profile.rb', ENV.fetch('SCRIPT', 'bench/fib.pl')
+end
+
+task default: %i[parser test grammar:check]

data/bin/peruby

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'peruby'
+require 'peruby/cli'
+
+exit Peruby::CLI.run(ARGV)

data/doc/COMPAT.md

@@ -0,0 +1,54 @@
+# Compatibility report
+
+Measured on 2026-08-31 by comparing each output line with the system Perl.
+
+## Oracle corpus
+
+All 617 scripts pass against the system Perl (100%). The corpus covers context,
+regexes, formatting, sorting, references, objects, I/O, numeric/string behavior,
+and dynamic scoping.
+
+## Migrated perl `t/op` subsets
+
+Run `bundle exec rake compat:perl` to reproduce this table.
+
+| file | passed | cases | rate |
+|---|---:|---:|---:|
+| arith.pl | 4 | 4 | 100.0% |
+| cond.pl | 4 | 4 | 100.0% |
+| context.pl | 4 | 4 | 100.0% |
+| local.pl | 4 | 4 | 100.0% |
+| ref.pl | 4 | 4 | 100.0% |
+| sort.pl | 4 | 4 | 100.0% |
+| substr.pl | 4 | 4 | 100.0% |
+
+These are small, independently written adaptations of the corresponding Perl
+core test themes; the Perl source distribution itself is not vendored.
+All migrated operator cases currently match the system Perl.
+
+## CPAN suites
+
+The official release archives were unpacked outside the repository and every
+top-level `t/*.t` file was run with its distribution `lib/` directory on
+peruby's include path. A file passes only when it exits successfully and emits
+a complete, nonempty TAP plan with no failing result (TODO failures are allowed).
+Skip-all files are reported separately and do not count as passes.
+
+| distribution | passed | skipped | files | rate |
+|---|---:|---:|---:|---:|
+| Text-CSV-2.06 (`Text::CSV_PP`) | 0 | 0 | 40 | 0.0% |
+| URI-5.36 (`URI::Escape`) | 0 | 0 | 64 | 0.0% |
+| MIME-Base64-3.16 (`MIME::Base64`) | 0 | 0 | 6 | 0.0% |
+| Time-Local-1.35 (`Time::Local`) | 0 | 0 | 2 | 0.0% |
+| Try-Tiny-0.32 (`Try::Tiny`) | 0 | 0 | 11 | 0.0% |
+
+Run the same measurement after unpacking the releases:
+
+```sh
+DISTS="/path/Text-CSV-2.06 /path/URI-5.36 /path/MIME-Base64-3.16 \
+  /path/Time-Local-1.35 /path/Try-Tiny-0.32" bundle exec rake compat:cpan
+```
+
+This is an L5 baseline, not a claim of CPAN compatibility. Most files stop on
+unsupported prototype/import syntax and module APIs before producing passing
+TAP. Release archives are not vendored.

data/doc/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Use Ruby 3.2 or newer and install dependencies with `bundle install`.
+
+Before submitting a change, run:
+
+```sh
+bundle exec rake test grammar:check
+bundle exec rubocop --cache false
+bundle exec rake oracle
+```
+
+When changing `lib/peruby/parser/grammar.y`, regenerate and commit
+`grammar.rb` in the same change. New Perl behavior needs a focused unit or
+integration test and, when output compatibility matters, an oracle script with
+its real-Perl expectation. Document deliberate incompatibilities in
+`doc/INCOMPATIBILITIES.md`.
+
+Keep Ops small and single-purpose. Preserve scalar/list/void context, aliasing,
+`undef`, and exception restoration paths in tests. Do not add a dependency
+when Ruby's standard library covers the behavior.

data/doc/DESIGN.md

@@ -0,0 +1,25 @@
+# Design overview
+
+Peruby is a pure-Ruby tree interpreter with an optional lambda-composed fast
+path. Source passes through these stages:
+
+1. the stateful lexer resolves Perl's quote, slash, and brace ambiguities;
+2. the generated Racc parser creates immutable nodes with file/line metadata;
+3. the compiler produces small `Peruby::Op` objects;
+4. hot Ops compose into Ruby lambdas, while unsupported shapes call the same
+   tree Ops; `--interpreter=tree` disables composition;
+5. `Peruby::Runtime` owns packages, lexicals, I/O, regex state, phases, modules,
+   and object destruction.
+
+Scalars are mutable cells so aliases in `@_`, `foreach`, and `map` share the
+same storage. Arrays and hashes contain cells. Every operation receives an
+explicit scalar/list/void context.
+
+`CompileUnit` makes nested `require`, string `eval`, and compile phases
+reentrant. User `@INC` paths are searched before internal Ruby-backed modules.
+The symbol table and lexical environment carry generation counters so cached
+lookups are invalidated by declarations and subroutine redefinition.
+
+The generated parser is committed beside `grammar.y`. `rake grammar:check`
+enforces zero undocumented conflicts. Compatibility is measured against the
+system Perl rather than inferred from unit tests alone.

data/doc/INCOMPATIBILITIES.md

@@ -0,0 +1,30 @@
+# Known incompatibilities
+
+This list reflects measurements made on 2026-08-31. See [COMPAT.md](COMPAT.md)
+for the reproducible reports.
+
+| Area | Current behavior | Workaround or status |
+|---|---|---|
+| `DESTROY` timing | Runs at shutdown; `--refcount` provides an eager approximation | Do not depend on exact Perl reference-count timing |
+| Hash key order | Preserves insertion order instead of Perl's randomized order | Do not depend on iteration order |
+| XS modules | Native extensions cannot load | Use a pure-Ruby internal replacement where provided |
+| `format` / `write` | Not implemented | None |
+| Taint mode | `-T` is rejected | None |
+| Source filters | Not implemented | None |
+| Regex `(?{ })` and `(??{ })` | Rejected at compilation | None |
+| ithreads | Not implemented | None |
+| Indirect object syntax | `new Foo(...)` is not parsed | Use `Foo->new(...)` |
+| Byte/character duality | Ruby encoding is used; Perl's UTF8 flag is not reproduced | Keep inputs in one explicit encoding |
+| Integer overflow | Uses Ruby integers rather than Perl IV overflow | Check numeric bounds explicitly |
+| Float stringification | Close to `%.15g`; extreme values can differ | Format explicitly with `sprintf` |
+| `local` references | Restoration works, but references taken before localization can differ | Avoid retaining localized slots |
+| Prototypes | `*`, `+`, and `_` prototype behavior is incomplete | Use explicit parentheses |
+| `goto LABEL` | Not implemented; `goto &sub` is supported | Restructure label jumps |
+| `dump`, `study`, `reset` | Not implemented | Remove obsolete calls |
+| `%SIG` | Uses Ruby `Signal.trap`; signals unavailable on the host remain unsupported | Restrict handlers to portable signal names |
+| Runtime error locations | Perl-shaped `at FILE line N.` output is emitted, but runtime line tracking currently reports line 1 | Use stack-free messages only for compatibility checks |
+| CPAN ecosystem | The five P14-03 upstream suites currently pass 0/123 files | L5 work; core-module substitutes remain available |
+
+All 617 scripts in the current oracle corpus match Perl. The remaining rows are
+outside that measured corpus or are architectural differences that cannot be
+removed by output-level compatibility tests.

data/doc/PERF.md

@@ -0,0 +1,51 @@
+# Performance
+
+Measurements were taken on 2026-08-30 with Ruby 4.0.0 and the system Perl.
+`RUNS=5 bundle exec rake bench` reports the median wall time including process
+startup. Absolute values vary by host; the before/after comparison used the
+same machine and scripts.
+
+| benchmark | P14 baseline (s) | compiled (s) | improvement |
+|---|---:|---:|---:|
+| fib.pl | 0.6183 | 0.4915 | 20.5% |
+| loop.pl | 1.3195 | 0.4644 | 64.8% |
+| method.pl | 1.0338 | 0.6404 | 38.1% |
+| regexp.pl | 1.2591 | 0.4812 | 61.8% |
+| total | 4.2307 | 2.0775 | 50.9% (2.04x) |
+
+Process startup puts a fixed floor under the command comparison. The P15-05
+acceptance measurement compiles once and times execution with
+`bundle exec rake bench:execution`. Set `INTERPRETER=tree` to measure the
+fallback with the same harness:
+
+| benchmark | P14 tree (s) | compiled (s) | speedup |
+|---|---:|---:|---:|
+| fib.pl | 0.3672 | 0.2766 | 1.33x |
+| loop.pl | 0.5486 | 0.2840 | 1.93x |
+| method.pl | 0.6302 | 0.4531 | 1.39x |
+| regexp.pl | 1.5173 | 0.2987 | 5.08x |
+| total | 3.0633 | 1.3124 | 2.33x |
+
+The loop target of at least 30%, the fib target of at least 20%, and the 2x
+combined execution target are met. Use `INTERPRETER=tree` for
+`bench:execution`, or `PERUBY_ARGS=--interpreter=tree` for the process-level
+benchmark, to measure the fallback tree walker.
+
+## Hotspots and changes
+
+Run `SCRIPT=bench/fib.pl bundle exec rake profile` for a stdlib-only method-call
+profile. `stackprof` and `vernier` are deliberately not development dependencies;
+TracePoint keeps the profile reproducible with the supported Ruby alone.
+
+The measured hot paths led to these changes:
+
+- compound assignment applies coercion directly instead of allocating three temporary Ops;
+- lexical and code-glob lookup use generation-based caches with invalidation on declarations and redefinition;
+- simple final `return` avoids a throw/catch round trip;
+- static regexes and simple interpolation templates compile once;
+- hot variable, argument, expression, branch, loop, method, and regexp paths compose into lambdas, with
+  `--interpreter=tree` as fallback.
+
+Regex compilation was already cached by pattern and modifiers. Method resolution
+now has the same symbol-generation fast path. Further work should target call
+frame allocation and method arguments; those dominate the remaining gap.

data/doc/ROADMAP.md

@@ -0,0 +1,18 @@
+# Roadmap
+
+The 0.1 line targets L4: modules and the selected core library on top of the
+implemented procedural, regex, reference, I/O, and OO layers.
+
+L5 work is driven by measured CPAN failures:
+
+- complete prototype and import syntax used by upstream test suites;
+- implement the remaining `Test::Builder` surface and TAP directives;
+- extend operator overloading beyond the L4 set and add tied variables;
+- support `Text::CSV_PP`, `URI::Escape`, `MIME::Base64` pure-Perl paths,
+  `Time::Local`, and `Try::Tiny` one suite at a time;
+- improve runtime line tracking and Perl's byte/UTF8 duality;
+- raise the official CPAN result from the current 0/123 files while keeping the
+  617-script oracle corpus at 100%.
+
+XS, ithreads, taint mode, source filters, and regex code execution remain out
+of scope.

data/examples/hello.pl

@@ -0,0 +1 @@
+print "Hello from peruby\n";

data/examples/json.pl

@@ -0,0 +1,2 @@
+use JSON::PP qw(encode_json);
+print encode_json({language => "Perl", numbers => [1, 2, 3]}), "\n";

data/examples/object.pl

@@ -0,0 +1,5 @@
+package Greeter;
+sub new { my ($class, $name) = @_; return bless {name => $name}, $class; }
+sub hello { my ($self) = @_; print "Hello, ", $self->{name}, "\n"; }
+package main;
+Greeter->new("Ruby")->hello();

data/examples/word_count.pl

@@ -0,0 +1,6 @@
+my %count;
+for my $word (split /\s+/, "the quick brown fox the fox") {
+  my $current = $count{$word};
+  $count{$word} = $current + 1;
+}
+print "fox=", $count{fox}, "\n";