Code Structure

As we mentioned already Bee is modular. It means one large project can be split into parts. Each part can contain reusable rules. A module can load several other modules. An application need an entry point that orchestrate the program execution. This is called the "main" module. Below we explain each kind of module:

Main module contains declarations for the main rule. One project can have one or more main modules. Each main module represent one single application. Main module is located in the project root folder.

Notes:

• The main module can not be loaded, in other modules;
• The main module do not have public members;
• One project can have many main modules;
• The main module can receive parameters;

A good designer will split a large problem into secondary modules. These modules are similar to the main module except they do not have the main rule. One secondary module can be used in one or more relate applications. Secondary modules are located in src folder. These modules can be loaded into other modules to be re-used.

Notes:

• Secondary modules are specific to a project;
• Secondary modules should be loaded in other modules;
• Secondary modules usually do not have rule main()
• Secondary modules usually have public members;

A library module is a file located in "lib" folder having extension *.bee. It is called simply: module. A library module can load other library modules and can execute its rules multiple times. You can install new libraries by downloading from the internet a package. Lib folder can have multiple sub-folders, where you create or modify a set of related libraries to be distributed for other people using a package creator tool.

Notes:

• Any library module should have public elements,
• One library module can load multiple other library modules,
• One library module do not contain rule main(),
• One library module can be loaded a single time in another module,
• You can not load a module from a block statement,
• Library modules can be installed in: bee/lib folder for multiple projects

A module can define "rules". These are sub-programs that can be executed on demand. One special rule is the main rule that can be defined only in the main module. This rule can receive multiple parameters and is automatically executed when a program starts.

Example:

# main rule
rule main(*params ∈ S):
   ** read the number of parameters
   new c := params.count;
   panic if (c = 0);

   ** print comma separated parameters
   new i:= 0 ∈ Z;
   while (i < c) do
     write params[i];
     let i += 1;
     write "," if (i < c);
   repeat;
   ** print the buffer to console
   print;
return;

Do not try to understand this example right now. It is just a warming-up code!

Notes:

• This program has a single module, that is main module;
• Input parameter *params is an array of strings;
• Early program termination can be trigger using: over or panic;
• Any rule is ending with mandatory keyword: "return";

Library modules that are reusable for multiple projects can be imported in Bee "lib" sub-folder. This folder is available in Bee as a system constant called: $bee_lib. You can install a set of libraries in a sub-folder of "$bee_lib". Then you can reuse external library by using "load" keyword. The folders can be concatenated using "." string operator.

Pattern:

# loading modules
use $bee_lib.folder_name.(*);     -- load all modules from folder
use $bee_lib.folder_name.(x,y,z); -- load modules x.bee, y.bee and z.bee

Notes:

• using.(*) all modules from a folder are loaded in local scope;
• using.(x,y,z) only some modules are loaded in local scope;
• loaded modules, will merge all public elements in global scope;

Qualifier Bee can use "dot notation" to locate external members. This technique is used to avoid name collision if one library has names that collide with other library.

Pattern:

# load a single module and create a qualifier
use  $bee_lib.folder_name.module_name as qualifier; -- load a single module
...
apply qualifier.member_name; -- using dot notation with qualifier
...

Notes:

1. A module can be loaded using a qualifier multiple times. However I do not see a useful use-case for this feature yet. I think is unusual to have same module loaded twice. It will be a waste of resources to do this.

2. All public members must use the specified qualifier or you can use "with" block to suppress the qualifier for a region of code. Using "with" is useful but sometimes not good enough so we have also invented the "alias".

Examples:

#load examples
use cpp:$runtime.cpp_lib.(*); -- load cpp library
use asm:$runtime.asm_lib.(*); -- load asm library
use bee:$runtime.bee_lib.(*); -- load bee core library
use pro:$program.pro_lib.(*); -- load project library

You can execute the public methods of a secondary module in two modes: synchronous mode and asynchronous mode. This is how you can split a large applications into smaller, more manageable parts that can be executed in parallel.

Example:

In next module called: "test_module.bee", we create a public rule that delay execution for several seconds using "wait" then it returns a result "r" equal to the argument value "t". So the rule basicity does nothing but wait.

# secondary module: test_module.bee
rule .test(t ∈ Z) => (r ∈ N):
  let  r := t; -- prepare the result
  wait t;      -- wait for t seconds
return;

1. Synchronous call using: apply

Let's use the module previously defined in synchronous mode.

# main module
use $pro_src.test_module;

alias test = test_module.test;

+--------------------------------
execute test() and append result
at the end of "collect" list
--------------------------------+
rule main:
   ** define a collector (list)
   new collect ∈ (N);

   apply collect <+ test(30);
   apply collect <+ test(40);
   apply collect <+ test(10);
   apply collect <+ test(20);

   ** the collector is unordered
   print collect; -- (30,40,10,20)
return;

2.Asynchronous call using: begin

Let's use the module previously defined in asynchronous mode. For this we use keywords "begin" to start a process and "wait" for all asynchronous sub-processes to synchronize.

# main module
use $pro_src.test_aspect.(*);

+-----------------------------------------
   execute test() and append result
   at the end of "collect" list
-----------------------------------------+
rule main:
   ** define a collector (list)
   new collect ∈ (N);

   begin collect <+ test(30); -- open one thread
   begin collect <+ test(40); -- open one thread
   begin collect <+ test(10); -- open one thread
   begin collect <+ test(20); -- open one thread

   wait; -- stop and wait for the all open threads to finish

   ** the collector is ordered
   print collect; -- (10,20,30,40)
return;

Note: By using begin and wait you can create multi-session applications. Each aspect is executed on a different core, and the application runs them in parallel. The main thread is waiting using resolve keyword for the threads to finish.