Flogram Syntax

Variables


By default all variables in Flogram are immutable, meaning once initially set you can't change them, and are declared using "let <variable_name>:<type> = <default>".</default></type></variable_name> For example: let PI: fp32 = 3.14159265 If you wish to declare a variable as mutable you may use "mut" in place of let. For example: mut count: =1 Which can later be changed to other values: count = 2 count = 3 Coming soon, Flogram can automatically infer the type of a variable by excluding the type:
let PI = 3.14159265 mut count = 1 Valid variable types Integer: Whole numbers that don't have a decimal value attached int8 1 byte integer valid range: -128 to 127 int16 2 byte integer valid range: -32,768 to 32,767 int32 4 byte integer valid range: -2,147,483,648 to 2,147,483,647 int64 8 byte integer valid range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 Unsigned Integer: Whole numbers that don't have a decimal value attached but can only be positive numbers doubling their positive range uint8 1 byte unsigned integer valid range: 0 to 255 uint16 2 byte unsigned integer valid range: 0 to 65,535 uint32 4 byte unsigned integer valid range: 0 to 4,294,967,295 uint64 8 byte unsigned integer valid range 0 to 18,446,744,073,709,551,615 Floating Point: Floating point numbers can include decimal values fp32 4 byte floating point fp64 8 byte floating point Strings: A sequence of characters wrapped in double quotes str $[] ${}




Comments


Comments are used to create notes within code that commute to future variables or yourself a week from now when you've forgotten exactly why you implemented something the way you did. Comments are very important but can be overused too. Good coding practice is to use descriptive variable and function names when possible. And to use comments when code does can't explain why something is occuring in a certain way or why you implemented something in a certain way. # Single line comments will comment out the rest of the line ## Multi-line comments will comment out the code until the next multiline comment symbol is reached ##




Objects


Objects in Flogram are composed of Variables and Functions




Functions


Flogram functions are where you will store code to be executed. You may call other functions from a given function. fn name( var_in : bool, var_in2: int) -> (var_out: bool, var_out2: int) { var_out = var_in; var_out2=var_in2; exit; } Both variable arguments in and out are optional. Temporarily only one output variable is allowed. Function calls that belong to current object are called by: function_call() Function calls to other objects are called with: object_name.function_call() By default arguments passed by value meaning that the function owns a seperate copy of the variable. Arguments may be passed by reference and the original value will be changed by that function if prepended by mut: fn function_call(does_not_change: str, mut changes int) { } Under the covers we might pass by reference or value for performance, so don't worry about that. Just worry about how much access to these variables you need and give as little as possible. This increases both performance and security. In other words, we recommend preferring Pass by value (aka copy) over Pass by mutable reference (mut) when possible.





Advanced Syntax

Atomic Objects


Both Global Objects and Flo(aka threaded) Functions rely on Atomic Objects to provide some protection against race conditions. Atomic Objects are objects that like regular objects may store variables and be accessed by functions. However, Atomic objects lock the object before and unlock the object after every function is called. This ensures that function calls made from a given object to atomic objects are executed in the order they were called and fully execute. Atomic Objects are protected from threading race conditions and therefore easier to share but are not guarenteed to be immune. For example, if you start an loop running in one function that relies on a different function being called to break out of the loop, then the Object will deadlock (or more specifically live lock). Atomic Objects are reference counted and when no more references to atomic objects exist, they are deleted. In order to declare an object as atomic, simply add the keyword 'atomic' in front of the object definition: atomic object sample_atomic_object{ }




When Do I Need Flogram's Advanced Features?


For the majority of programs, you will never need any advanced features. Your programs should run faster than naive C and be capable of whatever you might want to do. However, there are a few cases in which you may want to be aware of these features:

  • Force code to run in multiple threads
  • Access global variables
  • Squeezeing the last ounce of performance from your code




Flo Functions


Flo functions are special functions that force Flogram to execute them in a seperate thread. Flo functions are not allowed to accept mutable variables or return variables but may communicate with the outside world through the use of Atomic Objects. Atomic Object may be used to simulate an equivalent gochannels but are much more flexible and useful. You may use dynamically sized arrays within atomic objects and send seperate messages to tell it to prepare to stop execution of this flo function. Similar to how you exit the program you may call 'exit flo' to stop execution of a flo function.




Global Objects


Sometimes it is really convienent or faster to store shared state in a way that it is globally accessible without requiring that state to be passed all the way down as a mutable reference from function to function to function in two seperate parts of the program that need to communicate. Global Objects are faster when two threads can be split and execute as two seperate threads while normally they wouldn't be able to due to a shared dependency on specific variables. Only Atomic objects can be made global.





  • Force code to run in multiple threads

  • Access global variables

  • Squeeze the last ounce of performance from your code