HCL - Hybrid Command Language

Language Syntax

A HCL program is composed of expressions.

Keywords

• nil
• true
• false

Special Form Expression

• and
• break
• defun
• do
• elif
• else
• if
• lambda
• or
• return
• set
• until
• while

literals

• integer
• character
• small pointer
• error
• string
• dictionary
• array
• byte array

Builtin functions

• not
• _and
• _or
• eqv?
• eql?
• eqk?
• nqv?
• nql?
• nqk?
• sprintf
• printf
• +
• -
• *
• mlt
• /
• quo
• mod
• sqrt
• bit-and
• bit-or
• bit-xor
• bit-not
• bit-shift

Defining a function

(defun function-name (arguments)
	| local variables |
	function body
)

(set function-name (lambda (arguments)
	| local variables |
	function body
)

HCL Exchange Protocol

The HCL library contains a simple server/client libraries that can exchange HCL scripts and results over network. The following describes the protocol briefly.

Request message

TODO: fill here

Reponse message

There are two types of response messages.

• Short-form response
• Long-form response

A short-form response is useful when you reply with a single unit of data. A long-form response is useful when the actual data to return is more complex.

Short-form response

A short-form response is composed of a status line. The status line may span across multiple line if the single response data item can span across multiple lines without ambiguity. A short-form response begins with a status word. The status word gets followed by an single data item.

There are 2 status word defined.

• .OK
• .ERROR

The data must begin on the same line as the status word and there should be as least 1 whitespace characters between the status word and the beginning of the data. The optional data must be processible as a single unit of data. The followings are accepted:

• unquoted text line ** The end of the data is denoted by a newline character. The newline character also terminates the status line. ** Leading and trailing spaces must be trimmed off
• quoted text ** If the first meaningful character of the option data is a double quote, the option data ends when another ordinary double quote is encounted. ** If a double quote is preceded by a backslash("), the double quote becomes part of the data and doesn't end the data. ** Not only the double quote, any character character escaped by a preceding backslash is treated literally. (e.g. \ -> a single back slash, \n -> n) ** Trailing spaces after the ending quote must be ignored until a newline character is encounted. The newline character terminates the status line.

Take note of the followings when parsing a short-form response message

• Whitespace characters before the status word shall get ignored.

See the following samples.

.OK authentication success

.ERROR double login attempt

.OK "authentication\twas\tsuccessful"

.OK "this is a multi-line string message"

Long-form response

A long-form response begins with the status word line. The status line should be composed of the status word and a new line. The status line must get followed by data format line and the actual response data. Optional attribute lines may get inserted between the status line and the data format line.

The data format line begins with .DATA and it can get followed by a data length or the word 'chunked'.

• .DATA
• .DATA chunked

Use .DATA where indicates the length of data in bytes if the response data is length-bounded. For instance, .DATA 1234 indicates that the following data is 1234 bytes long.

Use .DATA chunked if you don't know the length of response data in advance.

The actual data begins at the next line to .DATA.

The length-bounded response message looks like this. The response message handler must consume exactly the number of bytes specifed on the .LENGTH line starting from the beginning of the next line to .DATA without ignoring any characters.

 .OK
 .DATA 10
 aaaaaaaaaa

The chunked data looks like this. Each chunk begins with the length and a colon. The 0 sized chunk indicates the end of data. A chunk size is in decimal and is followed by a colon. The actual data chunk starts immediately after the colon. The response processor must consume exactly the number of bytes specified in the chunk size part and attempt to read the size of the next chunk.

The whitespaces between the end of the previous chunk data and the next chunk size, if any, should get ignored.

 .OK
 .DATA chunked
 4:xxxx10:abcdef
 ghi
 0:

With the chunked data transfer format, you can revoke the ongoing response data and start a new response.

 .OK
 .DATA chunked
 4:xxxx-1:.ERROR "error has occurred"

An optional attribute line is composed of the attribute name and the attribute value delimited by a whitespace. There are no defined attributes but the attribute name must not be one of .OK, ERROR, .DATA. The attribute value follows the same format as the status data of the short-form response.

 .OK
 .TYPE json/utf8
 .DATA chunked
 ....