From c776d7659b9da49090ff98a06674a016e29a16d4 Mon Sep 17 00:00:00 2001 From: fennecdjay Date: Fri, 5 Jul 2019 03:16:57 +0200 Subject: [PATCH] :book: Doc clean --- .../00_First_Steps/01_InstallingGwion.md | 39 ++++++ docs/01_Overview/00_First_Steps/Configure.md | 18 +++ docs/01_Overview/BUILDING.md | 38 ++++++ docs/01_Overview/Keywords.md | 31 +++++ docs/{Make.mdr => 01_Overview/Make.md} | 0 docs/01_Overview/SpecialWords.md | 6 + docs/01_Overview/Testing.md | 28 +++++ docs/01_Overview/declaration.md | 50 ++++++++ docs/01_Overview/globalvalues.md | 16 +++ docs/02_Reference/01_Functions/Lambdas.md | 46 ++++++++ docs/02_Reference/01_Functions/Variadic.md | 18 +++ docs/02_Reference/01_Functions/function.md | 23 ++++ docs/02_Reference/ControlFlow/ControlFlow.md | 4 + docs/02_Reference/ControlFlow/Loops.md | 1 + docs/02_Reference/ControlFlow/forloop.md | 111 ++++++++++++++++++ docs/02_Reference/Extending/WIP_Driver.md | 9 ++ docs/02_Reference/Extending/WIP_Plugins.md | 68 +++++++++++ .../03_ContributingTranslation.mdr | 2 +- docs/Extending/WIP_Driver.md | 9 ++ docs/Extending/WIP_Plugins.md | 68 +++++++++++ docs/index.md | 26 ++++ 21 files changed, 610 insertions(+), 1 deletion(-) create mode 100644 docs/01_Overview/00_First_Steps/01_InstallingGwion.md create mode 100644 docs/01_Overview/00_First_Steps/Configure.md create mode 100644 docs/01_Overview/BUILDING.md create mode 100644 docs/01_Overview/Keywords.md rename docs/{Make.mdr => 01_Overview/Make.md} (100%) create mode 100644 docs/01_Overview/SpecialWords.md create mode 100644 docs/01_Overview/Testing.md create mode 100644 docs/01_Overview/declaration.md create mode 100644 docs/01_Overview/globalvalues.md create mode 100644 docs/02_Reference/01_Functions/Lambdas.md create mode 100644 docs/02_Reference/01_Functions/Variadic.md create mode 100644 docs/02_Reference/01_Functions/function.md create mode 100644 docs/02_Reference/ControlFlow/ControlFlow.md create mode 100644 docs/02_Reference/ControlFlow/Loops.md create mode 100644 docs/02_Reference/ControlFlow/forloop.md create mode 100644 docs/02_Reference/Extending/WIP_Driver.md create mode 100644 docs/02_Reference/Extending/WIP_Plugins.md create mode 100644 docs/Extending/WIP_Driver.md create mode 100644 docs/Extending/WIP_Plugins.md create mode 100644 docs/index.md diff --git a/docs/01_Overview/00_First_Steps/01_InstallingGwion.md b/docs/01_Overview/00_First_Steps/01_InstallingGwion.md new file mode 100644 index 00000000..1e7717b2 --- /dev/null +++ b/docs/01_Overview/00_First_Steps/01_InstallingGwion.md @@ -0,0 +1,39 @@ +# Installing gwion + +## Get the sources + +The source is accessible on [github](https://github.com). + +Provided you have git installed, you can get it with: + +``` sh +git clone https://github.com/fennecdjay/gwion +``` + +then change to the source directory +``` sh +cd gwion +``` + +### Don't forget submodules + +You'll need the sources for all base module +``` sh +git submodule update --init util ast +``` + +> At this point, you might want to configure the build. + In this case, have a look at the [configuration page](Configure.md) + + +## Build the libraries and program +``` sh +make +``` + +## Install the package + +``` sh +make install +``` +> You may need root privilege to do this. diff --git a/docs/01_Overview/00_First_Steps/Configure.md b/docs/01_Overview/00_First_Steps/Configure.md new file mode 100644 index 00000000..b05d398b --- /dev/null +++ b/docs/01_Overview/00_First_Steps/Configure.md @@ -0,0 +1,18 @@ +# Configuring Gwion + +## util/config.mk + +double + +gettext + +memcheck + +lto + +coverage + +## ast/config.mk + +## config.mk +Here are a few choices left diff --git a/docs/01_Overview/BUILDING.md b/docs/01_Overview/BUILDING.md new file mode 100644 index 00000000..1babfe52 --- /dev/null +++ b/docs/01_Overview/BUILDING.md @@ -0,0 +1,38 @@ +# Build / Configure Gwion + +## Configure +### gwion-util + + * `USE_MEMCHECK`: compile with debug flags (`-g`) and enable asserts + * `USE_COVERAGE`: add coverage instrumentation + + +## Make +Basically, all that is left to do is +```sh +make +``` +The only environment variable affecting the operation is `PREFIX` + +Except `--(no-)double`, everything can be set when running make, +using environment variables. + +Drivers can be set on using, e.g. for *alsa* : `ALSA_D=1` or `ALSA_D=on`. +In the same way, then can be disabled with `ALSA_D=0` or `ALSA_D=off` + +### Running tests +```bash +make tests +``` +to run all tests, or +```bash +bash util/test.sh my_file_or_directory (.. other files/dirs ...) +``` +to run specific ones. +look [here](#testing.md) for more. +## Install +*maybe as root* +```sh +make install +``` +The only environment variable affecting the operation is `PREFIX` diff --git a/docs/01_Overview/Keywords.md b/docs/01_Overview/Keywords.md new file mode 100644 index 00000000..0f8af7ce --- /dev/null +++ b/docs/01_Overview/Keywords.md @@ -0,0 +1,31 @@ +# Keywords + + * fun/function + * operator + * return + * goto + * switch/case/default + * if/else + * break/continue + * until/do/while/for/repeat + + + + + * global/static + * private/protect + * const + + * new + * spork + * fork + * typeof + + * typedef + * class + * dtor + * extends + * enum + * union + + * auto diff --git a/docs/Make.mdr b/docs/01_Overview/Make.md similarity index 100% rename from docs/Make.mdr rename to docs/01_Overview/Make.md diff --git a/docs/01_Overview/SpecialWords.md b/docs/01_Overview/SpecialWords.md new file mode 100644 index 00000000..3b4286a9 --- /dev/null +++ b/docs/01_Overview/SpecialWords.md @@ -0,0 +1,6 @@ +# Special Values + + * me + * this + * vararg + * maybe diff --git a/docs/01_Overview/Testing.md b/docs/01_Overview/Testing.md new file mode 100644 index 00000000..3c3a79dd --- /dev/null +++ b/docs/01_Overview/Testing.md @@ -0,0 +1,28 @@ +# Tests +[test.sh](https://github.com/fennecdjay/Gwion/blob/dev/util/test.sh) +requires [valgrind](http://valgrind.org/) +there are two kinds of tests: + * [gwion](#gwion-tests) + * [bash](#bash-tests) + +## Gwion tests +those tests are just gwion (.gw) files, handling special comments: + * `// [skip]` (*optionally* followed by reason to skip) + * `// [todo]` (*optionally* followed by reason to delay testing) + * `// [contains]` followed by string to match + * `// [excludes]` followed by string not to match + +## Shell test +those tests are just bash (.sh) files. +they should start with this snippet +```bash +#!/bin/bash +# [test] #5 +n=0 +[ "$1" ] && n="$1" +[ "$n" -eq 0 ] && n=1 +source tests/sh/common.sh +``` + +## TODO + [ ] `bailout` system for early exit on failure diff --git a/docs/01_Overview/declaration.md b/docs/01_Overview/declaration.md new file mode 100644 index 00000000..fcf06718 --- /dev/null +++ b/docs/01_Overview/declaration.md @@ -0,0 +1,50 @@ +# Declarations + +## Basics + +Declaring a primitive or an object is quite straight forward: +``` gw +int i; +Object o; +<<>>; +``` +0 0x56418af88660 + +## Declaring a reference +However ... +``` gw +Object @ref; +<<<"Reference points to no object yet: ", ref>>>; +//Object o @=> ref; +new Object @=> ref; +<<<"But now it does: ", ref>>>; +``` +make[1] : on entre dans le répertoire « /home/djay/src/git/gwion/gwion-github » +

