# parseupf

> Parse a UPF (IEEE 1801) power-intent file with an ANTLR4 grammar and write it back, optionally flattened with every sourced file inlined in execution order -- a front end and Java API for UPF tools.

- Catalog id: `Parseupf`; bundle: `parseupf`; latest version 20261018
- Documentation page: https://edautils.com/UPF.html
- Keywords: UPF parser, IEEE 1801, power intent, ANTLR UPF grammar
- Terms: as stated on edautils.com, EDAUtils tools are free for commercial and academic use, with no license server. The bundle's own metadata says: "Free to evaluate with the bundled licence; commercial licences from help@edautils.com". Licence prerequisites per tool are under "How an agent runs it".
- This file: https://edautils.com/capabilities/parseupf.md

## Downloads

- EDAUtils download site: https://edautils.ai/download/Parseupf (latest file `parseupf-20261018.tar.gz`)
- SourceForge: https://sourceforge.net/projects/parsers-liberty-upf-sdc-vcd/files/parseupf/
- GitHub Releases: https://github.com/edautils/releases/releases/download/RELEASE_20261018/parseupf-20261018.tar.gz (release `RELEASE_20261018`; all releases: https://github.com/edautils/releases/releases)

## How an agent runs it

The following is the AGENTS.md shipped at the root of the bundle.

Parses a UPF (IEEE 1801 power intent) file with an ANTLR4 grammar (`UPF.g4`) and writes it back
out (default `output.upf`). Following `source`/`load_upf` is on by default, and `-flatout` also
writes every command of every file the deck reads, in execution order (a followed `source` is
written commented out, its commands inline after it, so the flattened file does not read the file
twice; `load_upf` stays live). This is the grammar-layer
front end: it does not execute Tcl or build the upf-shell data model (compareupf and upf-shell
do that). Main class: `com.eu.miscedautils.upfgrammar.ReadUPFAndPrintBack`.

### Where it ships

Its own bundle, `parseupf.tar.gz` (flow `parseupf`; release tree `release_scripts/parseupf/1.0`,
jar `lib/designplayer.jar`), and as a point tool in the **upf-shell** bundle (launcher
`bin/parseupf`, jar `lib/upf.jar`) and the **designplayer-shell** bundle (`bin/parseupf`, jar
`lib/designplayer.jar`). A shell carries this guide as `tools/parseupf/AGENTS.md` and the
`examples/` below under `tools/parseupf/examples/`.

### Prerequisites

- Java on `PATH` (the launcher runs plain `java`). Use Java 11 or newer (Java 21 recommended: the
  release is built and regression-tested with OpenJDK 21); the bundled JAXB and Eclipse libraries
  are class-file version 55, so a Java 8 runtime fails with `UnsupportedClassVersionError`.
- `EDAUTILS_ROOT` = the unpacked bundle directory (must contain `bin/` and `lib/`). The
  launcher exits 1 with "Environment variable EDAUTILS_ROOT is not set" otherwise. The
  bundle's `setup_env.sh` / `setup_env.csh`, sourced from its root, sets it.
- Licence: a valid licence file. No licence-feature check is made (no `UPFPARSER` checkout),
  so any valid EDAUtils licence runs it. No valid licence: exit status 10 (messages 6037/6405).
  The licence file is searched in this order: `$EDAUTILS_LICENSE_FILE`, `./edautils.lic` (run
  directory), `$HOME/edautils.lic`, `$EDAUTILS_ROOT/edautils.lic`.
- In a shell bundle, its `bin/tcl` protected layer is verified at start-up, as for every tool
  in that bundle; a failed signature check or decryption is exit status 11.
- Optional environment: `JAVA_FLAGS` (passed to the JVM, e.g. `-Xmx8g`; with no heap option in it the launcher adds `-Xmx` sized to the machine (`bin/eu_heap.sh`: the largest of 64/32/16/12/8/4 GB within 3/4 of physical or cgroup memory, else 2 GB; `EDAUTILS_MAX_HEAP_GB` caps it)),
  `EDAUTILS_LOG_FILE` / `EDAUTILS_APPEND_LOG_FILE` (log file name; the second appends),
  `EDAUTILS_DISABLE_USAGE_TRACKING=true`, `EDAUTILS_PRINT_STACK_TRACE` (stack traces on
  internal exceptions). `$env(NAME)` references inside the UPF are resolved from the process
  environment when following `source`/`load_upf`.
