the-sett / elm-syntax-dsl / Elm.CodeGen

Elm.CodeGen is a DSL designed to make it easier to write Elm code that generates Elm code.

Build an Elm source file.

file : Module -> List Import -> List Declaration -> Maybe (Comment FileComment) -> File

Assembles all the components of an Elm file; the module declaration, the comments, the imports and the top-level declarations.

Build a module declaration.

elm-syntax also permits effects modules, but with kernel code restrictions you cannot use these so they have been ommitted from the DSL.

normalModule : ModuleName -> List TopLevelExpose -> Module

NormalModule DefaultModuleData

portModule : ModuleName -> List TopLevelExpose -> Module

PortModule DefaultModuleData

Build an 'exposing' statement.

exposeAll : Exposing

All Range

exposeExplicit : List TopLevelExpose -> Exposing

Explicit (List (Node TopLevelExpose))

infixExpose : String -> TopLevelExpose

Custom operators were removed from Elm 0.19, but you can still import them from the kernel modules that do define them, such as elm/parser.

closedTypeExpose : String -> TopLevelExpose

TypeExpose ExposedType

funExpose : String -> TopLevelExpose

FunctionExpose String

openTypeExpose : String -> TopLevelExpose

TypeExpose ExposedType

typeOrAliasExpose : String -> TopLevelExpose

TypeOrAliasExpose String

Build an import statement.

importStmt : ModuleName -> Maybe ModuleName -> Maybe Exposing -> Import

Creates an Elm import statement; the name of the module, an optional alias name for the module, and an optional list of exposings from the module.

Incrementally build import and exposing statements.

This is useful during code generation where the exact imports and exports are not known in advance but depend on what code is actually generated. Each section of code generation can declare the imports and exposings that it needs and they can be combined and de-duplicated to produce a final list.

I have used the name Linkage to refer to the combination of a modules imports and exports. It describes how a module is linked to other modules.


type alias Linkage =
( List Import
, List TopLevelExpose 
)

Linkage describes the lists of imports and exposings of a module and allows these to be built up incrementally as code generation progresses.

addExposing : TopLevelExpose -> Linkage -> Linkage

Adds an exposing to the list.

addImport : Import -> Linkage -> Linkage

Adds an import to the list.

combineLinkage : List Linkage -> Linkage

Simplifies the imports and exposings by removing any duplicates.

emptyLinkage : Linkage

Creates empty imports and exposings lists.

Build comments in a structured way.


type alias Comment a =
Elm.Comments.Comment a

A structured representation of an Elm comment on a file or declaration.


type alias DocComment =
Elm.Comments.DocComment

A comment type for doc comments on top-level declarations.


type alias FileComment =
Elm.Comments.FileComment

A comment type for file comments at the head of a .elm file.

emptyDocComment : Comment DocComment

Creates an empty documenting comment that will go on a declaration.

emptyFileComment : Comment FileComment

Creates an empty comment that will go on a module file.

markdown : String -> Comment a -> Comment a

Adds some markdown to a comment.

code : String -> Comment a -> Comment a

Adds a code block to a comment.

docTags : List String -> Comment FileComment -> Comment FileComment

Adds a set of doc tags to a comment.

Doc tags will never be merged into a single line, but if they are too long to fit the page width, the pretty printer can break them into separate lines.

docTagsFromExposings : List TopLevelExpose -> Comment FileComment -> Comment FileComment

Adds a set of doc tags taking from a description of what a module exposes, into a comment.

Doc tags will never be merged into a single line, but if they are too long to fit the page width, the pretty printer can break them into separate lines.

Build top-level declarations.

aliasDecl : Maybe (Comment DocComment) -> String -> List String -> TypeAnnotation -> Declaration

AliasDeclaration TypeAlias

customTypeDecl : Maybe (Comment DocComment) -> String -> List String -> List ( String, List TypeAnnotation ) -> Declaration

CustomTypeDeclaration Type

funDecl : Maybe (Comment DocComment) -> Maybe TypeAnnotation -> String -> List Pattern -> Expression -> Declaration

FunctionDeclaration Function

valDecl : Maybe (Comment DocComment) -> Maybe TypeAnnotation -> String -> Expression -> Declaration

A top-level value declaration or constant.

portDecl : String -> TypeAnnotation -> Declaration

PortDeclaration Signature

Operators


type BinOp

Represents all of the binary operators allowed in Elm.

composer : BinOp

The compose right operator >>.

composel : BinOp

The compose left operator <<.

power : BinOp

The to-the-power-of operator ^

mult : BinOp

The multiplication operator *.

div : BinOp

