The literals true
or false
.
Type declaration: Boolean
Value syntax: true
or false
JS representation: boolean
Any string; strings do not have to be valid UTF-16, but they are stored as UCS-2 and cannot have embedded NUL characters.
In Thingpedia, string parameters should have a #[string_values]
annotation pointing to a string dataset. The list of string datasets is available.
Type declaration: String
Value syntax: delimited by single or double quotes. Backlash can be used to escape quotes with \'
or \"
. The syntax \\
represents a literal backlash, and \n
can be used to escape a new line. No other backlash escapes are allowed. Unescaped new lines are not allowed in a string literal.
JS representation: string
Enumerated type, having values from a predefined list. For example, Enum(on,off)
represents the possibility of being on
or off
.
Type declaration: Enum(e1, e2, ...)
, for an enum having values e1
, e2
, etc.
Keywords such as
on
,in
etc. are allowed as enumerands. This is the only exception to the general rule that keywords cannot be used as identifiers.
Value syntax: enum <enumerand>
or enum(<enumerand>)
, e.g. enum off
or enum(off)
.
JS representation: string (the enum value)
An identifier to an object; the type is parametrized with the actual entity type. An entity has a value, and an optional display
property that represents the user visible name of the object.
Entities differ from strings because entities are referred to be ID, and the ID is normalized by a database lookup, while strings can be free-form. Entities differ from enums because entities are assumed to be from a much larger and potentially dynamic list, while enums should be from a small list (less than 10 elements).
Type declaration: Entity(prefix:type)
, e.g. Entity(com.yelp:restaurant)
. Prefix can be tt
for well-known entities, or the identifier of a class in Thingpedia.
Value syntax: if the ID is known: "<id>"^^<prefix>:<suffix>("<display>")
; for example "vhfPni9pci29SEHrN1OtRg"^^com.yelp:restaurant("Ramen Nagi")
; if the ID is unknown: null^^<prefix>:<suffix>("<display>")
; for example null^^com.yelp:restaurant("Ramen Nagi")
. The system automatically computes the ID of each entity by name before executing a program.
JS representation: string (ID only, name is omitted), or using the thingtalk.Builtin.Entity
class, which is also exposed as thingpedia.Value.Entity
For example, the stock ID of Google can be represented as:
new thingpedia.Value.Entity("google", "tt:stock_id", "Alphabet Inc.")
The following entity types have special meaning to the semantic parser:
Entity(tt:picture)
: a picture (identified by its URL)Entity(tt:hashtag)
: a hashtag (a word preceded by the # sign)Entity(tt:username)
: a username (a word preceded by an @ sign)Entity(tt:path_name)
: a path or file nameEntity(tt:url)
: a URL (not necessarily pointing to a picture)Entity(tt:phone_number)
: a phone numberEntity(tt:email_address)
: an email addressEntity(tt:device)
: a Thingpedia device type (e.g. com.twitter
)Entity(tt:function)
: a Thingpedia function identifier, composed of device type + :
+ function name (e.g. com.twitter:post
)The full list of entity types is available at ThingTalk Entity Types. Custom Entity types can be defined, using a prefix other than tt:
.
IEEE754 double precision floating point.
Parameters of type Number
can have #[min_number]
and #[max_number]
annotations indicating the minimum and maximum expected value. These annotations are advisory only, and APIs should check that the values are within range.
Type declaration: Number
Value syntax: decimal numeric literal
JS representation: number
Same as Number
, but parametrized by one of the unit types. Values of Measure
type have automatic conversion to and from the most common unit types
Type declaration: Measure(<unit>)
, e.g. Measure(C)
for a temperature
Value syntax: <number><unit>
(no space allowed between number and unit), e.g. 6ft
or 21C
.
JS representation: number, to be interpreted in the base unit of the Measure
type. For example, 6ft
will be converted to 1.8288m
, and will be interpreted as 1.8288
in JavaScript.
A Number
with a unit of monetary value. This differs from Measure
because the unit is not normalized, and is accessible at runtime.
Type declaration: Currency
Value syntax: <number>$<unit>
(no space allowed), e.g. 100$usd
JS representation: uses the thingtalk.Builtin.Currency
class, also available as thingpedia.Value.Currency
. For example:
new thingpedia.Value.Currency(100, 'usd')
A specific point in time (date and time). Dates are always interpreted in the local timezone of the user.
A date can be:
Relative and incomplete dates are normalized to absolute dates before execution.
Type declaration: Date
Value syntax:
new Date(<unix timestamp>)
or new Date(<iso string literal>)
or new Date(<year>, <month>, <day>, <hour>, <minute>, <second>)
. Hour, minute and second can be omitted if they are all 0.$now
, the other relative dates are $start_of(<unit>)
or $start_of(<unit>)
, e.g. "today" is $start_of(day)
, "this week" is $start_of(week)
, "tomorrow" is $end_of(day)
JS representation: represented with the Date class (after normalization).
A time of day without date.
Type declaration: Time
Value syntax: new Time(<hours>, <minutes>, <seconds>)
; seconds can be omitted if 0.
JS representation: an object of class thingtalk.Builtin.Time
, also available as thingpedia.Value.Time
.
For example, 7 PM is represented as:
new thingpedia.Value.Time(19, 0, 0)
A specific point on the Earth surface, as a pair of latitude and longitude, and optional name.
Type declaration: Location
Value syntax: new Location(<latitude>, <longitude>, <display>)
if the coordinates are known, or new Location(<display>)
if the coordinates are unknown. Values with unknown coordinates are looked up in the location database before execution.
JS representation: an object of class thingtalk.Builtin.Location
, also available as thingpedia.Value.Location
.
For example, Almond's birthplace:
new thingpedia.Value.Location(37.43, -122.1733, "Gates Computer Science, Stanford").
An ordered sequence of values of the same type. Arrays are compared by value, i.e., two arrays are equal if the have the same size and are pair-wise equal.
Type declaration: Array(<elem>)
, e.g. Array(String)
Value syntax: [<elem1>, <elem2>, ...]
JS representation: JS array
A structured type with fields. Also known as a record type.
Type declaration: { <f1>: <t1>, <f2>: <t2>, ...}
, e.g. { ratingValue: Number, reviewCount: Number }
Value syntax: { <f1>=<v1>, <f2>=<v2> }
, e.g. { ratingValue=4.5, reviewCount=1000 }
JS representation: plain JS object
!
, &&
, ||
: logical connectives NOT, AND and OR
>=
, <=
: comparison operators; if applied to String
s, values are compared lexicographically
==
: equality, inequality; equality for strings is case sensitive.
=~
: "soft match", returns true if the right hand side occurs in the left hand side; the second argument must be a string, while the first argument can be a string or an entity (in which case the comparison considers the entity display name). This comparison is case insensitive.
~=
: "reversed soft match", reversed argument version of =~
contains(array, elem)
: array containment; returns true if at least one element of the array compares equal (according to ==
) to the passed element
contains~(array, elem)
: soft array containment; returns true if at least one element of the array compares soft-equal (according to =~
) to the passed element
~contains(array, elem)
: soft array containment; returns true if at least one element of the array compares soft-equal (according to ~=
) to the passed element
in_array(elem, array)
: reversed array containment
in_array~(elem, array)
: soft reversed array containment (using =~
)
~in_array(elem, array)
: soft reversed array containment (using ~=
)
starts_with(string, prefix)
, ends_with(string, suffix)
, prefix_of(prefix, string)
, suffix_of(suffix, string)
: returns true if prefix
is a case-insensitive prefix (resp. suffix) of string
+
: between numbers, currencies, and compatible measures: addition; between strings: string concatenation; also valid between dates and Measure(ms)
(duration)-
: subtraction (and unary minus); valid for numbers, currencies, and compatible measures; also valid between dates and durations*
: multiplication; only valid between two numbers, a number and a measure, or a number and a currency/
: division; only valid between two numbers, a number and a measure, or a number and a currency%
: modulus; only valid between numbers**
: exponentiation: only valid between numbersdistance(loc1, loc2)
: distance between two locations (a Measure(m)
value)min
, max
, sum
, avg
, count
: aggregation operators, valid for arrays of the appropriate type$?
: the value is unspecified and must be slot filled
$result
: the description of the last result
$type
: the type (function identifier) of the last result
$program_id
: the current program id
$now
: the current time when the program was issued
$location.current_location
: the user's current location at the time the command was issued
$location.home
, $context.location.work
: predefined locations
$time.morning
, $time.evening
: user's preference of morning and evening time
$source
: the identity that originated this program, if the program was not entered by the user
timer(in req base : Date, in req interval : Measure(ms), in opt frequency : Number)
: interval timer, fires frequency
times every interval
attimer(in req time : Array(Time), in opt expiration_date : Date)
: daily timer, fires at the given times, forever or until the given expiration_date
The following units are valid for the type Measure(...)
:
ms
: time (milliseconds)m
: length (meters)m2
: area (square meters)m3
: volume (cubic meters)mps
: speed (meters per second)kg
: mass (kilograms)Pa
: pressure (Pascal)C
: temperature (Celsius)kcal
: energy (kilocalories)byte
: data size (Byte)W
: power (Watt)lm
: luminous flux, luminous power (lumen)lx
: luminous flux emitted by a surface (lux)dB
: volume or signal intensity (decibel)dBm
: signal strength (decibel-milliwatts)The following units are additionally recognized in measure literals, and
implicitly converted to the base unit for all operations.
Unit | Base Unit | Physical quantity |
---|---|---|
s (seconds) |
ms |
time |
min (minutes) |
ms |
time |
h (hours) |
ms |
time |
day (days) |
ms |
time |
week (weeks) |
ms |
time |
mon (business month = 30 days) |
ms |
time |
year (business year = 365 days) |
ms |
time |
km (kilometers) |
m |
distance |
mm (millimeters) |
m |
distance |
cm (centimeters) |
m |
distance |
mi (miles) |
m |
distance |
in (inches) |
m |
distance |
ft (feet) |
m |
distance |
ly (light-year) |
m |
distance |
km2 (square kilometers) |
m2 |
area |
mm2 (square millimeters) |
m2 |
area |
cm2 (square centimeters) |
m2 |
area |
mi2 (square miles) |
m2 |
area |
in2 (square inches) |
m2 |
area |
ft2 (square feet) |
m2 |
area |
km3 (cubic kilometers) |
m3 |
volume |
mm3 (cubic millimeters) |
m3 |
volume |
cm3 (cubic centimeters) |
m3 |
volume |
mi3 (cubic miles) |
m3 |
volume |
in3 (cubic inches) |
m3 |
volume |
ft3 (cubic feet) |
m3 |
volume |
gal (US gallon) |
m3 |
volume |
galuk (UK gallon) |
m3 |
volume |
pint (US pint) |
m3 |
volume |
pintuk (UK pint) |
m3 |
volume |
l (liter) |
m3 |
volume |
hl (hectoliter) |
m3 |
volume |
cl (centiliter) |
m3 |
volume |
ml (milliliter) |
m3 |
volume |
tsp (teaspoon (US)) |
m3 |
volume |
tbsp (tablepoon (US)) |
m3 |
volume |
cup (cup (US)) |
m3 |
volume |
floz (fluid ounce) |
m3 |
volume |
kmph (kilometers per hour) |
mps |
speed |
mph (miles per hour) |
mps |
speed |
g (grams) |
kg |
mass |
lb (US pound) |
kg |
mass |
oz (US ounce) |
kg |
mass |
bar (bar) |
Pa |
pressure |
psi (pounds per square inch) |
Pa |
pressure |
mmHg (millimeters of mercury) |
Pa |
pressure |
inHg (inches of mercury) |
Pa |
pressure |
F (Fahrenheit) |
C |
temperature |
K (Kelvin) |
C |
temperature |
kJ (kilojoule) |
kcal |
energy |
KB (1000 bytes) |
byte |
data size |
KiB (1024 bytes) |
byte |
data size |
MB (1000 KB) |
byte |
data size |
MiB (1024KiB) |
byte |
data size |
GB (1000 MB) |
byte |
data size |
GiB (1024 MiB) |
byte |
data size |
TB (1000 GB) |
byte |
data size |
TiB (1024 GiB) |
byte |
data size |
kW (kilowatt) |
W |
power |