//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::../_part_attributes.asciidoc[]

:leveloffset: -2

[[tools-scripting-chapter-tools]]
== Overview of scriptable tools

This page provides an overview of the CIF tools that are available in the `cif` library that is registered with ToolDef by CIF.

=== Tools

The following table shows the relation between the names of the ToolDef tools in the library and the tools of the CIF tool set:

[cols=2*,options="header"]
|===
| ToolDef tool name
| CIF tool

| `cif2yed`
| <<tools-chapter-cif2yed>>

| `cifinfogen`
| <<tools-chapter-infogen>>

| `cifdatasynth`
| <<tools-chapter-datasynth>>

| `cifmultilevel`
| <<tools-chapter-multilevel>>

| `cifcontrollercheck`
| <<tools-chapter-controller-checker>>

| `cif2supremica`
| <<tools-chapter-cif2supremica>>

| `cifsim`
| <<tools-cifsim-chapter-index>>

| `cif2mcrl2`
| <<tools-chapter-cif2mcrl2>>

| `cif2uppaal`
| <<tools-chapter-cif2uppaal>>

| `cifcodegen`
| <<tools-codegen-chapter-index>>

| `cif2plc`
| <<tools-cif2plc-chapter-index>>

| `cifplcgen`
| <<tools-plcgen-chapter-index>>

| `cifrelations`
| <<tools-chapter-relations>>

| `cif2cif`
| <<tools-cif2cif-chapter-index>>

| `cifmerge`
| <<tools-chapter-mergecif>>

| `cifevtdis`
| <<tools-chapter-event-disabler>>

| `cifexplorer`
| <<tools-chapter-cif-explorer>>

| `cifprod`
| <<tools-eventbased-chapter-product>>

| `cifsupsynth`
| <<tools-eventbased-chapter-supervisorsynthesis>>

| `cifsynthanalys`
| <<tools-eventbased-chapter-synthesis-analysis>>

| `cifncchk`
| <<tools-eventbased-chapter-nonconflicting-check>>

| `cifctrlchk`
| <<tools-eventbased-chapter-controllability-check>>

| `ciflngeqv`
| <<tools-eventbased-chapter-language-equivalence-check>>

| `cifnfadfa`
| <<tools-eventbased-chapter-nfa-to-dfa>>

| `cifdfamin`
| <<tools-eventbased-chapter-dfa-minimization>>

| `cifproj`
| <<tools-eventbased-chapter-projection>>

| `cifobschk`
| <<tools-eventbased-chapter-observer-check>>

| `cifabstr`
| <<tools-eventbased-chapter-automaton-abstraction>>

| `ciftrimchk`
| <<tools-eventbased-chapter-trim-check>>

| `ciftrim`
| <<tools-eventbased-chapter-trim>>
|===

=== Parameters

For every CIF tool, two ToolDef tool variants are available in the `cif` ToolDef library.
All the CIF tools in the `cif` ToolDef library have the same tool signatures, including the same parameters.
Only their names differ.
Below the tool signatures for the two variants are listed, with `toolname` instead of the actual tool name (e.g. `cifsim`):

[source, tooldef]
----
tool int toolname(
            string... args,
            string stdin = "-",
            string stdout = "-",
            string stderr = "-",
            bool appendOut = false,
            bool appendErr = false,
            bool errToOut = false,
            bool ignoreNonZeroExitCode = false
)

tool int toolname(
            list string args = [],
            string stdin = "-",
            string stdout = "-",
            string stderr = "-",
            bool appendOut = false,
            bool appendErr = false,
            bool errToOut = false,
            bool ignoreNonZeroExitCode = false
)
----

The meaning of each of the parameters is as follows:

args::
The command line arguments of the application.
Each argument string is parsed to zero or more actual arguments.
It is possible to use a single string with all arguments (where the arguments themselves are separated by spaces), comma separated strings for each of the arguments (each string has one argument), or a mix of those.
+
In argument strings, individual arguments are separated by whitespace (spaces, tabs, new lines, etc).
The whitespace itself is ignored, and only serves as separation.
To include whitespace in an argument, the argument (or a part of it), may be quoted, by putting it between double quotes (`"`) or single quotes (`'`).
Characters may be escaped by prefixing them with a backslash (`\`).
This is particularly useful for single/double quotes, and escape characters, and can also be used to escape spaces.
Escapes work the same inside of quoted parts as they do outside of quoted parts.

stdin::
Specify whether to have a standard input (stdin) stream and where the input comes from.
Use `""` to not have a stdin stream, "-" to use the stdin stream of the ToolDef interpreter, or otherwise an absolute or relative local file system path of the file from which to read the standard input.
May contain both `\` and `/` as file separators.

stdout::
Specify whether to have a standard output (stdout) stream and where to write the standard output.
Use `""` to not have a stdout stream, `"-"` to use the stdout stream of the ToolDef interpreter, or otherwise an absolute or relative local file system path of the file to which to write the standard output.
May contain both `\` and `/` as file separators.

stderr::
Specify whether to have a standard error (stderr) stream and where to write the standard error output.
Use `""` to not have a stderr stream, `"-"` to use the stderr stream of the ToolDef interpreter, or otherwise an absolute or relative local file system path of the file to which to write the standard error output.
May contain both `\` and `/` as file separators.
Is ignored when the standard error stream is redirected to the standard output stream.

appendOut::
Whether to append to the stdout file (`true`) or overwrite it (`false`).
Is ignored when standard output is not written to a file.

appendErr::
Whether to append to the stderr file (`true`) or overwrite it (`false`).
Is ignored if standard error output is not written to a file.
Is also ignored when standard error stream is redirected to the standard output stream.

errToOut::
Whether to redirect the standard error stream to the standard output stream (`true`) or use separate streams (`false`).

ignoreNonZeroExitCode::
Whether to ignore non-zero exit codes (`true`) or consider them as errors (`false`).

=== Return value

All the tools return an integer value.
This value is the exit code of the application.
A zero (`0`) exit code means the application terminated without any errors.
A non-zero exit code means the application terminated with an error.

=== Implementation

All the tools are internally implemented using the ToolDef `app` tool.
// Removed the previously present link to documentation about 'app tool'.
