cclang-compiler-js v1.2.0-beta.1

Call Control Language Compiler

Requirements

• NodeJS 6
• ES6

Language Specs

Comments

• Comments start with the pound(#).
• Any text can follow the # character.
• Comments must be on their own lines.
• Comments are ignored by the compiler.

Example

# This is a valid comment
SAY "That's a nice comment."
SAY "That's an invalid comment" # This is a bad comment

Variable Assignment and Evaluation

All variable names must begin with a dollar($) sign and only contain a-zA-Z0-9_ characters.

Variables and expressions are evaluated by a JavaScript engine, so all JS data types are supported. One caveat is that our expressions do not support undefined. Anything that resolve to undefined will throw an error and stop the phone call. Examples are accessing uninitialized variables, arrays with out-of-range indexes and objects with non-existent keys.

Supported Data Types: string, number, boolean, arrays and objects.

Our string types support interpolation: "Hello, ${varName}."

Spec

VAR $variable IS expression

Examples

VAR $name IS "John"
VAR $greeting IS "Hello, ${name}."
VAR $counter IS $counter + 1
VAR $pets IS ["Whiskers", "Spot", "Bubbles"]
VAR $pets IS {"cat": "Whiskers", "dog": "Spot", "fish": "Bubbles"}

Functions

Our system function names are all-caps (CONFERENCE). User-defined functions should be camelCase or PascalCase.

Arguments passed to functions can be passed in order or out-of-order with explicit parameter names. When passing a string with no spaces, you can omit surrounding double-quotes (see JOIN in the example below).

Invocation

Spec

FUNCNAME [[$arg=]_value ...] WITH
ON eventName
END FUNC_NAME

Examples

# Function with no arguments and events.
HANGUP

# Function with two implicit arguments and no events.
CONFERENCE JOIN "myConference"

# Function with two implicit and one explicit arguments and two events.
CONFERENCE JOIN "myConference" $startOnEnter=true WITH
    ON ENTER
        SAY "You joined the conference."
    ON ENTER_ERROR
        SAY "Sorry, you could not join."
        HANGUP
END CONFERENCE

Definition

Spec

DEF FunctionName [$arg1 [$argn?=_defaultValue] ...]]
[WITH @EVENTNAME @EVENT_NAME ...
...block...
END DEF

If only one event name (or one required event name) is defined (WITH @EVENT_NAME), then the event label can be omitted (ON EVENT_NAME) when invoked.

Function parameters are required unless followed by ? or a default value.

Example

DEF ConferenceGreeting $confName $callerName $maxParticipants=5 $optVar?
    WITH @CALL_ENTER @CALL_ERROR
    SAY "Hello, ${callerName}. We will attempt to put you in a conference."
    CONFERENCE JOIN $confName maxParticipants=$maxParticipants WITH
        ON ENTER
            @CALL_ENTER
        ON ENTER_ERROR
            @CALL_ERROR
    END CONFERENCE
END DEF

Conditionals

If Statements

Spec

IF conditional THEN consequent

IF conditional THEN
...block...
ELSE IF conditional THEN
...block...
END ELSE

Examples

IF $counter MORE 3 THEN HANGUP

IF $keyPresses IS NONE AND $attempts LESS 3 THEN
	SAY "Please try again."
ELSE IF $attempts MORE 2 THEN
	SAY "You will be forwarded to an operator."
	TRANSFER +17145551212
END IF

Operators

• IS (==)
• ISNOT (!=)
• NOT (!)
• LESS (<)
• MORE (>)
• JavaScript Operators (==, !=, !, >, >=, <, <=)

Constants

• NONE (null)
• EMPTY ("")

Loops

While Statement

WHILE statements will loop until the condition evaluates to false.

Use CONTINUE to stop the current loop and begin the next. Use BREAK to exit a loop and continue after the END WHILE.

Spec

WHILE condition
...block...
END WHILE

Examples

WHILE $counter LESS 4
	SAY "The count is ${counter}."
	VAR $counter IS $counter + 1
END WHILE

Each Statement

The EACH statement will allow you to iterate over arrays and objects.

For arrays, the value is the value and the index is the current position. For objects, the value is the value and the index is the key.

Use CONTINUE to stop the current loop and begin the next. Use BREAK to exit a loop and continue after the END EACH.

Spec

EACH iterator AS value AT index
...block...
END EACH

Examples

VAR $cars IS ["Chevy", "Ford", "Honda", "Volvo"]
EACH $cars AS $make AT $num
	SAY "This number ${num} car is a ${make}."
END EACH

VAR $housePets IS {"cat": "Whiskers", "dog": "Spot", "fish": "Bubbles"}
EACH $housePets AS $name AT $type
    SAY "Pet is a ${type} named ${name}."
END EACH

Labels and GOTO Statement

Spec

labelName:
GOTO labelName

Examples

labelName:
SAY "Hello, world."
GOTO labelName

Custom CCML

Spec

CCML
...ccml xml...
END CCML

Example

CCML
    <SAY text="Hello, world"/>
    <HANGUP/>
END CCML

Import Libraries

A script can import external user-defined functions and use them locally. To avoid name conflicts, external functions must be prefixed with the namespace set in the USE statement. The path to the external script to import must be relative and omit the .ccl file extension.

Note: If an imported file has any other "non-function-definition" code, it will be ignored on import.

Spec

USE Namespace FROM "cclangFilePath"

Examples

USE Foo FROM "./path/to/foo"
USE Bar FROM "./path/to/bar"

Foo$FunctionName "John" "Doe" 25
Bar$FunctionName 10 20 assert=30

Guessing Game Example

# Shoutpoint's Guessing Game Demo
# Written is CCLang.

SAY "Welcome to the Shoutpoint guessing game."

VAR $numToGuess IS 45
VAR $keyPresses IS NONE

# Loop until $keyPresses is the $numToGuess
WHILE $keyPresses ISNOT $numToGuess

    # Get the caller's guess
    COLLECT $numDigits=2  $timeout=5000 WITH
        SAY "Pick a number between 1 and 100."
    END COLLECT
    
    # Check the guess
    IF $keyPresses IS NONE THEN
        SAY "I'm sorry. I did not hear your guess. Please try again."
    ELSE IF $keyPresses LESS $numToGuess THEN
        SAY "You guessed ${keyPresses}. That was too low."
    ELSE IF $keyPresses MORE $numToGuess THEN
        SAY "You guessed ${keyPresses}. That was too high."
    END IF

END WHILE

SAY "Congratulations! The correct guess was ${numToGuess}. Call back to play again."
HANGUP

License

(The MIT License)

Copyright (c) 2016 Shoutpoint, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.