<!--
Copyright (C) 2023 - 2024:
The Trinitrix Project <soispha@vhack.eu, antifallobst@systemausfall.org>
SPDX-License-Identifier: LGPL-3.0-or-later

This file is part of the Trixy crate for Trinitrix.

Trixy is free software: you can redistribute it and/or modify
it under the terms of the Lesser GNU General Public License as
published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
and the Lesser GNU General Public License along with this program.
If not, see <https://www.gnu.org/licenses/>.
-->

# Trixy

A crate to generate a multi-language foreign function interface.

## Features

- Support for custom types, derived from a set of [primitive types](./src/types/mod.rs).
- Support for callbacks, thought c function pointers.
- Support for error handling, when checking a functions arguments (NULL pointer and such things).

## Supported languages:

- c

## Dependencies

Trixy only needs:

- `clang-format` to format the generated c header files.

## The Trixy Language

The API to generate is specified in a Trixy file. The language of these files is an subset
of rust and should thus be easy to learn and pick up.

A grammar file is provided [here](./docs/grammar.ebnf) encoded in [Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form).
The grammar file is rendered as railroad diagrams in PDF [here](./docs/grammar.pdf), run [`./docs/generate_docs`](./docs/generate_docs.sh) to regenerate the PDF file.

## Testing

Trixy contains integration tests in the `./tests` directory. These are maintained with the
`./scripts/tests.sh` script. Take a look at it's `--help` output for further usage
information.

This crate also contains a binary, which can help with manual testing and inspecting of the
generated AST. The `cargo run --features 'build-binary' -- --help` output should provide
all required information.

Tests are (as of now) only positive, i.e. they can only test successful situations.
Failing test will probably be supported in the future.

## Contributing

We have a [nix flake](./flake.nix), which provides the required dependencies to work with Trixy and the associated scripts in the `./scripts` directory.

Please also make sure to run the `./scripts/renew_copyright_header.sh` after you added a new file, to ensure that every file contains a license header.