Skip to main content
The Squirrel Programming Guide

The Squirrel Programming Guide

About Squirrel

Squirrel is the language you use to create Electric Imp applications.

If you’ve programmed before, Squirrel is not a hard language to adopt. It ultimately derives from C, so it has a structure that will be familiar to anyone coding with today’s most commonly used programming languages. It is also object-oriented, so its concepts will not be alien to programmers who work with C++, C#, Objective-C, Java or Swift. Squirrel’s use of asynchronous functions (‘callbacks’) will be very familiar to JavaScript programmers.

There are many similarities between Squirrel and other languages. For example, all of the standard mathematical, logical and bitwise operators, plus ?:, the ternary operator, are available in Squirrel.

Single-line comments are marked with the familiar // token, or with /* and */ to, respectively, begin and end blocks of multi-line comments.

Statements may be completed with a semi-colon, but this is not required by Squirrel. However, we recommend the use of semi-colons nonetheless to avoid ambiguity in certain circumstances that are discussed in our code style guide.

Braces — { and } — are used to mark out blocks of code in Squirrel. Variables declared within a block are scoped to that block.

Functions can be defined with both required and optional input parameters and single a return value.

Squirrel supports standard program-control structures: if… else if… else; for; while; do… while; and switch… case. The slightly less commonplace foreach loop mechanism is provided too; please see the Program Control section if it’s unfamiliar to you. It works exactly like for… in… structures in other languages.

Squirrel exposes some standard functionality in an idiosyncratic way, such as collections of key-value pairs, which are often known as dictionaries but which Squirrel calls tables. Tables are similar to JavaScript ‘objects’ and likewise declared and written as literals using braces and JSON formatting.

Squirrel also provides features that are unique. This guide is therefore primarily concerned with the points at which Squirrel diverges from other languages you may be familiar with. How distant it is from your own experience will depend on which particular language or languages you use.

Electric Imp Squirrel

This guide covers Squirrel as it is specifically implemented on the Electric Imp Platform. Electric Imp’s implementation of the language is a slightly modified form of Squirrel 3.0.4, though it incorporates bug fixes implemented in later versions of standard Squirrel. Other Squirrel implementations, including the language’s standard version, many include features absent in the Electric Imp version, and vice versa. If you have experience working with Squirrel on other platforms, please see Electric Imp Squirrel and Standard Squirrel for more guidance on how implementations of the language may vary.

We’re always keen to hear about specific gotchas and points of similarity we may have missed, so please tell us about any you find. Visit the Electric Imp Forum to inform us and your fellow Squirrel users (registration required).

About this Guide

This guide provides software developers new to the Squirrel language with the information they need to begin creating the applications that will power their connected products based on the Electric Imp Platform. The guide assumes some familiarity with languages like C, C++ and JavaScript with which Squirrel shares its syntax, and with the fundamentals of computer programming in general. It is primarily intended to help experienced engineers, programmers and amateur coders to quickly add Squirrel to the list of languages in which they are already fluent. It is not intended as an introduction to programming in general, but where appropriate it includes notes for new programmers to help them through some of the trickier concepts.

The guide includes the following chapters:

The Electric Imp imp API

Electric Imp provides a full selection of functions that you can make use of to extend your own code. You will need some of these functions to interact with the imp embedded in your product and to access the hardware connected to the imp. Other functions help you manage agent operations, such as communicating with remote Internet resources. Further functions have more general uses: you can use them to add extra functionality to your own application. All of these functions are accessed in the form of Squirrel class instances and their methods.

Electric Imp also provides impCentral™, a web-based application development and testing environment. You’ll use impCentral to develop your application, and you can use it to enter and run the examples in this guide. To do so you will need to create an Electric Imp developer account and add at least one imp-enabled development device to it. For assistance with this process, please see our Getting Started Guide which will walk you through setting up you account, getting your imp development hardware online and becoming familiar with impCentral, which is the subject of a full user guide on this site.

impCentral’s code editor view also feature a log into which messages from the device and its agent are posted. Many of the examples included in this guide make use of this log to view the results of program operations. They do so through the imp API method server.log() which is Electric Imp Squirrel’s equivalent of the print() function found an many other languages.

Compiler Directives

Squirrel generally treats # as an alternative single-line comment marker, not to indicate a preprocessor or compiler directive, for example #define or #import, as other languages do. Use the const keyword in place of #define.

There are two exceptions to this rule. Electric Imp’s impCentral™ uses #require to load code libraries and #line to set the line number of the code following the directive, to aid debugging. For example:

#line 5000
throw ("Error!");

will generate the following output in the log:

2018-01-15 14:30:03.205 "Action": [agent.error] ERROR: Error!
2018-01-15 14:30:03.205 "Action": [agent.error] ERROR:   in main agent_code:5000

This directive allows you to mark sections of your code by line number, the better to help you locate the code causing errors.

Back to the top