🧹 Create a contributing guide

[Ph0enixKM]

Things to do:

• Move current contribution section from README.md to CONTRIBUTING.md
• Explain the project's directories
• Mention that all packages distributed via package manager should be named amber-bash

[Mte90]

We already started #234

[Mte90]

I will work on that, if someone will work on how to add a new built-in (like cd, so a command that takes parameters) and a new block (like for sudo block) in Rust with a guide I think that we have a valuable contributing guide.

[Ph0enixKM]

@Mte90 Sure! Here is a basic built-in guide:

---

Built-in creation guide

In this guide we will see how to create a basic built-in function that in Amber syntax presents like:

builtin "Hello World"

And compiles to:

echo "Hello World"

Let's create a src/modules/builtin/builtin.rs file with the following content:

// This is the prelude that imports all necessary stuff of Heraclitus framework for parsing the syntax
use heraclitus_compiler::prelude::*;
// Expression module that can parse expressions
use crate::modules::expression::expr::Expr;
// Translate module is not included in Heraclitus prelude as it's leaving the backend up to developer
use crate::translate::module::TranslateModule;
// Metadata is the object that is carried when iterating over syntax tree.
// - `ParserMetadata` - it carries the necessary information about the current parsing context such as variables and functions that were declared up to this point, warning messages aggregated up to this point, information whether this syntax is declared in a loop, function, main block, unsafe scope etc.
// `TranslateMetadata` - it carries the necessary information for translation such as wether we are in a silent scope, in an eval context or what indentation should be used.
use crate::utils::{ParserMetadata, TranslateMetadata};

// This is a declaration of your built-in. Set the name accordingly.
#[derive(Debug, Clone)]
pub struct Builtin {
    // This particular built-in contains a single expression
    value: Expr
}

// This is an implementation of a trait that creates a parser for this module
impl SyntaxModule<ParserMetadata> for Echo {
    // Here you can define the name of this built-in that will displayed when debugging the parser
    syntax_name!("Builtin");

    // This function should always contain the default state of this syntax module
    fn new() -> Self {
        Echo {
            value: Expr::new()
        }
    }

    // This is a function that will parse this syntax module "Built-in". It returns SyntaxResult which is a `Result<(), Failure>` where the `Failure` is an Heraclitus primitive that returns an error. It can be either:
    - `Quiet` - which means that this is not the right syntax module to parse
    - `Loud` - which means that this is the correct syntax module but there is some critical error in the code that halts the entire compilation process
    fn parse(&mut self, meta: &mut ParserMetadata) -> SyntaxResult {
        // `token` parses a token `builtin` which is basically a command name for our built-in.
        // If we add `?` in the end of the heraclitus provided function - this function will return a quiet error.
        token(meta, "builtin")?;
        // `syntax` parses the `Expr` expression syntax module
        syntax(meta, &mut self.value)?;
        // This terminates parsing process with success exit code
        Ok(())
    }
}

// Here we implement the translator for the syntax module. Here we return valid Bash or sh code.
impl TranslateModule for Builtin {
    // Here we define the valid translate function. The String returns the current line.
    fn translate(&self, meta: &mut TranslateMetadata) -> String {
        // Here we run the translate function on the syntax module `Expr`
        let value = self.value.translate(meta);
        // Here we return the Bash code
        format!("echo {}", value)
    }
}

Now let's import it in the main module for built-ins src/modules/builtin/mod.rs

pub mod echo;
pub mod nameof;
// ...
pub mod builtin;

Now we have to integrate this syntax module with either statement Stmt or expression Expr. Since this is a statement module, we'll add it to the list of statement syntax modules. Let's modify src/modules/statement/stmt.rs:

// Let's import it first
use crate::modules::builtin::builtin::Builtin;

// Let's add it to the statement type enum
pub enum StatementType {
    // ...
    Builtin(Builtin)
}

// Now, let's add it to the list of statement syntax modules, arranged in the order of parsing precedence:
impl Statement {
    handle_types!(StatementType, [
        // ...
        Builtin,
        // ...
    }
    
    // ...
}

[Mte90]

I added that guide to #275