Add comprehensive interpreter mode documentation#192
Merged
Conversation
Relocated test files from src/main/java to src/test/java to separate test code from production code: - ClosureTest.java - EvalStringTest.java - ForLoopBenchmark.java - ForLoopTest.java - InterpreterTest.java These are standalone test harnesses with main() methods (not JUnit tests), but belong in the test source tree rather than main source tree. Updated SKILL.md documentation to reflect new file locations and recommended Gradle execution method (which handles classpath automatically). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace multiple instanceof checks with single getList() call. RuntimeBase.getList() already handles all cases: - RuntimeList returns itself - RuntimeScalar wraps in RuntimeList - RuntimeArray converts to RuntimeList - Other types use their getList() implementation This eliminates redundant type checking and relies on the existing polymorphic behavior in the runtime type hierarchy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Updated architecture documentation to reflect the dual execution modes: - Added Compiler Mode vs Interpreter Mode comparison with performance metrics - Added interpreter/ package to project structure diagram - Added dev/interpreter/ documentation directory to structure - Added src/test/java/org/perlonjava/interpreter/ test harnesses - New "Interpreter" section describing core components: - BytecodeInterpreter (register-based VM with tableswitch optimization) - BytecodeCompiler (AST to bytecode with register allocation) - InterpretedCode (bytecode container with disassembler) - Opcodes (instruction set organized into categories) - SlowOpcodeHandler (rare operations via SLOW_OP gateway) - VariableCaptureAnalyzer (variable sharing analysis) - Key features: register-based architecture, runtime API sharing, closures, bidirectional calling, variable sharing via persistent storage - Performance: 47M ops/sec (1.75x slower than compiler) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Corrected: - PerlLanguageProviderTest.java → PerlScriptExecutionTest.java (actual filename) - Alphabetized interpreter test files to match directory listing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Removed src/test/java/org/perlonjava/interpreter/ containing: - ClosureTest.java - EvalStringTest.java - ForLoopBenchmark.java - ForLoopTest.java - InterpreterTest.java These Java test harnesses were duplicates/redundant. The interpreter is tested using Perl test files in dev/interpreter/tests/ which are more appropriate for testing Perl semantics. Updated documentation: - SKILL.md: Removed references to Java test harnesses, updated benchmark instructions to use Perl benchmark script (for_loop_benchmark.pl) - architecture.md: Removed src/test/java/org/perlonjava/interpreter/ from project structure diagram Testing is now done exclusively through: - Perl test files (*.t) in dev/interpreter/tests/ - Perl benchmark scripts (*.pl) in dev/interpreter/tests/ - Standard unit tests via make test-unit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added new "Execution Mode Options" section documenting the --interpreter flag: - Explains interpreter mode vs compiler mode (default) - Performance characteristics: ~47M ops/sec vs ~82M ops/sec - Use cases: faster startup, lower memory, ideal for short-lived scripts - Notes that both modes share 100% of runtime APIs Updated --disassemble option: - Shows how to use with both compiler and interpreter modes - Explains that bytecode format differs between modes Added examples in "Combining Options" section: - Quick script execution with interpreter mode - Debugging interpreter bytecode with --interpreter --disassemble Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Changed format from: - **vX.X.X**: Title To: ## vX.X.X: Title This uses proper markdown header syntax (##) instead of bold list items, making the document structure more consistent and easier to navigate. No text content was changed, only formatting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added new section documenting the interpreter/ subdirectory: - Comprehensive documentation files (SKILL.md, STATUS.md, TESTING.md, BYTECODE_DOCUMENTATION.md) - Architecture design documents in architecture/ subdirectory - Test files for interpreter-specific features in tests/ subdirectory - Key features: register-based bytecode interpreter with tableswitch optimization - Performance: ~47M ops/sec (1.75x slower than compiler, within 2-5x target) - Variable sharing, closures, bidirectional calling, and context detection Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Simplified documentation for better readability: dev/README.md: - Condensed interpreter section to essential information - Removed detailed feature list (available in dedicated docs) docs/about/roadmap.md: - Removed v5.42.3 upcoming milestone (now in changelog) - Removed Work in Progress section (now in changelog) docs/reference/cli-options.md: - Reordered compiler mode before interpreter mode for clarity - Simplified interpreter mode description - Removed redundant "Both modes share..." statement - Kept essential performance and use case information Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation updates for the interpreter mode feature, including architecture documentation, CLI options, changelog updates, and developer guides.
Changes
Documentation Files
Architecture & Design:
docs/reference/architecture.mdwith interpreter module sectionCLI Options:
docs/reference/cli-options.mdsection for--interpreterflag--disassembleoption to show both modesChangelog:
docs/about/changelog.mdversion headers to use proper markdown (##)Developer Resources:
dev/README.mdwith interpreter/ directory documentationdocs/about/roadmap.mdby removing duplicated contentInterpreter Documentation:
dev/interpreter/SKILL.mdwith variable sharing implementationCode Changes
Cleanup:
src/test/java/org/perlonjava/interpreter/dev/interpreter/tests/Simplification:
BytecodeInterpreter.javaRETURN opcode handlinggetList()instead of multiple instanceof checksTesting
make test-unit)make build)./jperl dev/interpreter/tests/*.tDocumentation Coverage
✅ Architecture documentation (docs/reference/architecture.md)
✅ CLI options reference (docs/reference/cli-options.md)
✅ Changelog formatting (docs/about/changelog.md)
✅ Developer guide (dev/README.md, dev/interpreter/SKILL.md)
✅ Removed duplicate test code
Performance
Key Features Documented
Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com