+(int[]) (nil)
+(int[]) 0x4dedc10
+t: (nil)
+But now it does: 0x4dedc30
+✔ +

+make[1] : on quitte le répertoire « /home/djay/src/git/gwion/gwion-github » + +## Arrays + +### array as refs + +``` gw +int ref[]; +<<>>; +new int[2] @=> ref; +<<>>; +``` +make[1] : on entre dans le répertoire « /home/djay/src/git/gwion/gwion-github » +

+(int[]) (nil)
+(int[]) 0x4dedc10
+t: (nil)
+But now it does: 0x4dedc30
+✔ +

+make[1] : on quitte le répertoire « /home/djay/src/git/gwion/gwion-github » diff --git a/docs/01_Overview/globalvalues.md b/docs/01_Overview/globalvalues.md new file mode 100644 index 00000000..81566954 --- /dev/null +++ b/docs/01_Overview/globalvalues.md @@ -0,0 +1,16 @@ +# Global Values + + * adc + * blackhole + * dac + * pi + * null + * samp + * ms + * second + * hour + * me + * this + * \__func__ + * \__file__ + * \__line__ diff --git a/docs/02_Reference/01_Functions/Lambdas.md b/docs/02_Reference/01_Functions/Lambdas.md new file mode 100644 index 00000000..bf261a83 --- /dev/null +++ b/docs/02_Reference/01_Functions/Lambdas.md @@ -0,0 +1,46 @@ +# Lambda + +## Overview + +Simply put, *lambda*s are anonymous functions. + +The syntax to create them is simple: +``` +\ variable0 variable1 ... { your code here } +``` +You can even use it to +### Call a function just once +``` gw +\ i { <<<"passed '", i, "'">>>; }(3); +``` +

