commit 940cd13d503abd4018c551b328b752144cbf6d37
parent 274a8c8f29d88a696904c80312dbe0c6f0b146e8
Author: Ethan Long <ethandavidlong@gmail.com>
Date: Sun, 9 Jun 2024 21:48:14 +1000
Added a plaintext README for my own git repo
Also added a few things to the READMEs for some clarification.
Diffstat:
| A | README | | | 70 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | README.org | | | 18 | ++++++++++-------- |
2 files changed, 80 insertions(+), 8 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,70 @@
+A toy finite state automaton library & utilities built with Rust
+================================================================
+
+What is this?
+=============
+This is just a toy project that I've been working on to test my knowledge of
+COMP1600 topics (a course at the ANU). It's a very basic library for Rust that
+currently implements only the finite state automaton described in COMP1600.
+
+What is currently implemented:
+==============================
+ * ε-NFAs
+ * NFAs
+ * DFAs
+ * Deterministic wildcard transitions for all automata, any input not in the
+ alphabet (DFA) or with explicit transitions (NFA) follows the wildcard
+ transition.
+ * Regular expressions with a bit of sugar
+ - Current operators are `*`, `+`, `?`, `.`, and `|`.
+ - The following escape sequences: `\*`, `\+`, `\?`, `\.`, `\|`, `\(`, `\)`,
+ and `\\` to map to the characters that are reserved.
+ - Implemented with an LL(1) predictive recursive descent parser.
+ + Correct me if I'm wrong on this
+ * A WASM compilation target with accompanying TypeScript library for use with
+ Node/Bun & in the browser.
+ * A basic demo website of the regex engine and parser.
+
+Goals:
+======
+ - Publish demo to a static page. (Done!)
+ - Rewrite the JSON parsing for DFA, NFA, and ENFA to accept wildcard transitions.
+ - Write tests until I'm satisfied that everything is mostly okay.
+ - Implement Turing automaton.
+ - Implement step-through acceptance rendering.
+
+How do I run it?
+================
+Currently there are no prebuilt binaries beyond the WASM/JavaScript package in `/web/pkg`.
+
+To build the project, you need cargo and rust. I suggest `rustup`.
+
+ cargo build --release
+
+Then to run the binaries:
+
+ cargo run --release --bin <BINNAME> <ARGS>
+
+For a quick start, just run the `regex` binary:
+
+ cargo run --release --bin regex <REGEX> <INPUT>
+
+The regular expression engine will just build an automaton to match input
+strings, either accepting or rejecting the input string `<INPUT>`.
+
+If you want to work directly with the automaton binaries, they accept a path to
+a JSON file describing the automaton. See the `DFAs`, `ENFAs`, and `NFAs`
+directory. _NOTE: The JSON spec was made before a lot of changes involving the
+wildcard transition, so it doesn't yet support that._
+
+If you want to work with the automaton as a library, there is a simple
+`GraphENFA` with methods for building up an ε-NFA, which you can then convert to
+any of the other automaton.
+
+There is a web-demo available to build, this requires Bun for bundling, and
+cargo (note that this is already included pre-built in the repository):
+
+ cd web && bun i && bun run build
+
+If you don't want to run the demo, simply go to
+http://localhost:1313/projects/dfa-regex-engine/demo/
diff --git a/README.org b/README.org
@@ -1,7 +1,7 @@
-#+Title: Toy Finite State Automaton in Rust
+#+Title: A toy finite state automaton library & utilities built with Rust
#+Author: Ethan Long
* What is this?
-This is just a toy project I've been working on to test my knowledge on COMP1600 topics. It's a very basic library for Rust that implements the finite state automaton described in COMP1600.
+This is just a toy project I've been working on to test my knowledge of COMP1600 topics (a course at the ANU). It's a very basic library for Rust that currently implements only the finite state automaton described in COMP1600.
What is currently implemented:
* ε-NFAs
@@ -16,8 +16,8 @@ What is currently implemented:
* A WASM compilation target with accompanying TypeScript library for use with Node & in the browser.
* A basic demo website of the regex engine and parser.
-Goals: [0/1]
- - [ ] Publish demo to a static GitLab page.
+Goals: [1/5]
+ - [X] Publish demo to a static page.
- [ ] Rewrite the JSON parsing for DFA, NFA, and ENFA to accept wildcard transitions.
- [ ] Write tests until I'm satisfied that everything is mostly okay.
- [ ] Implement Turing automaton.
@@ -25,7 +25,7 @@ Goals: [0/1]
* How do I run it?
Currently there are no prebuilt binaries beyond the WASM/JavaScript package in ~/web/pkg~.
-To build the main project, simply go
+To build the project, you need cargo and rust. I suggest `rustup`.
#+begin_src shell
cargo build --release
#+end_src
@@ -38,13 +38,15 @@ For a quick start, just run the ~regex~ binary:
#+begin_src shell
cargo run --release --bin regex <REGEX> <INPUT>
#+end_src
-The ~regex~ is just a simple automaton in this program, it will not search the ~<INPUT>~ string, it will simply tell you if the regex ~<REGEX>~ accepts/directly matches ~<INPUT>~.
+The regular expression engine will just build an automaton to match input strings, either accepting or rejecting the input string ~<INPUT>~.
-If you want to work directly with the automaton binaries, they accept a path to a JSON file describing the automaton. See the ~DFAs~, ~ENFAs~, and ~NFAs~ section. _NOTE: The JSON spec was made before a lot of changes involving the wildcard transition, so it doesn't yet support that._
+If you want to work directly with the automaton binaries, they accept a path to a JSON file describing the automaton. See the ~DFAs~, ~ENFAs~, and ~NFAs~ directory. _NOTE: The JSON spec was made before a lot of changes involving the wildcard transition, so it doesn't yet support that._
If you want to work with the automaton as a library, there is a simple ~GraphENFA~ with methods for building up an ε-NFA, which you can then convert to any of the other automaton.
-There is a web-demo available to build (in future, it will also be hosted somewhere), this requires Bun for bundling, and of course cargo:
+There is a web-demo available to build, this requires Bun for bundling, and cargo (note that this is already included pre-built in the repository):
#+begin_src shell
cd web && bun i && bun run build
#+end_src
+
+If you don't want to run the demo, simply go to http://localhost:1313/projects/dfa-regex-engine/demo/
