Examples.txt Reference

Flashlight's API is designed to make it easy for plugins to take relatively complex input using natural language. Users shouldn't ever have to look up syntax for plugins — it should be easy for developers to build plugins that support a wide variety of phrases and syntaxes.

When a user types a query into Spotlight, Flashlight constructs a probabilistic model from the examples provided in your plugin's examples.txt file. Here's a simple one:

open iOS Simulator
launch iOS simulator
open iphone sim

Taking input

Plugins can take input by defining fields in their examples. Here's what the examples looks like, plus the dictionary that's passed to your plugin's run function:

speak ~message(hello world) out loud # {"~message": "hello, world"}
convert color to color/format(hex) # {"color/format": "hex"}
send an email to @contact(nate) saying ~message(hello) # {"@contact": {"displayName": "nate" _[plus more info, like phone numbers]_ }, "~message": "hello"}

There are three important types of input:

1. free text input: fields starting with ~ are used for free-text input

2. non-free text: fields that don't start with ~ are used for text that isn't free text — the algorithm takes the contents of the fields as given in examples.txt into account as probability signals when determining what text is part of the field.

3. special fields: fields starting with @ are handled specially by the code — they're parsed into dictionaries, which are then passed to your plugin. Right now, Flashlight supports @date, @file, and @contact. For information on the contents of those dictionaries, download FlashlightTool, create a plugin with examples containing those fields, and inspect the data that's passed to it.

Fields with slashes, like format/hex, are used to indicate that two fields are interchangeable. For example, color/red and color/blue may have different inside content, but the context they're used in is the same. Using slashes allows the parser to understand that turn it color/red(red) is just as likely as turn it color/blue(blue), even if that isn't present in examples.txt.