+passed '3'
+✔ +

+ + +## Use case + +### Passing to a function pointer +``` gw +typedef void fptr_t(int); +\ i { <<<"passed '", i, "'">>>; } @=> fptr_t fptr; +fptr(4); +``` +

+passed '4'
+✔ +

+ +### As Argument to Functions +``` gw +typedef void fptr_t(int); +fun void test(fptr_t fptr) { + fptr(5); +} +test(\ i { <<<"passed '", i, "'">>>; }); +``` +

+passed '5'
+✔ +

diff --git a/docs/02_Reference/01_Functions/Variadic.md b/docs/02_Reference/01_Functions/Variadic.md new file mode 100644 index 00000000..092b3dd0 --- /dev/null +++ b/docs/02_Reference/01_Functions/Variadic.md @@ -0,0 +1,18 @@ +# Variadic functions + +> A function whoses arity is not fixed. + +Well, a function that takes a fixed number of arguments, and additionnal ones. + +## a simple example +``` gw +fun void variadic_test(int i, ...) { + <<< "first argument is ", i >>>; + vararg.start; + <<< "\tadditionnal argument", vararg.i >>>; + vararg.end; +} +variadic_test(1); +variadic_test(1, 2); +variadic_test(1, 2, 3); +``` diff --git a/docs/02_Reference/01_Functions/function.md b/docs/02_Reference/01_Functions/function.md new file mode 100644 index 00000000..d5034ef9 --- /dev/null +++ b/docs/02_Reference/01_Functions/function.md @@ -0,0 +1,23 @@ +# Functions + +## a simple (commented example) + +``` gw +// declare function 'test_function' +// with return type int +// taking an int as argument +fun int test_function(int arg) { + // return the argument + 2 + return arg + 2; +} + +// now call the function (and debug print the result) +<<>>; +// or use alternate syntax +<<<1 => test_function>>>; +``` +

