jsharp 0.1.0

J# language: lexer -> parser -> AST -> bytecode -> VM

J# (J-sharp)

J# is a language project with a real execution pipeline:

source (.jsh) -> lexer -> parser -> AST -> bytecode -> VM

J# programs are not executed with Python eval/exec, and the runtime does not transpile J# source to Python/JS for execution.

Install

cd jsharp
python -m pip install -e .

If install is not available in your environment:

python jsh.py run examples/hello.jsh

Quick Start

Hello

python jsh.py run examples/hello.jsh

Web demo

python jsh.py run examples/web.jsh

Then open http://localhost:8080.

Dump and debug

python jsh.py dump examples/hello.jsh
python jsh.py run --debug examples/hello.jsh

CLI

• python jsh.py run <file.jsh>
• python jsh.py run --debug <file.jsh>
• python jsh.py run --native <file.jsh>
• python jsh.py dump <file.jsh>
• python jsh.py build <file.jsh> -o out.jbc

If installed as a package, jsh is available as a console script.

Architecture (text diagram)

.jsh source
   |
   v
 Lexer  -> token stream
   |
   v
 Parser -> AST
   |
   v
 Compiler -> bytecode chunks (per function)
   |
   v
 VM (stack + frames + globals)

Current Feature Set (v0.1)

• Function declarations and function literals
• let, assignment, if/else, while, break, continue, return
• Numbers, strings, bools, none
• Lists ([1,2,3]), indexing (a[i]), indexed assignment (a[i] = x)
• Calls, attribute access, short-circuit && / ||
• Stdlib objects: http, io, fs, json
• Builtins: print, len, div

Competitive Programming

Use the io module for fast buffered input/output.

• examples/cp_sum.jsh
• examples/cp_minmax.jsh
• examples/cp_prefix_sum.jsh
• Full guide: docs/cp-guide.md

Native Runtime Path

• python jsh.py build file.jsh -o file.jbc emits serialized bytecode.
• python jsh.py run --native file.jsh compiles to temp .jbc and executes jsh-native when available.
• If jsh-native is unavailable, CLI prints guidance and falls back to Python VM execution.
• Bytecode format spec: docs/bytecode-spec.md

Roadmap Summary

Near-term goals:

• expand stdlib and diagnostics,
• strengthen Python/native runtime compatibility tests,
• keep web demo smooth in Python VM path,
• improve performance with targeted compiler/VM optimizations.

Detailed plans: docs/roadmap.md.

Project Docs

• LANGUAGE_REFERENCE.md
• docs/getting-started.md
• docs/standard-library.md
• docs/internals.md
• docs/cp-guide.md
• docs/bytecode-spec.md
• docs/roadmap.md

Limitations (current)

• Closures/captures are intentionally disabled in v0.1 function literals.
• Native VM path is focused on CP/runtime core; Python VM remains the primary path for full web demo behavior.