Merge pull request #1 from marihachi/develop

0.3.0

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "develop" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "main", "develop" ]
 
 jobs:
   test:

CHANGELOG.md

@@ -1,14 +0,0 @@
-## 0.2.0
-
-- API: Rename class `Carol` -> `Pattern`
-- API: Rename function `regex()` -> `pattern()`
-- API: Reanme function `.build()` -> `.toRegex()`
-- API: Remove orverload `seq(Pattern)`
-- API: Add overload `pattern(string)`
-- API: Remove orverload `pattern(RegExp[])`
-- API: Improve error messages.
-- other: rename library filenames.
-
-## 0.1.0
-
-Initial Release.

README.md

@@ -4,19 +4,22 @@ We build a RegExp object by combining functions.
 
 ## Example
 ```js
-import * as C from 'carol-js';
+import carol from 'carol-js';
 
-const regex = C.seq([
-  C.pattern(/hello/),
-  C.pattern(/ /),
-  C.pattern(/world/),
-  C.pattern(/!/).many0(),
-]).many1().toRegex();
+const regex = carol.seq([
+  carol(/hello/),
+  carol(/ /),
+  carol(/world/),
+  carol(/!/).many(1),
+]).many().toRegex();
 
-assert.strictEqual(regex.source, '(?:hello world(?:!)*)+');
-assert.strictEqual(regex.test('hello world!hello world!!hello world!!!'), true);
+assert.strictEqual(regex.source, '(?:hello world(?:!)+)*');
 ```
 