The division operator /.

intDiv : BinOp

The integer division operator //.

modulo : BinOp

The modulo operator %.

remOp : BinOp

The remainder operator rem.

plus : BinOp

The addition operator +.

minus : BinOp

The subtraction operator -.

append : BinOp

The append operator ++.

cons : BinOp

The cons operator ::.

equals : BinOp

The equality operator ==.

notEqual : BinOp

The inequality operator /=.

lt : BinOp

The less-than operator <.

gt : BinOp

The greater-than operator >.

lte : BinOp

The less-than-or-equal operator <=.

gte : BinOp

The greater-than-or-equal operator >=.

and : BinOp

The logical and operator &&.

or : BinOp

The logical or operator ||.

piper : BinOp

The pipe right operator |>.

pipel : BinOp

The pipe left operator <|.

binOp : BinOp -> Expression

Creates a binary operator in its prefix form, as a bracketed expression.

binOp equals

Yields:

(=)

applyBinOp : Expression -> BinOp -> Expression -> Expression

Applies a binary operator to left and right expressions. This takes the expression in the order that is usual; that being expr op expr.

applyBinOp (int 2) plus (int 3)

Yields:

2 + 3

applyUnaryMinus : Expression -> Expression

There is only one unary operator in Elm, and that is the minus sign prefixed onto some numeric expression.

applyUnaryMinus (int 5)

Yields:

 -5

Other Expressions.

access : Expression -> String -> Expression

RecordAccess (Node Expression) (Node String)

accessFun : String -> Expression

RecordAccessFunction String

apply : List Expression -> Expression

Application (List (Node Expression))

construct : String -> List Expression -> Expression

Apply a named constructor to a list of arguments.

caseExpr : Expression -> List ( Pattern, Expression ) -> Expression

CaseExpression CaseBlock

char : Char -> Expression

CharLiteral Char

float : Basics.Float -> Expression

Floatable Float

fqConstruct : ModuleName -> String -> List Expression -> Expression

Apply a named constructor fully qualified with a module name, to a list of arguments.

fqFun : ModuleName -> String -> Expression

FunctionOrValue ModuleName String

fqVal : ModuleName -> String -> Expression

FunctionOrValue ModuleName String

Note this is the same as fqFun

fun : String -> Expression

Creates a FunctionOrValue with no qualifying module.

glsl : String -> Expression

GLSLExpression String

hex : Basics.Int -> Expression

Hex Int

ifExpr : Expression -> Expression -> Expression -> Expression

IfBlock (Node Expression) (Node Expression) (Node Expression)

int : Basics.Int -> Expression

Integer Int

lambda : List Pattern -> Expression -> Expression

LambdaExpression Lambda

letExpr : List LetDeclaration -> Expression -> Expression

LetExpression LetBlock

list : List Expression -> Expression

ListExpr (List (Node Expression))

negate : Expression -> Expression

Negation (Node Expression)

parens : Expression -> Expression

ParenthesizedExpression (Node Expression)

Note: elm-syntax-dsl should insert parentheses automatically in relevant places, however this can still be useful in corner cases.

record : List ( String, Expression ) -> Expression

RecordExpr (List (Node RecordSetter))

string : String -> Expression

Literal String

tuple : List Expression -> Expression

TupledExpression (List (Node Expression))

unit : Expression

UnitExpr

update : String -> List ( String, Expression ) -> Expression

RecordUpdateExpression (Node String) (List (Node RecordSetter))

val : String -> Expression

Creates a FunctionOrValue with no qualifying module.

Note this is the same as fun.

letFunction : String -> List Pattern -> Expression -> LetDeclaration

A function declared inside a let block.

letDestructuring : Pattern -> Expression -> LetDeclaration

A pattern matching declared inside a let block.

letVal : String -> Expression -> LetDeclaration

A value declared inside a let block.

Helper functions for common expression patterns.

chain : Expression -> List Expression -> Expression

Joins multiple expressions together with the function chain operator >>. An expression a combined with a list of expressions [b, c, d] results in:

a >> b >> c >> d

pipe : Expression -> List Expression -> Expression

Joins multiple expressions together with the pipe operator |>. An expression a combined with a list of expressions [b, c, d] results in:

a |> b |> c |> d

binOpChain : Expression -> BinOp -> List Expression -> Expression

Joins multiple expressions together with a binary operator. An expression a, and operator op, combined with a list of expressions [b, c, d] results in:

a op b op c op d

The expression is not bracketed so will parse as the operator associativity directs.

Build a pattern matching expression.

allPattern : Pattern

AllPattern

asPattern : Pattern -> String -> Pattern

