add grepArray and Array.prototype.grep

Author: suchipi

meta/examples/array-grep.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env yavascript
+/// <reference path="../../yavascript.d.ts" />
+
+echo(["abc", "bcd", "def", "cat"].grep(/c/i));
+
+// non-strings are coerced to strings
+echo([2, "ab2", "b2d", "def", "2at"].grep(/2/i));

meta/generated-docs/README.md

@@ -1,3 +1,5 @@
+<!-- meta/generated-docs/README.md is generated from meta/scripts/lib/generated-doc-index.md. Do not make edits to meta/generated-docs/README.md; instead, make them to meta/scripts/lib/generated-doc-index.md and then re-run the build. -->
+
 # YavaScript API Documentation Index
 
 Here is a list of all of YavaScript's builtin APIs, aside from those normally found in ECMAScript.
@@ -46,6 +48,7 @@ Here is a list of all of YavaScript's builtin APIs, aside from those normally fo
 - [`which`]: Find the path to a program on the system
 - [`grepFile`]: Search for matches in a file
 - [`grepString`]: Search for matches in a string
+- [`grepArray`]: Search for matches in an Array
 - [`whoami`]: Get user name/uid/gid
 - [`openUrl`]: Open a file/url using your operating system's default application for that file/url
 
@@ -201,6 +204,7 @@ For convenience, two of the builtin modules from QuickJS are also available as g
 [`which`]: /meta/generated-docs/which.md#which-function
 [`grepFile`]: /meta/generated-docs/grep.md#grepfile-function
 [`grepString`]: /meta/generated-docs/grep.md#grepstring-function
+[`grepArray`]: /meta/generated-docs/grep.md#greparray-function
 [`whoami`]: /meta/generated-docs/whoami.md#whoami-function
 [`openUrl`]: /meta/generated-docs/open-url.md#openurl-function
 [`Path`]: /meta/generated-docs/path.md#path-class
@@ -257,6 +261,7 @@ For convenience, two of the builtin modules from QuickJS are also available as g
 [`JSX`]: /meta/generated-docs/jsx.md#jsx-namespace
 [`yavascript.compilers`]: /meta/generated-docs/yavascript.md#yavascriptcompilers-object-property
 [`String.prototype.grep`]: /meta/generated-docs/grep.md#stringgrep-function-property
+[`Array.prototype.grep`]: /meta/generated-docs/grep.md#arraygrep-function-property
 [`RegExp.escape`]: /meta/generated-docs/regexp-escape.md#regexpconstructorescape-method
 [`String.dedent`]: /meta/generated-docs/string-dedent.md#stringconstructordedent-function-property
 [`bigint`]: /meta/generated-docs/others.md#bigint-bigintconstructor

meta/generated-docs/grep.md

