kiss-lang/tink_macro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix headline structure.

Browse Source
This commit is contained in:
Juraj Kirchheim
2018-01-16 17:19:42 +01:00
parent 0be2090232
commit a9bea4287a
1 changed files with 22 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
README.md
View File

@@ -17,7 +17,6 @@ The library is build on top of the haxe macro API and `tink_core`, having three
<!-- START INDEX --> <!-- START INDEX -->
- [Macro API](#macro-api) - [Macro API](#macro-api)
-
- [Expression Tools](#expression-tools) - [Expression Tools](#expression-tools)
- [Basic Helpers](#basic-helpers) - [Basic Helpers](#basic-helpers)
- [Extracting Constants](#extracting-constants) - [Extracting Constants](#extracting-constants)
@@ -51,9 +50,9 @@ It is suggested to use this API by `using tink.MacroApi;`
Apart form `tink_macro` specific things, it will also use `haxe.macro.ExprTools` and `tink.core.Outcome`. Apart form `tink_macro` specific things, it will also use `haxe.macro.ExprTools` and `tink.core.Outcome`.
### Expression Tools ## Expression Tools
#### Basic Helpers ### Basic Helpers
- `at(e:ExprDef, ?pos:Position):Expr` - `at(e:ExprDef, ?pos:Position):Expr`
A short hand for creating expression as for example `EReturn(value).at(position)`, instead of the more verbose `{ expr: EReturn(value), pos: position }`. A short hand for creating expression as for example `EReturn(value).at(position)`, instead of the more verbose `{ expr: EReturn(value), pos: position }`.
@@ -69,7 +68,7 @@ Traces the string representation of an expression and returns it.
- `concat(e1:Expr, e2:Expr):Expr` - `concat(e1:Expr, e2:Expr):Expr`
Concats two expressions into a block. If either sub-expression is a block itself, it gets flattened into the resulting block. Concats two expressions into a block. If either sub-expression is a block itself, it gets flattened into the resulting block.
#### Extracting Constants ### Extracting Constants
- `isWildcard(e:Expr):Bool` - `isWildcard(e:Expr):Bool`
Checks whether an expression is the identifier `_` Checks whether an expression is the identifier `_`
@@ -82,7 +81,7 @@ Attempts extracting an identifier from an expression. Note that an identifier ca
- `getName(e:Expr):Outcome<String, tink.core.Error>` - `getName(e:Expr):Outcome<String, tink.core.Error>`
Attempts extracting a name, i.e. a string constant or identifier from an expression Attempts extracting a name, i.e. a string constant or identifier from an expression
#### Shortcuts ### Shortcuts
Often reification is prefereable to these shortcuts - if applicable. Unlike reification, the position of these expressions will default to `Context.currentPos()` rather than the position where they were created. Often reification is prefereable to these shortcuts - if applicable. Unlike reification, the position of these expressions will default to `Context.currentPos()` rather than the position where they were created.
@@ -119,7 +118,7 @@ Generates a simple if statement.
- `iterate(target:Expr, body:Expr, ?loopVar:String = 'i', ?pos:Position):Expr` - `iterate(target:Expr, body:Expr, ?loopVar:String = 'i', ?pos:Position):Expr`
Will loop over `target` with a loop variable called `loopVar` using `body`- Will loop over `target` with a loop variable called `loopVar` using `body`-
#### Type Inspection ### Type Inspection
- `is(e:Expr, c:ComplexType):Bool` - `is(e:Expr, c:ComplexType):Bool`
Tells you whether a given expression has a given type. Tells you whether a given expression has a given type.
@@ -129,7 +128,7 @@ Inspects, whether an expression can be iterated over and if so returns the eleme
- `typeof(expr:Expr, ?locals:Array<Var>):Outcome<Type, tink.core.Error>` - `typeof(expr:Expr, ?locals:Array<Var>):Outcome<Type, tink.core.Error>`
Attempts to determine the type of an expression. Note that you can use `locals` to hint the compiler the type of certain identifiers. For example if you are in a build macro, and you want to get the type of a subexpression of a method body, you could "fake" the other members of the class as local variables, because in that context, the other members do not yet exists from the compiler's perspective. Attempts to determine the type of an expression. Note that you can use `locals` to hint the compiler the type of certain identifiers. For example if you are in a build macro, and you want to get the type of a subexpression of a method body, you could "fake" the other members of the class as local variables, because in that context, the other members do not yet exists from the compiler's perspective.
#### Advanced Transformations ### Advanced Transformations
- `has(e:Expr, condition:Expr->Bool, ?options: { ?enterFunctions: Bool })` - `has(e:Expr, condition:Expr->Bool, ?options: { ?enterFunctions: Bool })`
This function actually does no transformation, but is very close to the rest of these functions. It allows you to check whether an expression has a sub-expression that satisfies `condition`. By default, it does not enter nested functions. This function actually does no transformation, but is very close to the rest of these functions. It allows you to check whether an expression has a sub-expression that satisfies `condition`. By default, it does not enter nested functions.
@@ -187,7 +186,7 @@ This will traverse an expression and will apply the `yielder` to the "leafs", wh
If you set `options.leaveLoops` to `true`, then loops (both for and while) will be considered leafs. If you set `options.leaveLoops` to `true`, then loops (both for and while) will be considered leafs.
### Position Tools ## Position Tools
- `sanitize(pos:Position):Position` - `sanitize(pos:Position):Position`
Returns the position ITself or `Context.currentPos()` if it's null. Returns the position ITself or `Context.currentPos()` if it's null.
@@ -202,7 +201,7 @@ Creates a failed `Outcome` associated with the supplied position.
- `getOutcome<D, F>(pos:Position, outcome:Outcome<D, F>):D` - `getOutcome<D, F>(pos:Position, outcome:Outcome<D, F>):D`
Attempts getting the result of the supplied outcome. If it is a failure, it will cause an error at the given position. Attempts getting the result of the supplied outcome. If it is a failure, it will cause an error at the given position.
### Type Tools ## Type Tools
- `getID(t:Type, ?reduced = true):Null<String>` - `getID(t:Type, ?reduced = true):Null<String>`
Returns a String identifier for a type if available. By default, the type will be reduced prior to getting its name (typedefs are resolved etc.). With `reduced = false` you can also get the name of a typedef. Returns a String identifier for a type if available. By default, the type will be reduced prior to getting its name (typedefs are resolved etc.). With `reduced = false` you can also get the name of a typedef.
@@ -225,7 +224,7 @@ Will tell you whether a field is a variable or not. Signature is likely to chang
- `toComplex(type:Type, ?option:{ ?direct: Bool }):ComplexType` - `toComplex(type:Type, ?option:{ ?direct: Bool }):ComplexType`
Will convert a `Type` to a `ComplexType`. Ideally this is done with `Context.toComplexType` but for monomorphs and the like, this builtin method fails and `tink_macro` uses a hack to make it work none the less. You can also use `{ direct : true }` to force this hack in case the translation fails (which can be the case with private types). Will convert a `Type` to a `ComplexType`. Ideally this is done with `Context.toComplexType` but for monomorphs and the like, this builtin method fails and `tink_macro` uses a hack to make it work none the less. You can also use `{ direct : true }` to force this hack in case the translation fails (which can be the case with private types).
### Function Tools ## Function Tools
- `asExpr(f:Function, ?name:String, ?pos:Position):Expr` - `asExpr(f:Function, ?name:String, ?pos:Position):Expr`
Converts a function to an expression, i.e. a local function definition. Converts a function to an expression, i.e. a local function definition.
@@ -236,7 +235,7 @@ A shorthand to create function arguments.
- `getArgIdents(f:Function):Array<Expr>` - `getArgIdents(f:Function):Array<Expr>`
Will extract the argument list of a function as an expression list of identifiers (usefull when writing call-forwarding macros or the like). Will extract the argument list of a function as an expression list of identifiers (usefull when writing call-forwarding macros or the like).
### Operation Tools ## Operation Tools
- `get(o:Binop, e:Expr):Outcome<{ e1:Expr, e2:Expr, pos:Position }, tink.core.Error>` - `get(o:Binop, e:Expr):Outcome<{ e1:Expr, e2:Expr, pos:Position }, tink.core.Error>`
Attempts to extract a specific binary operation from an expression. Attempts to extract a specific binary operation from an expression.
@@ -250,7 +249,7 @@ Attempts to extract a specific unary operation from an expression.
- `getUnop(e:Expr):Outcome<{ op:Unop, e:Expr, postFix:Bool, pos:Position }, tink.core.Error>` - `getUnop(e:Expr):Outcome<{ op:Unop, e:Expr, postFix:Bool, pos:Position }, tink.core.Error>`
Attempts to decompose an expression into the parts of a unary operation. Attempts to decompose an expression into the parts of a unary operation.
### Metadata Tools ## Metadata Tools
- `toMap(m:Metadata):Map<String, Array<Array<Expr>>` - `toMap(m:Metadata):Map<String, Array<Array<Expr>>`
Will deconstruct an array of metadata tags to a `Map` mapping the tag names to an array of the argument lists of each tag with that name. So `@foo(1) @foo(2) @bar` becomes `["foo" => [[1], [2]], "bar" => [[]]]` Will deconstruct an array of metadata tags to a `Map` mapping the tag names to an array of the argument lists of each tag with that name. So `@foo(1) @foo(2) @bar` becomes `["foo" => [[1], [2]], "bar" => [[]]]`