Phasor Language

A statically typed, compiled programming language with a fast bytecode virtual machine.

Phasor does not have a traditional garbage collector, the entire toolchain makes use of my unified safe type system, which provides C++ RAII support to the runtime.

See Upcoming for more info on memory management.

See Building for info on building from source.

Phasor is stable, but still in beta, as I wish for a smooth, stable experience for the final language. The existing implementation still needs some work. The ABI is not stable, but conforms to semver most of the time (thus why this is 3.X.X and still in beta.)

You can check out the website as well.

Download Phasor Nightly

$ nix run github:DanielLMcGuire/Phasor -- -- <options>
$ phasor <options>

Language Features

• Dynamic typing with integers, floats (IEEE 754, double-percision), strings, booleans, and null. var x = 21; // int
• Type annotations (only in function declarations) fn func(input: string) -> void { ... }
• Control flow: if/else, while, for, switch/case, break/continue
• Standard library using(featureName: string)
• Plugin/FFI API PhasorFFI.h
• Runtime API PhasorRT.h
• Minimal Windows and POSIX API Bindings
• Supports most C format specifiers

// Print (keyword)
print "Hello World!\n"; // Print to console
// Or via std
using("stdio"); // Import io for puts
puts("Hello World!"); // Print string with newline

using("stdsys", "stdio"); // Import sys, io
// Variables
var code = 15; // int
var fmt = "Code = %d"; // string
// Formatting
printf("Exiting with code %d", code);
putf("%d", code);
var fmtStr = c_fmt(fmt, code);
// Exit with a code other than 0
shutdown(code); // from stdsys

Upcoming

Important

Some may appear to work before actual implementation

The existance of a keyword/token type does not imply there is planned support for said feature

• Structs with C style static field access struct.member = 14;
• Arrays with C syntax var arrayName[arraySize];
• stdmem stdlib module with free() (already in master!) using("stdmem"); free("variableName");
• stdrand xorshift+ psuedo-random number generator (already in master!)
• AppleScript bindings (already in master!)

Note

free() is not required to be called (you should consider it in heavy scripts/programs), the C++ resources are freed internally by the VM at shutdown.

free() behavior can be done in ANY release of Phasor (or pulsar) via value = null

You cannot get a use after free, as in the runtime its more like a use-after-reset.

---

Quick Start

# Compile and run a program
$ phasor input.phs

# Repl
$ phasor

# Compile to bytecode
$ phasorcompiler input.phs (-o, --output output.phsb)

# Run bytecode
$ phasorvm output.phsb

# Run a script raw
$ echo "print \"Hello World\!\\n\"" | phasor
Hello World!
$

Example Program

using("stdio", "stdtype", "stdmem");

puts("Enter a number:");
var input = gets();
var num1 = to_int(input);
var num2 = 25;
putf("%d + %d = %d\n", num, num2, num1 + num2);

---

Documentation

Note

Documentation may be partially wrong, stdlib might have added functions or changed features.

This will change once I have more time for this project

Online docs are always up to date with master (as much as I can at least), offline (installed) docs are always up to date with that version.

• Language Guide - Complete syntax and language features
• VM Internals - Virtual machine architecture details
• Adding Opcodes - Contributor guide for VM extensions
• Doxygen - Documentation and call graphs generated from source code
• Manuals/Man Pages: https://phasor-docs.pages.dev/man?f=[filename], e.g. /man?f=Phasor.3, /man?f=phasorvm.1, /man?f=PHIR.5, etc.

Contributing

1. Read the VM Internals and Adding Opcodes guides
2. Follow the existing code style (see .clang-format)
3. Add tests for new features
4. Update documentation as needed

Applications

• Phasor

  • phasor - Combines the Scripting Runtime, VM Runtime, and REPL, adds pipe support, and supports shabangs
  • phasor-lsp - JSON-RPC 2.0 LSP Protocol Handler for the Phasor Language
  • Bytecode Compiler (phasorcompiler) - Script to bytecode compiler
  • Native Compiler (phasornative) - Script to C++ transpiler
  • VM Runtime (phasorvm) - Bytecode executor
  • Disassembler (phasordecomp)
  • Assembler (phasorasm)

• Pulsar

  • pulsar - Scripting runtime and REPL
  • Bytecode Compiler (pulsarcompiler) - Script to bytecode compiler
  • Uses the Phasor VM Runtime for bytecode (phasorvm)

