Configurable🔗 i

1A tour by example🔗 i

This example illustrates implementing a tool that searches text by lines (think grep). The tool should allow users to select a search algorithm from three choices: literal matching, regexp, and fuzzy search (at least initially - we will see how the this library makes it easy to add more down the road).

Our tool’s implementation might initially look like this.

;;tool.rkt

#langracket

 

;;swapoutwithregexp.rktorfuzzy.rkt

(require "literal.rkt")

 

(module+ main

(require racket/cmdline)

(define-values {queryfiles-to-search}

(command-line

#:args[query.files-to-search]

(values queryfiles-to-search)))

(search!queryfiles-to-search))

With the different search styles implemented in their own files.

;;literal.rkt

#langracket

 

(provide (rename-out [search/literal!search!]))

 

(define (search/literal!strfiles)

;;todo...

(displayln ' searching-literally))

;;regexp.rkt

#langracket

 

(provide (rename-out [search/regexp!search!]))

 

(define (search/regexp!rxfiles)

;;todo...

(displayln ' searching-for-regexp))

;;fuzzy.rkt

#langracket

 

(provide (rename-out [search/fuzzy!search!]))

 

(define (search/fuzzy!patfiles)

;;todo...

(displayln ' searching-fuzzily))

To let users select a search style via a config file instead of modifying the tool, we’ll write a configurable feature set definition describing our configurable feature (the search style) and our known implementations. Then we’ll write a config that selects a style, which users can edit instead of editing the tool itself.

The feature set definition looks like this.

;;configurables.rkt

#langconfigurable/definition

 

(define-configurable search-style

#:provides[search!]

 

(define-implementation literal

#:module"literal.rkt")

 

(define-implementation regexp

#:module"regexp.rkt")

 

(define-implementation fuzzy

#:module"fuzzy.rkt"))

And a config file looks like this.

;;search-config.rkt

#langconfigurable/config"configurables.rkt"

 

;;`fuzzy`hereisboundbythedefinitioninconfigurables.rkt

(configure-all! [search-stylefuzzy])

Finally we refactor our tool to look like this. Each change is annotated with a comment.

;;tool.rkt

#langracket

 

(require "configurables.rkt");;requirethefeaturesetdefinition

 

(module+ main

(require racket/cmdline)

(define-values {queryfiles-to-search}

(command-line

;;obtaintheconfigpath...

#:once-each

[("--config""-c")

path

"searchstyleconfigurationtouse"

;;...andinstallit

(install-configuration!path)]

#:args[query.files-to-search]

(values queryfiles-to-search)))

;;accesstheconfiguredsearchfunctionwiththeparameter`configured:search!`

;;whichiscreatedby`define-configurable!`

((configured:search!)queryfiles-to-search))

Under the hood, what’s happening is that install-configuration! sets the value of the parameter configured:search!.

Of course, this example is a bit contrived because a single command-line switch would suffice to configure the search style. However, that approach quickly grows unwieldy when there are several features to configure, and especially so if some implementations themselves may be parameterized.

This library offers a natural solution for the second challenge of parameterized features as well, with implementation parameters. Implementation parameters are essentially arguments that can be specified in a config file to configure an implementation.

Let’s see how that works by adding a new feature to our search tool. We’ll support abbreviations in literal search queries, so that doing a literal search for @myemail instead searches for joe-schmoe9000@gmail.com. A table of abbreviation definitions in the user’s config file will define the set of these to use.

First, let’s update literal.rkt to support these abbrevs.

;;literal.rkt

#langracket

 

(provide (rename-out [search/literal!search!])

current-abbrevs)

 

(define current-abbrevs(make-parameter (hash )))

(define (search/literal!strfiles)

;;todo...

(displayln ' searching-literally/with-abbrevs)

(displayln (current-abbrevs)))

Next, let’s update the configurable feature set definition.

;;configurables.rkt

#langconfigurable/definition

 

(define-configurable search-style

#:provides[search!]

 

(define-implementation literal

#:module"literal.rkt"

#:parameters[current-abbrevs])

 

(define-implementation regexp

#:module"regexp.rkt")

 

(define-implementation fuzzy

#:module"fuzzy.rkt"))

And finally we can use it in the config.

;;search-config.rkt

#langconfigurable/config"configurables.rkt"

 

(configure-all! [search-styleliteral(hash "@myemail""joe-schmoe9000@gmail.com")])

The config would not need to change at all for other search styles, on the other hand. For instance, the same fuzzy-searching config we had before is still valid now.

2Configurable feature set definition DSL🔗 i

configurable feature set definitions are written in this language, and consist of a sequence of define-configurable forms at the top level.

The resulting module provides the names of all the defined configurable features, the features configured: parameters, and the operations on configs described in Config operations.

Each implementation-definition must be an define-implementation form.

This form creates and provides a parameter for each id named configured:id which will hold the currently configured implementation’s version of id.

Each parameter-id specified defines an implementation parameter.

3Config DSL🔗 i

configs are written in this language, which is parameterized by the configurable feature set definition whose relative path is provided after the #lang (see the example configs above). Configs consist of a sequence of configure! or configure-all! forms at the top level.

4Config operations🔗 i

These operations are also provided by every configurable feature set definition, which is the more typical way to obtain them.