Information Technology Environment — Ember

Introduction

This section documents the Ember computing environment: a centralized append-only information store, a computer operating system integrated with that information store, and related specifications.

Overview

The computing environment will consist of the following components:

Development principles

Prerequisites for code to be added to the repository

How issues should be prioritised

Ordered from highest priority to lowest priority

  1. Security vulnerabilities
  2. Functional regressions
  3. Incorrect results
  4. Crashes and similar critical usability issues
  5. Slow code with a significant impact on usability
  6. Aesthetic regressions
  7. Minor usability issues
  8. Slow code with a moderate impact on usability
  9. Missing features

Data formats

Ember Language

Objective: Develop a machine-readable language that can be source-to-source translated into other languages. A NQP translator should be the current development priority, followed by Qt and JavaScript translators.

Ember Language programs may optionally declare a non-default language profile to use: Core, Basic, and Dangerous (the default is "Standard"). Core and Basic both restrict the program to a subset of the language. The Basic language interpreter is written using the Core subset of the language, and provides useful shortcuts to use in the development of the interpreter for the Standard profile. The Default language interpreter is written using the Basic subset of the language. The Dangerous profile allows using language features which are probably a bad idea to use, but may be needed in some cases.

Ember Language programs can optionally run in one of three modes: Document, Terminal, and Web; these modes set up a basic environment for the program for running with a graphical raster display output, with a character-based terminal output, and as a Web server, respectively.

Specification

Standard syntax (Ember Language source files, terminal: .em/.emc/.emb/.emd; document: .ed/.edc/.edb/.edd; Web: .ew/.ewc/.ewb/.ewd)

Ember Language source files are a subset of ASCII text files, with lines delimited by 0x3B0A (semicolon+line feed). Bytes 0x00 through 0x09, 0x0B through 0x1F, and 0x7F through 0xFF (all ranges inclusive) are invalid. (0x0A may not be used except as a line separator.) File must end with 0x0A.

Text after a "#" on a line are comments.

Ember Language intermediate code, .emi

This is similar to standard syntax, but where shorthand notations are all expanded into the equivalent Dc sequences.

Ember Language sequence files, .ems

A comma-separated list of Dc numbers.

Ember Language Dc documents, .edc

Documents stored using a format similar to the DCE file format.

Ember Record Documents, .emr

This is a special format that can only represent a subset of Ember Documents, used for records storage in the Ember cloud.

Routines with some dangerous properties must be labeled accordingly, as follows:

cs!
Changeable routine signature (subtypes don't need to use this routine's signature when overriding it.)
nd!
Non-deterministic

Object hierarchy

All objects are addressed through a hierarchy:

lang
Basic language Objects and Routines (automatically included)
system
Objects and Routines related to the Ember environment
math
Objects and Routines related to mathematics

Types

Types have CamelCase names beginning with an uppercase letter.

C Type
Traits
C Type$type
Routines
C cs!this.$type:new(FuzzyList$params) { lang.new(this) }
C Routine
Traits
  • C String$code
  • C (Null|Routine)$onExit
Routines
  • C Any:run(FuzzyList$params) { lang.run(this,lang.cast($params,List,"return")) }
  • C Boolean:compare(Any$object) { /* return true if this object is identical to $object */ }
C List
Traits
  • B List{set this.$allowedTypes=lang.new(List).add(Type)}$allowedTypes: List of allowed types that can be put in this list
  • C Natural$last: last valid index
  • C Natural$count: number of entries
  • B (Null|Natural)$entryLimit: number of entries that the list may hold; defaults to Null (meaning unlimited)
  • S (Null|Natural)$indexLimit: maximum index the list may use; defaults to Null (meaning unlimited)
Routines
  • B Void:add(String$value|List$value) { this.insert(this.last()+1) }
  • B Void:set(Natural$index,(String$value|List$value)) { lang.set(this.record($index),$value) }
  • B Any:get(Natural$index) { lang.get(this.record($index)) }
  • C Reference:record(Natural$index) { lang.getListEntry(this,$index) }
  • B Void:insert(Natural$index,(String$value|List$value)): insert $value at $index, moving the current $index and following items ahead by $value.count() if it's a list, and by 1 if it's a string
C FuzzyList (inherits from List)

When a FuzzyList is used in a list, its contents are appended to the list, and it is deconstructed. When a FuzzyList is used in the declaration of the parameters of a Routine, its first elements, starting from 0, are set to the values of the parameters passed to the Routine from its position onwards (so, for example, if the parameters declared are Natural$a,Natural$b,FuzzyList{ lang.set(lang.trait(this.entryLimit),2) }$c,Natural$d,Natural$e and it gets called with 2,3,4,5,6,7,8, then that's an error because there's no place to put 6 (the 5th parameter) (but if the entryLimit weren't set, a=2,b=3,c=(4,5,6),d=7,e=8), and if it gets called with 2,3,4,5,6,7, a=2,b=3,c=(4,5),d=6,e=7).

C Resource
Traits
Routines
System object: Traits

Traits have camelCase names beginning with a lowercase letter. Routines are a type of trait.

C nd!List[Resource]:system.resources
List of resources (I/O, etc) available.
C nd!String:system.implementation
Description of the language backend.
System object: Routines

Routines have camelCase names beginning with a lowercase letter, and have parameters.

C Void:lang.run(Routine$routine,List$params)
Exceptions thrown
!routineSyntaxError, !parameterNumberMismatch, !parameterTypeMismatch
Notes
Determinism depends on String:$routine.code.
C (Void|$type):lang.cast(Any$object,Type$type,(|String$return))
Return value
None, unless $return="return" in which case it returns an object of type $type
Exceptions thrown
!incompatibleTypeError
Notes
If $return="return", determinism depends on types of objects (specifically, on value of String:$object.cast:$type.code).
C (Void|$trait.type):lang.set(Reference$trait,Any$value,(|String$return))
Return value
None, unless $return="return" in which case it returns an object of type $trait.type
Exceptions thrown
!targetTypeMismatch
Notes
If $return="return", determinism depends on $value.
C $trait.type:lang.get(Reference$trait)
Return value
An object of type $trait.type
Exceptions thrown
(none additional)
Notes
Determinism depends on $trait.
C Reference:lang.trait(Any$object)
Return value
A reference to the object passed to it
Exceptions thrown
(none additional)
Notes
(none)
C Boolean:lang.compare(Any$left,Any$right)
Return value
lang.and($left.compare($right),$right.compare($left))
Exceptions thrown
(inherit from $left.compare and $right.compare)
Notes
(none)
S Any:lang.otherwise(Routine$left,Routine$right)
Return value
try { return $left }; except { return $right }
Exceptions thrown
(inherit from $left and $right)
Notes
(none)