AsPattern (Node Pattern) (Node String)

charPattern : Char -> Pattern

CharPattern Char

floatPattern : Basics.Float -> Pattern

FloatPattern Float

fqNamedPattern : ModuleName -> String -> List Pattern -> Pattern

NamedPattern QualifiedNameRef (List (Node Pattern))

hexPattern : Basics.Int -> Pattern

HexPattern Int

intPattern : Basics.Int -> Pattern

IntPattern Int

listPattern : List Pattern -> Pattern

ListPattern (List (Node Pattern))

namedPattern : String -> List Pattern -> Pattern

NamedPattern QualifiedNameRef (List (Node Pattern))

parensPattern : Pattern -> Pattern

ParenthesizedPattern (Node Pattern)

recordPattern : List String -> Pattern

RecordPattern (List (Node String))

stringPattern : String -> Pattern

StringPattern String

tuplePattern : List Pattern -> Pattern

TuplePattern (List (Node Pattern))

unConsPattern : Pattern -> Pattern -> Pattern

UnConsPattern (Node Pattern) (Node Pattern)

unitPattern : Pattern

UnitPattern

varPattern : String -> Pattern

VarPattern String

Build a type annotation.

extRecordAnn : String -> List ( String, TypeAnnotation ) -> TypeAnnotation

GenericRecord (Node String) (Node RecordDefinition)

fqTyped : ModuleName -> String -> List TypeAnnotation -> TypeAnnotation

Typed (Node ( ModuleName, String )) (List (Node TypeAnnotation))

funAnn : TypeAnnotation -> TypeAnnotation -> TypeAnnotation

FunctionTypeAnnotation (Node TypeAnnotation) (Node TypeAnnotation)

recordAnn : List ( String, TypeAnnotation ) -> TypeAnnotation

Record RecordDefinition

tupleAnn : List TypeAnnotation -> TypeAnnotation

Tupled (List (Node TypeAnnotation))

typeVar : String -> TypeAnnotation

GenericType String

typed : String -> List TypeAnnotation -> TypeAnnotation

Typed (Node ( ModuleName, String )) (List (Node TypeAnnotation))

unitAnn : TypeAnnotation

Unit

boolAnn : TypeAnnotation

A Bool type annotation.

intAnn : TypeAnnotation

An Int type annotation.

floatAnn : TypeAnnotation

A Float type annotation.

stringAnn : TypeAnnotation

A String type annotation.

charAnn : TypeAnnotation

A Char type annotation.

listAnn : TypeAnnotation -> TypeAnnotation

Creates a List type annotation.

setAnn : TypeAnnotation -> TypeAnnotation

Creates a Set type annotation.

dictAnn : TypeAnnotation -> TypeAnnotation -> TypeAnnotation

Creates a Dict type annotation.

maybeAnn : TypeAnnotation -> TypeAnnotation

Creates a Maybe type annotation.

Build a type signature.

signature : String -> TypeAnnotation -> Elm.Syntax.Signature.Signature

Creates a type signature.

Types describing parts of the Elm AST.

These types are all declared in elm-syntax but are re-exported here for convenience.


type alias ModuleName =
List String

A module name can consist of mulitple Stirngs separated with '.'.


type alias Module =
Elm.Syntax.Module.Module

The AST for an Elm module.


type alias File =
{ moduleDefinition : Elm.Syntax.Node.Node Module
, imports : List (Elm.Syntax.Node.Node Import)
, declarations : List Declaration
, comments : Maybe (Comment FileComment) 
}

The AST for an Elm file.


type Declaration
    = DeclWithComment (Comment DocComment) (String -> Elm.Syntax.Declaration.Declaration)
    | DeclNoComment Elm.Syntax.Declaration.Declaration

The AST for a top-level Elm declaration; a function, a value, a type or a type alias.


type alias Import =
Elm.Syntax.Import.Import

The AST for an Elm import statement.


type alias TypeAnnotation =
Elm.Syntax.TypeAnnotation.TypeAnnotation

The AST for an Elm type annotation.


type alias Exposing =
Elm.Syntax.Exposing.Exposing

The AST for an Elm exposing statement.


type alias TopLevelExpose =
Elm.Syntax.Exposing.TopLevelExpose

The AST for a member of an Elm exposing statement.


type alias Expression =
Elm.Syntax.Expression.Expression

The AST for an Elm expression.


type alias Pattern =
Elm.Syntax.Pattern.Pattern

The AST for a de-structuring Elm pattern matching expression.


type alias LetDeclaration =
Elm.Syntax.Expression.LetDeclaration

The AST for an Elm let declaration.