API

Polyglot Piranha can be used as a python library or as a command line tool.

🐍 Python Library

pip install polyglot-piranha

Currently, we support one simple API (run_piranha_cli) that wraps the command line usage of Polyglot Piranha. We believe this makes it easy to incorporate Piranha in "pipelining".

run_piranha_cli

from polyglot_piranha import run_piranha_cli

path_to_codebase = "..."
path_to_configurations = "..."
piranha_summary = run_piranha_cli(path_to_codebase,
                                  path_to_configurations,
                                  dry_run=False)

Arguments

• path_to_codebase : Path to source code folder
• path_to_configuration : A directory containing files named piranha_arguments.toml, rules.toml and optionally edges.toml
  • piranha_arguments.toml: Allows a user to choose language (java, kotlin, ...), opt-in/out of other features like cleaning up comments, or even provide arguments to the piranha rules reference
  • rules.toml: piranha rules expresses the specific AST patterns to match and replacement patterns for these matches (in-place). These rules can also specify the pre-built language specific cleanups to trigger.
  • edges.toml (optional): expresses the flow between the rules
• dry_run : Disables in-place rewriting of code

Returns

[Piranha_Output] : a PiranhaOutputSummary for each file touched or analyzed by Piranha. It contains useful information like, matches found (for match-only rules), rewrites performed, and content of the file after the rewrite. The content is particularly useful when dry_run is passed as true.

💻 Command-line Interface

Get platform-specific binary from releases or build it from source following the below steps:

• Install Rust

git clone https://github.com/uber/piranha.git && cd piranha
python3 -m venv .env && source .env/bin/activate
cargo build --release --no-default-features

A Binary will be generated under target/release.

Polyglot Piranha
A refactoring tool that eliminates dead code related to stale feature flags.

USAGE:
    polyglot_piranha [OPTIONS] --path-to-codebase <PATH_TO_CODEBASE> --path-to-configurations <PATH_TO_CONFIGURATIONS>

OPTIONS:
    -c, --path-to-codebase <PATH_TO_CODEBASE>
            Path to source code folder or file

    -d, --dry-run <DRY_RUN>
            Disables in-place rewriting of code [default: false]

    -f, --path-to-configurations <PATH_TO_CONFIGURATIONS>
            Directory containing the configuration files - `piranha_arguments.toml`, `rules.toml`,
            and  `edges.toml` (optional)

    -h, --help
            Print help information

    -j, --path-to-output-summary <PATH_TO_OUTPUT_SUMMARY>
            Path to output summary json file

The output JSON is the serialization of- PiranhaOutputSummary produced for each file touched or analyzed by Piranha.

It can be seen that the Python API is basically a wrapper around this command line interface.