Metadata-Version: 2.4
Name: cobol-parser
Version: 2.0.1
Summary: A comprehensive COBOL parser for Python with IBM Enterprise COBOL focus
Author-email: Samuel Dion <sam94dion@gmail.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Landparty/cobol-parser
Project-URL: Repository, https://github.com/Landparty/cobol-parser
Project-URL: Bug Tracker, https://github.com/Landparty/cobol-parser/issues
Keywords: cobol,parser,mainframe,ibm,enterprise,legacy
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fast
Requires-Dist: cython>=3.0; extra == "fast"
Provides-Extra: jcl
Requires-Dist: jcl-parser>=2.0.0; extra == "jcl"
Provides-Extra: dev
Requires-Dist: jcl-parser>=2.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: cython>=3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Provides-Extra: profiling
Requires-Dist: psutil>=5.9; extra == "profiling"
Dynamic: license-file

# cobol-parser

Python library for parsing IBM Enterprise COBOL source into an AST. Supports dependency extraction, dead code detection, program flow analysis, and CRUD matrices. 99.1% parse success on the NIST COBOL-85 corpus.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-8000%2B%20passing-green.svg)](#commands)
[![Coverage](https://img.shields.io/badge/coverage-81%25%2B%20enforced-green.svg)](#commands)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)

## Install

```bash
pip install -e ".[dev]"
```

Requires Python 3.11, 3.12, or 3.13.

### Install the CLI globally (uv)

To get the `cobol-parser` command on your `PATH` in any directory, without
setting up a project virtualenv:

```bash
uv tool install .            # from a clone of this repo
uv tool install --editable . # dev mode: picks up code changes without reinstalling
```

`uv tool install` builds the Cython fast-path extensions as part of the
install, so the CLI runs at full speed. Verify it worked from anywhere:

```bash
cobol-parser --version
```

After pulling new commits (non-editable install only), rerun `uv tool install . --reinstall` to update.

## Quick Start

```python
from cobolparser import parse_cobol

result = parse_cobol(source, filename="prog.cbl")
if result.success:
    print(result.ast.program_name)
    print(result.ast.to_json())
```

CLI:

```bash
cobol-parser parse program.cbl
cobol-parser analyze program.cbl      # dynamic call analysis
cobol-parser dead-code program.cbl    # unreferenced paragraphs
cobol-parser lint program.cbl         # every analyzer at once, as one list
```

### Lint a program

`lint` runs several analyzers over a single parse and reports everything they
found as one severity-graded list, instead of one subcommand (and one
re-parse) per concern:

```bash
cobol-parser lint program.cbl --format text
```

```text
program.cbl:6:1: warning [unused-variables] WORKING-STORAGE item WS-NEVER-USED (level 01) is never referenced in the PROCEDURE DIVISION
program.cbl:12:5: error [move-type-check] Illegal MOVE: cannot move NUMERIC item 'WS-COUNTER' to ALPHABETIC item 'WS-ALPHA'
program.cbl:17:1: warning [dead-code] paragraph ORPHAN-PARA is never referenced
3 finding(s): 1 error, 2 warning, 0 info (7 rule(s) ran)
```

`--rule` narrows the run (rule ids are the analyzer subcommand names),
`--min-severity` narrows the output, and `--fail-on error` exits 3 when
anything at that severity was reported — a CI gate that stays distinct from
exit 1, which still means the run itself failed. `--format json` (the
default) additionally reports which rules ran, which raised, and what could
not be checked, so a quiet report is never mistaken for a clean program.

```python
from cobolparser import LintAnalyzer, parse_cobol

report = LintAnalyzer().analyze(parse_cobol(source, filename="prog.cbl").ast)
for finding in report.findings:
    print(finding.rule, finding.severity, finding.message)
```

### Generate test data from a copybook

`gen-data` turns a copybook record layout into a CSV of synthetic records —
one column per elementary field, values that always fit the field's PICTURE,
`USAGE`, and level-88 domain:

```bash
cobol-parser gen-data CUSTOMER.cpy --rows 100 --seed 7 -o customers.csv
```

```python
from cobolparser.generators import CopybookDataGenerator, DataGeneratorOptions

dataset = CopybookDataGenerator(
    DataGeneratorOptions(rows=100, seed=7)
).generate_from_file("CUSTOMER.cpy")
print(dataset.to_csv())
```

A `seed` makes output byte-identical across runs; omit it and the seed that
was drawn is reported on `dataset.seed` (and by `gen-data --describe`) so any
run can be replayed. `REDEFINES` and `FILLER` are excluded by default, and
`OCCURS` tables expand to one column per occurrence.

## Commands

```bash
# Tests
python -m pytest tests/ -v
python -m pytest --cov=cobolparser --cov-report=html

# Lint / format / type-check
ruff check .
black .
mypy cobolparser/
```

## Documentation

Full reference: [`.okf/index.md`](.okf/index.md)

## License

GNU Affero General Public License v3.0 or later — Copyright © 2026 Samuel Dion. See [LICENSE](LICENSE).
