crashlink 0.0.1__tar.gz

crashlink-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 N3rdL0rd
+
+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.

crashlink-0.0.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.1
+Name: crashlink
+Version: 0.0.1
+Summary: Just another HashLink decompiler/disassembler.
+Author-email: N3rdL0rd <n3rdl0rd@proton.me>
+License: MIT License
+        
+        Copyright (c) 2024 N3rdL0rd
+        
+        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.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Disassemblers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pdoc3; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: radon; extra == "dev"
+Requires-Dist: no_implicit_optional; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: tqdm; extra == "dev"
+Requires-Dist: snakeviz; extra == "dev"
+Requires-Dist: typeguard; extra == "dev"
+Requires-Dist: types-tqdm; extra == "dev"
+Provides-Extra: tqdm
+Requires-Dist: tqdm; extra == "tqdm"
+
+# crashlink
+
+![workflow](https://github.com/N3rdL0rd/crashlink/actions/workflows/python-package.yml/badge.svg)
+
+Pure Python HashLink bytecode parser/disassembler/decompiler/modding tool
+
+> [!WARNING]
+> This project is under active development. Breaking changes may be made to APIs with zero notice.
+
+## Features
+
+- Pure Python with zero dependencies, integrates nicely in a lot of places (IDAPython compatible!)
+- Allows values to be externally modified and reserialised through a scriptable interface
+- A very nice little CLI with [hlbc](https://github.com/Gui-Yom/hlbc)-compatible mode.
+
+## Installation
+
+```bash
+pip install crashlink
+```
+
+Optionally, install `tqdm` for progress bars when parsing large files:
+
+```bash
+pip install crashlink[tqdm]
+```
+
+You also need to have Graphviz installed to generate control flow graphs. On most *nix systems, on Windows (with Chocolatey or Scoop), and on MacOS (with Homebrew), you can install it with your package manager under `graphviz`.
+
+- Windows: `choco install graphviz`
+- MacOS: `brew install graphviz`
+- Debian: `sudo apt install graphviz`
+- Arch: `sudo pacman -S graphviz`
+- Fedora: `sudo dnf install graphviz`
+
+## Usage
+
+Either:
+
+```py
+from crashlink import *
+code = Bytecode.from_path("path/to/file.hl")
+for func in code.functions:
+    if func.findex.value == 22 or func.findex.value == 240: # typical entry points that the compiler generates
+        print(disasm.func(code, func))
+# > f@22 static $Clazz.main () -> Void (from Clazz.hx)
+# > Reg types:
+# >   0. Void
+# >
+# > Ops:
+# >   0. Ret             {'ret': 0}                                       return
+```
+
+Or:
+
+```txt
+$ crashlink path/to/file.hl # or python -m crashlink
+crashlink> funcs
+f@22 static Clazz.main () -> Void (from Clazz.hx)
+f@23 Clazz.method (Clazz) -> I32 (from Clazz.hx)
+crashlink> fn 22
+f@22 static Clazz.main () -> Void (from Clazz.hx)
+Reg types:
+  0. Void
+
+Ops:
+  0. Ret             {'ret': 0}                                       return
+```
+
+## Development
+
+> [!NOTE]
+> This project is configured for the [just](https://just.systems/) command runner. If you don't have it installed, you can still run the commands in the `justfile` manually, but I don't recommend it.
+
+For development purposes, you can clone the repo, install development dependencies, and run the tests:
+
+```bash
+git clone https://github.com/N3rdL0rd/crashlink
+cd crashlink
+# optionally, create and activate a venv here.
+just install # or pip install -e .[dev]
+just test # or pytest
+```
+
+Before committing, please run `just dev` to format the code, run tests, and generate documentation in `docs/`. If you're adding new features to the core serialisation/deserialisation code (`core.py`), please also add a test case in `tests/haxe/` for the new language feature you're adding. If you're adding a feature to the decompiler or disassembler, please add a normal test case (in Python) in `tests/` that tests the new feature.
+
+Pull requests are always welcome! For major changes, please open an issue first to discuss what you would like to change.
+
+You can use the following pre-defined commands with `just`:
+
+- `just dev`: Run tests, format code, and generate documentation.
+- `just build`: Build the package.
+- `just install`: Install development dependencies and the package in editable mode.
+- `just build-tests`: Build test samples.
+- `just test`: Run tests.
+- `just format`: Format code.
+- `just docs`: Generate documentation.
+- `just check`: Run static analysis/typechecking.
+- `just clean`: Clean up build artifacts.
+- `just profile`: Run the test suite with cProfile and then open the results in a browser.
+- `just serve-docs`: Serve the documentation locally.
+
+## Architecture
+
+![Architecture](docs/static/flow.svg)
+
+> [!NOTE]
+> IR and the IR optimization layers have not yet been fully implemented.
+
+## Credits
+
+- Thank you to [Gui-Yom](https://github.com/Gui-Yom) for writing hlbc and for maintaining documentation on the HashLink bytecode format, as well as for providing tests and helping me during development.
+- Thank you to [Haxe Foundation](https://haxe.org/) for creating the HashLink VM and the Haxe programming language.
+- And a big thank you to you, dear user, for being at least partially interested in this project.
+
+:heart: N3rdL0rd

crashlink-0.0.1/README.md

@@ -0,0 +1,116 @@
+# crashlink
+
+![workflow](https://github.com/N3rdL0rd/crashlink/actions/workflows/python-package.yml/badge.svg)
+
+Pure Python HashLink bytecode parser/disassembler/decompiler/modding tool
+
+> [!WARNING]
+> This project is under active development. Breaking changes may be made to APIs with zero notice.
+
+## Features
+
+- Pure Python with zero dependencies, integrates nicely in a lot of places (IDAPython compatible!)
+- Allows values to be externally modified and reserialised through a scriptable interface
+- A very nice little CLI with [hlbc](https://github.com/Gui-Yom/hlbc)-compatible mode.
+
+## Installation
+
+```bash
+pip install crashlink
+```
+
+Optionally, install `tqdm` for progress bars when parsing large files:
+
+```bash
+pip install crashlink[tqdm]
+```
+
+You also need to have Graphviz installed to generate control flow graphs. On most *nix systems, on Windows (with Chocolatey or Scoop), and on MacOS (with Homebrew), you can install it with your package manager under `graphviz`.
+
+- Windows: `choco install graphviz`
+- MacOS: `brew install graphviz`
+- Debian: `sudo apt install graphviz`
+- Arch: `sudo pacman -S graphviz`
+- Fedora: `sudo dnf install graphviz`
+
+## Usage
+
+Either:
+
+```py
+from crashlink import *
+code = Bytecode.from_path("path/to/file.hl")
+for func in code.functions:
+    if func.findex.value == 22 or func.findex.value == 240: # typical entry points that the compiler generates
+        print(disasm.func(code, func))
+# > f@22 static $Clazz.main () -> Void (from Clazz.hx)
+# > Reg types:
+# >   0. Void
+# >
+# > Ops:
+# >   0. Ret             {'ret': 0}                                       return
+```
+
+Or:
+
+```txt
+$ crashlink path/to/file.hl # or python -m crashlink
+crashlink> funcs
+f@22 static Clazz.main () -> Void (from Clazz.hx)
+f@23 Clazz.method (Clazz) -> I32 (from Clazz.hx)
+crashlink> fn 22
+f@22 static Clazz.main () -> Void (from Clazz.hx)
+Reg types:
+  0. Void
+
+Ops:
+  0. Ret             {'ret': 0}                                       return
+```
+
+## Development
+
+> [!NOTE]
+> This project is configured for the [just](https://just.systems/) command runner. If you don't have it installed, you can still run the commands in the `justfile` manually, but I don't recommend it.
+
+For development purposes, you can clone the repo, install development dependencies, and run the tests:
+
+```bash
+git clone https://github.com/N3rdL0rd/crashlink
+cd crashlink
+# optionally, create and activate a venv here.
+just install # or pip install -e .[dev]
+just test # or pytest
+```
+
+Before committing, please run `just dev` to format the code, run tests, and generate documentation in `docs/`. If you're adding new features to the core serialisation/deserialisation code (`core.py`), please also add a test case in `tests/haxe/` for the new language feature you're adding. If you're adding a feature to the decompiler or disassembler, please add a normal test case (in Python) in `tests/` that tests the new feature.
+
+Pull requests are always welcome! For major changes, please open an issue first to discuss what you would like to change.
+
+You can use the following pre-defined commands with `just`:
+
+- `just dev`: Run tests, format code, and generate documentation.
+- `just build`: Build the package.
+- `just install`: Install development dependencies and the package in editable mode.
+- `just build-tests`: Build test samples.
+- `just test`: Run tests.
+- `just format`: Format code.
+- `just docs`: Generate documentation.
+- `just check`: Run static analysis/typechecking.
+- `just clean`: Clean up build artifacts.
+- `just profile`: Run the test suite with cProfile and then open the results in a browser.
+- `just serve-docs`: Serve the documentation locally.
+
+## Architecture
+
+![Architecture](docs/static/flow.svg)
+
+> [!NOTE]
+> IR and the IR optimization layers have not yet been fully implemented.
+
+## Credits
+
+- Thank you to [Gui-Yom](https://github.com/Gui-Yom) for writing hlbc and for maintaining documentation on the HashLink bytecode format, as well as for providing tests and helping me during development.
+- Thank you to [Haxe Foundation](https://haxe.org/) for creating the HashLink VM and the Haxe programming language.
+- And a big thank you to you, dear user, for being at least partially interested in this project.
+
+:heart: N3rdL0rd

crashlink-0.0.1/crashlink/__init__.py

@@ -0,0 +1,111 @@
+"""
+Pure Python HashLink bytecode parser/disassembler/decompiler/modding tool
+
+## Features
+
+- Pure Python with zero dependencies, integrates nicely in a lot of places (IDAPython compatible!)
+- Allows values to be externally modified and reserialised through a scriptable interface
+- A very nice little CLI with [hlbc](https://github.com/Gui-Yom/hlbc)-compatible mode.
+
+## Installation
+
+```bash
+pip install crashlink
+```
+
+Optionally, install `tqdm` for progress bars when parsing large files:
+
+```bash
+pip install crashlink[tqdm]
+```
+
+You also need to have Graphviz installed to generate control flow graphs. On most *nix systems, on Windows (with Chocolatey or Scoop), and on MacOS (with Homebrew), you can install it with your package manager under `graphviz`.
+
+- Windows: `choco install graphviz`
+- MacOS: `brew install graphviz`
+- Debian: `sudo apt install graphviz`
+- Arch: `sudo pacman -S graphviz`
+- Fedora: `sudo dnf install graphviz`
+
+## Usage
+
+Either:
+
+```py
+from crashlink import *
+code = Bytecode.from_path("path/to/file.hl")
+for func in code.functions:
+    if func.findex.value == 22 or func.findex.value == 240: # typical entry points that the compiler generates
+        print(disasm.func(code, func))
+# > f@22 static $Clazz.main () -> Void (from Clazz.hx)
+# > Reg types:
+# >   0. Void
+# >
+# > Ops:
+# >   0. Ret             {'ret': 0}                                       return
+```
+
+Or:
+
+```bash
+$ crashlink path/to/file.hl # or python -m crashlink
+crashlink> funcs
+f@22 static Clazz.main () -> Void (from Clazz.hx)
+f@23 Clazz.method (Clazz) -> I32 (from Clazz.hx)
+crashlink> fn 22
+f@22 static Clazz.main () -> Void (from Clazz.hx)
+Reg types:
+  0. Void
+
+Ops:
+  0. Ret             {'ret': 0}                                       return
+```
+
+## Development
+
+> Note:
+> This project is configured for the [just](https://just.systems/) command runner. If you don't have it installed, you can still run the commands in the `justfile` manually, but I don't recommend it.
+
+For development purposes, you can clone the repo, install development dependencies, and run the tests:
+
+```bash
+git clone https://github.com/N3rdL0rd/crashlink
+cd crashlink
+# optionally, create and activate a venv here.
+just install # or pip install -e .[dev]
+just test # or pytest
+```
+
+Before committing, please run `just dev` to format the code, run tests, and generate documentation in `docs/`. If you're adding new features to the core serialisation/deserialisation code (`crashlink.core`), please also add a test case in `tests/haxe/` for the new language feature you're adding. If you're adding a feature to the decompiler or disassembler, please add a normal test case (in Python) in `tests/` that tests the new feature.
+
+Pull requests are always welcome! For major changes, please open an issue first to discuss what you would like to change.
+
+You can use the following pre-defined commands with `just`:
+
+- `just dev`: Run tests, format code, and generate documentation.
+- `just build`: Build the package.
+- `just install`: Install development dependencies and the package in editable mode.
+- `just build-tests`: Build test samples.
+- `just test`: Run tests.
+- `just format`: Format code.
+- `just docs`: Generate documentation.
+- `just check`: Run static analysis/typechecking.
+- `just clean`: Clean up build artifacts.
+- `just profile`: Run the test suite with cProfile and then open the results in a browser.
+- `just serve-docs`: Serve the documentation locally.
+
+## Credits
+
+- Thank you to [Gui-Yom](https://github.com/Gui-Yom) for writing hlbc and for maintaining documentation on the HashLink bytecode format, as well as for providing tests and helping me during development.
+- Thank you to [Haxe Foundation](https://haxe.org/) for creating the HashLink VM and the Haxe programming language.
+- And a big thank you to you, dear user, for being at least partially interested in this project.
+
+❤ N3rdL0rd
+
+"""
+
+from . import decomp, disasm
+from .core import *
+from .errors import *
+from .globals import *
+from .opcodes import *