# 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