@@ -0,0 +1,112 @@
1++++
2+title = "Regular Expressions Library"
3+date = "2022-06-07"
4+
5+[taxonomies]
6+grant_type = [ "Apprenticeship" ]
7+grant_category = [ "Core Dev" ]
8+
9+[extra]
10+image = ""
11+description = "Implement a regular expressions library in Hoon"
12+reward = "3 stars"
13+mentor = "~lagrev-nocfep"
14+assignee = ""
15+completed = false
16+canceled = false
17+work_request_link = "https://airtable.com/shr4qt9t9kz7RaOIa?prefill_Grant+ID=B0177&prefill_Grant+Name=Regular%20Expressions%20Library"
18++++
19+
20+# Regular Expression Library
21+
22+## Overview
23+
24+Regular expressions provide a formal way of matching and validating text structure using a powerful, well-established syntax.
25+
26+While the Hoon standard library provides powerful parsing primitives, these are strongly geared towards parsing Hoon itself. Many developers expect text parsing to be “as simple as” constructing a regular expression and using it to ingest or parse a single token from a given string, or to validate the structure of a string.
27+
28+## Project Requirements
29+
30+We would like a library which supports a variety of regular expression operations; at minimum:
31+
32+1. String search (single matching and multiple matching)
33+2. String parsing and tokenization
34+3. Validation of a string
35+4. Crash on failure-to-parse
36+5. Parse all and mark invalid segments
37+
38+The library should be built on top of the Hoon parser primitives as much as is feasible, but some rules will likely need to be introduced or perhaps recomposed.
39+
40+Regular expression (hereafter “regex”) rules vary slightly across implementations; here we will hew to the POSIX-standard Extended Regular Expression (ERE) syntax (GNU `grep -E`). In case of insufficient specification below, check ERE first.
41+
42+Supported metacharacters should include:
43+
44+| Metacharacter | Description |
45+| `^` | Match starting position in string (line). |
46+| `.` | Match any single character. |
47+| `[ ]` | Match a single character within the brackets. |
48+| `[^ ]` | Match a single character not within the brackets. |
49+| `$` | Match ending position in string (line). |
50+| `( )` | Group series to single element. |
51+| `\n` | Match *n*th marked subexpression matched. |
52+| `*` | Match the preceding element zero or more times. |
53+| `{m,n}` | Match the preceding element at least _m_ and not more than _n_ times. |
54+| `?` | Match the preceding element zero or one time. |
55+| `+` | Match the preceding element one or more times. |
56+| `|` | Allow choice in matching expressions before or after the operator. |
57+
58+Supported character classes should include:
59+
60+- `[:ascii:]` corresponds to `0x0-0x7f`.
61+- `[:alnum:]` corresponds to `A-Za-z0-9`.
62+- `[:alpha:]` corresponds to `A-Za-z`.
63+- `[:blank:]` corresponds to space ` ` and tab `\t`.
64+- `[:cntrl:]` corresponds to `0x0-0x1f0x7f`.
65+- `[:digit:]` corresponds to `0-9`.
66+- `[:graph:]` corresponds to visible characters.
67+- `[:lower:]` corresponds to `a-z`.
68+- `[:print:]` corresponds to visible characters plus space ` `.
69+- `[:punct:]` corresponds to `[]!"#$%&'()*+,./:;<=>?@\^_{|}~-]` (including \` tic).
70+- `[:space:]` corresponds to whitespace characters ` \t\r\n\v\f`.
71+- `[:upper:]` corresponds to `A-Z`.
72+- `[:xdigit:]` corresponds to hexadecimal digits `A-Fa-f0-9`.
73+
74+Perl-style character classes should include:
75+
76+- `\w` represents alphanumeric characters plus `_` cab.
77+- `\W` represents non-word characters.
78+- `\b` represents word boundaries.
79+- `\B` represents non-word boundaries.
80+- `\d` represents digits, `[:digit:]`.
81+- `\D` represents non-digits.
82+- `\s` represents whitespace characters, `[:space:]`.
83+- `\S` represents non-whitespace characters.
84+
85+A meta-character sequence such as the Oracle `(?i)` should support ignoring case. The `(?!...)...` meta-characters should match the say that if the first pattern is not present, then accept the second pattern.
86+
87+You may implement according to any of the common algorithms: DFA, NFA, or backtracking. Backtracking is preferred since it will better facilitate backreferences and other regex features.
88+
89+A Hoonish way to handle a regular expression would be to ingest a string, convert it to a tagged AST, and then allow that to be exported as text as appropriate. You have some flexibility in determining what the internal representation should look like; the JSON representation is a sound basis.
90+
91+The completed library will also include a full test suite for verifying library tool behavior. (We strongly encourage a test-driven development pattern which encourages you to compose such a test suite _first_.)
92+
93+## Future Work
94+
95+Possible extensions which may result from this work include:
96+
97+1. Perl-Compatible Regular Expressions, as both powerful direct library implementation and using PCRE as the basis for jetting regular expressions.
98+2. Unicode support, which is nonstandard but has good exemplars in some other language standard libraries.
99+3. Jetting the regex library, which will require integration into the Hoon standard library as this affects the runtime binary.
100+
101+## Worker Requirements
102+
103+- At least two years’ experience programming, including prior experience using regular expressions.
104+- Experience with Hoon development, such as finishing Hoon School in any format.
105+
106+Candidates that demonstrate the desire and ability to continue working on this project (see [Future Work](https://urbit.org/grants/regex#future-work)) will be given priority.
107+
108+## Timeline
109+
110+If completed within two months of acceptance, the reward is three stars.
111+
112+If completed within four months of acceptance, the reward is two stars.