senselogic-gson 0.1.0

package/LICENSE.md

@@ -0,0 +1,163 @@
+GNU Lesser General Public License
+=================================
+
+_Version 3, 29 June 2007_
+_Copyright © 2007 Free Software Foundation, Inc. &lt;<http://fsf.org/>&gt;_
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+### 0. Additional Definitions
+
+As used herein, “this License” refers to version 3 of the GNU Lesser
+General Public License, and the “GNU GPL” refers to version 3 of the GNU
+General Public License.
+
+“The Library” refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An “Application” is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A “Combined Work” is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the “Linked
+Version”.
+
+The “Minimal Corresponding Source” for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The “Corresponding Application Code” for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+### 1. Exception to Section 3 of the GNU GPL
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+### 2. Conveying Modified Versions
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+* **a)** under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+* **b)** under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+### 3. Object Code Incorporating Material from Library Header Files
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+* **a)** Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+* **b)** Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+### 4. Combined Works
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+* **a)** Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+* **b)** Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+* **c)** For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+* **d)** Do one of the following:
+    - **0)** Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+    - **1)** Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that **(a)** uses at run time
+a copy of the Library already present on the user's computer
+system, and **(b)** will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+* **e)** Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option **4d0**, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option **4d1**, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+### 5. Combined Libraries
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+* **a)** Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+* **b)** Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+### 6. Revised Versions of the GNU Lesser General Public License
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License “or any later version”
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,70 @@
+![](https://github.com/senselogic/GSON/blob/master/LOGO/gson.png)
+
+# GSON
+
+Granular Structured Object Notation.
+
+## Features
+
+*   Multiline strings
+*   File inclusions
+*   Very fast parsing
+
+## Sample
+
+```
+{
+    "path":
+        "test.json",
+    "text":
+        ′first line
+        second line
+        third line ‗
+        ‗ fourth line
+        fifth line′,
+    "person":
+        {
+            "name":
+                "Jack",
+            "age":
+                48
+        },
+    "personArray":
+        [
+            {
+                "name":
+                    "Mike",
+                "age":
+                    35
+            },
+            {
+                "name":
+                    "Nina",
+                "age":
+                    32
+            },
+            {
+                "name":
+                    "Pete",
+                "age":
+                    38
+            }
+        ],
+    "included":
+        ′‼@included.gson′
+}
+```
+
+## Version
+
+0.1
+
+## Author
+
+Eric Pelzer (ecstatic.coder@gmail.com).
+
+## License
+
+This project is licensed under the GNU Lesser General Public License version 3.
+
+See the [LICENSE.md](LICENSE.md) file for details.

package/building.js

@@ -0,0 +1,278 @@
+// -- FUNCTIONS
+
+function getEscapedLineContent( 
+    text 
+    )
+{
+    return text.replaceAll( '\\', '\\\\' ).replaceAll( '\r', '' );
+}
+
+// ~~
+
+function getMultilineText( 
+    value, 
+    indentationText, 
+    indentationSpaceCount 
+    )
+{
+    let lineArray = value.replaceAll( '\r', '' ).split( '\n' );
+    let lineCount = lineArray.length;
+    let lineIndentationText = indentationText + ' '.repeat( indentationSpaceCount );
+    let multilineText = '′';
+
+    for ( let lineIndex = 0; lineIndex < lineCount; ++lineIndex )
+    {
+        let line = lineArray[ lineIndex ];
+        let startingSpaceCount = line.match( /^\s*/ )[ 0 ].length;
+        let trimmedLine = line.trimEnd();
+        let endingSpaceCount = line.length - trimmedLine.length;
+        let lineContent = trimmedLine.slice( startingSpaceCount );
+        
+        let startingIndentationText;
+
+        if ( startingSpaceCount > 0 )
+        {
+            startingIndentationText = '‗' + ' '.repeat( startingSpaceCount - 1 );
+        }
+        else
+        {
+            startingIndentationText = '';
+        }
+
+        let endingIndentationText;
+
+        if ( endingSpaceCount > 0 )
+        {
+            endingIndentationText = ' '.repeat( endingSpaceCount - 1 ) + '‗';
+        }
+        else
+        {
+            endingIndentationText = '';
+        }
+
+        let encodedLine = startingIndentationText + getEscapedLineContent( lineContent ) + endingIndentationText;
+
+        if ( lineIndex === lineCount - 1 )
+        {
+            encodedLine = encodedLine + '′';
+        }
+
+        if ( lineIndex === 0 )
+        {
+            multilineText += encodedLine;
+        }
+        else
+        {
+            multilineText += '\n' + lineIndentationText + encodedLine;
+        }
+    }
+
+    return multilineText;
+}
+
+// ~~
+
+export function getGsonValueText( 
+    value, 
+    indentationLevel, 
+    indentationSpaceCount, 
+    isPacked 
+    )
+{
+    let indentationText = ' '.repeat( indentationLevel * indentationSpaceCount );
+
+    if ( value === null )
+    {
+        return 'null';
+    }
+    else if ( typeof value === 'boolean' )
+    {
+        if ( value )
+        {
+            return 'true';
+        }
+        else
+        {
+            return 'false';
+        }
+    }
+    else if ( typeof value === 'number' )
+    {
+        if ( Number.isFinite( value ) )
+        {
+            return String( value );
+        }
+        else
+        {
+            return 'null';
+        }
+    }
+    else if ( typeof value === 'string' )
+    {
+        let usePrimeQuote = value.includes( '\n' ) || value.startsWith( '‼' );
+
+        if ( usePrimeQuote )
+        {
+            if ( value.includes( '\n' ) )
+            {
+                if ( isPacked )
+                {
+                    return '′' + getEscapedLineContent( value ).replaceAll( '\n', '\\n' ) + '′';
+                }
+                else
+                {
+                    return getMultilineText( value, indentationText, indentationSpaceCount );
+                }
+            }
+            else
+            {
+                return '′' + getEscapedLineContent( value ) + '′';
+            }
+        }
+        else
+        {
+            return JSON.stringify( value );
+        }
+    }
+    else if ( Array.isArray( value ) )
+    {
+        if ( isPacked )
+        {
+            let elementTextArray = [];
+            let valueArray = value;
+            let elementCount = valueArray.length;
+
+            for ( let elementIndex = 0; elementIndex < elementCount; ++elementIndex )
+            {
+                let element = valueArray[ elementIndex ];
+                let elementText = getGsonValueText( element, 0, indentationSpaceCount, isPacked );
+                elementTextArray.push( elementText );
+            }
+
+            return '[' + elementTextArray.join( ',' ) + ']';
+        }
+        else
+        {
+            let valueindentationText = indentationText + ' '.repeat( indentationSpaceCount );
+            let elementTextArray = [];
+            let valueArray = value;
+            let elementCount = valueArray.length;
+
+            for ( let elementIndex = 0; elementIndex < elementCount; ++elementIndex )
+            {
+                let element = valueArray[ elementIndex ];
+                let elementText = valueindentationText + getGsonValueText( element, indentationLevel + 1, indentationSpaceCount, isPacked );
+                elementTextArray.push( elementText );
+            }
+
+            let inner = elementTextArray.join( ',\n' );
+
+            return '[\n' + inner + '\n' + indentationText + ']';
+        }
+    }
+    else if ( typeof value === 'object' )
+    {
+        let valueByKeyMap = value;
+        let keyArray = Object.keys( valueByKeyMap );
+        let keyCount = keyArray.length;
+
+        if ( isPacked )
+        {
+            let fieldTextArray = [];
+
+            for ( let keyIndex = 0; keyIndex < keyCount; ++keyIndex )
+            {
+                let key = keyArray[ keyIndex ];
+                let pair = JSON.stringify( key ) + ':' + getGsonValueText( valueByKeyMap[ key ], 0, indentationSpaceCount, isPacked );
+                fieldTextArray.push( pair );
+            }
+
+            return '{' + fieldTextArray.join( ',' ) + '}';
+        }
+        else
+        {
+            let keyindentationText = indentationText + ' '.repeat( indentationSpaceCount );
+            let valueindentationText = keyindentationText + ' '.repeat( indentationSpaceCount );
+            let lineArray = [];
+
+            for ( let keyIndex = 0; keyIndex < keyCount; ++keyIndex )
+            {
+                let key = keyArray[ keyIndex ];
+                let keyText = JSON.stringify( key );
+                let childValue = valueByKeyMap[ key ];
+                let isBlock = ( typeof childValue === 'object' && childValue !== null ) || Array.isArray( childValue );
+                let comma;
+
+                if ( keyIndex < keyCount - 1 )
+                {
+                    comma = ',';
+                }
+                else
+                {
+                    comma = '';
+                }
+
+                lineArray.push( keyindentationText + keyText + ':' );
+
+                if ( isBlock )
+                {
+                    let blockText = getGsonValueText( childValue, indentationLevel + 1, indentationSpaceCount, isPacked );
+                    let blockLineArray = blockText.split( '\n' );
+                    let blockLineCount = blockLineArray.length;
+                    let blocakIndentationtext = valueindentationText;
+                    let innerIndentationSpaceCount = ( indentationLevel + 2 ) * indentationSpaceCount;
+                    let contentIndentationText = blocakIndentationtext + ' '.repeat( indentationSpaceCount );
+                    let innerIndentationText = ' '.repeat( innerIndentationSpaceCount );
+                    let indentedLineArray = [];
+
+                    for ( let blockLineIndex = 1; blockLineIndex < blockLineCount; ++blockLineIndex )
+                    {
+                        let blockLine = blockLineArray[ blockLineIndex ];
+                        let indentedLine;
+
+                        if ( blockLine.slice( 0, innerIndentationSpaceCount ) === innerIndentationText )
+                        {
+                            indentedLine = contentIndentationText + blockLine.slice( innerIndentationSpaceCount );
+                        }
+                        else
+                        {
+                            indentedLine = blocakIndentationtext + blockLine.trimStart();
+                        }
+
+                        indentedLineArray.push( indentedLine );
+                    }
+
+                    let indentationTextedBlock = blocakIndentationtext + blockLineArray[ 0 ] + '\n' + indentedLineArray.join( '\n' );
+                    lineArray.push( indentationTextedBlock + comma );
+                }
+                else
+                {
+                    lineArray.push( valueindentationText + getGsonValueText( childValue, indentationLevel + 1, indentationSpaceCount, isPacked ) + comma );
+                }
+            }
+
+            let inner = lineArray.join( '\n' );
+
+            return '{\n' + inner + '\n' + indentationText + '}';
+        }
+    }
+    else
+    {
+        return 'null';
+    }
+}
+
+// ~~
+
+export function getGsonText( value, indentationSpaceCount )
+{
+    if ( indentationSpaceCount === undefined )
+    {
+        indentationSpaceCount = 4;
+    }
+
+    let isPacked = ( indentationSpaceCount === 0 );
+    let spaceCount = isPacked ? 0 : Math.max( 0, indentationSpaceCount );
+
+    return getGsonValueText( value, 0, spaceCount, isPacked );
+}

package/equivalence.js

@@ -0,0 +1,101 @@
+// -- CONSTANTS
+
+export function haveSameValue(
+    firstValue,
+    secondValue
+    )
+{
+    if ( firstValue !== firstValue
+         && secondValue !== secondValue )    // NaN
+    {
+        return true;
+    }
+    else if ( firstValue === secondValue )
+    {
+        return true;
+    }
+    else if ( firstValue == null
+              || secondValue == null )
+    {
+        return firstValue === secondValue;
+    }
+    else if ( firstValue instanceof Map
+              && secondValue instanceof Map )
+    {
+        if ( firstValue.size !== secondValue.size )
+        {
+            return false;
+        }
+        else
+        {
+            for ( let [ firstValueKey, firstValueValue ] of firstValue.entries() )
+            {
+                let entryWasFound = false;
+
+                for ( let [ secondValueKey, secondValueValue ] of secondValue.entries() )
+                {
+                    if ( haveSameValue( firstValueKey, secondValueKey )
+                         && haveSameValue( firstValueValue, secondValueValue ) )
+                    {
+                        entryWasFound = true;
+
+                        break;
+                    }
+                }
+
+                if ( !entryWasFound )
+                {
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+    else if ( Array.isArray( firstValue )
+              && Array.isArray( secondValue ) )
+    {
+        if ( firstValue.length !== secondValue.length )
+        {
+            return false;
+        }
+
+        for ( let valueIndex = 0;
+              valueIndex < firstValue.length;
+              ++valueIndex )
+        {
+            if ( !haveSameValue( firstValue[ valueIndex ], secondValue[ valueIndex ] ) )
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+    else if ( typeof firstValue === 'object'
+              && typeof secondValue === 'object' )
+    {
+        let firstValueKeyArray = Object.keys( firstValue );
+        let secondValueKeyArray = Object.keys( secondValue );
+
+        if ( firstValueKeyArray.length !== secondValueKeyArray.length )
+        {
+            return false;
+        }
+
+        for ( let key of firstValueKeyArray )
+        {
+            if ( !Object.prototype.hasOwnProperty.call( secondValue, key )
+                 || !haveSameValue( firstValue[ key ], secondValue[ key ] ) )
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+    else
+    {
+        return false;
+    }
+}

package/fetching.js

@@ -0,0 +1,105 @@
+// -- FUNCTIONS
+
+export async function fetchFileText(
+    filePath
+    )
+{
+    let response = await fetch( filePath );
+    let fileText = await response.text();
+
+    return fileText;
+}
+
+// ~~
+
+async function getUnprimedFetchedText(
+    primedText,
+    folderPath,
+    primedTextIsProcessed = true,
+    fetchFileTextFunction = fetchFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    if ( primedTextIsProcessed
+         && fetchFileTextFunction !== null
+         && primedText.startsWith( '‼@' ) )
+    {
+        let filePath = folderPath + primedText.slice( 2 );
+        let fileText = fetchFileTextFunction( filePath );
+
+        return await getFetchedJsonText( fileText, filePath, primedTextIsProcessed, fetchFileTextFunction, processPrimedTextFunction );
+    }
+    else if ( primedTextIsProcessed
+              && processPrimedTextFunction !== null
+              && primedText.startsWith( '‼' ) )
+    {
+        return '"' + processPrimedTextFunction( primedText ) + '"';
+    }
+    else
+    {
+        let lineArray = primedText.replaceAll( '\r', '' ).split( '\n' );
+
+        for ( let lineIndex = 0;
+              lineIndex < lineArray.length;
+              ++lineIndex )
+        {
+            lineArray[ lineIndex ]
+                = lineArray[ lineIndex ].trim().replaceAll( '‗', ' ' );
+        }
+
+        return '"' + lineArray.join( '\\n' ) + '"';
+    }
+}
+
+// ~~
+
+export async function getFetchedJsonText(
+    gsonText,
+    filePath,
+    fetchFileTextFunction = fetchFileText,
+    processPrimedTextFunction = processPrimedText,
+    primedTextIsProcessed = true
+    )
+{
+    gsonText = gsonText.replaceAll( '\r', '' ).trim();
+    filePath = filePath.replaceAll( '\\', '/' );
+
+    let folderPath = filePath.slice( 0, filePath.lastIndexOf( '/' ) + 1 );
+    let primedTextArray = gsonText.split( '′' );
+
+    for ( let primedTextIndex = 1;
+          primedTextIndex < primedTextArray.length;
+          primedTextIndex += 2 )
+    {
+        primedTextArray[ primedTextIndex ]
+            = await getUnprimedFetchedText( primedTextArray[ primedTextIndex ], folderPath, primedTextIsProcessed, fetchFileTextFunction, processPrimedTextFunction );
+    }
+
+    return primedTextArray.join( '' );
+}
+
+// ~~
+
+export async function fetchGsonFileText(
+    filePath,
+    primedTextIsProcessed = true,
+    fetchFileTextFunction = fetchFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    let gsonText = await fetchFileTextFunction( filePath );
+
+    return await getFetchedJsonText( gsonText, filePath, primedTextIsProcessed, fetchFileTextFunction, processPrimedTextFunction );
+}
+
+// ~~
+
+export async function fetchGsonFileValue(
+    filePath,
+    primedTextIsProcessed = true,
+    fetchFileTextFunction = fetchFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    return JSON.parse( await fetchGsonFileText( filePath, primedTextIsProcessed, fetchFileTextFunction, processPrimedTextFunction ) );
+}

package/index.js

@@ -0,0 +1,31 @@
+// -- IMPORTS
+
+import { getGsonText } from './building.js';
+import { getDumpText } from './dumping.js';
+import { haveSameValue } from './equivalence.js';
+import { fetchFileText, getFetchedJsonText, fetchGsonFileText, fetchGsonFileValue } from './fetching.js';
+import { readFileText, getReadJsonText, readGsonFileText, readGsonFileValue } from './reading.js';
+import { getTextHash, getTextUuid, getTextTuid, processPrimedText } from './processing.js';
+import { writeFileText, writeGsonValue } from './writing.js';
+
+// -- EXPORTS
+
+export {
+    fetchFileText,
+    fetchGsonFileText,
+    fetchGsonFileValue,
+    getDumpText,
+    getFetchedJsonText,
+    getGsonText,
+    getReadJsonText,
+    getTextHash,
+    getTextTuid,
+    getTextUuid,
+    haveSameValue,
+    processPrimedText,
+    readFileText,
+    readGsonFileText,
+    readGsonFileValue,
+    writeFileText,
+    writeGsonValue
+    };

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "senselogic-gson",
+    "description": "Granular Structured Object Notation.",
+    "version": "0.1.0",
+    "author": "Eric Pelzer <ecstatic.coder@gmail.com>",
+    "license": "LGPL-3.0-only",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/senselogic/GSON.git"
+    },
+    "bugs": {
+        "url": "https://github.com/senselogic/GSON/issues"
+    },
+    "homepage": "https://github.com/senselogic/GSON",
+    "type": "module",
+    "main": "index.js",
+    "files": [
+        "building.js",
+        "equivalence.js",
+        "fetching.js",
+        "index.js",
+        "parsing.js",
+        "processing.js",
+        "reading.js",
+        "writing.js",
+        "test.js",
+        "README.md"
+    ],
+    "keywords": [
+        "gson"
+    ],
+    "dependencies": {
+        "md5": "^2.3.0"
+    },
+    "scripts": {
+        "test": "node test.js"
+    }
+}

package/processing.js

@@ -0,0 +1,105 @@
+// -- IMPORTS
+
+import md5 from 'md5';
+
+// -- CONSTANTS
+
+const
+    isBrowser = ( typeof window !== 'undefined' && typeof window.document !== 'undefined' );
+
+// -- FUNCTIONS
+
+export function getTextHash(
+    text
+    )
+{
+    return md5( text );
+}
+
+// ~~
+
+export function getTextUuid(
+    text
+    )
+{
+    if ( text === '' )
+    {
+        return '';
+    }
+    else
+    {
+        let hash = md5( text );
+
+        return (
+            hash.slice( 0, 8 )
+            + '-'
+            + hash.slice( 8, 12 )
+            + '-'
+            + hash.slice( 12, 16 )
+            + '-'
+            + hash.slice( 16, 20 )
+            + '-'
+            + hash.slice( 20, 32 )
+            );
+    }
+}
+
+// ~~
+
+export function getTextTuid(
+    text
+    )
+{
+    if ( text === '' )
+    {
+        return '';
+    }
+    else
+    {
+        let hash = md5( text );
+        let tuid = '';
+
+        if ( isBrowser )
+        {
+            let buffer = '';
+
+            for ( let byteIndex = 0; byteIndex < hash.length; byteIndex += 2 )
+            {
+                buffer += String.fromCharCode( parseInt( hash.slice( byteIndex, byteIndex + 2 ), 16 ) );
+            }
+
+            tuid = btoa( buffer );
+        }
+        else
+        {
+            tuid = Buffer.from( hash, 'hex' ).toString( 'base64' );
+        }
+
+        return (
+            tuid
+                .replaceAll( '+', '-' )
+                .replaceAll( '/', '_' )
+                .replaceAll( '=', '' )
+            );
+    }
+}
+
+// ~~
+
+export function processPrimedText(
+    primedText
+    )
+{
+    if ( primedText.startsWith( '‼#' ) )
+    {
+        return getTextUuid( primedText.slice( 2 ) );
+    }
+    else if ( primedText.startsWith( '‼%' ) )
+    {
+        return getTextTuid( primedText.slice( 2 ) );
+    }
+    else
+    {
+        return primedText;
+    }
+}

package/reading.js

@@ -0,0 +1,107 @@
+// -- IMPORTS
+
+import { readFileSync } from 'node:fs';
+import { processPrimedText } from './processing.js';
+
+// -- FUNCTIONS
+
+export function readFileText(
+    filePath
+    )
+{
+    return readFileSync( filePath, 'utf8' );
+}
+
+// ~~
+
+function getUnprimedReadText(
+    primedText,
+    folderPath,
+    primedTextIsProcessed = true,
+    readFileTextFunction = readFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    if ( primedTextIsProcessed
+         && readFileTextFunction !== null
+         && primedText.startsWith( '‼@' ) )
+    {
+        let filePath = folderPath + primedText.slice( 2 );
+        let fileText = readFileTextFunction( filePath );
+
+        return getReadJsonText( fileText, filePath, primedTextIsProcessed, readFileTextFunction, processPrimedTextFunction );
+    }
+    else if ( primedTextIsProcessed
+              && processPrimedTextFunction !== null
+              && primedText.startsWith( '‼' ) )
+    {
+        return '"' + processPrimedTextFunction( primedText ) + '"';
+    }
+    else
+    {
+        let lineArray = primedText.replaceAll( '\r', '' ).split( '\n' );
+
+        for ( let lineIndex = 0;
+              lineIndex < lineArray.length;
+              ++lineIndex )
+        {
+            lineArray[ lineIndex ]
+                = lineArray[ lineIndex ].trim().replaceAll( '‗', ' ' );
+        }
+
+        return '"' + lineArray.join( '\\n' ) + '"';
+    }
+}
+
+// ~~
+
+export function getReadJsonText(
+    gsonText,
+    filePath,
+    primedTextIsProcessed = true,
+    readFileTextFunction = readFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    gsonText = gsonText.replaceAll( '\r', '' ).trim();
+    filePath = filePath.replaceAll( '\\', '/' );
+
+    let folderPath = filePath.slice( 0, filePath.lastIndexOf( '/' ) + 1 );
+    let primedTextArray = gsonText.split( '′' );
+
+    for ( let primedTextIndex = 1;
+          primedTextIndex < primedTextArray.length;
+          primedTextIndex += 2 )
+    {
+        primedTextArray[ primedTextIndex ]
+            = getUnprimedReadText( primedTextArray[ primedTextIndex ], folderPath, primedTextIsProcessed, readFileTextFunction, processPrimedTextFunction );
+    }
+
+    return primedTextArray.join( '' );
+}
+
+// ~~
+
+export function readGsonFileText(
+    filePath,
+    primedTextIsProcessed = true,
+    readFileTextFunction = readFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    let gsonText = readFileTextFunction( filePath );
+
+    return getReadJsonText( gsonText, filePath, primedTextIsProcessed, readFileTextFunction, processPrimedTextFunction );
+}
+
+// ~~
+
+export function readGsonFileValue(
+    filePath,
+    primedTextIsProcessed = true,
+    readFileTextFunction = readFileText,
+    processPrimedTextFunction = processPrimedText
+    )
+{
+    return JSON.parse( readGsonFileText( filePath, primedTextIsProcessed, readFileTextFunction, processPrimedTextFunction ) );
+}

package/test.js

@@ -0,0 +1,27 @@
+// -- IMPORTS
+
+import { getGsonText, readGsonFileText, readGsonFileValue, writeFileText } from './index.js';
+
+// -- STATEMENTS
+
+let jsonText = readGsonFileText( '../../../DATA/test.gson' );
+console.log( jsonText );
+writeFileText( 'OUT/processed_test.json', jsonText );
+
+let jsonValue = readGsonFileValue( '../../../DATA/test.gson' );
+console.log( JSON.stringify( jsonValue ) );
+
+let gsonText = getGsonText( jsonValue );
+console.log( gsonText );
+writeFileText( 'OUT/processed_test.gson', gsonText, 4 );
+
+jsonText = readGsonFileText( '../../../DATA/test.gson', false );
+console.log( jsonText );
+writeFileText( 'OUT/unprocessed_test.json', jsonText );
+
+jsonValue = readGsonFileValue( '../../../DATA/test.gson', false );
+console.log( JSON.stringify( jsonValue ) );
+
+gsonText = getGsonText( jsonValue );
+console.log( gsonText );
+writeFileText( 'OUT/unprocessed_test.gson', gsonText, 4 );

package/writing.js

@@ -0,0 +1,25 @@
+// -- IMPORTS
+
+import { writeFileSync } from 'node:fs';
+import { getGsonText } from './building.js';
+
+// -- FUNCTIONS
+
+export function writeFileText(
+    filePath,
+    fileText
+    )
+{
+    writeFileSync( filePath, fileText, 'utf8' );
+}
+
+// ~~
+
+export function writeGsonValue(
+    filePath,
+    value,
+    writeFileTextFunction = writeFileText
+    )
+{
+    writeFileText( filePath, getGsonText( value ) );
+}