diff --git a/README.md b/README.md index 1dae177..4d1d4a2 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,20 @@ # QuickFort Blueprint Parser -This is a simple library for parsing basic QuickFort blueprints. Only dig -blueprints are implemented. There are no plans to actively work on this project, -but pull requests for new features and layer types will be accepted. +This is a simple library for parsing basic QuickFort blueprints. Only 'dig' blueprints are implemented at this time. -## Example +There are no plans to actively work on this project, but pull requests for new features and layer types will be accepted. -### Usage +## Installation + +The recommended way to install this library is through [Composer](https://getcomposer.org/). + +```bash +composer require swichers/php-quickfort-parser +``` + +## Usage + +The following example demonstrates how to parse a 'dig' blueprint. ```php setBlueprint($blueprint); + +// Check if the blueprint is a valid 'dig' blueprint. +if (!$parser->checkHeader()) { + throw new \Exception('Invalid blueprint type.'); +} + +// Get the parsed layers. $layers = $parser->getLayers(); + +// Get the blueprint header information. +$header = $parser->getHeader(); ``` ### Result +The `$layers` variable will contain a nested array of the parsed blueprint layers: + ```text [ ['d'], @@ -37,6 +60,16 @@ $layers = $parser->getLayers(); ] ``` +The `$header` variable will contain an array of header information: + +```text +[ + 'command' => 'dig', + 'start' => null, + 'comment' => 'A simple dig blueprint', +] +``` + ## Not implemented * Build layer diff --git a/src/Enums/DigCommands.php b/src/Enums/DigCommands.php index 7c7a497..4597164 100644 --- a/src/Enums/DigCommands.php +++ b/src/Enums/DigCommands.php @@ -2,13 +2,39 @@ namespace QuickFort\Enums; +/** + * Enum for dig commands. + * + * @package QuickFort\Enums + */ enum DigCommands: string { + /** + * Dig a tile. + */ case DIG = 'd'; + /** + * Dig a downward staircase. + */ case STAIR_DOWN = 'j'; + /** + * Dig an upward staircase. + */ case STAIR_UP = 'u'; + /** + * Dig an up/down staircase. + */ case STAIR_UPDOWN = 'i'; + /** + * Dig a channel. + */ case CHANNEL = 'h'; + /** + * Dig a ramp. + */ case RAMP = 'r'; + /** + * Remove a designation. + */ case REMOVE = 'x'; } diff --git a/src/Enums/LayerCommands.php b/src/Enums/LayerCommands.php index 32362b1..af23505 100644 --- a/src/Enums/LayerCommands.php +++ b/src/Enums/LayerCommands.php @@ -2,8 +2,19 @@ namespace QuickFort\Enums; +/** + * Enum for layer commands. + * + * @package QuickFort\Enums + */ enum LayerCommands: string { + /** + * Go up one layer. + */ case UP = '#<'; + /** + * Go down one layer. + */ case DOWN = '#>'; } diff --git a/src/Parser/BlueprintParserBase.php b/src/Parser/BlueprintParserBase.php index 1fa03fd..6179730 100644 --- a/src/Parser/BlueprintParserBase.php +++ b/src/Parser/BlueprintParserBase.php @@ -3,31 +3,37 @@ namespace QuickFort\Parser; /** - * Base QuickFort blueprint parser class. + * Base class for QuickFort blueprint parsers. * - * Provides a barebones implementation of QuickFort blueprint CSV parsing. + * This class provides a barebones implementation of a QuickFort blueprint + * parser. It can be extended to create parsers for specific blueprint types, + * such as 'dig' blueprints. + * + * @package QuickFort\Parser */ class BlueprintParserBase implements BlueprintParserInterface { - /** * A key-value array of header information. * - * @var array - * - * @see BlueprintParserInterface::getHeader + * @var array{ + * command: string|null, + * start: array{x: int, y: int, comment: string}|null, + * comment: string|null + * } + * @see BlueprintParserInterface::getHeader() */ protected array $blueprintHeader; /** - * Original blueprint text. + * The original, unprocessed blueprint text. * * @var string */ protected string $originalBlueprint; /** - * The lines of the blueprint, minus the header. + * The lines of the blueprint, with the header line removed. * * @var string[] */ @@ -36,7 +42,7 @@ class BlueprintParserBase implements BlueprintParserInterface /** * BlueprintParserBase constructor. * - * @param null|string $blueprintText A blueprint to initialize with. + * @param string|null $blueprintText The blueprint text to parse. */ public function __construct(?string $blueprintText = null) { @@ -47,10 +53,6 @@ public function __construct(?string $blueprintText = null) /** * {@inheritdoc} - * - * @param string $blueprintText The new blueprint text to use. - * - * @return void */ public function setBlueprint(string $blueprintText): void { @@ -71,12 +73,11 @@ public function setBlueprint(string $blueprintText): void } /** - * Parse a blueprint string into individual lines. + * Parses a blueprint string into individual lines. * - * @param string $text The blueprint to parse into individual lines. + * @param string $text The blueprint text to parse. * - * @return string[] - * The individual lines of the blueprint. + * @return string[] An array of blueprint lines. */ protected function textToLines(string $text): array { @@ -87,14 +88,15 @@ protected function textToLines(string $text): array } /** - * Parse a blueprint line for header information. + * Parses a blueprint line for header information. * - * @param string $line The line to parse header information from. + * The header line is expected to start with a '#' character, followed by + * the command, and optional start coordinates and a comment. * - * @return array - * An array of header information. + * @param string $line The line to parse for header information. * - * @see BlueprintParserInterface::getHeader + * @return array An array of header information. + * @see BlueprintParserInterface::getHeader() */ protected function parseLineAsHeader(string $line): array { @@ -167,9 +169,6 @@ protected function parseLineAsHeader(string $line): array /** * {@inheritdoc} - * - * @return string - * The blueprint text. */ public function getBlueprint(): string { @@ -178,9 +177,6 @@ public function getBlueprint(): string /** * {@inheritdoc} - * - * @return array - * A key-value array of header information. */ public function getHeader(): array { @@ -189,9 +185,6 @@ public function getHeader(): array /** * {@inheritdoc} - * - * @return array[] - * A nested array of processed blueprint layers. */ public function getLayers(): array { @@ -199,10 +192,11 @@ public function getLayers(): array } /** - * Process blueprint lines into map layers. + * Processes the blueprint lines into a nested array of layers. * - * @return array[] - * A nested array of processed blueprint layers. + * @return array>> A nested array of + * processed blueprint + * layers. */ protected function processLines(): array { @@ -225,11 +219,11 @@ protected function processLines(): array /** * Groups blueprint lines by the layer they belong to. * - * @param array $lines An array of blueprint lines. + * @param string[] $lines An array of blueprint lines. * - * @return array[] - * An array of blueprint lines grouped into arrays for the layer they - * belong to. + * @return array> An array of blueprint lines, + * grouped into a nested array by + * layer. */ protected function groupLinesByLayer(array $lines): array { @@ -255,10 +249,10 @@ protected function groupLinesByLayer(array $lines): array /** * Reorders blueprint layers based on layer up or down commands. * - * @param array $layers A nested array of blueprint layers. + * @param array> $layers A nested array of blueprint + * layers. * - * @return array[] - * The original layers reordered by their layer up and down commands. + * @return array> The reordered layers. */ protected function adjustLayerOrder(array $layers): array { @@ -290,12 +284,14 @@ protected function adjustLayerOrder(array $layers): array } /** - * Process the given layer lines into individual commands. + * Processes the given layer lines into individual commands. * - * @param array[] $layers An array of layers and their lines. + * @param array> $layers An array of layers and their + * lines. * - * @return array[] - * An array of layers and their individual commands. + * @return array>> An array of layers and + * their individual + * commands. */ protected function processLayerLines(array $layers): array { @@ -313,14 +309,18 @@ protected function processLayerLines(array $layers): array /** * Expands command area expansions found in the given layers. * - * Turns d(2x2) into: - * d,d - * d,d + * For example, a command 'd(2x2)' will be expanded into a 2x2 grid of 'd' + * commands. * - * @param array[] $layers The layers to find area expansions within. + * @param array>> $layers The layers to + * process for + * area + * expansions. * - * @return array[] - * The layers with their area expansions replaced by individual commands. + * @return array>> The layers with their + * area expansions + * replaced by individual + * commands. */ protected function processAreaExpansions(array $layers): array { @@ -347,12 +347,13 @@ protected function processAreaExpansions(array $layers): array } /** - * Parse a blueprint line for available commands. + * Parses a blueprint line into an array of commands. + * + * This method filters out any commands that are not allowed. * - * @param string $line The blueprint line to parse commands from. + * @param string $line The blueprint line to parse. * - * @return string[] - * The parsed, filtered, and normalized commands. + * @return string[] An array of commands. */ protected function parseLine(string $line): array { diff --git a/src/Parser/Command.php b/src/Parser/Command.php index 78da704..208d62c 100644 --- a/src/Parser/Command.php +++ b/src/Parser/Command.php @@ -6,33 +6,39 @@ use QuickFort\Enums\LayerCommands; /** - * Class Command + * Represents a command in a QuickFort blueprint. * - * Parses a command string and provides methods to help use it. + * This class parses a command string, which can be a simple command like 'd' + * or a command with an expansion like 'd(3x3)'. It provides methods to inspect + * the command and its properties. + * + * @package QuickFort\Parser */ class Command { - /** - * The command. + * The command string, without any expansion data. * * @var string */ protected string $command; /** - * A keyed array (x,y) of expansion data. + * An array containing the expansion data for the command. + * + * The array has two keys: 'x' and 'y', representing the expansion in the + * x and y directions. * - * @var array + * @var array{x: int, y: int} */ protected array $expansion; /** * Command constructor. * - * Expects a simple command like 'd' or an expansion syntax like 'd(3x3)'. - * - * @param string $text Text to parse into command data. + * @param string $text The command string to parse. This can be a simple + * command like 'd' or a command with an expansion + * like 'd(3x3)'. */ public function __construct(string $text) { @@ -41,12 +47,13 @@ public function __construct(string $text) } /** - * Normalize the given text. + * Normalizes the given command text. + * + * This method converts the command text to lowercase and trims whitespace. * - * @param string $text The text to normalize. + * @param string $text The command text to normalize. * - * @return string - * The normalized text. + * @return string The normalized command text. */ protected function normalizeText(string $text): string { @@ -54,9 +61,12 @@ protected function normalizeText(string $text): string } /** - * Parses text into command data. + * Parses the normalized command text into its constituent parts. + * + * This method sets the `command` and `expansion` properties based on the + * given command text. * - * @param string $text The text to parse into command data. + * @param string $text The normalized command text to parse. * * @return void */ @@ -74,9 +84,12 @@ protected function parseTextToCommand(string $text): void } /** - * Parses command text that contains an expansion marker + * Parses command text that contains an expansion marker. * - * @param string $text The text to parse into command data. + * For example, 'd(2x3)' would be parsed into the command 'd' and the + * expansion array ['x' => 2, 'y' => 3]. + * + * @param string $text The command text with an expansion to parse. * * @return void */ @@ -86,16 +99,15 @@ protected function parseTextWithExpansion(string $text): void $xy_values = explode('x', $parts[1]); $this->command = $parts[0]; $this->expansion = [ - 'x' => $xy_values[0], - 'y' => $xy_values[1], + 'x' => (int) $xy_values[0], + 'y' => (int) $xy_values[1], ]; } /** - * Check if the command is an up layer navigation. + * Checks if the command is a layer up command. * - * @return bool - * Returns true if the command moves up a layer. + * @return bool True if the command is a layer up command, false otherwise. */ public function isLayerUp(): bool { @@ -103,10 +115,9 @@ public function isLayerUp(): bool } /** - * Check if the command is a down layer navigation. + * Checks if the command is a layer down command. * - * @return boolean - * Returns true if the command moves down a layer. + * @return bool True if the command is a layer down command, false otherwise. */ public function isLayerDown(): bool { @@ -114,10 +125,10 @@ public function isLayerDown(): bool } /** - * Check if the command is allowed. + * Checks if the command is an allowed dig command. * - * @return bool - * Returns true if the command is an allowed command. + * @return bool True if the command is an allowed dig command, false + * otherwise. */ public function isAllowedCommand(): bool { @@ -125,10 +136,11 @@ public function isAllowedCommand(): bool } /** - * Check if the command results in no operation. + * Checks if the command is a no-op. + * + * No-op commands are characters that are ignored by the parser. * - * @return bool - * Returns true if there is no operation to perform. + * @return bool True if the command is a no-op, false otherwise. */ public function isNoOp(): bool { @@ -138,10 +150,9 @@ public function isNoOp(): bool } /** - * Check if the command was a comment. + * Checks if the command is a comment. * - * @return bool - * Returns true if the command is a comment. + * @return bool True if the command is a comment, false otherwise. */ public function isComment(): bool { @@ -149,12 +160,12 @@ public function isComment(): bool } /** - * Get the formatted command string. + * Gets the formatted command string, including expansion information. * - * Will include expansion information. + * For example, a dig command with an expansion of 2x3 would be returned as + * 'd(2x3)'. * - * @return string - * The formatted command string. + * @return string The formatted command string. */ public function getFormatted(): string { @@ -173,10 +184,12 @@ public function getFormatted(): string } /** - * Check if the command has expansion information. + * Checks if the command has an expansion. + * + * An expansion is considered to be present if the expansion in the x or y + * direction is greater than 1. * - * @return bool - * Returns true if the command has worthwhile expansion information. + * @return bool True if the command has an expansion, false otherwise. */ public function hasExpansion(): bool { @@ -184,10 +197,9 @@ public function hasExpansion(): bool } /** - * Gets command expansion information. + * Gets the command expansion information. * - * @return array[] - * A key-value array of x and y data. + * @return array{x: int, y: int} A key-value array of x and y data. */ public function getExpansion(): array { @@ -195,12 +207,9 @@ public function getExpansion(): array } /** - * Get the command. + * Gets the command string, without any expansion information. * - * Will not return expansion information. - * - * @return string - * The command text. + * @return string The command string. */ public function getCommand(): string { @@ -208,10 +217,11 @@ public function getCommand(): string } /** - * Return the command as a string. + * Returns the command as a string. + * + * This is an alias for getCommand(). * - * @return string - * The command. + * @return string The command string. */ public function __toString(): string { diff --git a/src/Parser/Dig.php b/src/Parser/Dig.php index e991679..94cf58d 100644 --- a/src/Parser/Dig.php +++ b/src/Parser/Dig.php @@ -3,18 +3,20 @@ namespace QuickFort\Parser; /** - * QuickFort Dig blueprint parser implementation. + * A QuickFort blueprint parser for 'dig' blueprints. * - * Provides dig specific functionality for blueprint parsing. + * This class extends the BlueprintParserBase to provide functionality specific + * to 'dig' blueprints. + * + * @package QuickFort\Parser */ class Dig extends BlueprintParserBase { - /** - * Check if the header is valid for this type of parser. + * Checks if the blueprint header is valid for a 'dig' blueprint. * - * @return bool - * Returns true if the blueprint is a dig command. + * @return bool True if the blueprint is a 'dig' blueprint, false + * otherwise. */ public function checkHeader(): bool {