- No external tools needed.

### Invocation

```
parseupf -in <file.upf> [-out <file>] [-flatout <file>] [-nofollowsource] [-user <email>]
```

| Option | Meaning |
|---|---|
| `-in <file>` | UPF file to read (mandatory) |
| `-out <file>` | Print-back of the `-in` file only, statement by statement (default `output.upf`) |
| `-flatout <file>` | Also write every command of every file read, in execution order (off by default) |
| `-nofollowsource` | Parse only the `-in` file; do not follow `source`, `load_upf` or `load_upf_protected` |
| `-user <email>` | Usage-tracking user id |
| `-help` | Print usage and return (`-h` is not recognised) |

There is no `-nobanner`, `-quiet` or `-suppress`. Any other option prints Error
"Unrecognized option : <opt>" followed by the usage. With no arguments, or without `-in`, the
usage is printed. An option given without its value throws an index exception, which is
printed as an internal error; the exit status is 0.

Following sources: a relative path is tried beside the including file first, then from the
current directory. `set` variables seen earlier in the deck and `$env(...)` are substituted.
A path still holding `$` or `[` after substitution, a missing file, a source cycle, or nesting
deeper than 64 files is a Warning ("Not following '<cmd> <path>' at <file>:<line> : ...") and
that source is skipped; the run goes on.

### Inputs / Outputs

- Reads: the `-in` file and, unless `-nofollowsource`, every file it sources.
- Writes: `-out` (default `output.upf` in the current directory) and `-flatout` if given.
  Both are written only if every file parsed without a syntax error; one error anywhere
  means neither is written. A clean parse of a comment-free deck round-trips byte for byte.
- Log: `ParseUPF.log` in the current directory (override with `EDAUTILS_LOG_FILE`).

### Exit status and messages

- 0 on a normal finish, **including runs that reported errors** (syntax errors, missing input
  file, usage errors). 10 = no valid licence file. 11 = protected Tcl layer of the enclosing
  bundle failed its check. 1 = `EDAUTILS_ROOT` missing/invalid (launcher).
- Message format: `ParseUPF: <Severity>: <id>: <text>` (the prefix is `ParseUPF`, not
  `parseupf`); `<id>` is a 5-digit message number. Usage lines have no severity or id.
- Key messages: `File '<f>' not found ...` (Error), the ANTLR syntax error text (Error),
  `Parsed N file(s), M command(s) ...`, `Written decompiled UPF in file : <out>`,
  `Written flattened UPF in file : <flatout>`.
- A run that parses ends with `ParseUPF: Note: <id>: Found N error(s) and M warning(s) ...`.
  The usage paths return before that summary.

### Examples

In `release_scripts/parseupf/1.0/examples/`, each with a `runme.csh`:

| Directory | Command |
|---|---|
| `complex_tcl` | `parseupf -in complex_tcl.upf -out output.upf -flatout flattened.upf` (sources the `blocks/` tree; 9 files, 3 expected warnings: one source cycle, two unresolved paths) |
| `comprehensive_upf` | `parseupf -in comprehensive.upf -out output.upf` |
| `ieee1801_commands` | `parseupf -in ieee1801_commands.upf -out output.upf` |
| `tcl_constructs` | `parseupf -in tcl_constructs.upf -out output.upf` |

From the regression suite (reference: `tests.edautilscommandline/tests/parseupf/*/runme.csh`
via `../runme_common.csh`; goldens `decompiled.upf.gld`, `flattened.upf.gld`; six cases
including `ieee_soc` and `openroad_mpd_top`):

```
parseupf -in ieee_soc.upf -out decompiled.upf -flatout flattened.upf
```

### Integration notes

- Non-interactive; does not read stdin. Run with `</dev/null`.
- Writes the log and default output into the current directory: give each parallel run its
  own working directory (or distinct `-out` and `EDAUTILS_LOG_FILE`).
- Set `EDAUTILS_DISABLE_USAGE_TRACKING=true` to stop usage registration.
- Success test: exit status 0 **and** the log contains `Found 0 error(s)` **and** the `-out`
  file exists. Check warnings too: a skipped `source` is only a Warning, and `-flatout` then
  lacks that file's commands.

### See also

compareupf, xls2upf, upf-shell, parsesdc (the same front-end shape for SDC).
