description |
---|
Introduction to the Dawn language and it's structure. |
Welcome to the Dawn API GitBook! Here I'd like to introduce you to the Dawn compiler structure, the dawn
CLI tool, and the Dawn syntax (in a nutshell).
Dawn is a "mapping" language i.e. Dawn is a language that compiles to some other language. It's very possible Dawn will eventually remove the "middle-man" so to speak, as in, Dawn won't need another compiler to sustain it. The primary goal of Dawn, though, is to provide maximum cross-compatibility with two languages on the opposite ends of the spectrum.
{% tabs %} {% tab title="TypeScript" %} Dawn compiles all of its code directly to TypeScript.
Typescript example
//*dawn:ts-4.7.2; --strip-doccomments; --strip-dev
class Fraction {
n: number;
d: number;
constructor(n: number, d: number) {
this.n = n;
this.d = d;
};
toString(): string {
return `${this.n}/${this.d}`;
};
eval(): number {
return n/d;
}
};
export default class Point {
x: Fraction;
y: Fraction;
constructor(x: Fraction, y: Fraction) {
this.x = x;
this.y = y;
};
};
{% endtab %}
{% tab title="C" %} Dawn compiles all of its code directly to C.
C example
//*dawn:c99; --strip-doccomments; --strip-dev
#include "dawnc/dawn_string.h"
typedef struct Fraction {
n: int;
d: int;
} Fraction;
//*dawn:c99; poly-transform: Fraction(n,d) becomes declaration
void Fraction_constructor(Fraction* this, int n, int d) {
this->n = n;
this->d = d;
};
//*dawn:c99; Fraction.toString()
string Fraction_toString(Fraction* this) {
return genString("{}/{}", this->n, this->d);
};
//*dawn:c99; Fraction.eval()
int Fraction_eval(Fraction* this) {
return (float)this->n/this->d; //*dawn:c99; Might result in float
}
//*dawn:c99;export default--DefaultExportPoint
typedef struct DE__Point {
Fraction x;
Fraction y;
} DE__Point;
//*dawn:c99; poly-transform: Point(n,d) becomes declaration
void* DE__Point_constructor(DE__Point* this, Fraction x, Fraction y) {
this->x = x;
this->y = y;
};
{% endtab %} {% endtabs %}
dawnc
exposes an API for cross-compatibility between C and TypeScript applications.
import { CEngine } from `@dawnts/dawnc`;
// reverses Dawn-to-C abstractions
const { Fraction } = CEngine.execFile('./something.c');
// smart arguments
Fraction.constructor(5, 6);
// You have to stringify it, otherwise it'll return a CVariableInstance class
console.log(Fraction.eval().toString());
{% hint style="warning" %}
dawnts
is still a work in progress. Avoid usage until it is safe.
{% endhint %}
dawnts
exposes the TS-to-C API.
#include "dawnts/engine.h"
CEngine Module = CreateCEngineFromFile("./something.ts");
RunCEngine(*Module);
// get TS elements
Class Fraction = GetClass(Module, "Fraction");
Class a = Initialize(Fraction, 1, 2);
Dawn's compiler structure is actually pretty simple (Dawn is written in TypeScript). Dawn parses Dawn projects and constructs an AST. Then it parses the AST via a series of passes. This allows Dawn's code to be modular. For example:
struct MyStruct {
a: int;
b: int;
};
impl MyStruct {
init(a: int, b: int) {
this.a = a;
this.b = b;
};
};
Could be parsed into an AST similar to:
[
StructDeclaration {
name: 'MyStruct',
values: [
VarTypeDeclaration {
name: 'a',
type: 'int'
},
VarTypeDeclaration {
name: 'a',
type: 'int'
}
]
},
StructImplementation {
struct: 'MyStruct',
functions: [
'init': {
special: true,
type: 'constructor',
definition: FunctionDeclaration {
name: 'init',
params: [
VarTypeDeclaration {
name: 'a',
type: 'int'
},
VarTypeDeclaration {
name: 'a',
type: 'int'
}
],
body: {
EqualityDeclaration {
left: AttrReference {
root: SpecialKeyword {
name: 'this'
},
stem: 'a'
},
right: VarName {
name: 'a'
}
},
EqualityDeclaration {
left: AttrReference {
root: SpecialKeyword {
name: 'this'
},
stem: 'b'
},
right: VarName {
name: 'b'
}
}
}
}
}
]
}
]
By attaching a primitive
function next to these AST elements, we can perform primitive transformations on these elements. We can then refine these transformations with passes to include context.
Recursive passes require larger amounts of operations than linear ones.
dawn
is a super-useful CLI tool for running the Dawn compiler.
dawn [build | fmt | check] (*.dawn)... --output?:c-[spec] | ts-[ver] /
--post?: m(c-fmt | ts-fmt | babel | ugl | compile)
We can also download libraries to use in our project using:
dawntools get pkg-name --global?>-g