+(int) 2
+(int) 3
+✔ +

diff --git a/docs/02_Reference/ControlFlow/ControlFlow.md b/docs/02_Reference/ControlFlow/ControlFlow.md new file mode 100644 index 00000000..2e9c1854 --- /dev/null +++ b/docs/02_Reference/ControlFlow/ControlFlow.md @@ -0,0 +1,4 @@ +# Control Flow + +## Repeats +let start simple ;-) diff --git a/docs/02_Reference/ControlFlow/Loops.md b/docs/02_Reference/ControlFlow/Loops.md new file mode 100644 index 00000000..4b787b4b --- /dev/null +++ b/docs/02_Reference/ControlFlow/Loops.md @@ -0,0 +1 @@ +# Loops diff --git a/docs/02_Reference/ControlFlow/forloop.md b/docs/02_Reference/ControlFlow/forloop.md new file mode 100644 index 00000000..8510a1e5 --- /dev/null +++ b/docs/02_Reference/ControlFlow/forloop.md @@ -0,0 +1,111 @@ +# For Loops +**For** loops in Gwion is pretty similar to classic **C** syntax + +## basic loops +``` gw +for(int i; i < 3; ++i) + <<>>; +``` +

+(int) 0
+(int) 1
+(int) 2
+✔ +

+ +Of course, it also works with a block of code. + +``` gw +for(int i; i < 3; ++i) { + i/2 => float f1; + i/2. => float f2; + <<>>; +} +``` +

+0 0.0000 0.0000
+1 0.0000 0.5000
+2 1.0000 1.0000
+✔ +

+ +## Nested Loops +``` gw +int array[3][4]; + +for(int i; i < 3; ++i) { + for(int j; j < 4; ++j) { + <<>>; + } +} +``` +

+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+(int) 0
+✔ +

+ +### Auto Loops + +#### Simple auto loop +``` gw +int array[2][3]; +for(auto a: array) { + <<>>; + for(auto b: a) + <<>>; +} +``` +

+(int[]) 0x4e0ff00
+(int) 0
+(int) 0
+(int) 0
+(int[]) 0x4e0ff20
+(int) 0
+(int) 0
+(int) 0
+✔ +

+ +### Auto Pointer loop +With the simple auto loop, you only get the value in the array. +If you want to change it, you need a pointer + +``` gw +int array[2][3]; +int i; +for(auto a: array) { + for(auto @b: a) + <<<++i => *b>>>; +} +for(auto a: array) { + for(auto @b: a) + <<<*b>>>; +} +``` +

+(int) 1
+(int) 2
+(int) 3
+(int) 4
+(int) 5
+(int) 6
+(int) 1
+(int) 2
+(int) 3
+(int) 4
+(int) 5
+(int) 6
+✔ +

