gofra 0.0.1__tar.gz

gofra-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Kirill Zhosul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gofra-0.0.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.3
+Name: gofra
+Version: 0.0.1
+Summary: A Stack-based compiled programming language
+License: MIT
+Author: Kirill Zhosul
+Author-email: kirillzhosul@yandex.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+# Gofra Programming Language
+
+Gofra is an native stack based programming language.
+
+Language follows reverse polish notation (examples can be found below) \
+**Language is in development stage and mostly made for fun and research so don't expect a lot and try to test or implement your own idea**
+
+## Table of content
+
+- [Hello world example](#hello-world-example)
+- [Compatibility](#compatibility)
+- [Features](#features)
+- [Installation](#installation)
+- [Examples](#examples)
+- [Language overview](#language-overview)
+- [Command Line Interface](#command-line-interface-cli)
+- [Milestones and planned features](#milestones-and-planned-features)
+
+---
+
+### Hello world example
+###### (For now, language is mostly bare-metal so in this example there is raw `sc_write` syscall and file descriptor usage)
+```
+include "std.gof"
+func void main
+    FD_STD_OUT "Hello, World!\n" sc_write drop
+end
+```
+
+
+### Compatibility
+Language currently have codegenS only for:
+- AARCH64 MacOS (Darwin)
+- x86_64 Linux
+
+### Features
+- Native (codegen assembly)
+- Type safety (Validates stack usage and tries to infer types so you wont mess up)
+- Mostly self explanation errors (Tries to help you and correct your intentions)
+- Optimizer (DCE, CF, Helps optimize resulting assembly for codegen so your default usage will not be overwhelmed by language)
+- FFI with `global`/`extern` function modifers (there is CLI flags to emit an library/object file)
+- Simple CLI for working with language (simple toolkit)
+
+
+### Installation
+- Clone this repo
+- Install latest Python version
+- Navigate to root directory 
+- Run `python -m gofra --help` (`python` depends on your installation of Python)
+
+### Examples
+Examples may be found inside `./examples` directory
+
+### Language overview
+As language is stack based so your basic action is to *put something on a stack*, like `2 2` will push 2 and then another 2 on stack so stack underneath will look like [2, 2]
+
+If you want to operate on that numbers you may do something like `3 2 +` which is same as `3 + 2` in other language or default math. Underneath this will mean: push 3 on stack -> push 2 on stack -> take 2 elements from stack -> sum them -> push result back. Stack after that will become [5]
+
+Conditionals is also a bit controversial:
+```
+1 2 == if
+    ...
+end
+```
+which is same as other languages:
+```
+if (1 == 2){
+    ...
+}
+```
+(You can follow previous math example for checking stack manipulation)
+
+For writing a bit more complex programs you may want to use macros and includes:
+Macros is an collection of tokens (like functions in other languages) but does not have an object-like system they just an way to not write same logic (for now)
+So, this code:
+```
+macro multiply_by_2
+    2 *
+end
+
+4 multiply_by_2
+```
+at compilation stage will be converted into simple `4 2 *` (tokens expanded)
+For importing some file (same as macros system but for files) you can use `import "file.gof"`
+
+
+
+### Milestones and planned features
+
+- Standard library with not only syscall mapping
+- Stability improvements
+- Support for x86_64 Windows
+- More examples

gofra-0.0.1/README.md

@@ -0,0 +1,93 @@
+# Gofra Programming Language
+
+Gofra is an native stack based programming language.
+
+Language follows reverse polish notation (examples can be found below) \
+**Language is in development stage and mostly made for fun and research so don't expect a lot and try to test or implement your own idea**
+
+## Table of content
+
+- [Hello world example](#hello-world-example)
+- [Compatibility](#compatibility)
+- [Features](#features)
+- [Installation](#installation)
+- [Examples](#examples)
+- [Language overview](#language-overview)
+- [Command Line Interface](#command-line-interface-cli)
+- [Milestones and planned features](#milestones-and-planned-features)
+
+---
+
+### Hello world example
+###### (For now, language is mostly bare-metal so in this example there is raw `sc_write` syscall and file descriptor usage)
+```
+include "std.gof"
+func void main
+    FD_STD_OUT "Hello, World!\n" sc_write drop
+end
+```
+
+
+### Compatibility
+Language currently have codegenS only for:
+- AARCH64 MacOS (Darwin)
+- x86_64 Linux
+
+### Features
+- Native (codegen assembly)
+- Type safety (Validates stack usage and tries to infer types so you wont mess up)
+- Mostly self explanation errors (Tries to help you and correct your intentions)
+- Optimizer (DCE, CF, Helps optimize resulting assembly for codegen so your default usage will not be overwhelmed by language)
+- FFI with `global`/`extern` function modifers (there is CLI flags to emit an library/object file)
+- Simple CLI for working with language (simple toolkit)
+
+
+### Installation
+- Clone this repo
+- Install latest Python version
+- Navigate to root directory 
+- Run `python -m gofra --help` (`python` depends on your installation of Python)
+
+### Examples
+Examples may be found inside `./examples` directory
+
+### Language overview
+As language is stack based so your basic action is to *put something on a stack*, like `2 2` will push 2 and then another 2 on stack so stack underneath will look like [2, 2]
+
+If you want to operate on that numbers you may do something like `3 2 +` which is same as `3 + 2` in other language or default math. Underneath this will mean: push 3 on stack -> push 2 on stack -> take 2 elements from stack -> sum them -> push result back. Stack after that will become [5]
+
+Conditionals is also a bit controversial:
+```
+1 2 == if
+    ...
+end
+```
+which is same as other languages:
+```
+if (1 == 2){
+    ...
+}
+```
+(You can follow previous math example for checking stack manipulation)
+
+For writing a bit more complex programs you may want to use macros and includes:
+Macros is an collection of tokens (like functions in other languages) but does not have an object-like system they just an way to not write same logic (for now)
+So, this code:
+```
+macro multiply_by_2
+    2 *
+end
+
+4 multiply_by_2
+```
+at compilation stage will be converted into simple `4 2 *` (tokens expanded)
+For importing some file (same as macros system but for files) you can use `import "file.gof"`
+
+
+
+### Milestones and planned features
+
+- Standard library with not only syscall mapping
+- Stability improvements
+- Support for x86_64 Windows
+- More examples

gofra-0.0.1/gofra/__init__.py

@@ -0,0 +1,12 @@
+"""Gofra programming language.
+
+Provides toolchain including CLI, compiler etc.
+"""
+
+from .assembler import assemble_program
+from .gofra import process_input_file
+
+__all__ = [
+    "assemble_program",
+    "process_input_file",
+]

gofra-0.0.1/gofra/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for CLI."""
+
+from gofra.cli.entry_point import cli_entry_point
+
+if __name__ == "__main__":
+    cli_entry_point(prog=None)

gofra-0.0.1/gofra/assembler/__init__.py

@@ -0,0 +1,8 @@
+"""Assembler package that links and assembles generated code into final executable.
+
+Tools used for assembly is different for specified target
+"""
+
+from .assembler import assemble_program
+
+__all__ = ["assemble_program"]

gofra-0.0.1/gofra/assembler/assembler.py

@@ -0,0 +1,239 @@
+"""Assembler module to assemble programs in Gofra language into executables."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from platform import system as current_platform_system
+from shutil import which
+from subprocess import CalledProcessError, check_output
+from typing import TYPE_CHECKING, Literal
+
+from gofra.cli.output import cli_message
+from gofra.codegen import generate_code_for_assembler
+from gofra.codegen.backends.general import CODEGEN_ENTRY_POINT_SYMBOL
+from gofra.codegen.get_backend import get_backend_for_target
+
+from .exceptions import (
+    NoToolkitForAssemblingError,
+    UnsupportedBuilderOperatingSystemError,
+)
+
+if TYPE_CHECKING:
+    from gofra.codegen.targets import TARGET_T
+    from gofra.context import ProgramContext
+
+type OUTPUT_FORMAT_T = Literal["library", "executable", "object", "assembly"]
+
+
+def assemble_program(  # noqa: PLR0913
+    context: ProgramContext,
+    output: Path,
+    output_format: OUTPUT_FORMAT_T,
+    target: TARGET_T,
+    *,
+    build_cache_dir: Path,
+    verbose: bool,
+    additional_linker_flags: list[str],
+    additional_assembler_flags: list[str],
+    delete_build_cache_after_compilation: bool,
+) -> None:
+    """Convert given program into executable/library/etc using assembly and linker."""
+    _validate_toolkit_installation()
+    _prepare_build_cache_directory(build_cache_dir)
+
+    assembly_filepath = _generate_assembly_file_with_codegen(
+        context,
+        target,
+        output,
+        build_cache_dir=build_cache_dir,
+        verbose=verbose,
+    )
+
+    if output_format == "assembly":
+        assembly_filepath.replace(output)
+        return
+
+    object_filepath = _assemble_object_file(
+        target,
+        assembly_filepath,
+        output,
+        additional_assembler_flags=additional_assembler_flags,
+        build_cache_dir=build_cache_dir,
+        verbose=verbose,
+    )
+    if output_format == "object":
+        object_filepath.replace(output)
+        if delete_build_cache_after_compilation:
+            assembly_filepath.unlink()
+        return
+
+    assert output_format in ("executable", "library")
+    _link_final_output(
+        output,
+        target,
+        object_filepath,
+        output_format=output_format,
+        additional_linker_flags=additional_linker_flags,
+        verbose=verbose,
+    )
+
+    if delete_build_cache_after_compilation:
+        assembly_filepath.unlink()
+        object_filepath.unlink()
+
+
+def _prepare_build_cache_directory(build_cache_directory: Path) -> None:
+    """Try to create and fill cache directory with required files."""
+    if build_cache_directory.exists():
+        return
+
+    build_cache_directory.mkdir(exist_ok=False)
+
+    with (build_cache_directory / ".gitignore").open("w") as f:
+        f.write("# Do not include this newly generated build cache into git VCS\n")
+        f.write("*\n")
+
+
+def _link_final_output(  # noqa: PLR0913
+    output: Path,
+    target: TARGET_T,
+    o_filepath: Path,
+    output_format: Literal["executable", "library"],
+    additional_linker_flags: list[str],
+    *,
+    verbose: bool,
+) -> None:
+    """Use linker to link object file into executable."""
+    match current_platform_system():
+        case "Darwin":
+            assert target == "aarch64-darwin"
+
+            system_sdk = Path(
+                check_output(  # noqa: S603
+                    ["/usr/bin/xcrun", "-sdk", "macosx", "--show-sdk-path"],
+                    text=True,
+                ).strip(),
+            )
+            target_linker_flags = [
+                "-arch",
+                "arm64",
+                "-lSystem",
+                "-syslibroot",
+                str(system_sdk),
+            ]
+
+            if output_format == "library":
+                target_linker_flags += ["-dylib"]
+        case "Linux":
+            assert target == "x86_64-linux"
+
+            target_linker_flags = []
+            assert output_format == "executable", (
+                "Libraries on Linux is not implemented"
+            )
+        case _:
+            raise UnsupportedBuilderOperatingSystemError
+
+    linker_flags = [
+        *target_linker_flags,
+        *additional_linker_flags,
+    ]
+
+    if output_format == "executable":
+        linker_flags += ["-e", CODEGEN_ENTRY_POINT_SYMBOL]
+
+    command = ["/usr/bin/ld", "-o", str(output), str(o_filepath), *linker_flags]
+    cli_message(
+        level="INFO",
+        text=f"Running linker command: `{' '.join(command)}`",
+        verbose=verbose,
+    )
+    check_output(command)  # noqa: S603
+
+
+def _assemble_object_file(  # noqa: PLR0913
+    target: TARGET_T,
+    asm_filepath: Path,
+    output: Path,
+    *,
+    build_cache_dir: Path,
+    additional_assembler_flags: list[str],
+    verbose: bool,
+) -> Path:
+    """Call assembler to assemble given assembly file from codegen."""
+    object_filepath = (build_cache_dir / output.name).with_suffix(".o")
+
+    # Assembler is not crossplatform so we expect host has same architecture
+    match current_platform_system():
+        case "Darwin":
+            if target != "aarch64-darwin":
+                raise UnsupportedBuilderOperatingSystemError
+            assembler_flags = ["-arch", "arm64"]
+        case "Linux":
+            if target != "x86_64-linux":
+                raise UnsupportedBuilderOperatingSystemError
+            assembler_flags = []
+        case _:
+            raise UnsupportedBuilderOperatingSystemError
+
+    command = [
+        "/usr/bin/as",
+        "-o",
+        str(object_filepath),
+        str(asm_filepath),
+        *assembler_flags,
+        *additional_assembler_flags,
+    ]
+    cli_message(
+        level="INFO",
+        text=f"Running command: `{' '.join(command)}`",
+        verbose=verbose,
+    )
+    try:
+        check_output(command)  # noqa: S603
+    except CalledProcessError as e:
+        cli_message(
+            "ERROR",
+            "Failed to generate binary from output assembly, "
+            f"error code: {e.returncode}",
+        )
+        sys.exit(1)
+
+    return object_filepath
+
+
+def _generate_assembly_file_with_codegen(
+    context: ProgramContext,
+    target: TARGET_T,
+    output: Path,
+    *,
+    build_cache_dir: Path,
+    verbose: bool,
+) -> Path:
+    """Call desired codegen backend for requested target and generate file contains assembly."""
+    assembly_filepath = (build_cache_dir / output.name).with_suffix(".s")
+
+    infered_backend = get_backend_for_target(target).__name__  # type: ignore  # noqa: PGH003
+    cli_message(
+        level="INFO",
+        text=f"Generating assembly using codegen backend (Infered codegen for target `{target}` is `{infered_backend}`)...",
+        verbose=verbose,
+    )
+    generate_code_for_assembler(assembly_filepath, context, target)
+    return assembly_filepath
+
+
+def _validate_toolkit_installation() -> None:
+    """Validate that the host system has all requirements installed (linker/assembler)."""
+    match current_platform_system():
+        case "Darwin":
+            required_toolkit = ("as", "ld", "xcrun")
+        case "Linux":
+            required_toolkit = ("as", "ld")
+        case _:
+            raise UnsupportedBuilderOperatingSystemError
+    toolkit = {(tk, which(tk) is not None) for tk in required_toolkit}
+    missing_toolkit = {tk for (tk, tk_is_installed) in toolkit if not tk_is_installed}
+    if missing_toolkit:
+        raise NoToolkitForAssemblingError(toolkit_required=missing_toolkit)

gofra-0.0.1/gofra/assembler/exceptions.py

@@ -0,0 +1,19 @@
+from collections.abc import Iterable
+
+from gofra.exceptions import GofraError
+
+
+class NoToolkitForAssemblingError(GofraError):
+    toolkit_required: Iterable[str]
+
+    def __init__(self, *args: object, toolkit_required: Iterable[str]) -> None:
+        super().__init__(*args)
+        self.toolkit_required = toolkit_required
+
+    def __repr__(self) -> str:
+        return f"Unable to assemble program due to not all toolkit installed, required: {','.join(self.toolkit_required)}"
+
+
+class UnsupportedBuilderOperatingSystemError(GofraError):
+    def __repr__(self) -> str:
+        return "You are on unsupported operating system to compile that target"

gofra-0.0.1/gofra/cli/__init__.py

@@ -0,0 +1,6 @@
+"""Command-Line-Interface (CLI) for Gofra.
+
+Core toolchain provider for Gofra.
+"""
+
+__all__ = []