Metadata-Version: 2.4
Name: qivo-parseora
Version: 0.1.5
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: SQL
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Compilers
Summary: ParseOra: a fast, lossless parser for Oracle SQL, PL/SQL and SQL*Plus scripts (12.2 to 26ai), with a command line
Keywords: oracle,plsql,sql,parser,sqlplus,lexer,syntax tree
Author-email: QiVo Studio <admin@qivo.studio>
License: Proprietary: free to use under the QiVo Studio Licence Agreement 1.0
	(LICENSE.md in the package)
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://qivo.studio
Project-URL: Issues, https://github.com/qivo-studio/qivo-studio/issues

# ParseOra

A fast, lossless parser for Oracle SQL, PL/SQL and SQL*Plus scripts, from Oracle 12.2 to 26ai. Free to use; part of
[QiVo Studio](https://qivo.studio). The parser is compiled Rust: no Oracle client and no database are needed.

```bash
pip install qivo-parseora
```

## ParseOra Lab: the parser in your browser

```bash
parseora lab                    # opens http://127.0.0.1:8790/ (only on this machine; works offline)
```

Type or paste SQL, open several files or drop them on the page, choose the Oracle version, and see:

- **Tree**: the syntax tree drawn, to zoom, move and fold; click a node to find it in the source
- **Outline**: the same tree as a list you can search; **Tokens**: every token with its kind and position
- **Statements** and **Problems**: errors and warnings marked in the editor; click one to jump to it
- **Profile**: where the time goes, statement by statement
- **Download**: a report for all open files (HTML), each table as CSV, everything as JSON or one ZIP, and the
  tree as JSON or SVG

## Reports

```bash
parseora report src/ --out report/                 # report.html, files.csv, statements.csv, problems.csv,
                                                   # tables.csv, objects.csv, report.json
parseora report src/ --format csv --version 19c    # only the CSV files, checked against Oracle 19c
parseora report src/ --fail-on-errors              # exit status 1 if a statement does not parse (CI)
```

`report.html` is one file that opens anywhere, offline: summary, files, problems, statements, tables used, objects
created; each table sortable, filterable and downloadable. The same files give the same report, byte for byte.

## Command line

```bash
parseora parse  install.sql              # every statement and PL/SQL unit: kinds, errors, speed
parseora parse  --json src/              # one JSON line per statement: kind, errors, tables, text
parseora parse  --errors --version 19c . # where it does not parse, and constructs newer than 19c
parseora parse  --dump pkg_load.pkb      # the syntax tree
parseora split  --summary deploy.sql     # the script split the way SQL*Plus runs it
parseora lex    --strict src/            # tokens; exit status 1 on any diagnostic (for CI)
parseora catalog --schema APP install/   # the tables, views and code the scripts create
```

A path is a file or a folder (every `.sql`, `.pks`, `.pkb`, `.prc`, `.fnc`, `.trg`, `.vw`... file under it).

## Python

```python
import parseora

for s in parseora.parse(open("load.sql").read(), version="19c"):
    print(s["line"], s["statement"], s["tables"], [e["message"] for e in s["errors"]])

parseora.tables("INSERT INTO dw.fact SELECT * FROM stg.orders o JOIN stg.lines l USING (id)")
# ['DW.FACT', 'STG.LINES', 'STG.ORDERS']
parseora.split(script)      # [{kind: sql | plsql | sqlplus, text, line, col, command}]
parseora.tokenize(text)     # every token, comments and whitespace included (lossless)
```

What it covers: queries (WITH, joins, PIVOT, MODEL, MATCH_RECOGNIZE, analytics, CONNECT BY...), DML including
multi-table INSERT and MERGE, DDL, every PL/SQL unit and statement, conditional compilation, and SQL*Plus commands.
Unknown input never stops it: errors are reported and the rest is parsed.

Name resolution (what each name refers to), column lineage, code rules and the MetaGraph for AI tools are in
QiVo Studio: `pip install qivo-studio`.

Licence: the QiVo Studio Licence Agreement 1.0 (`LICENSE.md` in the package): free to use, no reverse engineering.
Open-source components: `THIRD_PARTY_NOTICES.md`.

Questions, bugs or ideas: admin@qivo.studio, or [open an issue](https://github.com/qivo-studio/qivo-studio/issues).

