Getting Started

Getting Started

This walkthrough starts with an installed release. You do not need a source checkout to generate or build a parser. 🙂

Install ISPA and its standard library

Install the current release using the platform installer from the repository README. Then install the standard library package and add the ISPA exports to your shell profile:

ispa-pkg install std
ispa-pkg --export-permanent

Open a new shell. The installed shell helper loads the target include paths and library settings. Run ispa-pkg --export in that shell to refresh the exports after installing or updating packages. The export creates ISPA_TARGETS_CMAKE, which points to a CMake file defining ISPA::Targets.

Generate a small C++ parser

Create grammar.isc:

module main -> demo;

NUMBER: @ [0-9]+ {@};
main: @ NUMBER {@};

Generate the parser:

ispa -l cpp -a LL grammar.isc -o generated/Parser

Create main.cpp:

#include <Parser.h>

int main() {
    Parser::Parser parser;
    auto& tree = parser.parse("123");
    (void)tree;
}

Create CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
project(demo LANGUAGES CXX)
include("$ENV{ISPA_TARGETS_CMAKE}")
add_executable(demo main.cpp generated/Parser.cpp)
target_link_libraries(demo PRIVATE ISPA::Targets)

Configure and build:

cmake -S . -B build
cmake --build build
./build/demo

ISPA::Targets supplies installed headers and runtime libraries through the generated package manifest, so the application does not need source-tree include paths or hand-written link flags. The same exports provide PYTHONPATH for Python target runtimes.

Generate Python output

Use the same grammar with the Python emitter:

ispa -l python -a LL --no-incremental grammar.isc -o generated/Parser
PYTHONPATH=generated:$PYTHONPATH python3 -c 'import Parser; print(Parser.Parser().parse("123"))'

The package export places the installed ispa_std runtime on PYTHONPATH. See Package Manager for package roots, catalogs, and shell export behavior.