Skip to content

Latest commit

 

History

History
117 lines (82 loc) · 4.81 KB

CONTRIBUTING.md

File metadata and controls

117 lines (82 loc) · 4.81 KB
Raw

Contributing

Issues, comments, and pull requests are always welcome!

Writing code

A few general rules:

  • Write unit tests.
  • Strongly type everything (except what is trivially inferred).
  • Document as much as possible but nothing obvious. (No i++; // increase variable)
  • Use an IDE that supports ESLint. This will take care of formatting and give warnings and errors.

Naming conventions

  • Casing
    • Lower camelCase for variables, functions, and parameters.
      • Private methods and variables in a class must have one leading underscore (_).
      • Unused function parameters may have a leading underscore (_).
    • PascalCase for classes, interfaces, types, and type parameters.
    • UPPER_CASE for compile-time constants.
  • Maximum and minimum
    • When referring to a maximum of something, call it maxSomething instead of maximumSomething. Same for "minimum" and "min".
    • When referring to a maximum and minimum to describe a range, call it max and min.
    • When referring to a maximum (without corresponding minimum), call it maximum. Same for "minimum".
  • Assertion vs. Lookaround
    • Always use "assertion" when referring to a lookaround (= lookbehind inclusive or lookahead).
    • Use "lookbehind" and "lookahead" only when referring to either specifically, excluding the other.

Useful commands

  • npm run test Run all tests.
  • npm run test:fast Run all tests except for the regex stress test that takes from 5s to 20s.
  • npm run build Compiles the whole project and creates the final index.{js,d.ts} files in the project's root directory.
  • npm run scripts:debug This will execute the scripts/debug.ts file. This is a quick way to test new or existing features with access to all files in the library.

Project structure

refa/
|-- scripts/
|   `-- ...
|-- src/
|   |-- ast/
|   |   `-- ...
|   |-- iter/
|   |   `-- ...
|   |-- js/
|   |   `-- ...
|   |-- transformers/
|   |   `-- ...
|   `-- ...
|-- tests/
|   `-- ...
|-- CONTRIBUTING.md  // this file
|-- index.{ts,d.ts}  // generated by `npm run build`
|-- package.json
`-- ...

scripts

This folder contains useful scripts when working on refa. Any script can be executed via npm run scripts:<script-name>.

The debug script is particularly useful. It's purpose is to be way to quickly try out things. It as access to all of refa's source files and can be run via npm run scripts:debug. Do not commit changes to this file.

src

This is folder for all files which will be in the compiled build of the library.

The most important files are:

  1. char{set,map}.ts defines the most important classes of refa: CharSet - a sorted interval set used to represent characters - and CharMap - a sorted interval map.
  2. finite-automaton.ts defines interfaces all concrete FA implementations use.
  3. {dfa,nfa}.ts define the concrete implementations of an NFA and DFA.
  4. words.ts includes function to convert from JS strings to number arrays and vise versa among others.

src/ast

This directory includes the definition of refa's RE AST format and simple functions/interfaces for traversal and modification.

src/iter

This directory contains functions that consume and produce graph iterators. Graph iterators are one of refa's core concepts and allow us to implement different algorithms independently from one specific graph representation.

When importing those functions from outside src/iter, it must be done via src/iter/index.ts. It's recommended to import all functions like this:

import * as Iter from "./iter";

From inside src/iter, functions MUST be imported directly from the file they are defined in.

src/js

This is where all JavaScript RegExp-specific logic lives. This is mainly includes a parser to convert RegExp to refa's RE AST format and a function to convert RE AST to JS RegExp.

Files from src/* (except index.ts) are not allowed to import files from src/js. The rest of the library is supposed to be independent from this part of it because it may later be moved to its own package.

src/transformers

This directory contains RE AST transformers. These tools can be used to simplify and change existing RE ASTs.

test

This folder has a similar layout to src. It's supposed to somewhat mirror the file structure of src, so it's easy to find where tests for specific files form src live.

You can run all tests using npm run test (or just npm test).

If you want to run the tests quicker, you can use npm run test:fast. This will run all tests except the stress test which is executed for thousands of regexes.

The helper folder contains functions used to implement tests. This includes useful constant, conversions function, and sets of test regexes.