Getting Started

Semantic is a language-independent program representation and programming language. It records the meaning of a program in a canonical SemanticProgram / Universal AST, then projects that program to a source language or a compiler backend.

How Semantic works

source code
    |
    v
language frontend and name/type analysis
    |
    v
SemanticProgram / Universal AST
    |
    +-- readable Semantic (.se)
    +-- compact Semantic transport (.sp)
    +-- compressed transport (.spz)
    +-- JSON interchange and diagnostics
    |
    v
target emitter, native compiler, or explicit external toolchain

The canonical program contains nodes, scopes, bindings, types, operations, effects, relations and source provenance. A backend must either preserve the requested semantics directly, lower them through a documented rule, or reject the construct. It must not silently replace unknown semantics with a guessed value.

Semantic formats

• .se is the readable Semantic language. It is intended for editing and review.
• .sp is the compact textual Semantic transport format.
• .spz is the compressed transport form for storage and transfer.
• .semantic.json is the explicit interchange and debugging format.

These formats describe the same SemanticProgram. Conversion is valid only when the parser can reconstruct the same canonical semantic graph; source text embedded as provenance is not required for later emission.

Recommended Go module

For Go applications, use the public Code Transpiler module as a normal dependency. The module path declared by the project is:

github.com/tarekwasfy01/Code-Transpiler

Install the current published version from your Go module:

go get github.com/tarekwasfy01/Code-Transpiler@latest

The package exposes the source-to-source API, SemanticProgram export and language registry. A minimal translation looks like this:

package main

import (
    "fmt"
    "log"

    codetranspiler "github.com/tarekwasfy01/Code-Transpiler"
)

func main() {
    out, err := codetranspiler.Transpile("python", "go", "print(2 + 3)")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(out)
}

Use go test ./... in a checkout to verify the package and its dependencies. The module is the bootstrap/reference implementation; the Semantic language and its separate project are documented independently.

Export a SemanticProgram

The CLI can export source into any Semantic transport:

CodeTranspiler.exe semantic-export -source go input.go -format se -o input.se
CodeTranspiler.exe semantic-export -source go input.go -format sp -o input.sp
CodeTranspiler.exe semantic-export -source go input.go -format spz -o input.spz

The short command name sp is an alias for the same CLI:

sp semantic-export -source go input.go -format se -o input.se

Read, convert and validate Semantic files

sp semantic-transpile -target rust program.se -o output.rs
sp semantic-convert program.semantic.json -o program.se
sp semantic-format program.se --readable -o readable.se
sp semantic-format program.se --compact -o compact.se
sp semantic-validate program.spz
sp semantic-info program.se

Every command also accepts CodeTranspiler.exe instead of sp. Formatting changes whitespace representation; it must not change the canonical SemanticProgram.

Source-to-source translation

CodeTranspiler.exe transpile -source go -target rust input.go -o output.rs
CodeTranspiler.exe transpile -source python -target cpp input.py -o output.cpp
CodeTranspiler.exe transpile -source c -target go input.c -o output.go

The registered language matrix covers R, Go, Rust, C++, C, Python, Zig, Julia, Nim, C#, Java, Kotlin and Swift. Route registration means that a common supported subset can be parsed and emitted; it does not claim that every language-specific feature is equivalent on every route. Unsupported or non-provable constructs must be reported explicitly.

Compilation and execution

Semantic compilation first lowers the canonical program to a target representation. The internal native and LLVM routes are separate backends. External compilers or runtimes are used only by explicit compile, run or validation commands; ordinary GUI transpilation does not start external processes.

CodeTranspiler.exe compile input.se -o output.exe
CodeTranspiler.exe compile-llvm input.se -o output.exe
CodeTranspiler.exe run input.R

Compilation success is distinct from semantic coverage and runtime success. A successful parse or generated intermediate file is not by itself proof that all source behavior is preserved.

Modules

Imports are resolved through the module store and represented as Semantic module identities. A module can be reused, linked or embedded according to the selected command. Licenses and provenance remain separate artifacts. If a dependency cannot be resolved or its semantics cannot be proved, the operation reports that condition instead of inventing an implementation.

Install the GUI

sudo snap install semantic-programming-language --channel=stable
snap run semantic-programming-language

The stable Snap was tested on a second Ubuntu machine after installation. Windows users can use the published Windows executable or build the Go package from source.

What is and is not guaranteed

• SemanticProgram is the canonical meaning-bearing representation.
• JSON, SP, SPZ and SE are interchange views; each conversion must preserve the canonical graph.
• Common-subset routes are supported; language-specific gaps remain explicit.
• Native executable output requires the selected backend to have a legal representation for every required fact.
• External toolchains are not silently used as a fallback for normal GUI transpilation.

Next: Architecture ->

Start with SWC

For the current native Windows track, begin with swc version, swc help, and a small .se fixture. Then inspect the generated artifact and its runtime result. For modules, browse the package registry and read the module system guide.