[spec] first attempt at a spec rewrite

tc39 · Sep 21, 2023 · 2e3eb89 · 2e3eb89
1 parent d2ff7fe
commit 2e3eb89
Show file tree

Hide file tree

Showing 7 changed files with 156 additions and 32 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,12 @@
+name: Build spec
+
+on: [pull_request, push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: ljharb/actions/node/install@main
+    - run: npm run build
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,20 @@
+name: Deploy gh-pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: ljharb/actions/node/install@main
+    - run: npm run build
+    - uses: JamesIves/[email protected]
+      with:
+        branch: gh-pages
+        folder: build
+        clean: true
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,46 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# Only apps should have lockfiles
+yarn.lock
+package-lock.json
+npm-shrinkwrap.json
+pnpm-lock.yaml
+
+# Build directory
+build
diff --git a/.npmrc b/.npmrc
@@ -0,0 +1 @@
+package-lock=false
diff --git a/package.json b/package.json
@@ -0,0 +1,23 @@
+{
+  "private": true,
+  "name": "proposal-regex-escaping",
+  "description": "Proposal for investigating RegExp escaping for the ECMAScript standard",
+  "scripts": {
+    "start": "npm run build-loose -- --watch",
+    "build": "npm run build-loose -- --strict",
+    "build-loose": "node -e 'fs.mkdirSync(\"build\", { recursive: true })' && ecmarkup --load-biblio @tc39/ecma262-biblio --verbose spec.emu build/index.html --lint-spec"
+  },
+  "homepage": "https://github.com/tc39/proposal-regex-escaping#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tc39/proposal-regex-escaping.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@tc39/ecma262-biblio": "^2.1.2632",
+    "ecmarkup": "^17.1.1"
+  },
+  "engines": {
+    "node": ">= 12"
+  }
+}
diff --git a/spec-ecmarkup.html b/spec-ecmarkup.html
diff --git a/spec.emu b/spec.emu
@@ -0,0 +1,54 @@
+<!doctype html>
+<meta charset="utf8">
+<link rel="stylesheet" href="./spec.css">
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/github.min.css">
+<script src="./spec.js"></script>
+<pre class="metadata">
+title: RegExp.escape
+stage: 1
+contributors: Jordan Harband
+</pre>
+
+<emu-clause id="sec-text-processing" number="22">
+  <h1>Text Processing</h1>
+
+  <emu-clause id="sec-regexp-regular-expression-objects" number="2">
+    <h1>RegExp (Regular Expression) Objects</h1>
+
+    <emu-clause id="sec-properties-of-the-regexp-constructor" number="5">
+      <h1>Properties of the RegExp Constructor</h1>
+
+      <ins>
+      <emu-clause id="sec-regexp.escape" number="2">
+        <h1>RegExp.escape ( _S_ )</h1>
+        <p>This method takes a string and returns a version of it with all control characters escaped. It escapes characters that would otherwise be treated by the regular expressions engine as special meta characters using an escape sequence character.</p>
+        <p>It performs the following steps when called:</p>
+        <p>
+          The phrase "<dfn id="the ASCII punctuators that need escaping">the ASCII punctuators that need escaping</dfn>"
+          denotes the following String value, which consists of every ASCII punctuator except U+005F (LOW LINE):
+          *"(){}[]|,.?\*+-^$=<>\/#&!%:;@~'"`"*.
+        </p>
+
+        <emu-alg>
+          1. Let _str_ be ? ToString(_S_).
+          1. Let _cpList_ be a List containing in order the code points as defined in 6.1.4 of _str_, starting at the first element of _str_.
+          1. Let _toEscape_ be a CharSet containing every character in the ASCII punctuators that need escaping.
+          1. Let _cuList_ be a new empty List.
+          1. For each code point _c_ in _cpList_, do
+            1. If _c_ is the first code point in _cpList_ and _c_ is a DecimalDigit, then
+              1. Append code unit 0x005C (REVERSE SOLIDUS) to cuList.
+              1. Append code unit 0x0078 (LATIN SMALL LETTER X) to cuList.
+            1. Else if _c_ is a CharSetElement of _toEscape_ or is WhiteSpace, then
+              1. Append code unit 0x005C (REVERSE SOLIDUS) to cuList.
+            1. Append the elements of the UTF16Encoding (10.1.1) of c to cuList.
+          1. Return CodePointsToString(_cuList_).
+        </emu-alg>
+
+        <emu-note>
+          <p>`escape` takes a string and escapes it so it can be literally represented as a pattern. In contrast EscapeRegExpPattern (as the name implies) takes a pattern and escapes it so that it can be represented as a string. While the two are related, they do not share the same character escape set or perform similar actions.</p>
+        </emu-note>
+      </emu-clause>
+      </ins>
+    </emu-clause>
+  </emu-clause>
+</emu-clause>