gobstones / gobstones-core

[GobstonesWeb2] A set of utility tools used through all GobstonesWeb2 repositories.

gobstones-core

A set of utility types, interfaces and classes that are used through all the Gobstones Platform repositories.

Install

Install with npm by using

npm install @gobstones/gobstones-core

Usage

Unless you are developing a library for the Gobstones Platform you probably won't need to use this library directly, as many of the elements in this library are re-exported by other tools. If you are however interesting in using this library directly or you are effectively developing things in the Gobstones Platform, there are several ways how you can use this library.

Main module

The main module is @gobstones/gobstones-core and contains useful classes and abstraction to most code usage in Gobstones. Currently some of the exported utilities are:

• Board related classes and interfaces (Board, Cell, Color, Direction)
• Expectations (The expect function and all it's associated matchers)
• Translator (Mainly the translator class and it's associated behavior)
• SourceReader (A class to solve the problem of locating characters in source input)
• helper tools (Such as a tool for creating matrices, a deepEqual comparison, and tools to flatten/unflatten an object)

Just import then from the main module the tools you want. Check the API for more information on what is exported and how it works.

import { Board } from '@gobstones/gobstones-core';
import { expect } from '@gobstones/gobstones-core';
import { SourceInput, SourceReader } from '@gobstones/gobstones-core';

CLI Module

The CLI module provides tools for constructing a CLI application. It resides on the /cli submodule. It exports mainly the cli type and function. Import it as follows:

import { cli } from '@gobstones/gobstones-core/cli';

Contributing

See our Contributions Guidelines to contribute.

gobstones-core's Issues

Create a SourceReader with functionality from gobstones-parser/Reader.ts

Issue gobstones-parser/#29 asks to move a new SourceReader to gobstones-core. This is the task for such a movement.

Update build configuration to scripts 0.6.x

Internal state for `_inputs` must refine its type

Currently, the private field _inputs has type SourceInput, but it is always converted to an Record<string,string>.
For that reason, there are some castings needed that may be removed.
So, it is a good idea to refine the type of _inputs and eliminate those castings.

Update locale structure for SourceReader

Update gobstones-core to latest version of scripts

Add contextual contents retrieval to Positions

Currently there are 2 kind of operations for content retrieval using positions:

1. retrieve the document contents of the position, as a whole,
2. retrieve a portion of the source input between two given positions.
   However, in order to provide better error reporting, there is a need to get just a few lines before and a few lines after a given position.
   So, operations like contextBefore and contextAfter should be added to DocumentSourcePositions.

Change `SourceRange` by `SourceSpan`

The current implementation has SourceRange as an interface with fields start and end.
As "ranges" are a particular form of defining lists, a better name is SourceSpan.
Also, its implementation must follow the definition of Span currently in gobstones-lang-def/src/Lexer/Tokens.ts.

Refine printing of positions and inputName

The way defined positions are being printed always include the inputName.
However, when the input is given by one single string with no identification, it may be ommited for brevity.
Additionally, printing of the inputName in StringSourcePosition include angle brackets that are redundant in printing of positions.

Add functionality for End Of String processing

Currently, all strings are processed as being just one, skipping immediately from the last char of one string to the first char of the next string (unless the End Of Input is reached).
However, this is inconvenient for several reasons:

• Regions can span across multiple input strings.
• Worse, tokens can span across multiple input strings.
• Tools cannot easily differentiate between different strings (files) in the input, and thus they cannot provide different processing for different files (e.g. modules vs main file, etc.).

Thus,SourceReaders must have the possibility to process End Of String positions.

Prettier problems on Subset.ts

The multi-alternative expression used in lines 17-23 is not properly indented, and produces an error in prettier.
Lines 20 to 23 have to be indented.

URGENT: Problems with new version of scripts...

My local branch fails when executing the following commands:

• npm run build
  The error is produced by Rollup.

  • RollupError: Could not resolve "./Types" from "src/index.ts" (in branch 12-...)
  • RollupError: Could not resolve "./Functions" from "src/index.ts" (in branch main)
    It looks like it is not recognizing the export (as if it were JS instead of TS).

• npm run test
  The problem here is the favicon.

  • Error: ENOENT: no such file or directory, copyfile '/home/fidel/GIT/GobstonesDev/gbs-core/.github/favicon.ico' -> '/home/fidel/GIT/GobstonesDev/gbs-core/root/fidelGIT/GobstonesDev/gbs-core/docs/favicon.ico'
    It looks like there is some problem with the second path...

    Besides, the command produces 2 warningns:

  • [warning] Failed to resolve link to "helpers!Matrix" in comment for GobstonesLang.Board.board.

  • [warning] Failed to resolve link to "Matrix" in comment for Types.

Export SourceReaderErrors, fix some minor problems

At present, SourceReaderErrors are not exported.
However, if they are to be trapped by users, they need to know about them.

Additionally, some minor fixes on translations and prettier issues may be fixed (no need for a whole issue for that).

Refactor to rename "parts" of a Source Input

Currently, the SourceInput parts are named as "Strings", and all operations involving them uses that name (StringSourcePosition, isEndOfString, atEndOfString, getStringPosition and many auxiliary operations).

That name is not completely satisfactory. An alternative is calling them "Files", but many uses do not use actual "files". Another proposal. which I like, is to use "documents". So, to have DocumentPosition, isEndOfDocument, atEndOfDocument, getDocumentPosition, etc. updated in ALL uses (documentation, auxiliaries, etc.)

Create a BiMap with functionality from gobstones-lang-intl/src/helpers/BidirectionalMaps.ts

Bidirectional maps are maps than can be accessed both by key or by value, providing a biyective association between keys and values.
Current implementation in gobstones-lang-intl has errors, and gobstones-core is a better location for it.

Provide a reimplementation of it, called BiMaps, with the same functionality (but with more similarity to Map interface).

There is an outdated reference in API.Translator

In the index.ts of the Translations module, it says:
" If you want to learn about how to translate the Gobstones Language see The Gobstones Language Translation Module."
This reference is outdated, and it must be updated.

Update build to export separated modules for index and cli

Currently the core exports only the main module, but this does not support importing it from cli application.
A separated module should be exported.
Additionally both ESM and CJS modules should be provided so the module may be used in different ways.

Efficiency in API: do not use API operations in other API operations

Using atEndOfInput and atEndOfDocument internally in operations is inefficient.
The reason is that those operations are assuming nothing about the external use, but usually more information is available.
In particular:
this.atEndOfInput() is defined as equivalent to !this._hasCurrentDocument(), and
this.atEndOfDocument() is defined as equivalent to this._hasCurrentDocument() && !this._hasCurrentCharAtCurrentDocument.
Thus, the expression !this.atEnfOfInput() && !this.atEndOfDocument() can be optimized to this._hasCurrentDocument() && this._hasCurrentCharAtCurrentDocument().

The worst case is the use of skip, when skipping several characters, because there may be a lot of extra verifications.
It may be greatly improved by using the internals...

Fix inconsistency on `SourcePosition.toString`

The method toString for SourcePosition has an inconsistency, as it generates a string with @ for DocumentPosition, but without @ for other positions. Additionally delimiters (< and >) are used for some positions, but not for all.
This has to be fixed to provide a uniform look to all positions.

Add Translation Support and CLI App support

[Internal Team]

• Add support for translation.
• Add support for creating CLI Applications with input/output and translation features.

Create a function for deep assign of string typed keys.

The function Object.assign works on a shallow level, assigning only strings on the first level.
When nested objects are used, a similar functionality but working on any depth level may be handy.

For example:

   interface A {
       a1: string;
       a2: {
           a21: string;
           a22: string;
       };
   }
   const defaultA: A = { a1: 'Default A1', a2: { a21: 'Default A21', a22: 'Default A22' } };
   const ej1: A = deepStringAssign<A>(defaultA, { a2: { a21: 'User A21' } });
   // EXPECTED: ej1 === { a1: 'Default A1', a2: { a21: 'User A21', a22: 'Default A22' } };
   const ej2: A = deepStringAssign<A>(defaultA, { a1: 'User A1' },
                                                { a2: { a22: 'User A22' } });
   // EXPECTED: ej2 === { a1: 'User A1', a2: { a21: 'Default A21', a22: 'User A22' } };