Skip to main content

Syntax

Instructions follow this pattern:

every <time period>
when 
    <function chain>
then 
    <function chain>;
    <function chain>;
    ...
until
    <function chain>;
    <function chain>;
    ...

I've illustrated the then and until here with multiple function chains, but it's fine to only have one.

Every instruction needs a when clause, but you can leave out then if you have an until or vice versa. You should also leave out the every clause unless you are using time functions within the when part of your instruction.

Time Period​

The parameter to every is a time period. It understands a range of type periods, including weeks, days, hours, minutes and seconds, and abbreviations of those measures, such as 3 mins or 2s.

These time periods and abbreviations are supported:

  • week, weeks, w, wk
  • day, days, d
  • hour, hours, h
  • minute, minutes, min, mins, m
  • second, seconds, sec, s

Function​

A function call looks like this:

object(type="airplane", capacity>50)

The function name is followed by brackets. Inside the brackets are the arguments for the function call. Arguments are separated by commas, and they can be simple values, or comparisons. Comparisons are expressed with a label followed by an operator, followed by a value. Allowed operators are =, <, >, !=, >=, <=.

Where you would write a simple value, you can instead write another function call.

object(type="sensor", value < object(type="dial").get("value"))

Bear in mind that functions return groups of things. In this case, object(type="dial").get("value") returns a group of all the value attributes of all the objects of type dial in the realm. Assuming these are numbers, when you use them in a comparison, they are implicitly averaged.

Functions operate on a group of values (called a context), they take arguments and comparisons, and they produce another context - often a filtered version of the one they received.

Function Chain​

Since functions operate on a context and produce another context, this allows them to be chained:

    <initial context>.func1(...arguments).func2(...arguments).func3(...arguments)

For example:

    object(type="bike").near(10, type="danger")

There is often an implicit context at the beginning of a function chain. In a then clause, it's the set of items that are newly joining the group defined by the when function chain. For an until chain, it's the set of items newly leaving that group.

Context​

A context is a group of values. Currently, HiveScript supports the following kinds of groups:

  • Objects
  • Areas
  • Strings. Strings are comparable, so a set of strings has a minimum and a maximum value.
  • Numeric. A set of numbers, stored as 64 bit floats. Numbers are comparable, so a set of numbers has a minimum and a maximum value. They are also accumulable, so a Numeric set also has a total and a mean which is used in comparisons.
  • Pairs. A set of pairs of values.

Not all functions work with all kinds of contexts, check the function documentation if you are uncertain.

Comments​

Hivescript supports comments starting with the # character and running until the end of the line.

# A really cool instruction
when                                    # it does something
  object(fred < 23)                     # involving 
then                                    # sending information
  sendToUrl("http://test.server.com")   # to another server