Veeyu Programming Language and Libraries

Programs

A Veeyu program is composed of zero or more forms. A semicolon character (;) or a line break is used for a boundary between forms.

<source-code>    ::= [ <shebang-line> ] <program>
<shebang-line>   ::= "#!" { <any character> - <newline> } <newline>
<program>        ::= { <form-separator> }
                     { <form> <form-separator> { <form-separator> } }
                     { <form-separator> }
<form-separator> ::= ";" | <newline>

A program has to be a Unicode string, not a byte string. Typically it is stored in a file, and the program reader i.e. parser reads it from the file. But because files store byte strings, not Unicode strings, so the program reader treats files as UTF–8 string by default. And program readers may implement following optional advantages:

• Detects the BOM (Byte Order Mark) from the beginning of the source code.
• Detects the -e/--encoding option from the shebang line.
• Character encoding auto-detection by some heuristics like Mozilla universal character encoding detection.

For example, an implementation may guess that the following Veeyu program is encoded by EUC-KR.

#!/usr/bin/env veeyu -eeuc-kr
write-line!: "안녕, 比喩!"

A program can start with shebang line, the #! syntax used in scripts to indicate an interpreter for execution in Unix, and then its first shebang line is just ignored. It is not a general comment in Veeyu, but just a character sequence ignored only in the beginning of the program. So, for example, the following program causes <name-error>, because #!/usr/bin/env is parsed to a symbol which is undefined.

"""The first line is not a shebang."""
#!/usr/bin/env veeyu -eascii

In order to use a symbol that starts with #! in the beginning of program, keep the first line empty or insert a meaningless shebang line.

#!/usr/bin/env veeyu
"""Shebang-line test."""
#!symbol := 123

The above example defines #!symbol, is 123.

As above examples showed, an implementation may provide several options through shebang line. For example, if an implementation is a compiler, it may have a -r/--restrict option or a -e/--extension for bootstrapping.

$!/usr/bin/env veeyu --restrict=eval,typeinfer --extension=partialclass
require: partial := veeyu.ext.partialclass

partial.extend!(<attribute-name>,
                +apply: method (environment: <object>) {
                  environment.+get-attribute(self)
                })

partial.extend!(<attribute>,
                +apply: method (environment: <object>) {
                  self.receiver(environment).+get-attribute(self.attribute)
                })

partial.extend!(<quote>,
                +apply: method (environment: <object>) {
                  self.form(environment)
                })

partial.subclass!(<form>, <function>)

Forms

There are several types of forms:

• Symbols e.g. apple, <fruit>
• Attributes e.g. apple.color
• Quotes e.g. :apple, :(eat(apple))
• Number literals e.g. 123, 3.14
• String literals e.g. 'Avishai Cohen', "Structure in Emotion"
• Calls e.g. eat(apple, with: fork)
• Indices e.g. [1, 2, 3, 4], [x * 3, x: 1 ~ 100, x +isa? <odd-number>]
• Definitions e.g. pi := 3.14, a = a + 1
• Blocks e.g. { eat(apple); eat(apple, with: fork) }

Read further for details.

<form> ::= <symbol> | <attribute> | <quote>
         | <number-literal> | <string-literal>
         | <call> | <index> | <definition> | <block>

Symbols

Symbols are used for identifiers. A symbol can be most of words e.g. value, <abstract-class>, +, ==. However, it’s not there is no constraint for symbols.

• Cannot be = or :=. Because these are treated as definition operators.

• Cannot include any whitespace characters e.g. like this.

• Cannot include period character (.) e.g. like.this. Because these are treated as attributes.

• Cannot consist of only digits even if a hyphen character (-) leads e.g. 123, -123. Because these are treated as number literals.

• Cannot include colon character (:) e.g. :like-this, like-this:. Because symbols with a leading colon are treated as symbol quotes, and symbols with a trailing colon are treated as function/macro calls.

• Cannot include any of parentheses, square brackets or curly brackets e.g. like(this), like[this], like{this}. Because these are treated as function/macro calls, indices or blocks.

• Cannot include commas (,) e.g. like,this. Because commas are already reserved for separation of arguments in a function/macro call.

• Cannot include semicolon characters (;) e.g. like;this. Because semicolons are already reserved together with new line characters for separation of statements.

