Ellie Docs

Welcome to ellie docs! Here you can find every single help about writing ellie.

Here is the content of the docs

v1.8.0

What is ellie

Ellie is a type-safe programing language that runs on embedded and sandboxed environments.

Package Management

Ellie’s package manager Lia keeps all the packages in a global archive. Lia uses ellie’s pre-compile system, so when you install a package, it will be compiled and stored in the archive. This helps you out in speed and memory usage.

Universally Compiled

Ellie has leveling system on target environments. Packages with matching levels can be used on the target environment.

VM Levels

Level	Environment	Architecture
0	Windows	x86, ARM, x64
0	Linux	x86, ARM, x64
2	Redox	x86
0	MacOS	ARM, x64
1	Metal	ARM, RISC-V, x64

FFI Interface

Ellie has a Foreign Function Interface that allows you to call C functions from your code. Also you can call Ellie functions from C.

File Extensions

Extension	Description
ei	Ellie default file extension
eib	Ellie compiled package
eic	Ellie bytecode executable binary
eia	Ellie bytecode executable text
eig	Ellie bytecode debug info file

`.ei`

Ellie default file extension. Bare code contained in this file.

`.eib`

Ellie precompiled package.

`.eic`

Ellie bytecode binary executable.

`.eia`

Ellie bytecode text file

`.eig`

Ellie bytecode debug information. This file helps vm to resolve errors beyond stack locations

`.eih`

Ellie debug headers. This package contains debug headers. For tracking the source code location.

EllieC

EllieC is the compiler for the Ellie language

Commands

compile

elliec compile [file] -j -b [version] -c [module-description] -m [module-name] -p ./ -o bin -i [File]=[Folder]

Options
- -j | --json-log
  - Outputs the compilation log in JSON format
- -b | --binary-version
  - Version of the package
- -d | --module-description
  - Description of the module
- -m | --module-name
  - Name of the module
- -p | --output-path
  - Output path
- -o | --output-type json |
  - Output type
    - bin: Binary
    - json: JSON
    - byteCode: Bytecode
    - byteCodeAsm: Bytecode Assembly
    - depA: Dependency Analysis
    - nop: No Output
- -i | --import-module {binary}={workspaceFolder}:
  - Import a module
  - example usage: --insert-module ./ellieStd.eib. For referencing code in other modules, you can give directory path to this option. For example; --insert-module ./ellieStd.eib=./ellieStdFolder.
- c | --arch
  - Targeted architecture for bytecode
    - 64: 64bit
    - 32: 32bit
- -e | --exclode-std
  - Exclude standard library
- -s | --show-debug-lines
  - Show debug lines
- -w | --disable-warnings
  - Disable warnings
- -h | --help
  - Show help
- -a | --allow-panics
  - Allow panics

viewModule

elliec viewModule [file]

Options

-j | --json-log
- Outputs the viewer process log in JSON format

Output

    ModuleName        = test
    ModuleDescription = A ellie package
    ModuleVersion     = 1.0.0
    EllieVersion      = 2.0.0
    InnerModules      =
        ModuleName    = ellie
        ModuleVersion = 1.0.0

EllieVM

EllieVM is the Virtual Machine for ellie bytecode

Commands

run
ellievm run [file] -j -c 64
Options
- -j | --json-log
- Outputs the compilation log in JSON format
- -a | --arch
- Targeted architecture

EllieFMT

Formatter for the Ellie language

Commands

format
elliefmt format [file] -j
Options
- -j | --json-log
- Outputs the compilation log in JSON format
analyze
elliefmt analyze [file] -j
Options
- -j | --json-log
- Outputs the compilation log in JSON format

Lia - The package manager

Lia is the package manager for Ellie. Also version manager for ellie.

Lia will be re-written in Ellie soon.

Lia - The package manager

Lia is the package manager for Ellie. Also version manager for ellie.

Lia will be re-written in Ellie soon.

Installation

Windows (Not supported)

Not yet implemented

MacOS

sh -c "$(curl -L https://github.com/behemehal/Lia/releases/download/v0.1.0/mac_install.sh)"

