Refactor, add extensive README.md, add future planning

src/Program/Builder/ProgramBuilder.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Program\Builder;
+
+use Program\Block;
+use Program\Program;
+use Program\Word;
+use RuntimeException;
+
+class ProgramBuilder
+{
+	/**
+	 * @param Word[] $words
+	 * @return Program
+	 */
+	public function build(array $words): Program
+	{
+		$firstWord = array_shift($words);
+		if (!preg_match('/^N9\d\d\d$/i', $firstWord)) {
+			throw new RuntimeException('Expected program number (N9xxx), got ' . $firstWord);
+		}
+
+		$program = new Program($firstWord->value);
+
+		$blockBuffer = null;
+		while ($word = array_shift($words)) {
+			if ($word->register === 'N') {
+				if (!is_null($blockBuffer)) {
+					$program->addBlock($blockBuffer);
+				}
+				$blockBuffer = new Block($word->value);
+				continue;
+			}
+			$blockBuffer->addWord($word);
+		}
+		if (!is_null($blockBuffer)) {
+			$program->addBlock($blockBuffer);
+		}
+
+		return $program;
+	}
+}

src/Program/Parser/WordParser.php

@@ -1,12 +1,16 @@
 <?php
 
-namespace Program;
+namespace Program\Parser;
 
-use RuntimeException;
+use Program\Word;
 
-class ProgramParser
+class WordParser
 {
-	public function parseFile(string $filename): Program
+	/**
+	 * @param string $filename
+	 * @return Word[]
+	 */
+	public function parseFile(string $filename): array
 	{
 		$lines = explode(PHP_EOL, file_get_contents($filename));
 		$lines = array_filter($lines);
@@ -15,9 +19,12 @@ class ProgramParser
 	}
 
 
-	public function parse(array $lines): Program
+	/**
+	 * @param string[] $lines
+	 * @return Word[]
+	 */
+	public function parse(array $lines): array
 	{
-		// In the first parsing stage, all words are parsed from the file.
 		/** @var Word[] $words */
 		$words = [];
 		foreach ($lines as $line) {
@@ -34,7 +41,6 @@ class ProgramParser
 					$words[] = new Word($wordBuffer['register'], $wordBuffer['value']);
 					$wordBuffer = [];
 					$state = 'NONE';
-					continue;
 				}
 
 				if ('NONE' === $state && ctype_alpha($character)) {
@@ -43,7 +49,7 @@ class ProgramParser
 					continue;
 				}
 
-				if (stripos($line, 'EOF') !== false) {
+				if (strpos($line, 'EOF') !== false) {
 					break 2; // End of program reached
 				}
 
@@ -53,28 +59,6 @@ class ProgramParser
 			}
 		}
 
-		// In the second stage, the words are ordered by N numbers
-		// and shaped into a program
-		$firstWord = array_shift($words);
-		if (!preg_match('/^N9\d\d\d$/i', $firstWord)) {
-			throw new RuntimeException('Expected program number, got ' . $firstWord);
-		}
-		$program = new Program($firstWord->value);
-		$lineBuffer = null;
-		while ($word = array_shift($words)) {
-			if ($word->register === 'N') {
-				if (!is_null($lineBuffer)) {
-					$program->addBlock($lineBuffer);
-				}
-				$lineBuffer = new Block($word->value);
-				continue;
-			}
-			$lineBuffer->addWord($word);
-		}
-		if (!is_null($lineBuffer)) {
-			$program->addBlock($lineBuffer);
-		}
-
-		return $program;
+		return $words;
 	}
 }