Browse the docs

A reading from an app is

Passes when a number or word an app shows (its unread count, a label, a script's answer) equals, is above or below, contains or matches a value, or changed recently.

name in kit is value

Details #

Compares one of an App Kit's readings with value. kit is the kit's id (kit.mail), name the reading's name (unread), and op how to compare:

  • equals (default): the same value. Numbers and numeric text compare as numbers.

  • above, below: the reading is a number larger or smaller than value.

  • contains: the text contains value (ignoring case), or the list holds it.

  • matches: the text matches the regular expression value (ignoring case).

  • changedWithin: the reading changed in the last value seconds (30, or "5m"). A reading that hasn't changed since Switchboard first read it never passes.

A reading that doesn't exist (the kit is off, or the name is wrong) is false, and the trace says so. A stale reading (it couldn't be read just now) still compares its last value; the trace shows stale.

Use it in Only if, in an if step, or with Wait for or Wait for a change. To use a reading's value inside a step instead, write {{ kit.mail.unread }} in any text (the kit's id without the kit.; a hyphenated id is {{ kit["github-plus"].count }}). Every app also has a free reading of the number on its Dock icon, {{ app.badge.Mail }}, with no kit installed.

Parameters #

ParameterTypeRequiredValuesWhat it does
kittextThe kit's id, like kit.mail.
nametextThe reading's name in that kit.
opone ofequals above below contains matches changedWithinequals, above, below, contains, matches or changedWithin.
sampleany value
valueany valueWhat to compare with.

Examples #

Only when there is mail waiting
When
  1. Press ⌃⌥J
Only if
  1. If “unread” in “mail” is above 0
Do
  1. Show “{{ kit.mail.unread }} unread”
Open in Switchboard to try it

Gotchas #

  • above and below need a number in value; a reading that isn't a number (as: text) is false for them.

  • The reading is read while the condition is used, so the first check after a kit turns on can wait a moment for the first read.

See also #