Using Carbide
Once you have a Carbon application or library set up you can begin using the features that Carbide adds to Lua.
Carbide Lua is a direct superset of Lua, implementing features in 'levels' that add various functionality at the compiler level. Files that end in a .clua
extension are Carbide Lua files.
Feature Levels and Extensions
The following feature levels are exposed by Carbide Lua:
- Level 1:
- Bang methods for in-place operations
object:Bang!()
translates toobject:BangInPlace()
- Increment operator
number++
translates tonumber = number + 1
- Mutating operators
number += 2
translates tonumber = number + 2
- Supported operators:
+=
,-=
,*=
,/=
,^=
- Direct Arrow Notation (DAN) for array lookups
print(vec2->x, vec2->y)
translates toprint(vec2[1], vec2[2])
- Similar to GLSL's vector member lookups
- Supports the following sets of lookups:
(x, y, z, w)
(r, g, b, a)
(s, t, p, q)
(u, v)
- Lookups can be mixed
print(vec2->x, vec2->r, vec2->y)
translates toprint(vec2[1], vec2[1], vec2[2])
- Lookups can be chained
print(vec3->xyz)
is the same asprint(vec3->x, vec3->y, vec3->z)
- Lookups can swizzle
print(color3->gbr
is a fast way to switch around a color
- Fat-arrow lambdas (added in 1.1)
(x) => x^2
translates tofunction(x) return x^2 end
- Parentheses are required for both definitions and calls
- Bang methods for in-place operations
Directives
Carbide also exposes a set of directives to control the flow of compilation.
Directives can appear in any place in the file, they affect compilation globally.
#CARBIDE_FEATURE_LEVEL <level>
- Denotes that this file uses the given Carbide feature level
- Default:
#CARBIDE_FEATURE_LEVEL 2
#CARBIDE_EXTENSIONS <extension>, <extension>, ...
- Enables Carbide extensions with given names.
#TEMPLATES_ENABLED
- Enables the templating engine for inline metaprogramming.
- Templates can output Carbide Lua and it will be parsed correctly.
#TEMPLATE_LEVEL <level>
- Lets the templating engine know what level of templates to use.
- Default:
#TEMPLATE_LEVEL 0
#COMPILE_TO <target>
- Ouputs the source to a given target.
stdout
writes out usingprint
.- Other values write out to files.
- Ouputs the source to a given target.
Using Carbide Features
Carbide's additions can be very helpful, especially when working with vectors:
local Carbon = (...)
local Vector2 = Carbon.Math.Vector2
local Vector3 = Carbon.Math.Vector3
local vec2 = Vector2(0, 0)
print(vec2) --> (0, 0)
-- Increment the x component
vec2->x++
-- Add 2 to the y component
vec2->y += 2
print(vec2) --> (1, 2)
-- Normalize the vector in-place using bang notation
vec2:Normalize!()
print(vec2) --> (0.447214, 0.894427)
-- Reinitialize the vector with zero values
vec2:Init(0, 0)
print(vec2) --> (0, 0)
print(vec2->x, vec2->y) -- 0 0
print(vec2->u, vec2->v) -- 0 0
-- Reverse the vector in-place
vec2:Init(vec2->yx)
-- Initialize a Vector3 with a Vector2 and an extra value
local vec3 = Vector3(vec2->xy, 3)
-- Collapse this Vector3's Y/Z down into a Vector2
vec2:Init(vec3->yz)
Using Templates
Carbide Lua files using the template features can use inline templates to enable metaprogramming within the metaprogramming. This can be humorously referred to as (meta-)+programming
.
For example:
--#TEMPLATES_ENABLED
--#TEMPLATE_LEVEL 1
{!%
print("This is run at compile time!")
_(__engine:Render([[
{%
print("This is run in a compile-time template at compile time!")
_([=[
print("This is run at run time!")
]=])
%}
]]))
%!}
When compiled, the code will output:
This is run at compile time!
This is run in a compile-time template at compile time!
When run, the code will output:
This is run at run time!