Linux

sh -c "$(curl -L https://github.com/behemehal/Lia/releases/download/v0.1.0/linux_install.sh)"

Usage

Creating new project

lia init

Optios

-l or --lib: Create a library project.

This command will give you the file structure of a new project.

lia.yaml configuration file

package_name: MyProject
details: My project
license: MIT
version: 0.0.1
dependencies:
  - name: ellieStd
    version: 0.1.0
    url: github.com/behemehal/Ellie-Standard-Library

Installing packages

lia install <git_url>

Installed packages will be saved to global registry See registry command.

Installing features

lia install --feature <feature_name>

Installing Compiler

lia install --feature elliec

Installing EllieVM

lia install --feature ellievm

Publishing packages

`Publishing packages not ready`

For publishing packages, you need to register to lia.

~~After registering, you can get your api key and save it by running the following command:~~

Lia cannot serve any packages right now

lia config set api-key <api-key>

After that, you can publish your package by running the following command:

lia publish

Building packages

For compiling ellie workspace, you can use the following command:

lia build

Note

This command requires elliec feature.

Options

<target> [Not Required] - Targets current dir if not present

Running packages

For running ellie code, you can use the following command:

Note

This command requires elliec and ellievm feature.

lia run

Running tests

For testing ellie code, you can use the following command:

Note

This command requires elliec and ellievm feature.

lia test

Formatter

todo

Global Registry

Lia saves packages, features and executables to global registry. You can see registry info by running the following command:

lia registry

Deep Dive

Welcome to deeper level of the ice mountain.

Project Structure

-- lib
    | -- main.ei
-- lia.yaml

Let’s explore the file structure of the ellie project.

lib is the folder where all the code belongs
lib/main.ei is the main file generated by default.
lia.yaml is the configuration file for ellie.

Config command

Lia has a internal config command that allows you to set and get config values.

lia config get <key>

lia config set <key> <value>

Get all config values

lia config getAll

Todo

This page is not yet ready

Syntax

Keywords

Current Ellie keywords

fn - function
class - class
enum - Enum
v - variable
c - constant
co - constructor
this - Current object
for - for loop
go - Continue next iteration of loop
brk - Break loop
if - if statement
else if - else if statement
else - else statement
ret - return statement
get - getter
set - setter

Reserved Future Ellie keywords

function - Long form of fn
var - Long form of v
const - Long form of c
constructor - Long form of co
async - Asynchronous function
await - Await for asynchronous function
s- Static variable
static - Long form of s
while - while loop

Shortening

Ellie has a shortening for nearly every item in the language. You could use them to quickly build a thing in your mind. After that you can use ellie’s formatter to make it look pretty. Also you can choose to make it stand as is.

v is a short for var

c is a short for const

co is a short for constructor

ret is a short for return

g is a short for get

s is a short for set

Types

Data Types

Numeric
```
    int
    float
    double
    byte
```
String
```
    v name : string = "ellie";
```
Char
```
    v firstName : char = 'e';
```

Cloak

    v letters : (char, char, char, char, char) = ('e', 'l', 'l', 'i', 'e');

Array

    v letters : [char, *] = [
        'e',
        'l',
        'l',
        'i',
        'e'
    ];

Collective

    v letters : {int, char} = {
        1 :'e',
        2 :'l',
        3 :'l',
        4 :'i',
        5 :'e'
    }

Arrow Functions

    v callingAwesomeness : @(string, int):string = @(name, count):string {
        v awesomenes : string;
        for (element, count) {
            awesomenes += "ellie";
        }
        ret awesomeness;
    }

bool

Variables

Ellie has a very simple syntax for declaring variables.

v x = 5;

Giving a type to a variable is optional.

v x : int = 5;

Constants

For unchangeable variables, you can use the c keyword.

c x : int = 5;

Functions

fn functionName(param1: Type, param2: Type) : ReturnType {
    // function body
}

Native functions

Functions without bodies are native functions.

fn print(str: string);

Generics with functions

