Skip to content

Latest commit

 

History

History
180 lines (151 loc) · 7.8 KB

README.md

File metadata and controls

180 lines (151 loc) · 7.8 KB
Raw

NativeRegexExamples

I'm Job Hunting

👋🏼 My name is Daniel Lyons, I'm a Swift developer, and I'm currently looking for a job. I hope this package is helpful for you and the community. If so, please consider viewing and sharing my developer site with others: dandylyons.github.io. 🙏🏼

Purpose

NativeRegexExamples is a place for the Swift community to: 

  1. crowd-source Regex solutions that can be used in your projects
  2. learn from each other and develop best practices
    • Provide cheat sheets
  3. test Regexes for:
    • matches: so we can assess their capabilities
    • non-matches: so we can eliminate false positives
    • replacing capabilities

Basic Usage

@RegexActor
func foo() {
  let ssnRegex = RegexLiterals.ssn
  let string = "111-11-1111"
  string.contains(ssnRegex) // true
  string.wholeMatch(of: ssnRegex)
  
  var text = """
one SSN -> 111-11-1111
222-22-2222 <- another SSN 
"""
  text.replace(ssnRegex, with: "___")
// text is now:
//  one SSN -> ___
//  ___ <- another SSN
}

Don't just use the library. Have a look at the source code so that you can learn from it. Each regex has a literal definition and a RegexBuilder definition. For example:

public extension RegexLiterals {
  static let ssn = #/
  # Area number: Can't be 000-199 or 666
  (?!0{3})(?!6{3})[0-8]\d{2}
  -
  # Group number: Can't be 00
  (?!0{2})\d{2}
  -
  # Serial number: Can't be 0000
  (?!0{4})\d{4}
  /#
}

public extension RegexBuilders {
  static let ssn = Regex {
    NegativeLookahead {
      Repeat(count: 3) {
        "0"
      }
    }
    NegativeLookahead {
      Repeat(count: 3) {
        "6"
      }
    }
    ("0"..."8")
    Repeat(count: 2) {
      One(.digit)
    }
    "-"
    NegativeLookahead {
      Repeat(count: 2) {
        "0"
      }
    }
    Repeat(count: 2) {
      One(.digit)
    }
    "-"
    NegativeLookahead {
      Repeat(count: 4) {
        "0"
      }
    }
    Repeat(count: 4) {
      One(.digit)
    }
  }
  .anchorsMatchLineEndings()
}

Motivation

Regular expressions are an extremely powerful tool capable of complex pattern matching, validation, parsing and so many more things. Nevertheless, it can be quite difficult to use, and it has a very esoteric syntax that is extremely easy to mess up. Every language has it's own "flavor" of Regex, and Swift's improves in some significant ways: 

  1. Strict compile time type-checking
  2. Syntax highlighting for Regex literals
  3. An optional, more readable, DSL through RegexBuilder

However, many Swift resources about Regular expressions are about older technologies such as NSRegularExpressions, or third-party Swifty libraries. While these technologies and resources are great, they don't give us a chance to learn and unlock the new capabilities of native Swift Regex.

Regex is also a decades-old technology. This means that many problems have long ago been solved in regular expressions. Better yet, Swift Regex literals are designed so that they are compatible with many other language flavors of regex including Perl, Python, Ruby, and Java. We might as well learn from the experiences of other communities!

Contributing

Contributions are greatly appreciated for the benefit of the Swift community. Please feel free to file a PR or Issue!

All data types should have tests added. Testing is done entirely through the new Swift Testing framework. This should ensure, that the library is usable/testable on non-Xcode, non-Apple platforms in the future.

Sorry, Swift Testing is Swift 6 and up only. Though, I see no reason why we shouldn't be able to backdeploy the library to 5.7 and up.

Recommended Resources

I strongly recommend using swiftregex.com by SwiftFiddle. It's a powerful online playground for testing Swift Regexes. One of it's best features is that it can convert back and forth from traditional regex patterns and Swift's RegexBuilder DSL.

Inspirations

  • RegExLib.com is one of many sites that crowd-sources regular expressions. It also, tests regular expressions for matches and non-matches
  • iHateRegex.com can visualize regular expression logic.

Gotchas

Strict Concurrency Checking

The Swift Regex type is not Sendable. Apparently, this is because Regex allows users to hook in their own custom logic so Swift cannot guarantee data race safety. For this reason, I have made all the Regexes in the library isolated to @RegexActor, (a minimal global actor defined in the library). If I can find a better solution I will remove this actor isolation. If you use any regex from the library in your code directly, you will most likely need to isolate to @RegexActor. That being said, you should be able to copy and paste any regex in the library into your own code, and then you will no longer be limited to @RegexActor.

Recommended Resources

Swift Regex

Swift Testing

Installation

Add NativeRegexExamples as a package dependency in your project's Package.swift:

// swift-tools-version:6.0
import PackageDescription

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(
            url: "https://github.com/DandyLyons/NativeRegexExamples",
            .upToNextMinor(from: "0.0.1")
        )
    ],
    targets: [
        .target(
            name: "MyTarget",
            dependencies: [
                .product(name: "NativeRegexExamples", package: "NativeRegexExamples")
            ]
        )
    ]
)

Project Status

The project is in an early development phase. Current goals:

  • More examples with passing tests: Increase examples to all common use cases of regular expressions
  • Documentation: Ensure accuracy and completeness of documentation and include code examples.

Your contributions are very welcome!

Thank Yous

  • the iOS Code Review newsletter for featuring us in Issue #71.

Star History

Star History Chart

License

This project is licensed under the MIT License. See the LICENSE file for details.