#Morphir Elm

#Purpose

#Use from the engine

[pipeline]
backend = "elm"

[backends.elm]
profile = "model"            # "model" (default) | "literal"
placeholders = "refuse"      # "refuse" (default) | "debug-todo"
width = 120
elm_package = "finos/morphir-elm 22.0.2"

[backends.elm.mapping]
"morphir/SDK:basics#add" = { operator = "+" }
"morphir/SDK:list#map" = { function = "List.map" }
"morphir/SDK:decimal#decimal" = { type = "Decimal.Decimal", import = "MyCo.Decimal as Decimal" }
"morphir/SDK:basics#max" = {}

[backends.elm.packages]
"acme/common" = { package = "acme/common 1.0.0" }

• profile selects the profile. See Profiles.
• placeholders tells the backend what to do with a value that has no body. refuse stops generation with elm.placeholder. debug-todo writes Debug.todo "<reason>".
• width is the line width of the printer. It must be an integer from 1 to 1000.
• elm_package is the Elm package that supplies unmapped Morphir.SDK modules. The value is "author/name major.minor.patch". The default is finos/morphir-elm 22.0.2.
• mapping adds, replaces or removes mapping entries. See Mapping.
• packages maps a Morphir dependency package to an Elm package. An entry has only the form { package = "author/name 1.2.3" }.

#Profiles

add : Int -> Int -> Int
add a b =
    a + b

add : Morphir.SDK.Basics.Int -> Morphir.SDK.Basics.Int -> Morphir.SDK.Basics.Int
add a b =
    Morphir.SDK.Basics.add a b

#Mapping

• { operator = "+" }: an Elm operator. With two arguments it becomes a + b. With fewer arguments it becomes a prefix operator, for example (+) a. An operator entry takes no import.
• { function = "List.map" }: an Elm value or constructor, qualified or not.
• { type = "Dict.Dict" }: an Elm type, qualified or not.
• {}: removes the entry. The reference falls back to the qualified form.

#The built-in table

#Namespaces

#Keys

#Output

elm.json
morphir.json
src/<Package>/<Module>.elm

• Each IR module becomes one file in src/. The Elm module name is the package path followed by the module path, for example Acme.Shapes.Geometry for package acme/shapes and module geometry.
• elm.json has "type": "package". Its name is the first part of the Morphir package path, /, and the other parts joined with -, for example acme/shapes. It exposes the public modules. If no module is public, it exposes all modules.
• morphir.json has the Morphir package name, "sourceDirectory": "src" and the exposed modules.

• elm/core 1.0.5 <= v < 2.0.0, always.
• The elm_package, only when the code uses an unmapped Morphir.SDK reference.
• One entry for each dependency package that has an entry in packages. A dependency package with no entry gives a warning, not an error. elm make then reports the missing modules.

#Declarations

• Declarations keep the IR order. Imports are sorted.
• Public types and values are exposed. Private ones are not. A custom type with public constructors is exposed as T(..). A custom type with private constructors is exposed as T.
• An opaque type specification becomes a custom type with one hidden constructor, <Type>Opaque.
• Module documentation becomes the module doc comment. Member documentation becomes the doc comment of the declaration. An empty doc gives no doc comment.
• An Elm reserved word as a name gets the suffix _, for example type_.
• Elm updates only a record with a bare name. A record update of a local or of a value that prints without a qualifier names it: { origin | x = 1 }. Any other record is first bound in a let, as record_<n>.
• A type variable with a typeclass constraint gets the Elm prefix of that class: number, comparable, appendable or compappend. An unconstrained variable whose name starts with one of these prefixes gets the prefix t, so Elm does not read it as constrained.

#Attributes

@morphir.entry { kind = "main", name = "run" }
@morphir.annotation { fqname = "acme/api:tags#stable" }
@morphir.external { platform = "js", name = "Math.max" }

• @morphir.entry marks the target value of an entry point in an Application.
• @morphir.annotation holds an annotation of a value specification. A compact annotation has fqname and an optional text. A structured annotation has fqname and arguments.
• @morphir.external holds one binding of an ExternalBody.

#Local names

#Refusals

#Limits