• Cannot include single quotes (') or double quotes (") e.g. like-this', like"this". Because these quotation marks are already reserved for string literals.

Though there are above many constraints, practically it is not a problem and symbols are expressive enough. For example, you can append a trailing question mark (?) into names of predicate functions like is-okay?.

Symbols can include underscore characters (_) like other programming languages, but Veeyu prefer instead hyphen characters (-) for separation of words according Lisp tradition.

<symbol>   ::= ( <sym-char> - ( <digit> | "=" ) ) { <sym-char> }
             | "=" <sym-char> { <sym-char> }
<sym-char> ::= <any charactr> -
               ( <whitespace> | ":" | "." | "," | ";" | "(" | ")" |
                 "[" | "]" | "{" | "}" | '"' | "'" )

Attributes

Every value (object) has some attributes. We can say that physically every object is just a key-value storage (where keys are surely attribute names) which remembers its class. And there’s a syntax to access to it.

a-value.an-attribute

Attribute syntax is like the above code: the first receiver form (a-value in the example) comes, a middle period character (.) follows, and the trailling attribute name (an-attribute in the example) ends. If whitespaces close to the middle period character present, they are ignored.

a-value . an-attribute
a-value. an-attribute
a-value .an-attribute

New line characters follows the middle period character are acceptable.

a-value.
an-attribute

Attribute name can be either a symbol, an index or a block.

a-value.symbol-attribute
a-value.[index-attribute]
a-value.{ block-attribute }

Middle period character can be omitted if the attribute name is an index or a block.

a-value[index-attribute]
a-value { block-attribute }

Attribute access is internally a call of +get-attribute method. For example, the following three forms:

receiver.symbol-attribute
receiver[index-attribute]
receiver { block-attribute }

and following three forms:

receiver.+get-attribute(:symbol-attribute)
receiver.+get-attribute(:([index-attribute]))
receiver.+get-attribute(:({ block-attribute }))

share the same behavitor.

<attribute>      ::= <form> "." <attribute-name>
                   | <form> ( <index> | <block> )
<attribute-name> ::= <symbol> | <index> | <block>

Quotes

Quotes are similar to Lisp’s quotes. A leading colon character and trailing parentheses that wrap a form are quote forms. They are evaluated as form objects.

:(form)
:(1)
:(complex(form))
:identifier

Parentheses can be omitted when a quoted form is an symbol.

<quote> ::= ":(" <form> ")"
          | ":" <symbol>

Number Literals

Number literals represents <integer> and <float> instances like 123 and 3.14. It includes a minus sign, because Veeyu has no unary operator. (That’s why symbols cannot be decimal string even a hyphen leads like -123.) But there’s no plus sign for number literals.

Number literals accept decimal numbers only. Hexadecimal or octal numbers can be represented by string literals with prefix characters.

<number-literal>   ::= <integer-literal> | <float-literal>
<integer-literal>  ::= [ "-" ] <digit> { <digit> }
<float-literal>    ::= <integer-literal> "." <digit> { <digit> }
                     | <exponent-literal>
<exponent-literal> ::= <integer-literal> [ "." <digit> { <digit> } ]
                       [ "e" | "E" ] [ "+" | "-" ] <digit> { <digit> }

String Literals

The main purpose of string literals is to represent string values by hardcoding in source codes. There are four types of string literals:

There are special escaping sequences for double-quoted strings: most of C-style escape sequences.

Single-quoted strings can be named as raw string also; escape sequences described above are interpreted just literally in single-quoted strings.

It can also have a prefix character is a case-sensitive roman character i.e. [A-Za-z] in a regular expression, so it can be used for representing another types of values.

The type of an evaluated string literal can be vary depending on its prefix character, but its type is invariable in the same prefix character. For example, string literals with the prefix character c are evaluated as a <character> object.

Any other prefix characters not described in the above table of prefix characters can be user-defined or extended by the specific implementation but defining a prefix character is not preferred because of forward compatibility.

How to define an operation of prefix character is just to define +literal-x-type and +literal-x function in the environment where x is a prefix character to define its operation.

+literal-r-type := regex.<pattern>
+literal-r := regex.compile

For example, the above code defines a prefix character r, then a form r'^[a-z]' will be evaluated to an instance of regex.<pattern> class, that is a return value of a call regex.compile('[^a-z]'). Evaluating a string literal with undefined prefix character cause a <literal-error>, a subclass of <syntax-error>.

If a return value of a call the function +literal-x is not an instance of +literal-x-type (or its subtype), it raises a <type-error>.

<string-literal>          ::= [ <string-literal-prefix> ]
                              <string-literal-body>
<string-literal-prefix>   ::= <alpha>
<string-literal-body>     ::= <string-literal-doublequote-body>
                            | <string-literal-doublequote-body>
<string-literal-dq-body>  ::= '"' { <string-item> } '"'
                          ::  <string-literal-quote> ::= '"'
<string-literal-sq-body>  ::=  "'" { <string-item> } "'"
                          ::  <string-literal-quote> ::= "'"
<string-literal-tdq-body> ::=  '"""' { <string-item> } '"""'
                          ::  <string-literal-quote> ::= <no character>
<string-literal-tsq-body> ::=  "'''" { <string-item> } "'''"
                          ::  <string-literal-quote> ::= <no character>
<string-literal-quote>    ::= '"' | "'"
<string-item>             ::= <string-character> | <string-escape-sequence>
<string-character>        ::= <any character> - "\" - <string-literal-quote>
<string-escape-sequence>  ::= "\" <any character>

Calls

The call, the calling form is either a function application, a macro expansion or a fexpr call. It takes zero or more arguments wrapped with parentheses, typically, in the case of normal calling form.

There are three types of calling forms.

normal calling form

A traditional C-style calling form e.g. function(arguments), function(). It can takes positional arguments and named arguments both.

simple calling form

A calling form using only beginning colon character instead of wrapping parentheses pair e.g. function: arguments. There is a limit that named arguments cannot be applied for simple calling forms and it must one or more positional arguments.

binary operator form

A binary operator-style calling form e.g. receiver attribute argument. There is a limit that only one (and not zero) positional argument can be applied for binary operator form and its function is an attribute form.

The mostly used calling form is a normal calling form. Because it can replace any other two types of calling forms.

The purpose of a simple calling form is a typography of C block-style macro, fexpr or higher-order functions:

[1, 2, 3, 4].for-each!: \(el) {
  io.*stdout*.write(el)
}

All of binary operator forms can be replaced by any other calling forms. So, every calling form of the next code has the same behavior:

receiver method argument
receiver.method: argument
receiver.method(argument)

The purpose of a binary operator form is a typography of binary operator-style methods as its name. For example, sum two integers can operated with the instance method + of the <integer> class like 12.+(34), it usually is represented like the following code:

12 + 34

All of simple calling forms can be replaced by normal calling forms:

function: argument
function(argument)

Calling a function with no arguments or some named arguments can be represented by normal calling form only:

function()
function(a: 1)
function(a, b: 2)
function(a: 1, b: 2)

It is not every object can be called. There are <callable> objects like functions, macros, fexprs and classes. <callable> type has a method named +call, and it can say that calling forms are aliases of invoking a method +call.

Therefore, every form of the following code shares the same behavior:

f(x)
f.+call(x)
f.+call.+call(x)
f.+call.+call.+call(x)

Because all of +call attributes (in <callable> objects) have to be a <callable> object also. Recursive invoking +call method can be stopped when a +call attribute and its receiver are the same object.

Calling an object that is not <callable> causes a <call-error>, a subtype of <type-error>.

Any trial of definition of call causes a <call-definition-error>, a subtype of <call-error> and <definition-error> unless +define macro is redefined by user.

<call>                  ::= <form> "(" <argument-list> ")"
                          | <form> ":" <unnamed-argument-list>
                          | <binary-operator>
<binary-operator>       ::= <form> <symbol> <form>

Indices

An index is an argument list wrapped with square brackets. Its purpose is to style accessor methods of data structures typographically similar to subscript indexing e.g. map[:key].

It is a syntactic sugar for a call +index macro (or fexpr), assumed already defined. For example, the following two forms share the same behavior:

[1, 2, 3, 4]
+index (1, 2, 3, 4)

In short, an index form:

[argument-list]

is an alias of:

+index (argument-list)

And of course, an index form with no arguments:

[]

is an alias of:

+index ()

Index can be an attribute name also. In this case, it finds +index macro (or fexpr) in the same receiver.

For example, two forms of the following code have the same behavior:

list.[1]
list.+index (1)

In short, a following form:

receiver.[argument-list]

is an alias of:

receiver.+index (argument-list)

And a middle period character (.) can be omitted when an index is an attribute name:

receiver[argument-list]

The best examples of typographical use of indices are list comprehensions and random access for <sequence>s.

[x * 3, x: 1 ~ 100, x +isa? <odd-number>]
list[123]

Environments or receivers that invoke indices have to be an instance of <indexable>. If it’s not, it raises a <index-error>, a subtype of <type-error>.

Unless +define macro is redefined by user, the following two forms are equivalent:

receiver[index] := value
receiver.+define-index (index, value, local: true)

In the same manner, setf definition form:

receiver[index] = value

is the same as:

receiver.+define-index (index, value, local: false)

provided the receiver is an <index-definable> object. If not, it raises <index-definition-error>, a subtype of <index-error> and <definition-error>.

Note that a value +define-index method returns is just ignored and an index definition form returns its rvalue, evaluated. So if we have to explain about index definitions exactly, f(r[i] := v()) is equivalent to _v := v(); r.+define-index (i, _v, local: true); f(_v) (but the name _v is never exposed, is used only for explanation).

<index> ::= "[" <argument-list> "]"

Definitions

A definition is either a call to a user-defined defining macro (or fexpr), or a call to a built-in defining macro. In any case, it is a just syntactic sugar for a call +define macro, assumed already defined.

For example, following two lines have the same behavior:

minhee-hong := <person>()
+define (minhee-hong, <person>(), local: true)

Following code is the same:

greet(name: <string>) = "Hi, " ++ name
+define (greet(name: <string>), "Hi, " ++ name, local: false)

In short, a := local definition form (:=, also called as let definition):

(lvalue-form) := (rvalue-form)

is an alias of:

+define ((lvalue-form), (rvalue-form), local: true)

In the same manner, a setf definition form (=, also called as assignment):

(lvalue-from) = (rvalue-from)

is an alias of:

+define ((lvalue-form), (rvalue-form), local: false)

There’s +define defined in the root class <object>, a built-in defining macro. So typically a definition makes a binding in the environment by default.

<definition> ::= <form> ( ":=" | "=" ) <form>

Blocks

The main purpose of blocks is to style macros/fexprs typographically to make programmers to guess that forms in the block are not evaluated immediately. It takes a program that contains zero or more forms.

It is a syntactic sugar for a call +block macro (or fexpr), assumed already defined.

{ msg := "log: " ++ $0
  io.*stdout*.write(msg) }

For example, the above code and the following code share the same behavior:

+block (msg := "log: " ++ $0,
        io.*stdout*.write(msg))

In short, a block form:

{ form-1; form-2; form-3; form-n }

is an alias of:

+block (form-1, form-2, form-3, form-n)

And of course, an empty block form:

{}

is an alias of:

+block ()

Block can be an attribute name also. In this case, it finds +block macro (or fexpr) in the same receiver.

For example, following forms of two lines have the same behavior:

\(a, b).{ a + b }
\(a, b).+block (a + b)

In short, a following form:

receiver.{ forms }

is an alias of:

receiver.+block (forms)

And a middle period character (.) can be omitted when a block is an attribute name:

receiver { forms }

The best example of typographical use of blocks is a lambda syntax.

\(a, b) { a + b }

Environments or receivers that invoke blocks have to be an instance of <block-callable>. If it’s not, it raises a <block-error>, a subtype of <type-error>.

Any trial of definition of block or block attribute causes a <block-definition-error>, a subtype of <block-error> and <definition-error> unless +define macro is redefined by user.

Under the hood, a form receiver { forms } actually becomes compiled to:

receiver.+get-attribute(:({ forms }))

Because { forms } is an attribute name in this case. And then, default +get-attribute method defined in <object> raises a <block-error> when its name argument is a <block>. Instead, <block-callable> overrides +get-attribute method to call +block method.

<block>          ::= "{" <program> "}"

Argument lists

Argument lists are mini syntax used inside calls or indices. Arguments are separated by comma characters (,). A trailing comma after all arguments is also allowed, but usually omitted.

There are two argument types:

Positional argument (unnamed argument)

Passed by its position.

Named argument (keyword argument)

Passed by its name. There is a preceding name symbol with a trailing colon (:) that separates an argument name and its value for each named argument e.g. name: value.

There is a defined rule of argument passing for function applications and most macro expansions (but except fexpr calls).

• Passes named arguments to the parameters that have a matched name.
• Passes positional arguments to their matched position in the parameter list excluding already matched named parameters.

For example, assume that there’s a defined function f:

f := \(a, b, c, d) { [a, b, c, d] }

Then four applications of the following code share the same return value [1, 2, 3, 4]:

f(1, 2, 3, 4)
f(a: 1, b: 2, c: 3, d: 4)
f(d: 4, c: 3, 1, 2)
f(2, a: 1, d: 4, 3)

But rarely, fexprs can have a their different rule of arguments passing. For a representative instance, list comprehensions are not a specific syntax of Veeyu, but implemented by a fexpr aware to its exact argument positions and names.

<argument-list>         ::= [ <argument> { "," <argument> } [ "," ] ]
<unnamed-argument-list> ::= [ <form> { "," <form> } [ "," ] ]
<argument>              ::= [ <symbol> ":" ] <form>

Glossary

abstract class

An instance of <abstract-class>; cannot be instantiated directly and would be subclassed.

class

An instance of <class>.

instance of <c>

An object that has <c> as its +class property.

kind of <t>

An object that satisfies <t>.is-type?(object) returns true i.e. object.isa?(<t>) returns true.

method

A property, an instance of <method>.

type

An instance of <type>.

union type

An instance of <union-type>.

intersection type

An instance of <intersection-type>.

Control Structures

factorial := \(integer) {
  (integer > 1) then (factorial(integer - 1) * integer, 1)
}

adder := \(number) {
  \(delta) {
    number = number + delta
  }
}

>>> a := adder(1); a(1)
==> 2
>>> a(2)
==> 4
>>> b := adder(1); b(1)
==> 2

>>> adder2 := \(number) {
...   \(delta) { number := number + delta }
... }
==> \(number) { ... }
>>> c := adder2(1); c(1)
==> 2
>>> c(1)
==> 2
>>> c(2)
==> 3

a := 1
b := 2
assert (b == (a + 1))

a := 1
b := 2
(b == (a + 1)).then(<assert-error>().rise!(), nil)

assert (b == (a + 1), "b must be a + 1")

(b == (a + 1)).then(<assert-error("b must be a + 1").rise!(), nil)

Basic Types

true.not := false
false.not := true

true.+apply := \(true-value, false-value) {
  true-value
}

false.+apply := \(true-value, false-value) {
  false-value
}

true.then := macro (true-value, false-value) {
  true-value(environment)
}

false.then := macro (true-value, false-value) {
  false-value(environment)
}

true.and := macro (operand) {
  <boolean>(operand(environment))
}

false.and := macro (operand) {
  false
}

true.or := macro (operand) {
  true
}

false.or := macro (operand) {
  <boolean>(operand(environment))
}

true.and? := \(operand) {
    operand
}

false.and? := \(operand) {
    false
}

true.or? := \(operand) {
    true
}

false.or? := \(operand) {
    operand
}

Object Protocol

Veeyu has modern and powerful object-oriented runtime type facilities: metaclasses, multiple inheritance (using C3 linearization) and multimethods.

<object>.+make(a: 1, b: 2)

hash  := an-object.+get-attribute(:+hash)
hash2 := an-object.+hash

<integer-or-string> := <integer> | <string>

<mutable-enumerable> := <mutable-object> & <enumerable>

<integer-or-string> := <union-type>(<integer>, <string>)

<mutable-enumerable> := <intersection-type>(<mutable-object>, <enumerable>)

<odd-number> := <predicate-type>: \(value: <integer>) {
  value.rem(2) == 1
}

<point> := <class>(x: <integer>,
                   y: <integer>)

p := <point>(x: 10, y: 15)

<point3d> := <point>.subclass(z: <integer>)
p3d := <point3d>(p, z: 20)

<point> := <class> {
  +make := class-method (x: <integer>, y: <integer>) {
    super.+make(x: x, y: y)
  }

  is-aligned-horizontally? := method (point: <point>) {
    self.y == point.y
  }

  is-aligned-vertically? := method (point: <point>) {
    self.x == point.x
  }
}

Forms

Veeyu is a homoiconic language like Lisp. Therefore it has to provide classes for representing its codes. There are several types of forms in Veeyu. Form classes are straight model classes of them. An instance of these classes can be created with a quote syntax also, not only by these constructors.

f := :y
quote(x + ~f + x.~f)

:(x + y + x.y)

f := :x
quote(f + ~f + ~~f + ~~~f + ~~~~f)

:(f + x + ~f + ~~f + ~~~f)

:(a + b + (c - d)).replace(:c, :k)

:(a + b + (k - d))

:(a + b + (c - d(e - f) * g)).replace(:(d(e - f)), :h)

:(a + b + (c - h * g))

:(a + :(b + c)).replace(:b, :d)

:(a + :(b + c))

:(a + :(b + c)).replace(:b, :d, includng-quote: true)

:(a + :(d + c))

>>> :hello.+class
<symbol>

>>> :([123]).+class
<index>

>>> :({ block! }).+class
<block>

>>> <attribute>(:receiver, :attribute)
:(receiver.attribute)
>>> <attribute>(:receiver, :([123]))
:(receiver[123])
>>> <attribute>(:receiver, :({ block! }))
:(receiver { block! })

Exceptions

Veeyu provides exception handling mechanism and basic hierarchy of exceptions and errors.

f := \() {
  <return>(value: 123).rise!()
}

val := f()

f := \() {
  return (123)
}

val := f()

return := \(value) {
  <return>(value).rise!()
}

raise: <exception>()
raise (<exception>)

Data Structures

Veeyu contains several common data structures like strings, hash maps. You can find test codes for them in the directory /runtime/tests/data-structures/.

l.fold(\(a, b) { a + b }, 0)

l.fold(\(a, b) { a + 1 }, 0)

method (binary-operation: <function> taking 2, identity) {
  empty := nil +is? self.rest
  empty.then(identity,
             binary-operation(identity,
                              self.rest.fold(binary-operation, self.first)))
}

method (map(<function> taking 1) := <boolean>) {
  self.null.then(true,
                 map(self.first) and self.rest.is-all?(map))
}

method (map(<function> taking 1) := <boolean>) {
  self.null.then(false,
                 map(self.first) or self.rest.is-any?(map))
}

method (do!: <function> taking 1) {
  empty := nil +is? self.rest
  empty({},
        { do!(self.first)
          self.rest.for-each!(do!) })()
}

"""It calculates `100 - 1 - 2 - 3 - 4 - 5`."""
[1, 2, 3, 4, 5].fold(\(a, b) { a - b }, 100)

method (binary-operation: <function> taking 2, identity) {
  empty := nil +is? self.rest
  empty.then(identity,
             binary-operation(identity,
                              self.rest.fold-left(binary-operation,
                                                  self.first)))
}

Module System

Veeyu provides facilities of modules, packages and namespaces to support modular programming.

require: module-name

require: datetime, regex

require: bytes.encodings,
         io.*stdout*

message := 'Hello modular programming!'
bytes := encodings.<utf-8>.encode(message)
*stdout*.write-line!(bytes)

require: encs := bytes.encodings,
         stdout := io.*stdout*

require: bytes.encodings

encodings := import(:(bytes.encodings))

hello := <module>()

hello-env := <environment>()
with (hello-env) {
  greet := \(name) {
    'Hello ' ++ name
  }
}
hello := <module>(hello-env)

>>> hello.greet('Hong Minhee')
==> 'Hong Minhee'

use-literal: bytes (B)
example := B'byte string'

require: io.bytes.+literal-B-type, io.bytes.+literal-B

use-literal: bytes (B: o)
example := o'byte string'

module bytes — Byte Strings

It provides byte type and bidrectional codec interface between bytes and string.

use-literal: bytes (B)
example := B'byte string'

module bytes.encodings — Codecs

module io — Input/Output Streams

To make programs useful, these have to interact with “outer world” e.g. users, other programs. This module abstracts generalized stream concept from channels for such communications.