espressopp-spec.adoc

The Espresso++ Language Specification

Table of Contents

• 1. Introduction
• 2. Syntax
• 3. Grammar
• 4. Examples

1. Introduction

Espresso++ is a natural query language that abstracts away the native query language of any data management system. Espresso++ aims to provide API users with a powerful yet very simple query mechanism, that hides type and schema of the underlying database. Last but not least, Espresso++ is designed with security in mind to prevent any kind of cyber-attack like code-injection.

The next sections describe syntax and grammar of Espresso++ in great detail. This article ends with some helpful examples that show Espresso++ in action.

2. Syntax

Syntax is how a statement is worded and structured. It is the study of the principles and processes by which statements are constructed in Espresso++.

The first version of Espresso++ supports logical and matching operators as well as a number of helpful macros. A record is selected when the filtering expression evaluates to true — an expression is a combination of one or more constants, fields, operators, and macros that Espresso++ interprets and computes to produce a native query.

Logical operators allow a program to make a decision based on multiple conditions. Each expression is considered a condition that can be evaluated to true or false.

Table 1. Logical Operators

Operator	Usage	Description
or	expr1 or expr2	Evaluates to true if either expression does
and	expr1 and expr2	Evaluates to true if both expressions do
not	not expr	Evaluates to true if the expression does not

Matching operators allow a program to compare two expressions or determine whether an expression matches a given condition. Matching conditions can be evaluated to true or false.

Table 2. Matching Operators

Operator	Usage	Description
eq	expr1 eq expr2	Evaluates to true if two expressions are equal
neq	expr1 neq expr2	Evaluates to true if two expressions are not equal
is	expr is true [or false]	Evaluates to true if the expression equals the right-hand side Boolean
gt	expr1 gt expr2	Evaluates to true if the left-hand side expression is greater than the right-hand side expression
gte	expr1 gte expr2	Evaluates to true if the left-hand side expression is greater than or equal to the right-hand side expression
lt	expr1 lt expr2	Evaluates to true if the left-hand side expression is less than the right-hand side expression
lte	expr1 lte expr2	Evaluates to true if the left-hand side expression is less than or equal to the right-hand side expression
between	expr1 between expr2 and expr3	Evaluates to true if the expression is within the given range
startswith	expr1 startswith expr2	Evaluates to true if the expression starts with the given string
endswith	expr1 endswith expr2	Evaluates to true if the expression ends with the given string
contains	expr1 contains expr2	Evaluates to true if the expression contains the given string

Macros are single instructions that expand automatically into a set of instructions.

Table 3. Macros

Macro	Arguments	Description
#now		Expands to current time
#duration	Duration in ISO-8601 format	Expands to a duration in milliseconds

Finally, Espresso++ supports basic mathematics that allow complex expressions.

Table 4. Mathematics

Math	Usage	Description
add	expr1 add expr2	Adds up an expression with another
sub	expr1 sub expr2	Subtracts an expression from another
mul	expr1 mul expr2	Multiplies an expression by another
div	expr1 div expr2	Divides an expression by another

3. Grammar

Grammar is the set of structural rules that govern the composition of statements in Espresso++, and Extended Backus-Naur Form 2 (EBNF2) is the formalism (or metalanguage) used to describe it.

digit               = . // https://golang.org/ref/spec#decimal_digit
identifier          = . // https://golang.org/ref/spec#identifier
int                 = . // https://golang.org/ref/spec#int_lit
float               = . // https://golang.org/ref/spec#float_lit
string              = . // https://golang.org/ref/spec#string_lit
bool                = "true" | "false" .
date                = digit digit digit digit "-" digit digit "-" digit digit .
time                = digit digit ":" digit digit ":" digit digit [ "." { digit } ] .

Query               = Expression { Expression } .

Expression          = "and" | "or"
                    | SubExpression
                    | Comparison
                    | Equality
                    | Match
                    | Range
                    | Is .
SubExpression     = [ "not" ] "(" Expression { Espression } ")" .

Date                = "\"" date "\"" | "'" date "'" .
Time                = "\"" time "\"" | "'" time "'" .
DateTime            = "\"" date "T" time [ "+" digit digit ] "\""
                    | "'" date "T" time [ "+" digit digit ] "'" .

Term                = identifier
                    | int | float | string | bool
                    | Date | Time | DateTime
                    | Macro .

Macro               = "#" identifier [ "(" Term { "," Term } ")" ] .

Math                = Term ( "add" | "sub" | "mul" | "div" ) Term .

TermOrMath          = ( Math | "(" Math ")" | Term ) .

Comparison          = TermOrMath ( "gt" | "gte" | "lt" | "lte" ) TermOrMath.

Equality            = TermOrMath ( "eq" | "neq" ) TermOrMath .

Match               = Term ( "startswith" | "endswith" | "contains" ) Term .

Range               = TermOrMath "between" TermOrMath "and" TermOrMath .

Is                  = identifier "is" [ "not" ] bool
                    | "is" [ "not "] identifier
                    | identifier "is" [ "not" ] "null" .

4. Examples

This article ends with some examples that show Espresso++ in action.

Select the persons with surname Walker and name starting with J:

surname eq "Walker" and name startswith "J"

Select the persons who are between 20 and 40 years old:

age between 20 and 40

Select the orders with at least 2000 items that have been created in the past 2 hours:

size gte 2000 and not(create_time lt #now sub #duration("PT2H"))

Select internal orders issued by employee 110110:

employee_id eq 110110 and internal is true

Or alternatively:

employee_id eq 110110 and is internal

Select the orders with customer notes:

customer_note is not null

---

Copyright © 2020 Skeeter Health