First Documentation Write

cobyj33 · cobyj33 · commit 02889845f913 · 2023-04-02T23:41:59.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,7 +1,12 @@
 
 # llcacodec Changelog
 
-# April 1, 2023
+# April 2, 2023: Version 0.1.0
+
+Fixed throws function, as output was returning true when not throwing and false when throwing, which is
+the opposite of what should have been happening
+
+# April 1, 2023: Version 0.1.0
 
 Changed all functions with "PlainText" in the name to "Plaintext" instead
 
@@ -11,7 +16,9 @@ Changed name to just be llcacodec from llcacodec.js
 
 Added RLE File Writing
 
-## March 30, 2023
+Fixed Life 1.05 Reading
+
+## March 30, 2023: Version 0.1.0
 
 Removed public api function readLifeFileLiveCoordinates. Now all file types return coordinates, and they can be read through readLifeFile(string, format).liveCoordinates
 
diff --git a/DEV_DOCUMENTATION.md b/DEV_DOCUMENTATION.md
@@ -0,0 +1,31 @@
+
+# llcacodec 0.1.0 Developer Documentation
+
+Currently unwritten, will be here soon.
+
+## Test data downloads
+
+Here will reside some links to test files to download that can be read by llcacodec. Feel free to add any new links
+that could provide more data.
+
+[Life Page Links](http://conwaylife.com/ref/DRH/lifelinks.html)
+
+[Conway Life Wiki Pattern Index](https://conwaylife.com/patterns/)
+[Zip File for all patterns found on Conway Life Wiki](https://conwaylife.com/patterns/all.zip)
+
+[Alan Hensel lifep](www.ibiblio.org/lifepatterns/lifep.zip)
+[Alan Hensel lifebc](www.ibiblio.org/lifepatterns/lifebc.zip)
+[Alan Hensel lifepw](www.ibiblio.org/lifepatterns/lifepw.zip)
+[Stamp Collection](http://conwaylife.com/ref/DRH/stamps.html)
+[Dean Hickerson Patterns](http://conwaylife.com/ref/DRH/life.html)
+
+## Further Reading
+
+[Alan Hensel Applet](http://www.ibiblio.org/lifepatterns/lifeapplet.html)
+
+## Unsupported File Formats
+
+- Extended RLE Format | [Golly Source Format Documentation](https://golly.sourceforge.net/Help/formats.html#rle)
+- MacroCell Format | [Golly Source Format Documentation](https://golly.sourceforge.net/Help/formats.html#rle)
+- Rule Format | [Golly Source Format Documentation](https://golly.sourceforge.net/Help/formats.html#rle)
+- Small Object Format | [LifeWiki](https://conwaylife.com/wiki/Small_object_format) [Pentdecathlon](https://web.archive.org/web/20211102020428/http://pentadecathlon.com/objects/definitions/definitions.php)
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
diff --git a/NEXT.md b/NEXT.md
@@ -0,0 +1,6 @@
+
+# An incrementally struck-out list of the next plans for llcacodec
+
+Start: Version 0.1.0
+
+- Create a function to test the validity of life-like strings before calling **readLifeString**. **isValidLifeString**.
diff --git a/README.md b/README.md
@@ -7,11 +7,12 @@ llcacodec - Short for **L**ife-**L**ike **C**ellular **A**utomata **Codec**
 
 ![llacodec logo](assets/llcacodec_logo_112x112.png)
 
+[Documentation, Supported File and Rule Formats](DOCUMENTATION.md)
+
 Decoding and Encoding of Life-Like Cellular Automata Data Files implemented in Typescript
 
-> **NOTE**: cacodec.js is currently in pre-alpha testing, which means that there may be many unaccounted bugs and
+> **NOTE**: llcacodec is currently in pre-alpha testing, which means that there may be many unaccounted bugs and
 > unpredicted behaviors present, as well as that the API is subject to change at any time.
 
-- [Documentation, Supported File and Rule Formats](DOCUMENTATION.md)
 - [cobyj33's automata project page](https://cobyj33.github.io/automata)
 - [cobyj33's automata project github](https://www.github.com/cobyj33/automata)
diff --git a/dist/api.js b/dist/api.js
@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeLifeString = exports.getLifeFileFormat = exports.isLifeStringFormat = exports.readLifeString = exports.getLifeRuleFormat = exports.isValidLifeRule = exports.makeLifeRule = exports.readLifeRule = exports.CONWAY_LIFE_RULE_DATA = void 0;
+exports.writeLifeString = exports.getLifeStringFormat = exports.isLifeStringFormat = exports.readLifeString = exports.getLifeRuleFormat = exports.isValidLifeRule = exports.makeLifeRule = exports.readLifeRule = exports.CONWAY_LIFE_RULE_DATA = void 0;
 const life106_1 = require("./formats/file/life106");
 const plaintext_1 = require("./formats/file/plaintext");
 const rle_1 = require("./formats/file/rle");
@@ -16,7 +16,7 @@ function readLifeString(data, format = "") {
     if (format === undefined) {
         throw new Error("Cannot parse undefined life file");
     }
-    const foundFormat = format === "" ? getLifeFileFormat(data) : format;
+    const foundFormat = format === "" ? getLifeStringFormat(data) : format;
     switch (foundFormat) {
         case "plaintext": return (0, plaintext_1.readPlaintextString)(data);
         case "life 1.06": return (0, life106_1.readLife106String)(data);
@@ -35,7 +35,7 @@ function isLifeStringFormat(data, format) {
     }
 }
 exports.isLifeStringFormat = isLifeStringFormat;
-function getLifeFileFormat(data) {
+function getLifeStringFormat(data) {
     if ((0, life106_1.isLife106String)(data)) {
         return "life 1.06";
     }
@@ -50,7 +50,7 @@ function getLifeFileFormat(data) {
     }
     return "";
 }
-exports.getLifeFileFormat = getLifeFileFormat;
+exports.getLifeStringFormat = getLifeStringFormat;
 function writeLifeString(data) {
     switch (data.format) {
         case "life 1.06": return (0, life106_1.writeLife106String)(data);
diff --git a/dist/types/api.d.ts b/dist/types/api.d.ts
@@ -11,7 +11,7 @@ export declare function readLifeString(data: string, format: "rle"): RLEDecodedD
 export declare function readLifeString(data: string, format: "life 1.05"): Life105DecodedData;
 export declare function readLifeString(data: string): Life106DecodedData | PlaintextDecodedData | RLEDecodedData | Life105DecodedData;
 export declare function isLifeStringFormat(data: string, format: SupportedLifeLikeFormats): boolean;
-export declare function getLifeFileFormat(data: string): SupportedLifeLikeFormats | "";
+export declare function getLifeStringFormat(data: string): SupportedLifeLikeFormats | "";
 type FileFormatData = (Life106EncodingData & {
     format: "life 1.06";
 }) | (PlaintextMatrixWriteData & {
diff --git a/src/api.ts b/src/api.ts
@@ -15,10 +15,10 @@ export function readLifeString(data: string, format: "life 1.05"): Life105Decode
 export function readLifeString(data: string): Life106DecodedData | PlaintextDecodedData | RLEDecodedData | Life105DecodedData
 export function readLifeString(data: string, format: SupportedLifeLikeFormats | "" = ""): Life106DecodedData | PlaintextDecodedData | RLEDecodedData | Life105DecodedData {
     if (format === undefined) {
-        throw new Error("Cannot parse undefined life file")
+        throw new Error("[llcacodec]: Cannot parse undefined life file")
     }
 
-    const foundFormat = format === "" ? getLifeFileFormat(data) : format;
+    const foundFormat = format === "" ? getLifeStringFormat(data) : format;
     switch (foundFormat) {
         case "plaintext": return readPlaintextString(data);
         case "life 1.06": return readLife106String(data);
@@ -37,7 +37,11 @@ export function isLifeStringFormat(data: string, format: SupportedLifeLikeFormat
     }
 }
 
-export function getLifeFileFormat(data: string): SupportedLifeLikeFormats | "" {
+export function getLifeStringFormat(data: string): SupportedLifeLikeFormats | "" {
+    // Note how the tests are ordered. They are ordered from the most simple to identify
+    // to the least simple to identify. Life 1.06 and Life 1.05 can simply be identified by
+    // if their file begins with the appropriate header data. isRLEString is identified by the existence of 
+    // a 
     if (isLife106String(data)) {
         return "life 1.06"
     } else if (isLife105String(data)) {
diff --git a/src/core/util.ts b/src/core/util.ts
@@ -28,9 +28,9 @@ export function isRectangularMatrix(matrix: unknown[][]): boolean {
 export function throws(action: () => unknown): boolean {
     try {
         action();
-        return true;
-    } catch (e) {
         return false;
+    } catch (e) {
+        return true;
     }
 }
 
diff --git a/src/formats/file/life105.ts b/src/formats/file/life105.ts
@@ -37,8 +37,8 @@ export interface Life105DecodedData {
     cellBlocks: Life105CellBlock[]
     liveCoordinates: [number, number][]
     descriptions: string[],
-    ruleString: string | null,
-    rule: LifeRuleData | null,
+    rule: string | null,
+    parsedRule: LifeRuleData | null,
     hashLines: HashLine[]
 }
 
@@ -124,13 +124,13 @@ export function isLife105String(file: string): boolean {
 export function readLife105String(file: string): Life105DecodedData {
     file = file.replace("\r", "")
 
-    const life105FileData: Life105DecodedData = {
+    const life105StringData: Life105DecodedData = {
         format: "life 1.05",
         cellBlocks: [],
         liveCoordinates: [],
         descriptions: [],
-        ruleString: CONWAY_RULE_STRING_SB,
-        rule: CONWAY_LIFE_RULE_DATA(),
+        rule: null,
+        parsedRule: null,
         hashLines: []
     }
 
@@ -148,18 +148,18 @@ export function readLife105String(file: string): Life105DecodedData {
         const trimmedContent = afterID.trim();
 
         if (id === "D") {
-            life105FileData.descriptions.push(trimmedContent)
+            life105StringData.descriptions.push(trimmedContent)
         } else if (id === "R") {
-            life105FileData.ruleString = trimmedContent
-            life105FileData.rule = readLifeRule(trimmedContent)
+            life105StringData.rule = trimmedContent
+            life105StringData.parsedRule = readLifeRule(trimmedContent)
         } else if (id === "N") {
-            life105FileData.ruleString = CONWAY_RULE_STRING_SB
-            life105FileData.rule = CONWAY_LIFE_RULE_DATA()
+            life105StringData.rule = CONWAY_RULE_STRING_SB
+            life105StringData.parsedRule = CONWAY_LIFE_RULE_DATA()
         } else if (id === "P") { // encountered beginning of Cell Block Data
             break;
         }
 
-        life105FileData.hashLines.push({
+        life105StringData.hashLines.push({
             id: id,
             content: trimmedContent,
             full: lines[currentLineIndex].trim()
@@ -172,13 +172,11 @@ export function readLife105String(file: string): Life105DecodedData {
 
     for (let i = 0; i < cellBlockStrings.length; i++) {
         const cellBlock = readLife105CellBlock(cellBlockStrings[i])
-        life105FileData.cellBlocks.push(cellBlock)
-        life105FileData.liveCoordinates.push(...cellBlock.liveCoordinates)
+        life105StringData.cellBlocks.push(cellBlock)
+        life105StringData.liveCoordinates.push(...cellBlock.liveCoordinates)
     }
 
-    life105FileData.liveCoordinates = uniqueNumberPairArray(life105FileData.liveCoordinates)
+    life105StringData.liveCoordinates = uniqueNumberPairArray(life105StringData.liveCoordinates)
 
-    return life105FileData
-}
-
-// function writeLife105String()
+    return life105StringData
+}
diff --git a/src/formats/file/plaintext.ts b/src/formats/file/plaintext.ts
@@ -12,17 +12,6 @@ export interface PlaintextDecodedData {
     liveCoordinates: [number, number][]
 }
 
-export interface PlaintextMetadata {
-    name: string,
-    description: string | string[]
-}
-
-export function isPlaintextMetadata(data: unknown): data is PlaintextMetadata {
-    return typeof(data) === "object" && data !== null &&
-    "name" in data && "description" in data &&
-    typeof(data.name) === "string" && (typeof(data.description) === "string" || isStringArray(data.description))
-}
-
 export interface PlaintextMatrixWriteData {
     name: string,
     description: string | string[]
diff --git a/src/formats/file/rle.ts b/src/formats/file/rle.ts
@@ -141,7 +141,7 @@ export function readRLEData(rlePattern: string, topleft: [number, number] = [0,
 export function readRLEStringHeader(headerLine: string): RLEHeaderDecodedData {
     const trimmed = headerLine.trim();
 
-    const ruleFileHeaderData: RLEHeaderDecodedData = {
+    const rleFileHeaderData: RLEHeaderDecodedData = {
         width: 0,
         height: 0,
         ruleString: null,
@@ -151,24 +151,24 @@ export function readRLEStringHeader(headerLine: string): RLEHeaderDecodedData {
 
     const [, afterXEquals] = readChars(trimmed, "x=")
     const [width, afterWidth] = readCrampedNumber(afterXEquals)
-    ruleFileHeaderData.width = width
+    rleFileHeaderData.width = width
 
     const [, afterYEquals] = readChars(afterWidth, ",y=")
     const [height, afterHeight] = readCrampedNumber(afterYEquals)
-    ruleFileHeaderData.height = height
+    rleFileHeaderData.height = height
 
     if (isNextChars(afterHeight, ",rule=")) {
         const [, afterRule] = readChars(afterHeight, ",rule=")
         const [rule, end] = readNext(afterRule)
         if (isValidLifeRule(rule)) {
-            ruleFileHeaderData.rule = readLifeRule(rule)
-            ruleFileHeaderData.ruleString = rule;
+            rleFileHeaderData.rule = readLifeRule(rule)
+            rleFileHeaderData.ruleString = rule;
         } else {
             throw new Error(`Invalid Rule found in RLE Data while parsing RLE Header Line: "${rule}" ( passed in "${headerLine}") `)
         }
     }
 
-    return ruleFileHeaderData
+    return rleFileHeaderData
 }
 
 export function isRLEString(file: string): boolean {
diff --git a/src/formats/rule/index.ts b/src/formats/rule/index.ts
@@ -1,17 +1,17 @@
 import { CONWAY_RULE_STRING_BS, isValidBSLifeString, makeBSLifeString, readBSRuleString } from "./bs";
 import { CONWAY_RULE_STRING_SB, isValidSBLifeString, makeSBLifeString, readSBRuleString } from "./sb";
 import { CONWAY_LIFE_RULE_INTEGER, isValidLifeRuleInteger, makeLifeRuleInteger, readLifeRuleInteger } from "./int"
-import { CONWAY_LIFE_RULE_DATA, LifeRuleData } from "./ruleData";
+import { CONWAY_LIFE_RULE_DATA, LifeRuleData, isValidLifeRuleData } from "./ruleData";
 import { getErrorMessage } from "../../core/util";
 
-export { CONWAY_LIFE_RULE_DATA, CONWAY_RULE_STRING_BS, CONWAY_RULE_STRING_SB, LifeRuleData, CONWAY_LIFE_RULE_INTEGER }
+export { CONWAY_LIFE_RULE_DATA, CONWAY_RULE_STRING_BS, CONWAY_RULE_STRING_SB, CONWAY_LIFE_RULE_INTEGER, LifeRuleData, isValidLifeRuleData }
 
 export type LifeRuleStringNotation = "b/s" | "s/b" | "int"
 
 export function isValidLifeRule(rule: string, format: "b/s"): boolean
 export function isValidLifeRule(rule: string, format: "s/b"): boolean
 export function isValidLifeRule(rule: number, format: "int"): boolean
-export function isValidLifeRule(rule: string | number, format?: ""): boolean
+export function isValidLifeRule(rule: string | number): boolean
 export function isValidLifeRule(rule: string | number, format: LifeRuleStringNotation | "" = ""): boolean {
     const foundFormat = format === "" ? getLifeRuleFormat(rule) : format
     if (foundFormat === "N/A") {
diff --git a/src/formats/rule/ruleData.ts b/src/formats/rule/ruleData.ts
@@ -2,6 +2,7 @@
 export const CONWAY_LIFE_RULE_DATA = () => ({ birth: [3], survival: [2, 3]})
 export type LifeRuleData = { birth: number[], survival: number[] }
 
+
 export function getLifeRuleDataError({ birth, survival }: LifeRuleData): string | "" {
     if (survival.some(num => num < 0 || num > 8)) {
         return "Survival neighborhood rules must be between 0 and 8";
@@ -45,6 +46,13 @@ export function isLifeRuleDataType(obj: unknown): obj is LifeRuleData {
     return typeof(obj) === "object" && obj !== null && "birth" in obj && "survival" in obj && Array.isArray(obj.birth) && Array.isArray(obj.survival)
 }
 
+/**
+ * 
+ * The validity of a LifeRuleData object is given
+ * 
+ * @param lifeRuleData The LifeRuleData object to validate
+ * @returns Whether the provided LifeRuleData object is valid
+ */
 export function isValidLifeRuleData(lifeRuleData: LifeRuleData): boolean {
     return getLifeRuleDataError(lifeRuleData) === ""
 }
diff --git a/src/formats/rule/sb.ts b/src/formats/rule/sb.ts
@@ -1,4 +1,3 @@
-import { isDigit } from "core/util";
 import { LifeRuleData, getLifeRuleDataError, isValidLifeRuleData } from "./ruleData";
 
 export const CONWAY_RULE_STRING_SB = "23/3"
diff --git a/tests/plaintext.test.ts b/tests/plaintext.test.ts
@@ -34,6 +34,36 @@ describe("Reading", () => {
             })
         })
 
+        it("Acorn with asterisks instead of capitalized O's", () => {
+            expect(readPlaintextString(
+                "!Name: Acorn\n" +
+                "!\n" + 
+                ".........\n" +
+                ".**..***.\n" +
+                "....*....\n" + 
+                "..*......\n" +
+                ".........\n"
+            )).toEqual({
+                format: "plaintext",
+                name: "Acorn",
+                description: [],
+                matrix: [[0, 0, 0, 0, 0, 0, 0, 0, 0],
+                [0, 1, 1, 0, 0, 1, 1, 1, 0],
+                [0, 0, 0, 0, 1, 0, 0, 0, 0],
+                [0, 0, 1, 0, 0, 0, 0, 0, 0],
+                [0, 0, 0, 0, 0, 0, 0, 0, 0]],
+                liveCoordinates: [
+                    [1, -1],
+                    [2, -1],
+                    [5, -1],
+                    [6, -1],
+                    [7, -1],
+                    [4, -2],
+                    [2, -3]
+                ]
+            })
+        })
+
         it("Acorn w/ Description", () => {
             expect(readPlaintextString(
                 "!Name: Acorn\n" +
diff --git a/tests/util.test.ts b/tests/util.test.ts
diff --git a/tsconfig.json b/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`"use strict";`
`2`	`2`	`Object.defineProperty(exports, "__esModule", { value: true });`
`3`		`-exports.writeLifeString = exports.getLifeFileFormat = exports.isLifeStringFormat = exports.readLifeString = exports.getLifeRuleFormat = exports.isValidLifeRule = exports.makeLifeRule = exports.readLifeRule = exports.CONWAY_LIFE_RULE_DATA = void 0;`
	`3`	`+exports.writeLifeString = exports.getLifeStringFormat = exports.isLifeStringFormat = exports.readLifeString = exports.getLifeRuleFormat = exports.isValidLifeRule = exports.makeLifeRule = exports.readLifeRule = exports.CONWAY_LIFE_RULE_DATA = void 0;`
`4`	`4`	`const life106_1 = require("./formats/file/life106");`
`5`	`5`	`const plaintext_1 = require("./formats/file/plaintext");`
`6`	`6`	`const rle_1 = require("./formats/file/rle");`
`@@ -16,7 +16,7 @@ function readLifeString(data, format = "") {`
`16`	`16`	`if (format === undefined) {`
`17`	`17`	`throw new Error("Cannot parse undefined life file");`
`18`	`18`	`}`
`19`		`- const foundFormat = format === "" ? getLifeFileFormat(data) : format;`
	`19`	`+ const foundFormat = format === "" ? getLifeStringFormat(data) : format;`
`20`	`20`	`switch (foundFormat) {`
`21`	`21`	`case "plaintext": return (0, plaintext_1.readPlaintextString)(data);`
`22`	`22`	`case "life 1.06": return (0, life106_1.readLife106String)(data);`
`@@ -35,7 +35,7 @@ function isLifeStringFormat(data, format) {`
`35`	`35`	`}`
`36`	`36`	`}`
`37`	`37`	`exports.isLifeStringFormat = isLifeStringFormat;`
`38`		`-function getLifeFileFormat(data) {`
	`38`	`+function getLifeStringFormat(data) {`
`39`	`39`	`if ((0, life106_1.isLife106String)(data)) {`
`40`	`40`	`return "life 1.06";`
`41`	`41`	`}`
`@@ -50,7 +50,7 @@ function getLifeFileFormat(data) {`
`50`	`50`	`}`
`51`	`51`	`return "";`
`52`	`52`	`}`
`53`		`-exports.getLifeFileFormat = getLifeFileFormat;`
	`53`	`+exports.getLifeStringFormat = getLifeStringFormat;`
`54`	`54`	`function writeLifeString(data) {`
`55`	`55`	`switch (data.format) {`
`56`	`56`	`case "life 1.06": return (0, life106_1.writeLife106String)(data);`
Original file line number	Diff line number	Diff line change
`@@ -28,9 +28,9 @@ export function isRectangularMatrix(matrix: unknown[][]): boolean {`
`28`	`28`	`export function throws(action: () => unknown): boolean {`
`29`	`29`	`try {`
`30`	`30`	`action();`
`31`		`- return true;`
`32`		`- } catch (e) {`
`33`	`31`	`return false;`
	`32`	`+ } catch (e) {`
	`33`	`+ return true;`
`34`	`34`	`}`
`35`	`35`	`}`
`36`	`36`