🍱 bento

• Getting Started
  • Installation
  • Running A Program
• Example Use Case
• Language
  • File Structure
  • Sentences
    • Wrapping Long Sentences
  • Comments
  • Variables
    • Blackhole
    • Text
    • Number
      • Mathematical Operations
  • Functions
    • Arguments
    • Questions
  • Controlling Flow
    • Conditions
    • Decisions (if/unless)
    • Loops (while/until)
• Backends
  • Locating and Starting Backends
  • Communication Protocol
    • Request
    • Response
    • Special Cases
      • sentences
  • Examples
    • PHP
  • System
• Examples
  • Hello, World!
  • Variables
  • Functions (Custom Sentences)

bento is a forth-generation programming language that is English-based. It is designed to separate orchestration from implementation as to provide a generic, self-documenting DSL that can be managed by non-technical individuals.

That's a bunch of fancy talk that means that the developers are able to setup the complex tasks and make them easily rerunnable by non-technical people.

The project is still very young, but it has a primary goal for each half of its intended audience:

For the developer: Programs can be written in any language and easily exposed through a set of specific DSLs called "sentences".

For the user: An English-based language that avoids any nuances that non-technical people would find difficult to understand. The language only contains a handful of special words required for control flow. Whitespace and capitalization do not matter.

Getting Started

Installation

Bento is available for Mac, Windows and Linux. You can download the latest release from the Releases page.

Running A Program

Create a file called hello-world.bento with the contents:

start:
	display "Hello, World!"

Then run this file with (you may need to replace the path to the file if you are not in the same directory as the file):

bento hello-world.bento

Example Use Case

The sales team need to be able to run customer reports against a database. They do not understand SQL, or the reports may need to be generated from multiple tools/steps. As the developer, your primary options are:

1. Run the reports for them. This is a waste of engineering time and a blocker for the sales team if they need to do it frequently, or while you're on holiday.

2. Write up some documentation and give them readonly access to what they need. The process could be highly technical. Also, allowing them to access production systems is a bad idea. Also, it's still a waste of time for everyone when things aren't working as expected.

3. Build a tool that runs the reports for them. This is another rabbit hole of wasted engineering time, especially when requirements change frequently or they need a lot of flexibility.

4. Build the reporting queries/tasks once in bento, and provide them with a script that they can edit and rerun. An example might look like:

run sales report for last 7 days for customer 123
if there were sales, email report to "bob@mycompany.com"

The developer would implement the following sentences:

run sales report for last ? days for customer ?
there were sales
email report to ?

Language

File Structure

A .bento file consists of one or more functions. Each of those functions can contain zero or more sentences and call other sentences before of after they are defined.

The file must contain a start function. This can be located anywhere in the
file, but it is recommended to put it as the first function.

Sentences

A sentence contains a collection of words and values and it is terminated by a new line. For example:

display "Hello"

Wrapping Long Sentences

You can explicitly use ... at the end of the line to indicate a continuation:

this is a really long...
	sentence that should go...
	over multiple lines

Indentation between lines does not make an difference. However, it is easier to read when following lines are indented.

Sentences can also contains new lines if the line ends with a ,. This is useful for long inline statements:

if my-name != "John",
  display "oops!",
  otherwise display "All good."

Comments

Comments start with a # and continue until a new line or the end of the program is reached. The comment may be on its own line or at the end of a sentence:

# A comment looks like this.
display "Hello" # It can also be here

Variables

declare first-name is text
declare counter is a number

1. Only text and number is supported. See specific documentation below.
2. The word a or an may appear before the type. This can make it easier to read: "is a number" rather than "is number". However, the "a" or "an" does not have any affect on the program.
3. All variables for a function must be declare before any other sentences.
4. The same variable name cannot be defined twice within the same function. However, the same variable name can appear in different functions. These are unrelated to each other.
5. You cannot declare a variable with the same name as one of the function parameters.
6. All types have a default value which is safe to use before it is set to another value.
7. There is a special variable called _ which is called the blackhole. Explained in more detail below.

Variables can be set with:

set first-name to "Bob"

Blackhole

The blackhole variable is a single underscore (_). It can be used as a placeholder when the value can be ignored. For example:

divide 1.23 by 7.89 into _

If _ is used in a place where the value would be read it will return a zero value (the same as the default value for that type).

The following lines would function the same. However, you should not rely on the blackhole variable as a readable value and it may be made illegal in the future:

add _ and 7.89 into result
add 0 and 7.89 into result

Text

my-variable is text

1. A text variable can contain any text, including being empty (zero characters).
2. It's perfectly safe to use text variables before they have been given a value, the default value will be empty.

Number

my-variable is number
my-variable is number with 1 decimal place
my-variable is number with 3 decimal places

1. A number variable is exact and has a maximum number of decimal places (this is also called the precision).
2. If the number of decimal places is not specified it will use 6.
3. For integers you should use number with 0 decimal places.
4. The number of decimal places cannot be negative.
5. A number has no practical minimum (negative) or maximum (positive) value. You can process incredibly large numbers with absolute precision.
6. Any calculated value will be rounded at the end of the operation so that it never contains more precision than what is allowed. For example if the number has one decimal place, 5.5 * 6.5 * 11 evaluates to 393.8 because 5.5 * 6.5 = 35.75 => 35.8, 35.8 * 11 = 393.8.
7. Numbers are always displayed without trailing zeroes after the decimal point. For example, 12.3100 is displayed as 12.31 as long as the number of decimal places is at least 2.
8. The words places and place mean the same thing. However, it is easier to read when place is reserved for when there is only one decimal place.
9. The default value of a number is 0. This is safe to use use before it has been set.

Mathematical Operations

add a and b into c          # c = a + b
subtract a from b into c    # c = b - c
multiply a and b into c     # c = a * b
divide a and b into c       # c = a / b

Note: Be careful with subtract as the operands are in the reverse order of the others.

Functions

Functions (custom sentences) can be defined by using the : character:

print everything:
	display "Hello"
	display "World"

The whitespace is not required. However, it is easier to read when content of functions are indented with spaces or tabs.

Arguments

Variables can be declared in the function name by specifying their names and types in (), for example:

say greeting to persons-name (greeting is text, persons-name is text):
	display greeting
	display persons-name

Can be called with:

say "Hi" to "Bob"

The order in which the arguments are defined is not important.

Questions

A question is a special type of function that is defined with a ? instead of a ::

it is ok?
	yes

A question is answered with the yes or no sentences. Once a question is answered it will return immediately.

If a question is not explicitly answered by the end, it's assumed to be no.

Questions can be asked in conditionals:

start:
	if it is ok, display "All good!"

Questions can also take arguments in the same way that functions do:

start:
	declare x is number

	set x to 123
    if x is over 100, display "It's over 100", otherwise display "Not yet"

the-number is over threshold (the-number is number, threshold is number)?
	if the-number > threshold, yes
``