---

Overview

This repo contains:

• Frontend:

  • Phasor Language (Specifications, C++)
  • Pulsar Language (C++)
  • Phasor Runtime / VM (ISA Specs, C/C++/Assembly)
  • Phasor Standard Library (Specifications, C/C++)

• Backend:

  • Phasor Compiler Infrastructure (C++)
  • FFI API (C)
  • Runtime API (C)

• Extensions:

  • Phasor & Phasor IR TextMate Grammar

  • Phasor Visual Studio Code Extension (Typescript)

  • Python Module src/Extensions/py/phasor

    from phasor import Bytecode, Value, OpCode, Runtime
    help(phasor)
    
    bc = Bytecode()
    bc.emit(OpCode.PUSH_CONST, bc.add_constant(Value.from_string("Hello, World!\n")))
    bc.emit(OpCode.PRINT)
    bc.emit(OpCode.HALT)
    bc.save("hello_world.phsb")
    Runtime.run(bc) # wraps phasorrt lib

  • PowerShell Module (windows only, phasorrt.dll bindings) src/Extensions/powershell/Phasor

    Import-Module .\src\Extensions\powershell\Phasor\Phasor.psd1
    Get-Help Phasor
    # Get-Help <cmdlet>
    
    # state is always optional (-State is optional)
    # anything not using state will create thier own
    Start-PhasorScript -ScriptPath .\hello.phs
    Start-PulsarScript -ScriptPath .\hello.pul
    
    $vm = New-PhasorState
    # stdlib is already registered if not using your own state
    Register-PhasorStdlib -State $vm 
    
    Start-PhasorEval -State $vm -Script 'var x = 42; var y = 53;'
    # x and y still in scope
    Start-PhasorEval -State $vm -Script 'print(x + y);' 
    
    # all states are cleared at powershell shutdown, but to clear them early:
    Remove-PhasorState $vm
    
    $bytecode = Build-PhasorScript -Script 'print("hi\n");'
    # can also optionally accept state
    Invoke-PhasorBytecode -Bytecode $bytecode

  • phasor-web REST API src/Extensions/web (Typescript, Node 22)

    $ curl -d 'using("stdio"); puts("Hi!");' -H "x-api-key: API_KEY" http://0.0.0.0:62811/run
    {stdout: "Hi!\n", stderr: "", exitCode = 0}

---

Building

_{Using Arch BTW? Just run makepkg -si, or get phasor-git on the AUR}

Note

If you have forked and do not plan to contribute back, you should modify cmake/Version.cmake to match your forks URL!

Prerequisites

• Required:
  • CMake 3.21+
  • Supported CC (23) compiler and CXX (23) compiler (MSVC latest, GCC 14, Clang (LLVM Latest) )
  • Ninja
• Optional:
  • Python (for the python API)
  • PowerShell (for the powershell module)
  • Node.js (for the web server, and building the vscode extension)
  • Docker (for the docs (man to pdf), optional)

Build Steps

See the Building Phasor wiki.

Plugin locations

(Like win32 api, posix) are available in different locations based on your OS:

• Unix - /usr/lib/phasor/plugins/
• macOS - /library/Application Support/org.Phasor.Phasor/plugins/
• Windows - C:\Program Files\Phasor Programming Language\bin\plugins\

---

Phasor - Fast, flexible programming/scripting with near native VM performance.

GitLab Mirror

• Phasor Language / ISA / VM / Toolchain / Standard Library | Apache 2.0
• Phasor Shell | MIT License
• Phasor coreutils implementation | GNU General Public License 3.0

Regarding any age verification laws, I will not entertain rules set in place by people who do not understand the core aspect of OSS.

Mentions of 'coreutils', the Free Software Foundation, Inc., 'Java™', Oracle® Corporation, '.NET™', Microsoft® Corporation, Google® LLC, or other third-party companies, products, or trademarks do not imply any affiliation, endorsement, or sponsorship by those third parties, or thier affiliates, unless explicitly stated otherwise.

Phasor Toolchain is licensed for use under the Apache 2.0 License.

Phasor Runtime (phasorrt.dll, libphasorrt.so, libphasorrt.dylib, PhasorRT.h, etc) is licensed for use under the Apache 2.0 with LLVM-Exceptions License.

Phasor and the "sinewave Phasor" logo are trademarks of Daniel McGuire.