SOARE

SOARE Documentation

Welcome to the SOARE documentation! SOARE is a simple, interpreted programming language write in C, designed to be easy to learn, especially for beginners. This documentation will guide you step by step, explaining basic concepts with concrete examples. We’ll draw from the original documentation and practical examples like those in the test/array.soare file.

Table of Contents

What is SOARE?

SOARE is an interpreted programming language, meaning you can write code and run it immediately without compiling first. It’s simple, write in C, and perfect for learning the basics of programming. You can use it for scripts, calculations, or even more complex programs.

Before starting, make sure you have installed SOARE (see Installing SOARE).

Interpreter

The SOARE interpreter allows you to run code from the command line or via files.

Installing SOARE

To install SOARE, download the release from the official repository: https://github.com/AntoineLandrieux/SOARE/.

With Git:

git clone https://github.com/AntoineLandrieux/SOARE.git

On Windows, after compiling the interpreter (see below), run the install.bat file.

To launch SOARE:

# Linux
bin/soare
# Windows
%SOARE%\\bin\\soare.exe

Compiling the Interpreter

Recommended Tools for Windows:

Recommended Tools for Linux:

# Ubuntu / Debian based Linux Distributions
sudo apt update && sudo apt upgrade -y
sudo apt install binutils build-essential make -y

Compilation:

make

Run Executable:

# Windows/Linux
make run

# Windows
.\\bin\\soare.exe
# Linux
./bin/soare

Loading a File

To load a file, use the command:

soare "filename.soare"

Interpreter Commands

The interpreter works in interactive mode. Type code and press Enter to execute it.

Simple Execution:

>>> write("Hello!");
Hello!
>>>

With statement:

>>> let x = 0;

>>> if (x < 0)
...   write("x is less than 0");
... or (x > 0)
...   write("x is greater than 0")
... else
...   write("x is equal to 0");
... end
x is equal to 0
>>>

Add Interpreter Keywords/Functions in C/C++

[!IMPORTANT] See core/Memory.c and modules/Mocule.c for examples.

Functions

Example: Custom Function - Add Numbers with Variable Arguments:

This example shows how to implement a custom function that adds an unknown number of integer arguments.

Implementation Steps:

  1. Initialize the result accumulator.
  2. Loop through arguments using soare_get_argument.
  3. Convert each argument from string to integer.
  4. Add to the result.
  5. Print the result.
  6. Return NULL (or a string if needed).

Example:

char *ret = malloc(6 * sizeof(char));

if (!ret)
  return NULL;

strcpy(ret, "value");
return ret;

Code:

char *int_add(soare_arguments_list_t args)
{
  // Accumulator for the sum
  int result = 0;
  // Pointer to current argument string
  char *x = NULL;

  // Loop through all arguments
  for (unsigned int i = 0; 1; i++)
  {
    // Retrieve the i-th argument
    x = soare_get_argument(args, i);
    if (!x)
      // Exit loop if no more arguments
      break;

    // Convert argument to integer and add to result
    result += atoi(x);
    // Free the memory used by x
    free(x);
  }

  // Output the result to the console
  printf("%d", result);

  // Return NULL (no value returned to SOARE)
  // If you need to return a value, allocate memory as shown above
  return NULL;
}

Implement this function: soare_add_function(<function name>, <function>)

soare_add_function("int_add", int_add);

Keywords

Example: Custom Keyword - Clear Screen:

This example shows how to implement a custom keyword.

Code:

void clear(void)
{
  // ANSI escape code to clear the screen
  printf("\033c\033[3J");
}

Implement this keyword: soare_add_keyword(<keyword name>, <function>)

soare_add_keyword("clear", clear);

Variables

Example: Custom Variables - Booleans:

This example demonstrates how to implement a custom variable.

Code:

char *bool_true  = "1";
char *bool_false = "0";

Implement these variables: soare_add_keyword(<variable name>, <value>, <mutable>)

soare_add_variable("true",  bool_true,  0);
soare_add_variable("false", bool_false, 0);

Create Your Own Interpreter

[!IMPORTANT] Functions like write, input, or system are predefined functions.

Copy modules/Module.c to create your own interpreter with these functions.

Minimal Code:

#include <stdio.h>
#include <stdlib.h>
#include <SOARE/SOARE.h>

// Module (Predefined functions/keywords/variables)
//#include "modules/module.h"

int main(void)
{
  // Predefined functions in SOARE
  // write, input, system...
  // See `modules/Module.c`
  //load_module();

  // soare_execute(<filename>, <code>)
  char *value = soare_execute("<input>", "return 'Hello World!';");

  // Print returned value and free it
  if (value)
  {
    printf("%s", value);
    free(value);
  }

  // Kill SOARE
  soare_kill();
  return 0;
}

SOARE Language

Now, let’s dive into the language itself. We’ll start with the basics and progress to more advanced concepts.

Introduction

SOARE programs consist of statements that the interpreter executes line by line. Comments start with ? and are ignored by the interpreter. They are used to explain the code.

Examples:

? This is a comment
let number = 1; ? And this is another comment
                ? ... and one more!
let text = "? This is not a comment because it's inside quotes.";

[!NOTE] You can use ; at the end of a statement to indicate it is complete, but it’s not always required.

Text and Numbers

In SOARE, you can manipulate text (called strings) and numbers. Strings are enclosed in single quotes ('...') or double quotes ("...").