fn functionName<T>(param1: T, param2: T) : T {
    // function body
}

Functions with unsized parameter

fn functionName(*param1: T) {
    // function body
}

Now you can call the function with any size of parameter. But inside the function, variable param1 will be a array of T type.


fn functionName(*param1: int) {
    // function body
    println("I have " + param1.length + " elements");
}

functionName(1, 2, 3, 4, 5);
// I have 5 elements

functionName(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
// I have 10 elements

Classes

No constructor body

If body of the constructor is not given, values will be set to corresponding fields.

class Test {
    co(x);
    v x : int;
}

Generics

class Test<T> {
    co(x);
    v x : T;
}

Constructor body

class Test {
    co(x) {
        self.x = x;
    }
    v x : int;
}

Imports

Ellie has two kinds of imports:

Unnamed import

Imports anything public from module.

    import ellieStd;

    v age : int = 11;

Named import

Imports anything public from module, but with reference.

    import ellieStd as std;
    v age : std.int = 11;

File Keys

There is two types of file keys:

Global File Key

This could be used to store global file keys. For example disabling various syntax warnings.

@!allow="ClassNameRule"; //Allow 'ClassNameRule' rule to be ignored

Element File Key

This could be used in top of the language items. For example disabling single syntax warning or creating comment.

@description = "Print line";
@example = "
    v text = "Hello world!";
    test(text); //Prints 'Hello world!'
";
fn test(text: string) {
    print(text);
}

Getter / Setter

Getter

g test : int {
    ret 1;
}

Setter

s test(type:int) {
    print("Hello" + (type as string));
}

Deep Dive

Building Ellie

Package Features

Packages

ellie_engine - Ellie Engine contains tokenizer, parser, bytecode, fmt, vm and other core components.
elliec - EllieC is compiler binary for Ellie.
ellievm - EllieVM is virtual machine binary for Ellie.
elliefmt - EllieFmt is formatter binary for Ellie.

ellie-engine

Features
- compiler
  This feature enables only compiler related components. Imports following libraries ellie_tokenizer, ellie_parser, ellie_bytecode and ellie_core/compiler_utils.
- vm
  This feature enables only vm related components. Imports following libraries ellie_vm, ellie_vm/std.
- fmt
  This feature enables only fmt related components. Imports following libraries ellie_fmt.
- standard_rules
  This feature enables standard rules check on syntax. Imports following libraries ellie_parser/standard_rules.
- cli-utils
  This feature enables cli utils. Imports following libraries ellie_renderer_utils/cli-utils.
- B64
  This feature selects x64 architecture. Imports following libraries ellie_vm/B64.
- B32
  This feature selects x32 architecture. Imports following libraries ellie_vm/B32.
- B16
  This feature selects x16 architecture. Imports following libraries ellie_vm/B16.

Tools

Ellie has tools relasing reAssembling bytecode instuctions, cleaning up repository and many more.

clean_up.sh | clean_up.ps1

This script cleans up repository by removing all the compiled binaries and other files.
reAssembler.js

This script reAssembles instruction.json file to required instruction_table.rs, instruction_utils.rs and instructions.md files.
release.js

This script selected binaries and preapares output for release.
integration_test crate

This crate contains integration tests for Ellie. You can test compiler, tokenizer, parser, vm and fmt using this crate.

Run Stages

Ellie code has 4 stages to be run. These stages are:

Tokenizer Module
Tokenizes the code. This stage is the first stage of the code. It takes the code and splits it into code elements. These tokens are used in the next stage.
Parser
Parses the code. This stage is the second stage of the code. It takes the tokens and parses them into a tree and checks for type errors. These Definite items are used in the next stage.
ByteCode
Generates bytecode. This stage is the third stage of the code. It takes the Definite items and generates bytecode. These bytecode are used in the next stage.
VM
Runs the bytecode. This stage is the fourth stage of the code. It takes the bytecode and runs it.

Tokenizer Module

Source: /ellie_engine/tokenizer

Creating Tokenizer
- Example Implementation
  - Creating ProgramRepository
  - Building Pager
    - What is Pager::new?

Creating Tokenizer

Example Implementation

Creating `ProgramRepository`

To create tokenizer you should create a struct for [Program Repository]() trait. ProgramRepository is the file reader bridge between tokenizer and user-defined code.

Create a struct that implements ProgramRepository trait.

#[derive(Clone)]
struct Repository {
    used_modules: Vec<String>,
    main_hash: usize,
    module_name: String,
    target_path: String,
}

What is `ProgramRepository::read_main`?

Signature of ProgramRepository::read_main:

impl ProgramRepository for Repository {
    fn read_main(&self) -> MainProgram {
        //...
    }
    //...
}

What is ellie_engine::utils::MainProgram? And whats content of it?

By default every file’s should have a unique file_hash, contents of it file_content and directory information such as file_name and start_director. file_hash is a unique hash, but Id doesn’t need to be hash of file content. It can be anything that is unique.

Implementing `ProgramRepository::read_main`

In this example we got the hash of the file but its not necessary.

impl ProgramRepository for Repository {
    fn read_main(&self) -> MainProgram {
        let main_file_content = fs::read_to_string(&self.target_path).unwrap();

        let file_name = self.target_path.split("/").collect::<Vec<&str>>();
        let file_name = file_name[file_name.len() - 1];

        let mut main_file_hasher = DefaultHasher::new();
        main_file_content.hash(&mut main_file_hasher);
        let first_page_hash = main_file_hasher.finish();
        self.main_hash = first_page_hash as usize;
        MainProgram {
            file_content: main_file_content,
            file_name: 
            file_hash: first_page_hash as usize,
            start_directory: format!(
                "<ellie_module_{}>",
                self.cli_compiler_settings.compiler_settings.name
            ),
        }
    }
    //...
}

Now ProgramRepository::read_main function is implemented. Lets implement ProgramRepository::read_module function.

What is `ProgramRepository::read_module`?

Signature of ProgramRepository::read_module:

impl ProgramRepository for Repository {
    fn read_module(
        &mut self,
        link_module: bool,
        current_path: String,
        requested_path: String,
    ) -> ResolvedImport {
        //...
    }
    //...
}

So what is ResolvedImport? ResolvedImport is message that we’re sending to tokenizer.

#[derive(Default, Debug)]
pub struct ResolvedImport {
    pub found: bool,
    pub resolve_error: String,
    pub hash: usize,
    pub path: String,
    pub matched: ImportType,
}

ResolvedImport::found is a boolean that tells tokenizer if the file is found or not. If the file is not found tokenizer will throw an error. The error message is dependend on ResolvedImport::resolve_error if its provided it will display that custom error message. If not it will display default error message.
ResolvedImport::hash is a hash of the file. It can be anything that is unique.
ResolvedImport::path is a path of the file. It can be anything that is unique.
ResolvedImport::matched This is the part where everything gets complicated.
```
pub enum ImportType {
    Code(String),
    Module(Module),
}
```
So this enum has two variants. Code and Module. Code variant is for importing code. Module variant is for importing pre-compiled modules, we will talk about this later.
What is parameters of ProgramRepository::read_module?
- link_module is a boolean that tells tokenizer if the file is a module or not. Think of it like you are importing a module from package manager. Usually import imports from path this is why we need link_module parameter.
- current_path is a path of the file that is importing the module.
- requested_path is a path of the module that is being imported.

Implementing `ProgramRepository::read_module`

Providing Code `ImportType::Code`

In this example we will provide ImportType::Code (Text) to tokenizer. We will read the file and return it as ImportType::Code.

First of all, we should see how paramters could be:

Link module: false
Current path: <ellie_module_main>/main.ei
Requested path: ./deb.ei

What’s this <ellie_module_main>?

Ellie does not have a directory manager built-in because of maximum flexibility. So we need to provide a directory manager. In this example we will use <ellie_module_main> as our main directory. We already know our main.ei file’s path so its not that hard to figure out where is ./deb.ei file.

impl ProgramRepository for Repository {
    fn read_module(
        &mut self,
        link_module: bool,
        current_path: String,
        requested_path: String,
    ) -> ResolvedImport {
        let starter_name = format!("<ellie_module_{}>", self.module_name);
        match parse_module_import(&current_path, &requested_path) {
            Ok(path) => {
                ...
            },
            Err(err) => {
                ...
            }
        }

Wow what happened here? Do you remember module_name variable? We used it in Repository struct. Also parse_module_import function comes from ellie_engine::ellie_core::module_path module. It takes two parameters current_path and requested_path. It returns Ok(path) if the path is valid. If the path is not valid it returns Err(err). Now how to handle errors?

impl ProgramRepository for Repository {
    fn read_module(
        &mut self,
        link_module: bool,
        current_path: String,
        requested_path: String,
    ) -> ResolvedImport {
        let starter_name = format!("<ellie_module_{}>", self.module_name);
        match parse_module_import(&current_path, &requested_path) {
            Ok(path) => {
                ...
            }
            Err(err) => {
                ResolvedImport {
                    found: false,
                    resolve_error: "Cannot access outside of workspace".to_string(),
                    ..Default::default()
                }
            }
        }

If parse_module_import gives a error its definetly because of the path is not valid. So we will return ResolvedImport with found as false and resolve_error as Cannot access outside of workspace. Now lets handle Ok(path).

impl ProgramRepository for Repository {
    fn read_module(
        &mut self,
        link_module: bool,
        current_path: String,
        requested_path: String,
    ) -> ResolvedImport {
        let starter_name = format!("<ellie_module_{}>", self.module_name);
        match parse_module_import(&current_path, &requested_path) {
            Ok(path) => {
                let real_path = path
                    .replace(
                        &starter_name,
                        Path::new(&self.target_path)
                            .absolutize()
                            .unwrap()
                            .parent()
                            .unwrap()
                            .to_str()
                            .unwrap(),
                    ).clone();
                if Path::new(&real_path).exists() {
                    let mut file = File::open(&real_path).unwrap();
                    let mut contents = String::new();
                    file.read_to_string(&mut contents).unwrap();
                    let mut hasher = DefaultHasher::new();
                    contents.hash(&mut hasher);
                    ResolvedImport {
                        found: true,
                        hash: hasher.finish().try_into().unwrap(),
                        path,
                        matched: ImportType::Code(contents),
                    }
                } else {
                    ResolvedImport {
                        found: false,
                        resolve_error: "Path does not exist".to_string(),
                        ..Default::default()
                    }
                }
            }
            Err(err) => {
                ...
            }
        }
    }
}

In this part we got target_path from our struct. Its the main.ei file’s absolute path. path is <ellie_module_main>/deb.ei and we replaced <ellie_module_main> with absolute path of our main.ei file. Which in this case its /home/ellie/main.ei. Now we are changing <ellie_module_main> with this path. So the path is now /home/ellie/deb.ei. Now we are checking if the file exists. If it exists we will read the file and return it as ImportType::Code. If it does not exist we will return ResolvedImport with found as false and resolve_error as Path does not exist.

Providing Module `ImportType::Module`

This functionality will be removed in the future. So we will not talk about it.

Signature:

pub fn new(
        main: String,
        main_file_name: String,
        path: String,
        import_resolver: E,
        initial_hash: usize,
    ) -> Self {
        ...
    }

main is the main file’s content.
main_file_name is the main file’s name.
path is the main file’s path.
import_resolver is closure for importing modules. |link_module: boolean, path: string, current_path: string| -> ResolvedImport

Pager is interface for tokenizing workspace. It takes main file’s content and main_file_name and path and import_resolver and initial_hash. initial_hash is the hash of main file’s content. It returns Pager struct.

What is Pager::new?

let main_program = program_repository.read_main();
let mut pager = Pager::new(
    main_program.file_content,
    main_program.file_name,
    format!("{}/", main_program.start_directory),
    move |link_module, path, module_identifier| {
        program_repository.read_module(link_module, path.clone(), module_identifier)
    },
    main_program.file_hash,
);
match pager.run() {
    Ok(_) => Ok(pager.pages),
    Err(errors) => Err(errors),
}

Now we are creating Pager with main_program.file_content and main_program.file_name and format!("{}/", main_program.start_directory) and closure for importing modules and main_program.file_hash. Now we are running pager and if it returns Ok we are returning pager.pages. If it returns Err we are returning Err(errors).

In next stage, we will talk about Parser and how to use pager.pages.

ByteCode

Ellie ByteCode is the binary representation of an Ellie program that can be executed by the VM.

Instruction	Implicit	Immediate	Absolute	AbsoluteIndex	AbsoluteProperty	AbsoluteStatic	IndirectA	IndirectB	IndirectC	IndirectX	IndirectY
LDA	-	0x1	0x2	0x3	0x4	0x5	-	0x6	0x7	0x8	0x9
LDB	-	0xa	0xb	0xc	0xd	0xe	0xf	-	0x10	0x11	0x12
LDC	-	0x13	0x14	0x15	0x16	0x17	0x18	0x19	-	0x1a	0x1b
LDX	-	0x1c	0x1d	0x1e	0x1f	0x20	0x21	0x22	0x23	-	0x24
LDY	-	0x25	0x26	0x27	0x28	0x29	0x2a	0x2b	0x2c	0x2d	-
STA	0x2e	0x2f	0x30	0x31	0x32	-	-	-	-	-	-
STB	0x33	0x34	0x35	0x36	0x37	-	-	-	-	-	-
STC	0x38	0x39	0x3a	0x3b	0x3c	-	-	-	-	-	-
STX	0x3d	0x3e	0x3f	0x40	0x41	-	-	-	-	-	-
STY	0x42	0x43	0x44	0x45	0x46	-	-	-	-	-	-
EQ	0x47	-	-	-	-	-	-	-	-	-	-
NE	0x48	-	-	-	-	-	-	-	-	-	-
GT	0x49	-	-	-	-	-	-	-	-	-	-
LT	0x4a	-	-	-	-	-	-	-	-	-	-
GQ	0x4b	-	-	-	-	-	-	-	-	-	-
LQ	0x4c	-	-	-	-	-	-	-	-	-	-
AND	0x4d	-	-	-	-	-	-	-	-	-	-
OR	0x4e	-	-	-	-	-	-	-	-	-	-
ADD	0x4f	-	-	-	-	-	-	-	-	-	-
SUB	0x50	-	-	-	-	-	-	-	-	-	-
MUL	0x51	-	-	-	-	-	-	-	-	-	-
EXP	0x52	-	-	-	-	-	-	-	-	-	-
DIV	0x53	-	-	-	-	-	-	-	-	-	-
MOD	0x54	-	-	-	-	-	-	-	-	-	-
JMP	-	-	0x55	-	-	-	-	-	-	-	-
JMPA	-	-	0x56	-	-	-	-	-	-	-	-
CALL	-	-	0x57	-	-	-	-	-	-	-	-
RET	0x58	-	-	-	-	-	-	-	-	-	-
PUSH	-	-	0x59	0x5a	-	-	0x5b	0x5c	0x5d	0x5e	0x5f
SPUS	-	-	0x60	0x61	-	-	0x62	0x63	0x64	0x65	0x66
LEN	-	-	0x67	-	-	-	-	-	-	-	-
A2I	0x68	-	-	-	-	-	-	-	-	-	-
A2F	0x69	-	-	-	-	-	-	-	-	-	-
A2D	0x6a	-	-	-	-	-	-	-	-	-	-
A2B	0x6b	-	-	-	-	-	-	-	-	-	-
A2S	0x6c	-	-	-	-	-	-	-	-	-	-
A2C	0x6d	-	-	-	-	-	-	-	-	-	-
A2O	0x6e	-	-	-	-	-	-	-	-	-	-
ARR	0x6f	-	-	-	-	-	-	-	-	-	-
STR	0x70	-	-	-	-	-	-	-	-	-	-

EllieDocs