Kaleidoscope

Kaleidoscope is a small library which provides pattern matching using regular expressions, and extraction of capturing groups into values. In particular, patterns are written inline, and do not need to be predefined.

Features

• pattern match strings against regular expressions
• regular expressions can be written inline in patterns
• extraction of capturing groups in patterns
• static verification of regular expression syntax

Getting Started

To use Kaleidoscope, first import its package,

import kaleidoscope._

and you can then use a Kaleidoscope regular expression—a string prefixed with the letter r—anywhere you can use a pattern in Scala. For example,

path match {
  case r"/images/.*" => println("image")
  case r"/styles/.*" => println("stylesheet")
  case _ => println("something else")
}

or,

email match {
  case r"^[a-z0-9._%+-][email protected][a-z0-9.-]+\.[a-z]{2,6}$$" => Some(email)
  case _ => None
}

Such patterns will either match or not, however should they match, it is possible to extract parts of the matched string using capturing groups. The pattern syntax is exactly as described in the Java Standard Library, with the exception that a capturing group (enclosed within ( and )) may be bound to an identifier by prefixing the group with an @, and the identifier to extract to, which in standard Scala syntax, is written either as $identifier or ${identifier}.

Here is an example:

path match {
  case r"/images/${img}@(.*)" => Image(img)
  case r"/styles/[email protected](.*)" => Stylesheet(styles)
}

or as an extractor on a val, like so,

val r"^[a-z0-9._%+-][email protected][email protected]([a-z0-9.-]+\[email protected]([a-z]{2,6})$$" = "[email protected]"
> domain: String = "example.com"
> tld: String = "com"

In addition, regular expressions will be checked at compile-time, and any issues will be reported then.

Escaping

Note that inside an extractor pattern string, whether it is single- (r"...") or triple-quoted (r"""..."""), special characters, notably \, do not need to be escaped, with the exception of $ which should be written as $$. It is still necessary, however, to follow the regular expression escaping rules, for example, an extractor matching a single opening parenthesis would be written as r"\(" or r"""\(""".

Limitations

Kaleidoscope currently has no support for optional or repeated capturing groups.

Status

Kaleidoscope is classified as maturescent. Propensive defines the following five stability levels for open-source projects:

• embryonic: for experimental or demonstrative purposes only, without guarantee of longevity
• fledgling: of proven utility, seeking contributions, but liable to significant redesigns
• maturescent: major design decisions broady settled, seeking probatory adoption and refinement of designs
• dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version 1.0 or later
• adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated

Availability

Kaleidoscope’s source is available on GitHub, and may be built with Fury by cloning the layer propensive/kaleidoscope.

fury layer clone -i propensive/kaleidoscope

or imported into an existing layer with,

fury layer import -i propensive/kaleidoscope

A binary is available on Maven Central as com.propensive:kaleidoscope-core_<scala-version>:0.4.0. This may be added to an sbt build with:

libraryDependencies += "com.propensive" %% "kaleidoscope-core" % "0.4.0"

Contributing

Contributors to Kaleidoscope are welcome and encouraged. New contributors may like to look for issues marked .

We suggest that all contributors read the Contributing Guide to make the process of contributing to Kaleidoscope easier.

Please do not contact project maintainers privately with questions, as other users cannot then benefit from the answers.

Author

Kaleidoscope was designed and developed by Jon Pretty, and commercial support and training is available from Propensive OÜ.

License

Kaleidoscope is copyright © 2018-20 Jon Pretty & Propensive OÜ, and is made available under the Apache 2.0 License.