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 theexamples provided in your plugin'sexamples.txt file. Here's a simple one:

open iOS Simulatorlaunch iOS simulatoropen iphone sim

Plugins can take input by definingfields in their examples. Here's what the examples looks like, plus the dictionary that's passed to your plugin'srun 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 arethree important types of input:

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

2. non-free text: fields thatdon't start with~ are used for text thatisn't free text — the algorithm takes the contents of the fields as given inexamples.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, downloadFlashlightTool, create a plugin with examples containing those fields, and inspect the data that's passed to it.

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