+## Documents
+- [API list](https://github.com/marihachi/carol-js/blob/1e432a782c70e8ce112e4ea0f7d29410407141d3/doc/api.md)
+- [Usage](https://github.com/marihachi/carol-js/blob/1e432a782c70e8ce112e4ea0f7d29410407141d3/doc/usage.md)
+
 ## Installation
 ```sh
 npm i carol-js

doc/api.md

@@ -1,36 +1,40 @@
-## Regex pattern
-```js
-C.pattern(/[a-z]/);
-C.pattern('[a-z]');
+# API
+
+## function: carol
+```ts
+function carol(source: string | RegExp): Pattern;
+```
+
+## function: seq
+```ts
+function seq(patterns: Pattern[]): Pattern;
+```
+
+## class: Pattern
+```ts
+class Pattern {
+  constructor(source: string);
+}
 ```
 
-## Convert to a Regex
-```js
-C.pattern(/[a-z]/).toRegex();
+### method: Pattern.many
+```ts
+function many(min?: number, greedy?: boolean): Pattern;
+function many(min: number, max: number, greedy?: boolean): Pattern;
+function many(opts: { min?: number, max?: number, greedy?: boolean, length?: number }): Pattern;
 ```
 
-## Pattern sequence
-```js
-C.seq([
-  C.pattern(/[a-z]/),
-  C.pattern(/[0-9]/),
-]);
+### method: Pattern.option
+```ts
+function option(greedy?: boolean): Pattern;
 ```
 
-## Repeat pattern
-```js
-C.pattern(/[a-z]/).many0();
-C.pattern(/[a-z]/).many1();
-C.pattern(/[a-z]/).many(2);
-C.pattern(/[a-z]/).many(2, 4);
-C.pattern(/[a-z]/).manyJust(2);
+### method: Pattern.capture
+```ts
+function capture(): Pattern;
 ```
 
-## Capture input string
-```js
-C.seq([
-  C.pattern(/[a-z]+/),
-  C.pattern(/-/),
-  C.pattern(/[0-9]+/).capture(),
-]);
+### method: Pattern.toRegex
+```ts
+function toRegex(flags?: Flag | Flag[]): RegExp;
 ```

doc/usage.md

@@ -0,0 +1,44 @@
+# Usage
+
+## New carol pattern
+```js
+carol(/[a-z]/);
+carol('[a-z]');
+```
+
+## Convert to a Regex
+```js
+carol(/[a-z]/).toRegex();
+```
+
+## Pattern sequence
+```js
+carol.seq([
+  carol(/[a-z]/),
+  carol(/[0-9]/),
+]);
+```
+
+## Repeat pattern
+```js
+carol(/[a-z]/).many(0); // *
+carol(/[a-z]/).many(1); // +
+carol(/[a-z]/).many(2); // {2,}
+carol(/[a-z]/).many(2, 4); // {2,4}
+carol(/[a-z]/).many({ length: 2 }); // {2}
+carol(/[a-z]/).many(2, 2); // {2}
+```
+
+## Optional pattern
+```js
+carol(/[a-z]/).option();
+```
+
+## Capture input string
+```js
+carol.seq([
+  carol(/[a-z]+/),
+  carol(/-/),
+  carol(/[0-9]+/).capture(),
+]);
+```

lib/carol.d.ts

@@ -25,65 +25,63 @@ SOFTWARE.
 ---------------------------------------------------------------------------*/
 
 /**
- * RegExp flag
-*/
-export type Flag = 'g' | 'i' | 'd' | 'm' | 's' | 'u' | 'y';
-
-/**
- * Pattern Model
+ * Creates a new pattern from a RegExp or regex string.
 */
-export declare class Pattern {
-  source: string;
-
-  /**
-   * Constructor
-  */
-  constructor(source: string);
-
-  /**
-   * Creates a new pattern that repeats the pattern with `*`.
-  */
-  many0(greedy?: boolean): Pattern;
-
-  /**
-   * Creates a new pattern that repeats the pattern with `+`.
-  */
-  many1(greedy?: boolean): Pattern;
+declare function carol(source: string | RegExp): carol.Pattern;
+export default carol;
 
+declare namespace carol {
   /**
-   * Creates a new pattern that repeats the pattern with `{count}`.
+   * RegExp flag
   */
-  manyJust(count: number): Pattern;
+  export type Flag = 'g' | 'i' | 'd' | 'm' | 's' | 'u' | 'y';
 
   /**
-   * Creates a new pattern that repeats the pattern with `{min,}`.
+   * Creates a new pattern from a pattern sequence.
+   * @param patterns pattern sequence
   */
-  many(min: number, greedy?: boolean): Pattern;
+  export function seq(patterns: Pattern[]): Pattern;
 
   /**
-   * Creates a new pattern that repeats the pattern with `{min,max}`.
+   * Pattern Model
   */
-  many(min: number, max: number, greedy?: boolean): Pattern;
-
-  /**
-   * Capture the pattern.
-  */
-  capture(): Pattern;
-
-  /**
-   * Build a RegExp from the pattern.
-   * @param flags regex flags
-  */
-  toRegex(flags?: Flag | Flag[]): RegExp;
+  export class Pattern {
+    source: string;
+
+    /**
+     * Constructor
+    */
+    constructor(source: string);
+
+    /**
+     * Creates a new pattern that repeats the pattern.
+    */
+    many(min?: number, greedy?: boolean): Pattern;
+
+    /**
+     * Creates a new pattern that repeats the pattern.
+    */
+    many(min: number, max: number, greedy?: boolean): Pattern;
+
+    /**
+     * Creates a new pattern that repeats the pattern.
+    */
+    many(opts: { min?: number, max?: number, greedy?: boolean, length?: number }): Pattern;
+
+    /**
+     * Create a new pattern that is allowed to not match the pattern.
+    */
+    option(greedy?: boolean): Pattern;
+
+    /**
+     * Capture the pattern.
+    */
+    capture(): Pattern;
+
+    /**
+     * Build a RegExp from the pattern.
+     * @param flags regex flags
+    */
+    toRegex(flags?: Flag | Flag[]): RegExp;
+  }
 }
-
-/**
- * Creates a new pattern from a RegExp or regex string.
-*/
-export declare function pattern(source: string | RegExp): Pattern;
-
-/**
- * Creates a new pattern from a pattern sequence.
- * @param patterns pattern sequence
-*/
-export declare function seq(patterns: Pattern[]): Pattern;