Metadata-Version: 2.4
Name: cronslate
Version: 0.1.0
Summary: ANTLR4-powered cron expression translator and scheduler
Author-email: NickyWu <nickywu123@example.com>
License: MIT
Keywords: cron,crontab,scheduler,antlr4,translator
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: antlr4-python3-runtime>=4.13.0
Dynamic: license-file

# cronslate

ANTLR4-powered cron expression translator and scheduler.

## Features

- Parse standard 5-field cron expressions (minute hour day month weekday)
- Translate cron expressions to human-readable descriptions
- Compute next run time
- Support for: `*`, `*/N`, `N-M`, `N-M/S`, `N,W`, aliases (JAN-DEC, MON-SAT)
- Built-in scheduler engine
- CLI tool

## Install

```bash
pip install cronslate
```

## Quick Start

### As a library

```python
from cronslate import parse, describe, next_run

# Parse
expr = parse("*/5 * * * *")

# Translate to human-readable
print(describe(expr))
# "Every 5 minutes"

# Next run time
print(next_run(expr))
# 2026-09-11 16:45:00
```

### CLI

```bash
cronslate "*/5 * * * *"
# Cron:    */5 * * * *
# Desc:    Every 5 minutes
# Next:    2026-09-11 16:45:00

cronslate "0 2 * * * echo backup" --next
# Cron:    0 2 * * * echo backup
# Desc:    At 2:00 AM, running: echo backup
# Next:    2026-09-12 02:00:00

cronslate --interactive
# cron> 0 9-17 * * 1-5
#   -> At 9:00 AM, 10:00 AM, ..., 5:00 PM, on Monday through Friday
```

## Supported Syntax

| Expression | Description |
|---|---|
| `* * * * *` | Every minute |
| `*/5 * * * *` | Every 5 minutes |
| `0 2 * * *` | At 2:00 AM |
| `0,15,30,45 * * * *` | At minutes 0, 15, 30, 45 |
| `0 9-17 * * 1-5` | Weekdays 9 AM to 5 PM |
| `*/15 8-18 * * MON-FRI` | Every 15 min, 8 AM to 6 PM, weekdays |
| `30 3 1 1 *` | 3:30 AM on January 1st |
| `0 0 1 */3 *` | Midnight on the 1st, every 3 months |

## Architecture

```
cronslate/
├── cronslate/
│   ├── __init__.py      # Public API
│   ├── parser.py        # ANTLR4-driven parser
│   ├── translator.py    # Human-readable description
│   ├── scheduler.py     # Scheduler engine
│   ├── generated/       # ANTLR-generated code
│   └── Cron.g4          # ANTLR grammar
├── cli.py               # CLI entry point
├── tests.py             # Test suite
└── pyproject.toml
```

Data flow: `input string -> CronLexer (tokenizer) -> TokenStream -> CronParser (parser) -> parse tree -> CronFieldVisitor (traversal) -> CronExpr AST`

## License

MIT