To display text, use write:

write("Hello World!\n"); ? \n is a newline character
write(123.456);

To display errors, use werr:

werr("Error: an error!");

Learn more about Escape Sequences (learn.microsoft.com) for more details on \n.

Storing Data

Variables allow you to store values (text or numbers) for later reuse. Use let to create a new variable.

? Create a new variable with let
let name = "Antoine";
let age = 15;

? For an existing variable, no need for let
age = age + 1;

? Concatenate text with ,
let hello_name = "Hello ", name;

? write can take multiple arguments separated by ;
write(hello_name; " "; age; " years old");

Beginner Tip: Think of variables as boxes where you store things. You give the box a name and put a value in it.

Defining Functions

Functions are reusable blocks of code. They take parameters and can return a value.

Example: A function to compute the Fibonacci sequence:

fn fib(n)
  ? Print the Fibonacci series up to n
  let a = 0;
  let b = 1;
  let next = b;

  while (a < n)
    write(a; '\n');
    a = b;
    b = next;
    next = a + b;
  end

  return a;
end

write("The last number is ", fib(100));

The fn keyword defines a function. Followed by the name and parameters in parentheses (separated by ;).

return exits the function and returns a value.

Tip: Functions are like recipes: you call them with ingredients (parameters), they do something, and can give you a result.

Loops and Conditional Structures

While Loops

A while loop repeats code as long as a condition is true.

? Fibonacci series
let a = 0;
let b = 1;
let next = b;

while (a < 100)
  write(a; '\n');
  a = b;
  b = next;
  next = a + b;
end

In SOARE, like in C, any non-zero integer is true; zero is false. Comparison operators are <, >, ==, <=, >=, !=, ~=.

Break

Use break to exit a loop prematurely.

let i = 0;

while (1) ? Infinite loop
  if (i > 10)
    break;
  end

  write(i; '\n');
  i = i + 1;
end

Result :

0
1
2
3
4
5
6
7
8
9
10

If and Iferror Conditions

if tests a condition and executes code if true. or allows alternative conditions, else for the otherwise case.

try
  ? Include standard functions like NaN (Not a Number)
  loadimport "script/math.soare";

  let x = input("Enter a number: ");

  if (NaN(x))
    write("Not a number\n");
  or (x > 0)
    write("Positive\n");
  or (x < 0)
    write("Negative\n");
  else
    write("Zero\n");
  end

? Store the error name in the variable "error"
iferror as error
  werr("Error: "; error);
end

iferror handles errors.

Tip: Think of conditions as decisions: “If it’s raining, take an umbrella; otherwise, go for a walk.”

Arrays

In SOARE, strings and numbers are treated as arrays of characters. Access an element with : followed by the index (starting at 0).

let msg = "Hello";
let num = 713705;

write(msg:0; '\n'); ? Prints H
write(num:3; '\n'); ? Prints 7

The index can be a variable or negative (to count from the end).

loadimport "script/std.soare";

let msg = "Hello World!";

let index = 0;
let size = len(msg); ? Length of the string

while (index < size)
  write(msg:index; '\n');
  index = index + 1;
end

? Negative to start from the end
write(msg:(0-1); '\n'); ? Last character: !
write(msg:(0-2); '\n'); ? Second to last: d

Practical Example: See the test/array.soare file for array tests, like counting vowels.

User Inputs

Use input() to get user input.

let user = input("Enter your name: ");
write("Hello "; user; "!");

Predefined

Predefined functions

Function Description
eval(code) Execute SOARE code and return value
exit(status) Quit SOARE
system(cmd) Execute a shell command
time() Show current timestamp
random(seed) Generate a random number [0; 255] based on a seed
def(name; value; mutable) Create new a variable
chr(integer) Get char from ASCII number
ord(char) Get ASCII number from char
input(…) User input, print text
write(…) Print text
werr(…) Print error

Predefined variables

Variable Description
OS Current Operating System
true Boolean True value (non-zero)
false Boolean False value (zero)
null Empty string
void NULL pointer
version Current SOARE version

Practical Examples

Based on test/array.soare, here are examples to practice with arrays.

Indexing Test:

let msg = "Hello";
let num = 713705;

write("msg:0 -> '"; msg:0; "'\n"); ? Expected: H
write("num:3 -> '"; num:3; "'\n"); ? Expected: 7

Iteration and Vowel Counting:

loadimport "script/std.soare";

let s = "Hello World!";
let i = 0;
let n = len(s);
let vowels = 0;

while (i < n)
  let ch = s:i;
  if (ch == "a" || ch == "e" || ch == "i" || ch == "o" || ch == "u" || ch == "y")
    write("caca");
    vowels = vowels + 1;
  end
  i = i + 1;
end

write("Number of vowels: "; vowels; '\n');

Reversing a String:

loadimport "script/std.soare";

let original = "Hello";
let reversed = "";
let i = len(original) - 1;

while (i >= 0)
  reversed = reversed, original:i;
  i = i - 1;
end

write("Original: "; original; '\n');
write("Reversed: "; reversed; '\n');

These examples will help you understand how to manipulate strings as arrays. Experiment by changing the values!

SOARE Antoine LANDRIEUX https://github.com/AntoineLandrieux/SOARE (MIT LICENSE) ❤️

This site is open source. Improve this page.