Implement Thompson NFA-based Regular Expressions

CMakeLists.txt

@@ -61,6 +61,7 @@ check_modular("SPECIALMATRICES")
 check_modular("STRINGLIST")
 check_modular("STATS")
 check_modular("SYSTEM")
+check_modular("REGEX")
 
 option(FIND_BLAS "Find external BLAS and LAPACK" ON)
 

doc/specs/index.md

@@ -30,6 +30,7 @@ This is an index/directory of the specifications (specs) for each new module/fea
  - [optval](./stdlib_optval.html) - Fallback value for optional arguments
  - [quadrature](./stdlib_quadrature.html) - Numerical integration
  - [random](./stdlib_random.html) - Probability Distributions random number generator
+ - [regex](./stdlib_regex.html) - Regular expression pattern matching
  - [sorting](./stdlib_sorting.html) - Sorting of rank one arrays
  - [stats](./stdlib_stats.html) - Descriptive Statistics
  - [stats_distributions_uniform](./stdlib_stats_distribution_uniform.html) - Uniform Probability Distribution

doc/specs/stdlib_regex.md

@@ -0,0 +1,138 @@
+---
+title: regex
+---
+
+# Regular Expressions
+
+[TOC]
+
+## Overview
+
+The `stdlib_regex` module provides a pure Fortran regular expression engine
+based on Thompson's NFA (Nondeterministic Finite Automaton) construction.
+It guarantees linear-time matching `O(n × m)` with no backtracking,
+making it safe for use with arbitrary input without risk of catastrophic
+performance degradation.
+
+### Supported Syntax
+
+| Pattern     | Description                          | Example          |
+|-------------|--------------------------------------|------------------|
+| `.`         | Match any single character           | `a.c` → `abc`   |
+| `*`         | Zero or more of preceding element    | `ab*c` → `ac`   |
+| `+`         | One or more of preceding element     | `ab+c` → `abbc` |
+| `?`         | Zero or one of preceding element     | `colou?r`        |
+| `\|`        | Alternation                          | `cat\|dog`       |
+| `(` `)`     | Grouping                             | `(ab)+`          |
+| `[...]`     | Character class                      | `[a-z]`          |
+| `[^...]`    | Negated character class              | `[^0-9]`         |
+| `^`         | Start of string anchor               | `^foo`           |
+| `$`         | End of string anchor                 | `bar$`           |
+| `\d`        | Digit `[0-9]`                        | `\d+`            |
+| `\w`        | Word character `[a-zA-Z0-9_]`        | `\w+`            |
+| `\s`        | Whitespace (space, tab, newline, CR) | `\s+`            |
+| `\`         | Escape next character                | `\.`             |
+
+## `regex_type` - Regular expression type
+
+### Status
+
+Experimental
+
+### Description
+
+A derived type representing a compiled regular expression. It stores the
+internal NFA state graph produced by `regcomp` and is passed to `regmatch`
+for pattern matching.
+
+### Syntax
+
+```fortran
+type(regex_type) :: re
+```
+
+## `regcomp` - Compile a regular expression
+
+### Status
+
+Experimental
+
+### Description
+
+Compiles a regular expression pattern string into a `regex_type` object.
+The compiled object can then be reused for multiple calls to `regmatch`
+without recompilation.
+
+### Syntax
+
+```fortran
+call [[stdlib_regex(module):regcomp(subroutine)]](re, pattern [, status])
+```
+
+### Class
+
+Subroutine
+
+### Arguments
+
+`re`: Shall be of type `regex_type`. It is an `intent(out)` argument.
+The compiled regular expression.
+
+`pattern`: Shall be of type `character(len=*)`. It is an `intent(in)` argument.
+The regular expression pattern string to compile.
+
+`status` (optional): Shall be of type `integer`. It is an `intent(out)` argument.
+Returns 0 on success, or a non-zero value if the pattern is invalid
+(e.g., mismatched parentheses or brackets).
+
+### Example
+
+```fortran
+{!example/regex/example_regex_regcomp.f90!}
+```
+
+## `regmatch` - Match a compiled regular expression
+
+### Status
+
+Experimental
+
+### Description
+
+Searches for the first occurrence of the compiled regular expression `re`
+within the input `string`. If a match is found, `is_match` is set to `.true.`
+and the optional `match_start` and `match_end` arguments are set to
+the 1-based start and end positions of the matched substring.
+
+### Syntax
+
+```fortran
+call [[stdlib_regex(module):regmatch(subroutine)]](re, string, is_match [, match_start, match_end])
+```
+
+### Class
+
+Subroutine
+
+### Arguments
+
+`re`: Shall be of type `regex_type`. It is an `intent(in)` argument.
+A compiled regular expression obtained from `regcomp`.
+
+`string`: Shall be of type `character(len=*)`. It is an `intent(in)` argument.
+The input string to search for a match.
+
+`is_match`: Shall be of type `logical`. It is an `intent(out)` argument.
+Set to `.true.` if a match is found, `.false.` otherwise.
+
+`match_start` (optional): Shall be of type `integer`. It is an `intent(out)` argument.
+The 1-based index of the first character of the match.
+
+`match_end` (optional): Shall be of type `integer`. It is an `intent(out)` argument.
+The 1-based index of the last character of the match.
+
+### Example
+
+```fortran
+{!example/regex/example_regex_regmatch.f90!}
+```

example/CMakeLists.txt

@@ -44,6 +44,9 @@ add_subdirectory(optval)
 if (STDLIB_QUADRATURE)
   add_subdirectory(quadrature)
 endif()
+if (STDLIB_REGEX)
+  add_subdirectory(regex)
+endif()
 add_subdirectory(selection)
 add_subdirectory(sorting)
 add_subdirectory(specialfunctions_gamma)

example/regex/CMakeLists.txt

@@ -0,0 +1,2 @@
+ADD_EXAMPLE(regex_regcomp)
+ADD_EXAMPLE(regex_regmatch)

example/regex/example_regex_regcomp.f90

@@ -0,0 +1,10 @@
+program example_regex_regcomp
+  use stdlib_regex, only: regex_type, regcomp
+  implicit none
+  type(regex_type) :: re
+  integer :: stat
+
+  call regcomp(re, "(cat|dog)s?", stat)
+  if (stat /= 0) error stop "Invalid regex pattern"
+  print *, "Pattern compiled successfully."
+end program example_regex_regcomp

example/regex/example_regex_regmatch.f90

@@ -0,0 +1,25 @@
+program example_regex_regmatch
+  use stdlib_regex, only: regex_type, regcomp, regmatch
+  implicit none
+  type(regex_type) :: re
+  logical :: found
+  integer :: stat, ms, me
+
+  ! Find a sequence of digits
+  call regcomp(re, "[0-9]+", stat)
+  call regmatch(re, "foo123bar", found, ms, me)
+  print "(a,l1,a,i0,a,i0)", "found = ", found, ", ms = ", ms, ", me = ", me
+
+  ! Anchored match
+  call regcomp(re, "^hello", stat)
+  call regmatch(re, "hello world", found)
+  print "(a,l1)", "found = ", found
+  call regmatch(re, "say hello", found)
+  print "(a,l1)", "found = ", found
+
+  ! Alternation with optional suffix
+  call regcomp(re, "(cat|dog)s?", stat)
+  call regmatch(re, "I like cats", found, ms, me)
+  print "(a,l1,a,i0,a,i0)", "found = ", found, ", ms = ", ms, ", me = ", me
+
+end program example_regex_regmatch

src/CMakeLists.txt

@@ -44,6 +44,7 @@ add_subdirectory(datetime)
 ADD_SUBDIR(system)
 
 ADD_SUBDIR(stats)
+ADD_SUBDIR(regex)
 
 add_subdirectory(sparse)
 

src/regex/CMakeLists.txt

@@ -0,0 +1,12 @@
+set(regex_fppFiles
+    )
+
+set(regex_cppFiles
+    )
+
+set(regex_f90Files
+    stdlib_regex.f90
+    )
+
+configure_stdlib_target(${PROJECT_NAME}_regex regex_f90Files regex_fppFiles regex_cppFiles)
+target_link_libraries(${PROJECT_NAME}_regex PUBLIC ${PROJECT_NAME}_core)