@@ -1,20 +1,29 @@
 - [grepString (function)](#grepstring-function)
   - [grepString(...) (call signature)](#grepstring-call-signature)
   - [grepString(...) (call signature)](#grepstring-call-signature-1)
+- [grepArray (function)](#greparray-function)
+  - [grepArray(...) (call signature)](#greparray-call-signature)
+  - [grepArray(...) (call signature)](#greparray-call-signature-1)
 - [grepFile (function)](#grepfile-function)
   - [grepFile(...) (call signature)](#grepfile-call-signature)
   - [grepFile(...) (call signature)](#grepfile-call-signature-1)
 - [String (interface)](#string-interface)
   - [String.grep (function property)](#stringgrep-function-property)
     - [String.grep(...) (call signature)](#stringgrep-call-signature)
     - [String.grep(...) (call signature)](#stringgrep-call-signature-1)
+- [Array (interface)](#array-interface)
+  - [Array.grep (function property)](#arraygrep-function-property)
+    - [Array.grep(...) (call signature)](#arraygrep-call-signature)
+    - [Array.grep(...) (call signature)](#arraygrep-call-signature-1)
 - [GrepOptions (interface)](#grepoptions-interface)
   - [GrepOptions.inverse (boolean property)](#grepoptionsinverse-boolean-property)
   - [GrepOptions.details (boolean property)](#grepoptionsdetails-boolean-property)
 - [GrepMatchDetail (interface)](#grepmatchdetail-interface)
   - [GrepMatchDetail.lineNumber (number property)](#grepmatchdetaillinenumber-number-property)
-  - [GrepMatchDetail.lineContent (string property)](#grepmatchdetaillinecontent-string-property)
+  - [GrepMatchDetail.lineContent (ItemType property)](#grepmatchdetaillinecontent-itemtype-property)
   - [GrepMatchDetail.matches (RegExpMatchArray property)](#grepmatchdetailmatches-regexpmatcharray-property)
+  - [GrepMatchDetail.index (number property)](#grepmatchdetailindex-number-property)
+  - [GrepMatchDetail.content (ItemType property)](#grepmatchdetailcontent-itemtype-property)
 
 # grepString (function)
 
@@ -25,7 +34,8 @@ the specified pattern, as an array of strings or detail objects.
 - `@param` _pattern_ — The pattern to find. Can be a string or a RegExp.
 - `@param` _options_ — Options which control matching behavior.
 
-See also [grepFile](/meta/generated-docs/grep.md#grepfile-function) and [String.prototype.grep](/meta/generated-docs/grep.md#stringgrep-function-property).
+See also [grepFile](/meta/generated-docs/grep.md#grepfile-function), [grepArray](/meta/generated-docs/grep.md#greparray-function), [String.prototype.grep](/meta/generated-docs/grep.md#stringgrep-function-property),
+and [Array.prototype.grep](/meta/generated-docs/grep.md#arraygrep-function-property).
 
 ```ts
 const grepString: {
@@ -54,16 +64,61 @@ const grepString: {
 (str: string, pattern: string | RegExp, options?: GrepOptions): Array<string>;
 ```
 
+# grepArray (function)
+
+Returns those Array items matching the specified pattern, as either an
+Array of items or an Array of detail objects.
+
+- `@param` _targetArray_ — The Array of strings to search through. Non-strings will be coerced to string during matching.
+- `@param` _pattern_ — The pattern to find. Can be a string or a RegExp.
+- `@param` _options_ — Options which control matching behavior.
+
+See also [grepString](/meta/generated-docs/grep.md#grepstring-function), [grepFile](/meta/generated-docs/grep.md#grepfile-function), [String.prototype.grep](/meta/generated-docs/grep.md#stringgrep-function-property),
+and [Array.prototype.grep](/meta/generated-docs/grep.md#arraygrep-function-property).
+
+```ts
+const grepArray: {
+  <T>(
+    targetArray: Array<T>,
+    pattern: string | RegExp,
+    options: GrepOptions & {
+      details: true;
+    },
+  ): Array<GrepMatchDetail<T>>;
+  <T>(
+    targetArray: Array<T>,
+    pattern: string | RegExp,
+    options?: GrepOptions,
+  ): Array<T>;
+};
+```
+
+## grepArray(...) (call signature)
+
+```ts
+<T>(targetArray: Array<T>, pattern: string | RegExp, options: GrepOptions & {
+  details: true;
+}): Array<GrepMatchDetail<T>>;
+```
+
+## grepArray(...) (call signature)
+
+```ts
+<T>(targetArray: Array<T>, pattern: string | RegExp, options?: GrepOptions): Array<T>;
+```
+
 # grepFile (function)
 
 Reads the file content at `path`, splits it on `\n`, and then returns the
-lines matching the specified pattern, as an array of strings or detail objects.
+lines matching the specified pattern, as an array of strings or detail
+objects.
 
 - `@param` _str_ — The string to search through.
 - `@param` _pattern_ — The pattern to find. Can be a string or a RegExp.
 - `@param` _options_ — Options which control matching behavior.
 
-See also [grepString](/meta/generated-docs/grep.md#grepstring-function) and [String.prototype.grep](/meta/generated-docs/grep.md#stringgrep-function-property).
+See also [grepArray](/meta/generated-docs/grep.md#greparray-function), [grepString](/meta/generated-docs/grep.md#grepstring-function),
+[String.prototype.grep](/meta/generated-docs/grep.md#stringgrep-function-property), and [Array.prototype.grep](/meta/generated-docs/grep.md#arraygrep-function-property).
 
 ```ts
 const grepFile: {
@@ -121,7 +176,8 @@ specified pattern, as an array of strings or detail objects.
 - `@param` _pattern_ — The pattern to find. Can be a string or a RegExp.
 - `@param` _options_ — Options which control matching behavior.
 
-See also [grepString](/meta/generated-docs/grep.md#grepstring-function) and [grepFile](/meta/generated-docs/grep.md#grepfile-function).
+See also [grepString](/meta/generated-docs/grep.md#grepstring-function), [grepArray](/meta/generated-docs/grep.md#greparray-function), [grepFile](/meta/generated-docs/grep.md#grepfile-function), and
+[Array.prototype.grep](/meta/generated-docs/grep.md#arraygrep-function-property).
 
 ```ts
 grep: {
@@ -146,6 +202,56 @@ grep: {
 (pattern: string | RegExp, options?: GrepOptions): Array<string>;
 ```
 
+# Array (interface)
+
+```ts
+interface Array<T> {
+  grep: {
+    (
+      pattern: string | RegExp,
+      options: GrepOptions & {
+        details: true;
+      },
+    ): Array<GrepMatchDetail<T>>;
+    (pattern: string | RegExp, options?: GrepOptions): Array<T>;
+  };
+}
+```
+
+## Array.grep (function property)
+
+Returns those Array items matching the specified pattern, as either an
+Array of items or an Array of detail objects.
+
+- `@param` _pattern_ — The pattern to find. Can be a string or a RegExp.
+- `@param` _options_ — Options which control matching behavior.
+
+See also [grepString](/meta/generated-docs/grep.md#grepstring-function), [grepArray](/meta/generated-docs/grep.md#greparray-function), [grepFile](/meta/generated-docs/grep.md#grepfile-function), and
+[String.prototype.grep](/meta/generated-docs/grep.md#stringgrep-function-property).
+
+```ts
+grep: {
+  (pattern: string | RegExp, options: GrepOptions & {
+    details: true;
+  }): Array<GrepMatchDetail<T>>;
+  (pattern: string | RegExp, options?: GrepOptions): Array<T>;
+};
+```
+
+### Array.grep(...) (call signature)
+
+```ts
+(pattern: string | RegExp, options: GrepOptions & {
+  details: true;
+}): Array<GrepMatchDetail<T>>;
+```
+
+### Array.grep(...) (call signature)
+
+```ts
+(pattern: string | RegExp, options?: GrepOptions): Array<T>;
+```
+
 # GrepOptions (interface)
 
 ```ts
@@ -176,15 +282,17 @@ details?: boolean;
 
 # GrepMatchDetail (interface)
 
-When `grepString`, `grepFile`, or `String.prototype.grep` are called with the
-`{ details: true }` option set, an Array of `GrepMatchDetail` objects is
-returned.
+When `grepString`, `grepArray`, `grepFile`, or `String.prototype.grep` are
+called with the `{ details: true }` option set, an Array of `GrepMatchDetail`
+objects is returned.
 
 ```ts
-declare interface GrepMatchDetail {
+declare interface GrepMatchDetail<ItemType = string> {
   lineNumber: number;
-  lineContent: string;
+  lineContent: ItemType;
   matches: RegExpMatchArray;
+  index: number;
+  content: ItemType;
 }
 ```
 
@@ -194,14 +302,30 @@ declare interface GrepMatchDetail {
 lineNumber: number;
 ```
 
-## GrepMatchDetail.lineContent (string property)
+## GrepMatchDetail.lineContent (ItemType property)
 
 ```ts
-lineContent: string;
+lineContent: ItemType;
 ```
 
 ## GrepMatchDetail.matches (RegExpMatchArray property)
 
 ```ts
 matches: RegExpMatchArray;
 ```
+
+## GrepMatchDetail.index (number property)
+
+Same as lineNumber - 1.
+
+```ts
+index: number;
+```
+
+## GrepMatchDetail.content (ItemType property)
+
+Alias for lineContent.
+
+```ts
+content: ItemType;
+```

meta/scripts/lib/generated-doc-index.md

@@ -1,3 +1,5 @@
+<!-- meta/generated-docs/README.md is generated from meta/scripts/lib/generated-doc-index.md. Do not make edits to meta/generated-docs/README.md; instead, make them to meta/scripts/lib/generated-doc-index.md and then re-run the build. -->
+
 # YavaScript API Documentation Index
 
 Here is a list of all of YavaScript's builtin APIs, aside from those normally found in ECMAScript.
@@ -46,6 +48,7 @@ Here is a list of all of YavaScript's builtin APIs, aside from those normally fo
 - [`which`]: Find the path to a program on the system
 - [`grepFile`]: Search for matches in a file
 - [`grepString`]: Search for matches in a string
+- [`grepArray`]: Search for matches in an Array
 - [`whoami`]: Get user name/uid/gid
 - [`openUrl`]: Open a file/url using your operating system's default application for that file/url
 

meta/scripts/lib/generated-doc-links.json5

@@ -41,6 +41,7 @@
   which: "/meta/generated-docs/which.md#which-function",
   grepFile: "/meta/generated-docs/grep.md#grepfile-function",
   grepString: "/meta/generated-docs/grep.md#grepstring-function",
+  grepArray: "/meta/generated-docs/grep.md#greparray-function",
   whoami: "/meta/generated-docs/whoami.md#whoami-function",
   openUrl: "/meta/generated-docs/open-url.md#openurl-function",
 
@@ -112,6 +113,7 @@
 
   // ECMAScript Extensions
   "String.prototype.grep": "/meta/generated-docs/grep.md#stringgrep-function-property",
+  "Array.prototype.grep": "/meta/generated-docs/grep.md#arraygrep-function-property",
   "RegExp.escape": "/meta/generated-docs/regexp-escape.md#regexpconstructorescape-method",
   "String.dedent": "/meta/generated-docs/string-dedent.md#stringconstructordedent-function-property",
 

meta/tests/src/globals.test.ts

@@ -242,6 +242,7 @@ test("globals", async () => {
    __dirname: string set throws error (GS)
    grepFile: function (CWE)
    grepString: function (CWE)
+   grepArray: function (CWE)
    global: object (CW)
    process: object (CW)
    ",