diff --git a/docs/02_Reference/Extending/WIP_Driver.md b/docs/02_Reference/Extending/WIP_Driver.md new file mode 100644 index 00000000..20478632 --- /dev/null +++ b/docs/02_Reference/Extending/WIP_Driver.md @@ -0,0 +1,9 @@ +# Giving gwion a new driver + +## basics + +> in order to use GWION_CTL ... + +# concept + +# upd driver diff --git a/docs/02_Reference/Extending/WIP_Plugins.md b/docs/02_Reference/Extending/WIP_Plugins.md new file mode 100644 index 00000000..cd1822fd --- /dev/null +++ b/docs/02_Reference/Extending/WIP_Plugins.md @@ -0,0 +1,68 @@ +# Writing a Gwion plugin + +> THIS IS OUTDATED. please look at the source code in src/lib/ instead + + * [getting started] + +## Getting started +use the script + +### headers +``` +#include "vm.h" +#include "instr.h" +#include "import.h +``` + + +### Class +Define the type: +``` +struct Type_ t_mytype = { "MyType", SZ_INT, &t_object}; +``` +> every type extending t_object should have SZ_INT + +### Handling Constructors and Destructors +#### CTOR +``` +CTOR(mytype_ctor) { + /* constructor code here */ +} +``` +#### DTOR +``` +DTOR(mytype_dtor) { + /* destructor code here */ +} +``` + +those macros provide two variables: + * `o`: the *M_Object* for the (con/des)tructor + * `shred`: the *VM_Shred* for the (con/des)tructor + +``` +CHECK_BB(import_class_begin(env, &t_mytpe, env->global_nspc, mytype_ctor, mytype_dtor)) +``` +#### variable +declare a `m_int`. coding convention require + * a leading *_o* + * a following *_type_* +```c +m_int o_mytype_myvaroffset; +``` +#### function +```c +/* declare a member function */ +MFUN(mytype_memberfunction) { + /* code here */ +} + +SFUN(mtype_staticfunction) { + /* code here */ +} +``` + +#### operator + +### Import function + diff --git a/docs/08_Contributing/03_ContributingTranslation.mdr b/docs/08_Contributing/03_ContributingTranslation.mdr index fbafbfbd..7a9c35b8 100644 --- a/docs/08_Contributing/03_ContributingTranslation.mdr +++ b/docs/08_Contributing/03_ContributingTranslation.mdr @@ -41,7 +41,7 @@ You can now get back to [step 2](#2-Edit). ## Add to VCS -It's now time to add your changes to the package :smile: +It's now time to add your changes to the package ``` sh make translation-commit TRANSLATION_TARGET= diff --git a/docs/Extending/WIP_Driver.md b/docs/Extending/WIP_Driver.md new file mode 100644 index 00000000..20478632 --- /dev/null +++ b/docs/Extending/WIP_Driver.md @@ -0,0 +1,9 @@ +# Giving gwion a new driver + +## basics + +> in order to use GWION_CTL ... + +# concept + +# upd driver diff --git a/docs/Extending/WIP_Plugins.md b/docs/Extending/WIP_Plugins.md new file mode 100644 index 00000000..cd1822fd --- /dev/null +++ b/docs/Extending/WIP_Plugins.md @@ -0,0 +1,68 @@ +# Writing a Gwion plugin + +> THIS IS OUTDATED. please look at the source code in src/lib/ instead + + * [getting started] + +## Getting started +use the script + +### headers +``` +#include "vm.h" +#include "instr.h" +#include "import.h +``` + + +### Class +Define the type: +``` +struct Type_ t_mytype = { "MyType", SZ_INT, &t_object}; +``` +> every type extending t_object should have SZ_INT + +### Handling Constructors and Destructors +#### CTOR +``` +CTOR(mytype_ctor) { + /* constructor code here */ +} +``` +#### DTOR +``` +DTOR(mytype_dtor) { + /* destructor code here */ +} +``` + +those macros provide two variables: + * `o`: the *M_Object* for the (con/des)tructor + * `shred`: the *VM_Shred* for the (con/des)tructor + +``` +CHECK_BB(import_class_begin(env, &t_mytpe, env->global_nspc, mytype_ctor, mytype_dtor)) +``` +#### variable +declare a `m_int`. coding convention require + * a leading *_o* + * a following *_type_* +```c +m_int o_mytype_myvaroffset; +``` +#### function +```c +/* declare a member function */ +MFUN(mytype_memberfunction) { + /* code here */ +} + +SFUN(mtype_staticfunction) { + /* code here */ +} +``` + +#### operator + +### Import function + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..dcc9457d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,26 @@ +# Welcome to Gwion + +gwion is a easy yet powerful, strongly-timed programming language, + +## And now for the hello world + +So, as it is mandatory, here is the piece of code you're waiting +for: + +``` gw +<<<"Hello, World!", "">>>; +``` +

+Hello, World!
+✔ +

+ +## (Bag of) Features + * horizontal inheritance + * typedef (function pointers and type aliases) + * enums and unions + * templates (both class and functions) + * easy concurrency/async + * [lambdas](Functions/Lambdas) + * memoization + * [variadic](Functions/Variadic) functions -- 2.43.0