• The backend does not write regular comments. krueger prints doc comments only.
• Derived types and decimal literals are refused (elm.derived_type and elm.decimal_literal).
• elm make --optimize rejects Debug.todo. Code generated with placeholders = "debug-todo" compiles only without --optimize.
• The finos/morphir-elm Elm package has no Morphir.SDK.Maybe module. An unmapped morphir/SDK:maybe reference, for example morphir/SDK:maybe#has-value, gives code that elm make rejects. Add a mapping entry for it.
• packages takes only Elm packages. Dependency source directories are not supported.

#Frontend

pub fn compile_project(
  sources : Array[ElmSource],   // every .elm file: path relative to the source directory, and content
  package_name : String,        // the dotted package name, for example "My.Pkg"
  exposed : Array[String],      // the exposed modules relative to the package, as in morphir.json
  output? : OutputModules = Parity,  // Parity: the modules of morphir-elm; Referenced: also every module the output names
) -> @ir.IRFile raise ElmFailed

• finos/morphir-elm/mapping: Elm names to Morphir names, and the elm/core table.
• finos/morphir-elm/frontend: parsing, module rules, module selection, access, docs and compile_project.
• finos/morphir-elm/frontend/resolve: the project symbol table, exports, imports and name resolution.
• finos/morphir-elm/frontend/lower: type definitions and value definitions (signatures and bodies) to IR.

