OpenSCAD User Manual/WIP/Module Literals

module literals / module references

A module_reference is a type of variable that refers to a module

Module literal and module reference syntax

The module_reference is initialised using a module_literal. In the following snippet my_cube is the module_reference and module cube([2,3,4]) is the module_literal. A module literal is an expression which is syntactically identified by being prefixed with the module keyword.

Syntax in detail

There are several ways to define a module reference, depending on what you want to do.

Simple syntax

In this syntax you define the module exactly as you want to see it output.

// Create a reference to a cube module
my_cube = module cube([2,3,4]);

The above code creates the variable my_cube but doesn't instantiate it, so there will be no output in the graphics window. To instantiate the module you use the existing syntax that you use with modules.

// Instantiate the module through the module reference
my_cube();

Instantiated module reference

Alias syntax

In this variation, the name of the module reference is just another name for the module.

my_cylinder = module cylinder;

To instantiate the module, the alias takes exactly the same arguments as the module it aliases

my_cylinder(h=20, r=10, center=true);

Instantiated module reference

Arguments forwarding syntax

In another form you provide arguments to the module_literal. The arguments are forwarded to the original module.

my_cylinder = module(height) cylinder(h = height, r=10, center=true);

In this case you call the reference with the modified arguments

my_cylinder(20);

Instantiated module reference

Anonymous module syntax without arguments

In the final forms you can create an anonymous module_literal and initialise the reference to it.
( Note that in this form there must be a semicolon after the closing curly brace )

my_shapes = module {
  cube(2,center = true); 
  translate([5,0,0]) 
    sphere(1,center = true);
};

The module can be instantiated in the usual way.

my_shapes();

Instantiated module reference

Anonymous module syntax with arguments

The anonymous module form can of course also take arguments

my_rotated_square  = module ( r, s) { rotate(r) square(s);};

The module reference is instantiated in the usual way.

my_rotated_square(45,10);

Instantiated module reference

Instantiating a module via an expression

Module literals can be stored in arrays and returned from functions In these cases it can be inconvenient to assign them to a symbol before invoking them. You can instantiate an expression resolving to a module_literal by encasing the expression before the instantiation arguments, in parentheses.

 //-------------
 // n is an integer index between 0 and 3
 // choose_shape returns the shape given by the index
function choose_shape(n) = 
    let (ar = [
         module cube([5,20,30]),
         module sphere(r = 6 , $fn = 20),
         module cylinder(d = 15, h = 20, $fn = 30)
     ])
     ar[n];
  //--------------
  // instantiate the chosen module
  (choose_shape(2))();  // choose the cylinder

Further examples

For more advanced uses of module_literals and module references see https://github.com/kwikius/openscad/tree/module_literal_v3/examples/ModuleLiterals