feature: explain crons closes #53

example/05-explain-crontabs.php

@@ -0,0 +1,35 @@
+<?php
+use GT\Cron\CrontabParser;
+use GT\Cron\CronExplainer;
+
+chdir(dirname(__DIR__));
+require "vendor/autoload.php";
+
+$crontab = <<<'CRON'
+# Explain a few different schedule styles.
+@DAILY printf 'Daily backup.\n'
+*/10s * * * * printf 'Heartbeat tick.\n'
+0 9 * * MON,WED,FRI printf 'Team summary.\n'
+05 01 * MAY SUN#2 printf 'May maintenance window.\n'
+CRON;
+
+$parser = new CrontabParser();
+$explainer = new CronExplainer();
+
+echo "Crontab:" . PHP_EOL;
+echo $crontab . PHP_EOL . PHP_EOL;
+echo "Explanations:" . PHP_EOL;
+
+foreach(explode("\n", $crontab) as $line) {
+	$line = trim($line);
+	if($line === "" || $line[0] === "#") {
+		continue;
+	}
+
+	[$expression, $command] = $parser->parseLine($line);
+	echo $expression
+		. " " . $command
+		. PHP_EOL . "  -> "
+		. $explainer->explain($expression)
+		. PHP_EOL;
+}

example/README.md

@@ -7,6 +7,7 @@ php example/01-run-due-jobs.php
 php example/02-next-job.php
 php example/03-nickname-expressions.php
 php example/04-custom-expression-factory.php
+php example/05-explain-crontabs.php
 ```
 
 Each script embeds its own crontab string so you can read the schedule and the code together.

src/Cli/RunCommand.php

@@ -8,8 +8,11 @@
 use Gt\Cli\Parameter\Parameter;
 use Gt\Cli\Stream;
 use GT\Cron\CronException;
+use GT\Cron\CronExplainer;
 use GT\Cron\CrontabNotFoundException;
+use GT\Cron\CrontabParser;
 use GT\Cron\FunctionExecutionException;
+use GT\Cron\ParseException;
 use GT\Cron\RunnerFactory;
 use GT\Cron\ScriptExecutionException;
 
@@ -45,6 +48,11 @@ public function run(?ArgumentValueList $arguments = null):int {
 			exit(0);
 		}
 
+		if($arguments->contains("explain")) {
+			$this->explainCrontab(file_get_contents($filePath));
+			return 0;
+		}
+
 		$runner->setRunCallback([$this, "cronRunStep"]);
 
 		if($arguments->contains("now")) {
@@ -139,6 +147,28 @@ protected function displayCommandName(string $command):string {
 		return basename(str_replace("\\", "/", $script));
 	}
 
+	protected function explainCrontab(string $contents):void {
+		$parser = new CrontabParser();
+		$explainer = new CronExplainer();
+
+		foreach(explode("\n", $contents) as $line) {
+			$line = trim($line);
+			if($line === "" || $line[0] === "#") {
+				continue;
+			}
+
+			try {
+				[$crontab, $command] = $parser->parseLine($line);
+				$explanation = $explainer->explain($crontab);
+			}
+			catch(ParseException) {
+				throw new ParseException("Invalid syntax: $line");
+			}
+
+			$this->writeLine("$crontab $command\t\t$explanation");
+		}
+	}
+
 	public function getName():string {
 		return "run";
 	}
@@ -179,6 +209,12 @@ public function getOptionalParameterList():array {
 				null,
 				"Check the syntax of the crontab file without running anything."
 			),
+			new Parameter(
+				false,
+				"explain",
+				null,
+				"List the cron jobs and explain when each one will run."
+			),
 			new Parameter(
 				true,
 				"now",