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

Availability

The current latest release of Kaleidoscope is 0.4.0.

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._%+-]+@[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/$styles@(.*)" => Stylesheet(styles)

or as an extractor on a val, like so (using the Scala REPL):

val r"^[a-z0-9._%+-]+@$domain@([a-z0-9.-]+\.$tld@([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.

Related Projects

The following Scala One libraries are dependencies of Kaleidoscope:

The following Scala One libraries are dependents of Kaleidoscope:

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 any guarantees of longevity
• fledgling: of proven utility, seeking contributions, but liable to significant redesigns
• maturescent: major design decisions broady settled, seeking probatory adoption and refinement
• 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

Kaleidoscope is designed to be small. Its entire source code currently consists of 116 lines of code.

Building

Kaleidoscope can be built on Linux or Mac OS with Irk, by running the irk script in the root directory:

./irk

This script will download irk the first time it is run, start a daemon process, and run the build. Subsequent invocations will be near-instantaneous.

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. While it can be tempting to repsond to such questions, private answers cannot be shared with a wider audience, and it can result in duplication of effort.

Author

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

Name

Kaleidoscope is named after the optical instrument which shows pretty patterns to its user, while the library also works closely with patterns.

License

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