From 74ccc905616e648b443f68fe1e96c5a64449290c Mon Sep 17 00:00:00 2001 From: mdegirolami Date: Tue, 2 Nov 2021 13:26:19 +0100 Subject: [PATCH] [sing/en] Added sing language (#4256) * Added sing language * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Update sing.html.markdown Co-authored-by: Andre Polykanine * Fixed a comment Co-authored-by: De Girolami Co-authored-by: Andre Polykanine --- sing.html.markdown | 446 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 446 insertions(+) create mode 100644 sing.html.markdown diff --git a/sing.html.markdown b/sing.html.markdown new file mode 100644 index 00000000..2e439800 --- /dev/null +++ b/sing.html.markdown @@ -0,0 +1,446 @@ +--- +name: Sing +category: language +language: Sing +filename: learnsing.sing +contributors: + - ["Maurizio De Girolami", "https://github.com/mdegirolami"] +--- + +The purpose of sing is to provide a simple, safe, fast language that +can be a good replacement for c++ for high performance applications. + +Sing is an easy choice because it compiles to human-quality readable c++. + +Because of that, if you work for a while with Sing and, at any time, you discover you don't like Sing anymore, you lose nothing of your work +because you are left with nice and clean c++ code. + +In some way you can also think Sing as a tool to write c++ in a way that enforces some best practices. + +```go +/* Multi- line comment. + /* It can be nested */ + Use it to remark-out part of the code. + It leaves no trace in the intermediate c++ code. + (sing translates into nice human readable c++) +*/ + +// Single line comment, can be placed only before a statement or declaration... +// ...or at the right of the first line of a statement or declaration. +// single line comments are kept into c++. +// +// here we declare if we need to use public declarations from other files. +// (in this case from files 'sio', 'sys') +requires "sio"; +requires "sys"; + +// +// A sing function declaration. +// All the declarations can be made public with the 'public' keyword. +// All the declarations start with a keyword specifying the type of declaration +// (in this case fn for function) then follows the name, the arguments and the +// return type. +// +// Each argument starts with a direction qualifyer (in, out, io) which tells if +// the argument is an input, an output or both... +// ...then follows the argument name and the type. +public fn singmain(in argv [*]string) i32 +{ + // print is from the sio file and sends a string to the console + sio.print("Hello World\n"); + + // type conversions are allowed in the form of (expression). + sio.print(string(sum(5, 10)) + "\n"); + + // For clarity you can specify after an argument its name separated by ':'. + var result i32; + recursive_power(10:base, 3:exponent, result); + + // referred here to avoid a 'not used' error. + learnTypes(); + + // functions can only return a single value of some basic type. + return(0); +} + +// You can have as many arguments as you want, comma separated. +// You can also omit the 'in' direction qualifyer (it is the default). +fn sum(arg1 i32, arg2 i32) i32 +{ + // as 'fn' declares a function, 'let' declares a constant. + // With constants, if you place an initializer, you can omit the type. + let the_sum = arg1 + arg2; + + return(the_sum); +} + +// Arguments are passed by reference, which means that in the function body you +// use the argument names to refer to the passed variables. +// Example: all the functions in the recursion stack access the same 'result' +// variable, supplied by the singmain function. +fn recursive_power(base i32, exponent i32, out result i32) void +{ + if (exponent == 0) { + result = 1; + } else { + recursive_power(base, exponent - 1, result); + result *= base; + } +} + +//********************************************************** +// +// TYPES +// +//********************************************************** +fn learnTypes() void +{ + // the var keyword declares mutable variables + // in this case an UTF-8 encoded string + var my_name string; + + // ints of 8..64 bits size + var int0 i8; + var int1 i16; + var int2 i32; + var int3 i64; + + // uints + var uint0 u8; + var uint1 u16; + var uint2 u32; + var uint3 u64; + + // floats + var float0 f32; + var float1 f64; + + // complex + var cmplx0 c64; + var cmplx1 c128; + + cmplx0 = 0; + cmplx1 = 0; + + // and of course... + var bool0 bool; + + // type inference: by default constants are i32, f32, c64 + let an_int32 = 15; + let a_float32 = 15.0; + let a_complex = 15.0 + 3i; + let a_string = "Hello !"; + let a_bool = false; + + // To create constant of different types use a conversion-like syntax: + // NOTE: this is NOT a conversion. Just a type specification + let a_float64 = f64(5.6); + + // in a type definition [] reads as "array of" + // in the example []i32 => array of i32. + var intarray []i32 = {1, 2, 3}; + + // You can specify a length, else the length is given by the initializer + // the last initializer is replicated on the extra items + var sizedarray [10]i32 = {1, 2, 3}; + + // Specify * as the size to get a dynamic array (can change its length) + var dyna_array [*]i32; + + // you can append items to a vector invoking a method-like function on it. + dyna_array.push_back(an_int32); + + // getting the size of the array. sys.validate() is like assert in c + sys.validate(dyna_array.size() == 1); + + // a map that associates a number to a string. + // "map(x)..." reads "map with key of type x and vaue of type..." + var a_map map(string)i32; + + a_map.insert("one", 1); + a_map.insert("two", 2); + a_map.insert("three", 3); + let key = "two"; + + // note: the second argument of get_safe is the value to be returned + // when the key is not found. + sio.print("\nAnd the value is...: " + string(a_map.get_safe(key, -1))); + + // string concatenation + my_name = "a" + "b"; +} + +// an enum type can only have a value from a discrete set. +// can't be converted to/from int ! +enum Stages {first, second, last} + +// you can refer to enum values (to assign/compare them) +// specifying both the typename and tagname separated with the '.' operator +var current_stage = Stages.first; + + +//********************************************************** +// +// POINTERS +// +//********************************************************** + +// This is a factory for a dynamic vector. +// In a type declaration '*' reads 'pointer to..' +// so the return type is 'pointer to a vector of i32' +fn vectorFactory(first i32, last i32) *[*]i32 +{ + var buffer [*]i32; + + // fill + for (value in first : last) { + buffer.push_back(value); + } + + // The & operator returns the address of the buffer. + // You can only use & on local variables + // As you use & on a variable, that variable is allocated on the HEAP. + return(&buffer); +} + +fn usePointers() void +{ + var bufferptr = vectorFactory(0, 100); + + // you don't need to use the factory pattern to use pointers. + var another_buffer [*]i32; + var another_bufferptr = &another_buffer; + + // you can dereference a pointer with the * operator + // sys.validate is an assertion (causes a signal if the argument is false) + sys.validate((*bufferptr)[0] == 0); + + /* + // as all the pointers to a variable exit their scope the variable is + // no more accessible and is deleted (freed) + */ +} + +//********************************************************** +// +// CLASSES +// +//********************************************************** + +// This is a Class. The member variables can be directly initialized here +class AClass { +public: + var public_var = 100; // same as any other variable declaration + fn is_ready() bool; // same as any other function declaration + fn mut finalize() void; // destructor (called on object deletion) +private: + var private_var string; + + // Changes the member variables and must be marked as 'mut' (mutable) + fn mut private_fun(errmsg string) void; +} + +// How to declare a member function +fn AClass.is_ready() bool +{ + // inside a member function, members can be accessed thrugh the + // this keyword and the field selector '.' + return(this.public_var > 10); +} + +fn AClass.private_fun(errmsg string) void +{ + this.private_var = errmsg; +} + +// using a class +fn useAClass() void +{ + // in this way you create a variable of type AClass. + var instance AClass; + + // then you can access its members through the '.' operator. + if (instance.is_ready()) { + instance.public_var = 0; + } +} + +//********************************************************** +// +// INTERFACES +// +//********************************************************** + +// You can use polymorphism in sing defining an interface... +interface ExampleInterface { + fn mut eraseAll() void; + fn identify_myself() void; +} + +// and then creating classes which implement the interface +// NOTE: you don't need (and cannot) re-declare the interface functions +class Implementer1 : ExampleInterface { +private: + var to_be_erased i32 = 3; +public: + var only_on_impl1 = 0; +} + +class Implementer2 : ExampleInterface { +private: + var to_be_erased f32 = 3; +} + +fn Implementer1.eraseAll() void +{ + this.to_be_erased = 0; +} + +fn Implementer1.identify_myself() void +{ + sio.print("\nI'm the terrible int eraser !!\n"); +} + +fn Implementer2.eraseAll() void +{ + this.to_be_erased = 0; +} + +fn Implementer2.identify_myself() void +{ + sio.print("\nI'm the terrible float eraser !!\n"); +} + +fn interface_casting() i32 +{ + // upcasting is automatic (es: *Implementer1 to *ExampleInterface) + var concrete Implementer1; + var if_ptr *ExampleInterface = &concrete; + + // you can access interface members with (guess what ?) '.' + if_ptr.identify_myself(); + + // downcasting requires a special construct + // (see also below the conditional structures) + typeswitch(ref = if_ptr) { + case *Implementer1: return(ref.only_on_impl1); + case *Implementer2: {} + default: return(0); + } + + return(1); +} + +// All the loop types +fn loops() void +{ + // while: the condition must be strictly of boolean type + var idx = 0; + while (idx < 10) { + ++idx; + } + + // for in an integer range. The last value is excluded + // 'it' is local to the loop and must not be previously declared + for (it in 0 : 10) { + } + + // reverse direction + for (it in 10 : 0) { + } + + // configurable step. The loop stops when it's >= the final value + for (it in 0 : 100 step 3) { + } + + // with an auxiliary counter. + // The counter start always at 0 and increments by one at each iteration + for (counter, it in 3450 : 100 step -22) { + } + + // value assumes in turn all the values from array + var array [*]i32 = {0, 10, 100, 1000}; + for (value in array) { + } + + // as before with auxiliary counter + for (counter, value in array) { + } +} + +// All the conditional structures +interface intface {} +class c0_test : intface {public: fn c0stuff() void;} +class delegating : intface {} + +fn conditionals(in object intface, in objptr *intface) void +{ + let condition1 = true; + let condition2 = true; + let condition3 = true; + var value = 30; + + // condition1 must be a boolean. + if (condition1) { + ++value; // conditioned statement + } + + // you can chain conditions with else if + if (condition1) { + ++value; + } else if (condition2) { + --value; + } + + // a final else runs if any other condition is false + if (condition1) { + ++value; + } else if (condition2) { + --value; + } else { + value = 0; + } + + // based on the switch value selects a case statement + switch (value) { + case 0: sio.print("value is zero"); // a single statement ! + case 1: {} // do nothing + case 2: // falls through + case 3: sio.print("value is more than one"); + case 4: { // a block is a single statement ! + value = 0; + sio.print("how big !!"); + } + default: return; // if no one else matches + } + + // similar to a switch but selects a case based on argument type. + // - object must be a function argument of type interface. + // - the case types must be classes implementing the object interface. + // - in each case statement, ref assumes the class type of that case. + typeswitch(ref = object) { + case c0_test: ref.c0stuff(); + case delegating: {} + default: return; + } + + // - object must be an interface pointer. + // - the case types must be pointers to classes implementing the objptr interface. + // - in each case statement, ref assumes the class pointer type of that case. + typeswitch(ref = objptr) { + case *c0_test: { + ref.c0stuff(); + return; + } + case *delegating: {} + default: sio.print("unknown pointer type !!"); + } +} +``` + +## Further Reading + +[official Sing web site](https://mdegirolami.wixsite.com/singlang). + +If you want to play with sing you are recommended to download the vscode plugin. Please +follow the instructions at [Getting Started](https://mdegirolami.wixsite.com/singlang/copy-of-interfacing-sing-and-c-2)