Metadata-Version: 2.4
Name: jsharp
Version: 0.1.0
Summary: J# language: lexer -> parser -> AST -> bytecode -> VM
Author: J# Contributors
License: MIT
Project-URL: Homepage, https://github.com/jsharp-lang/jsharp
Project-URL: Repository, https://github.com/jsharp-lang/jsharp
Project-URL: Issues, https://github.com/jsharp-lang/jsharp/issues
Keywords: programming-language,bytecode,vm,compiler,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# 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

```bash
cd jsharp
python -m pip install -e .
```

If install is not available in your environment:

```bash
python jsh.py run examples/hello.jsh
```

## Quick Start

### Hello

```bash
python jsh.py run examples/hello.jsh
```

### Web demo

```bash
python jsh.py run examples/web.jsh
```

Then open [http://localhost:8080](http://localhost:8080).

### Dump and debug

```bash
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)

```text
.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.