1. The morphir.json exposedModules entries are module names relative to the package name ("Types" for My.Pkg.Types).
2. morphir-elm processes the exposed modules and the project modules that they import, transitively. The output keeps the exposed modules and the processed modules that they reach in the module graph, transitively. A module depends on the modules of the names in its type definitions (the constructors of a custom type count, whatever their access) and of the value references in its value bodies: values, operators other than <| and |>, and Basics.negate for a negation of anything but a number literal. A module that is named only in value signatures, used only through constructors in bodies, imported and not used, or not imported, is not in the output. The graph compares module paths without the package, so a project module with the path of an SDK module that is used (for example My.Pkg.Basics and Int) is kept. Every output module keeps all of its declarations.
3. The exposed modules are Public. A module that is not exposed is Public when an exposed module shows one of its types: as the target of a public type alias, as a constructor argument of a public type with public constructors, or in the signature of a public value. This continues through the public definitions of the types that it reaches. morphir-elm takes the names in Elm order and follows only the first name that it finds in each module. All other output modules are Private.
4. A type exported as T is Public with Private constructors. T(..) gives Public constructors. A type or value that the module does not export is Private.
5. The module path is the module name without the package prefix (My.Pkg.Types in package My.Pkg is ["types"]).
6. A declaration doc keeps the raw text between {-| and -}: {-| A point. -} gives " A point. " and {-| D.-} gives " D.". A declaration without a doc gets "". The module doc is the first {-| comment in the file that is not a declaration doc, without its first 3 and its last 3 characters. Thus the character before -} goes too, whatever it is: {-| Doc. -} gives " Doc.", {-| Doc.-} gives " Doc", {-| Doc. -} gives " Doc. " and {-| Doc.\n\n-} gives " Doc.\n". A module without one has no doc.
7. A {-| comment is the doc of a declaration only when the declaration starts on the row directly after the row where the comment ends. A blank line between them makes the comment an ordinary comment. Thus a {-| comment directly above the first declaration is the doc of that declaration, not the module doc.
8. The arguments of a top-level value are the declaration arguments, then the arguments of the leading lambdas in the body, looking through parentheses. Inputs are lifted from the front of this list while the lowered pattern is a variable (x, (x) and _ as x) and, when the value has an annotation, the rest of the annotation is a function type (also in parentheses). Anything else, also a type alias of a function type, stops the inputs. An unannotated value lifts every leading variable, each with a placeholder type. The output type is the rest of the annotation. The arguments that are not lifted stay in the body as one Lambda each. Thus wild _ y = y has no inputs and the body Lambda(_, Lambda(y, y)). f : Handler with type alias Handler = Int -> Int and f x = x has no inputs, the output Handler and the body Lambda(x, x). h : Int -> Handler with h a b = a has the input a : Int, the output Handler and the body Lambda(b, a).
9. A record pattern fails in morphir-elm, in every position. The frontend gives elm.unsupported for it.
10. Literals: 1 and 0xFF are IntegerLiteral ("1", "255"). -1 and -2.5 fold into the literal. -(1) and -x are Apply(Reference basics#negate, …). 1.5 is FloatLiteral. Char and string literals are decoded ("\u{0041}" is "A"). Unqualified True and False are BoolLiteral.
11. Names: a local name is Variable. A lower-case global name is Reference. An upper-case global name is Constructor, also a record alias constructor such as Point 1 2, with the alias name.
12. f a b is Apply(Apply(f, a), b). a |> f and f <| a are Apply(f, a). (+) is the Reference of the operator function.
13. Every other binary operator a op b is Apply(Apply(Reference op, a), b), with this fixed table (all in basics, except ::). An operator that is not in the table gives elm.unsupported_value.

    Operator	Function	Operator	Function	Operator	Function
    \|\|	or	<=	lessThanOrEqual	/	divide
    &&	and	>=	greaterThanOrEqual	//	integerDivide
    ==	equal	++	append	^	power
    /=	notEqual	+	add	<<	composeLeft
    <	lessThan	-	subtract	>>	composeRight
    >	greaterThan	*	multiply	::	list#cons

14. if is IfThenElse. case is PatternMatch, with the cases in source order.
15. Patterns: _ is WildcardPattern. x is AsPattern(WildcardPattern, x). Integer, hex, char and string literal patterns are LiteralPattern. True and False are LiteralPattern(BoolLiteral). Tuples are TuplePattern. [] is EmptyListPattern. [a, b] is HeadTailPattern(a, HeadTailPattern(b,EmptyListPattern)). x :: xs is HeadTailPattern. A constructor has its argument patterns. p as n is AsPattern. () is UnitPattern. A pattern in parentheses is its inner pattern.
16. \x y -> b is Lambda(x, Lambda(y, b)), one Lambda for each argument.
17. Records: { y = 2, x = 1 } is Record. p.x is Field. .x is FieldFunction. { p | x = 1 } is UpdateRecord, with the target as Variable (a local name) or Reference (a global name). Tuples, lists and unit are Tuple, List and Unit.
18. Let: a let function or value is LetDefinition(name, definition, in). The definition has no inputs. Its output is the let annotation or, when there is no annotation, a placeholder. Its body is the Lambda chain of its arguments. Let definitions are never lifted. A destructuring let is Destructure(pattern, value, in). A group of let definitions that refer to each other (or one that refers to itself) is LetRecursion. A recursive destructuring gives elm.unsupported.
19. The let chain is in dependency order, not in source order, as morphir-elm builds it with elm-community/graph 6.0.0. The dependencies are the unqualified names that each right-hand side mentions. When there is no cycle, the chain is the depth-first post-order of the declarations, outermost first. When there is a cycle, the chain is the reverse of the Kosaraju components, outermost first.
20. Each value node and each pattern node has the source location of its Elm code.
21. morphir-elm refuses top-level mutual recursion (ValueCycleDetected). Elm accepts it, and the frontend accepts it too.
22. The last pass is @typing.infer(file, sdk, Fill) with the Morphir SDK specification. It gives every value and pattern node an inferred_type, and it replaces each placeholder of an unannotated value or let definition with its solution. It sees every processed module, also one that the output drops (rule 2), because a value signature can name a type of such a module. The types can differ from those of morphir-elm: inference generalizes a let definition (morphir-elm does not), and morphir-elm types an unannotated top-level value in a first pass without the other values.
23. After inference, a whole-number literal of type Float becomes a FloatLiteral, as morphir-elm Infer.fixNumberLiterals does: fi : Float with fi = 2 gives FloatLiteral(2.0). An alias of Float counts, with one alias resolved only (Distribution.resolveType): an alias of an alias of Float keeps the whole number. The rewrite reaches the values of every body and let definition, not the patterns. A literal that nothing fixes keeps its number type variable. Because inference generalizes a let definition (rule 22), a let value can keep a whole number where morphir-elm writes a float: in scaled price = let rate = 2 in price * rate with scaled : Float -> Float, rate stays IntegerLiteral "2" of type number. The parity test then finds a body difference, and a body difference hides the type comparison of that value (bead morphir-ukvn.5.22.7.1).

#Tests

moon test pkgs/morphir-elm/backend       # unit and generation tests
moon test pkgs/morphir-elm/conformance   # frontend parity with morphir-elm make and the IR round trip
mise run test:elm                        # elm make on the generated fixture projects
mise run elm:parity-refresh              # regenerate the parity corpus after a project change