WIXLIB

26.3 Extension Nodes453In this example, the @@deprecated annotation is only attached to the Planets module,and the human-readable argument string redirects developers to the newer code. Nowif we try to use the value that has been marked as deprecated, the compiler will issuea warning.# let is pluto a planet Planets.pluto;;Line 1, characters 25-38:Alert deprecated: module PlanetsSorry, Pluto is no longer a planet. Use the Planets2016 moduleinstead.val is pluto a planet : bool true# let is pluto a planet Planets2016.pluto;;val is pluto a planet : bool falseFinally, an attribute can also be attached to an individual expression. In the nextexample, the@warn on literal patternattribute indicates that the argument to thetype constructor should not be pattern matched upon with a constant literal.# type program result Error of string [@warn on literal pattern] Exit code of int;;type program result Error of string Exit code of int# let exit with function Error "It blew up" - 1 Exit code code - code Error - 100;;Line 2, characters 11-23:Warning 52 [fragile-literal-pattern]: Code should not depend on theactual values ofthis constructor's arguments. They are only for informationand may change in future versions. (See manual section 11.5)val exit with : program result - int fun 26.3.2Commonly Used Extension AttributesWe have already used extension points in Chapter 21 (Data Serialization with SExpressions) to generate boilerplate code for handling s-expressions. These are introduced by a third-party library using the(preprocess)directive in a dune le, forexample:(library(name hello world)(libraries core)(preprocess (pps ppx jane))This allows you to take advantage of a community of syntax augmentation. Thereare also a number of builtin attributes in the core OCaml compiler. Some are performance oriented and give directives to the compiler, whereas others will activate usagewarnings. The full list is available in the attributes tps://doi.org/10.1017/9781009129220.030 Published online by Cambridge University Press8 of the OCaml manual.

454The Compiler Frontend: Parsing and Type Checking26.3.3Extension NodesWhile extension points are useful for annotating existing source code, we also need amechanism to store generic placeholders within the OCaml AST for code generation.OCaml provides this facility via theextension node syntax.The general syntax for an extension node isfor a particular extension node rewriter and[%id expr], where id is an identi erexpr is the payload for the rewriter to parse.An in x form is also available when the payload is of the same kind of syntax. Forexamplelet%foo bar 1 is equivalent to [%foo let bar 1].We've already seen extension nodes in use via the Core syntax extensions earlierin the book, where they act as syntactic sugar for error handling (let%bind), forcommand-line parsing (let%map) or inline testing (let%expect test). Extension nodesare introduced via dune rules in the same fashion as extension attributes, via the(preprocess) attribute.26.4Static Type CheckingAfter obtaining a valid abstract syntax tree, the compiler has to verify that the codeobeys the rules of the OCaml type system. Code that is syntactically correct but misusesvalues is rejected with an explanation of the problem.Although type checking is done in a single pass in OCaml, it actually consists ofthree distinct steps that happen simultaneously:automatic type inferenceAn algorithm that calculates types for a module withoutrequiring manual type annotationsmodule systemCombines software components with explicit knowledge of their typesignaturesexplicit subtypingChecks for objects and polymorphic variantsAutomatic type inference lets you write succinct code for a particular task and havethe compiler ensure that your use of variables is locally consistent.Type inference doesn't scale to very large codebases that depend on separate compilation of les. A small change in one module may ripple through thousands of otherles and libraries and require all of them to be recompiled. The module system solvesthis by providing the facility to combine and manipulate explicit type signatures formodules within a large project, and also to reuse them via functors and rst-classmodules.Subtyping in OCaml objects is always an explicit operation (via the: operator).This means that it doesn't complicate the core type inference engine and can be testedas a separate concern.https://doi.org/10.1017/9781009129220.030 Published online by Cambridge University Press

26.4 Displaying Inferred Types from the Compiler26.4.1455Displaying Inferred Types from the CompilerWe've already seen how you can explore type inference directly from the toplevel. It'salso possible to generate type signatures for an entire le by asking the compiler to dothe work for you. Create a le with a single type de nition and value:type t Foo Barlet v FooNow run the compiler with the-iag to infer the type signature for that le. Thisruns the type checker but doesn't compile the code any further after displaying theinterface to the standard output: ocamlc -i typedef.mltype t Foo Barval v : tThe output is the default signature for the module that represents the input le. It'soften useful to redirect this output to anmli le to give you a starting signature to editthe external interface without having to type it all in by hand.The compiler stores a compiled version of the interface as ais either obtained from compiling antype if there is only ancmi le. This interfacemli signature le for a module, or by the inferredml implementation present.ml and mli les have compatible signatures. TheThe compiler makes sure that yourtype checker throws an immediate error if this isn't the case. For example, if you havethis as yourml le:type t Fooand this as yourmli:type t Barthen, when you try to build, you'll get this error: ocamlc -c conflicting interface.mli conflicting interface.mlFile "conflicting interface.ml", line 1:Error: The implementation conflicting interface.mldoes not match the interface conflicting interface.cmi:Type declarations do not match:type t Foois not included intype t BarConstructors number 1 have different names, Foo and Bar.File "conflicting interface.mli", line 1, characters 0-12:Expected declarationFile "conflicting interface.ml", line 1, characters 0-12:Actual declaration[2]Which Comes First: The ml or the mli?There are two schools of thought on which order OCaml code should be written in. It'svery easy to begin writing code by starting with anhttps://doi.org/10.1017/9781009129220.030 Published online by Cambridge University Pressml le and using the type inference

456The Compiler Frontend: Parsing and Type Checkingto guide you as you build up your functions. Themlile can then be generated asdescribed, and the exported functions documented.If you're writing code that spans multiple les, it's sometimes easier to start bywriting all themlisignatures and checking that they type-check against one another.Once the signatures are in place, you can write the implementations with the con dencethat they'll all glue together correctly, with no cyclic dependencies among the modules.As with any such stylistic debate, you should experiment with which system worksbest for you. Everyone agrees on one thing though: no matter in what order you writethem, production code should always explicitly de ne anml le inthe project. It's also perfectly ne to have an mli le without a corresponding ml le ifmlile for everyyou're only declaring signatures (such as module types).Signature les provide a place to write succinct documentation and to abstractinternal details that shouldn't be exported. Maintaining separate signature les alsospeeds up incremental compilation in larger code bases, since recompiling amlisignature is much faster than a full compilation of the implementation to native code.26.4.2Type InferenceType inference is the process of determining the appropriate types for expressionsbased on their use. It's a feature that's partially present in many other languages suchas Haskell and Scala, but OCaml embeds it as a fundamental feature throughout thecore language.OCaml type inference is based on the Hindley-Milner algorithm, which is notablefor its ability to infer the most general type for an expression without requiring anyexplicit type annotations. The algorithm can deduce multiple types for an expressionand has the notion of aprincipal type that is the most general choice from the possibleinferences. Manual type annotations can specialize the type explicitly, but the automaticinference selects the most general type unless told otherwise.OCaml does have some language extensions that strain the limits of principal typeinference, but by and large, most programs you write will neverrequire annotations(although they sometimes help the compiler produce better error messages).Adding Type Annotations to Find ErrorsIt's often said that the hardest part of writing OCaml code is getting past the typechecker but once the code does compile, it works correctly the rst time! This is anexaggeration of course, but it can certainly feel true when moving from a dynamicallytyped language. The OCaml static type system protects you from certain classes ofbugs such as memory errors and abstraction violations by rejecting your programat compilation time rather than by generating an error at runtime. Learning how tonavigate the type checker's compile-time feedback is key to building robust librariesand applications that take full advantage of these static checks.There are a couple of tricks to make it easier to quickly locate type errors in yourcode. The rst is to introduce manual type annotations to narrow down the source ofhttps://doi.org/10.1017/9781009129220.030 Published online by Cambridge University Press

26.4 Adding Type Annotations to Find Errors457your error more accurately. These annotations shouldn't actually change your typesand can be removed once your code is correct. However, they act as anchors to locateerrors while you're still writing your code.Manual type annotations are particularly useful if you use lots of polymorphicvariants or objects. Type inference with row polymorphism can generate some verylarge signatures, and errors tend to propagate more widely than if you are using moreexplicitly typed variants or classes.For instance, consider this broken example that expresses some simple algebraicoperations over integers:let rec algebra function Add (x,y) - Sub (x,y) - Mul (x,y) - Num x- (algebra x) (algebra y)(algebra x) - (algebra y)(algebra x) * (algebra y)xlet algebra ( Add (( Num 0),( Sub (( Num 1),( Mul (( Nu 3),( Num 2)))))))There's a single character typo in the code so that it usesNuinstead ofNum.Theresulting type error is impressive: ocamlc -c broken poly.mlFile "broken poly.ml", lines 9-18, characters 10-6:9 .(10 Add (11 ( Num 0),12 ( Sub (13 ( Num 1),14 ( Mul (15 ( Nu 3),( Num 2)16 ))17 ))18 ))Error: This expression has type[ Add of([ Add of 'a * 'a Mul of 'a * 'a Num of int Sub of 'a * 'a Num ]as 'a) *[ Sub of 'a * [ Mul of [ Nu of int ] * [ Num ofint ] ]] ]https://doi.org/10.1017/9781009129220.030 Published online by Cambridge University Press

458The Compiler Frontend: Parsing and Type Checkingbut an expression was expected of type[ Add of 'a * 'a Mul of 'a * 'a Num of int Sub of'a * 'a Num ]as 'aThe second variant type does not allow tag(s) Nu[2]The type error is perfectly accurate, but rather verbose and with a line number thatdoesn't point to the exact location of the incorrect variant name. The best the compilercan do is to point you in the general direction of thealgebra function application.This is because the type checker doesn't have enough information to match theinferred type of thealgebra de nition to its application a few lines down. It calculatestypes for both expressions separately, and when they don't match up, outputs thedi erence as best it can.Let's see what happens with an explicit type annotation to help the compiler out:type t Add Sub Mul Num][ofofofoft * tt * tt * tintlet rec algebra (x:t) match x with Add (x,y) - (algebra x) (algebra y) Sub (x,y) - (algebra x) - (algebra y) Mul (x,y) - (algebra x) * (algebra y) Num x- xlet algebra ( Add (( Num 0),( Sub (( Num 1),( Mul (( Nu 3),( Num 2)))))))This code contains exactly the same error as before, but we've added a closed typede nition of the polymorphic variants, and a type annotation to thealgebra de nition.The compiler error we get is much more useful now: ocamlc -i broken poly with annot.mlFile "broken poly with annot.ml", line 22, characters 14-21:22 ( Nu 3),( Num 2) Error: This expression has type [ Nu of int ]but an expression was expected of type tThe second variant type does not allow tag(s) Nu[2]https://doi.org/10.1017/9781009129220.030 Published online by Cambridge University Press

26.4 Enforcing Principal Typing459This error points directly to the correct line number that contains the typo. Once youx the problem, you can remove the manual annotations if you prefer more succinctcode. You can also leave the annotations there, of course, to help with future refactoringand debugging.Enforcing Principal TypingThe compiler also has a stricter-principalprincipal type checking mode that is activated via theag. This warns about risky uses of type information to ensure that thetype inference has one principal result. A type is considered risky if the success orfailure of type inference depends on the order in which subexpressions are typed.The principality check only a ects a few language features: Polymorphic methods for objectsPermuting the order of labeled arguments in a function from their type de nitionDiscarding optional labeled argumentsGeneralized algebraic data types (GADTs) present from OCaml 4.0 onwardAutomatic disambiguation of record eld and constructor names (since OCaml 4.1)Here's an example of principality warnings when used with record disambiguation.type s { foo: int; bar: unit }type t { foo: int }let f x x.bar;x.fooInferring the signature with-principal will show you a new warning: ocamlc -i -principal non principal.mlFile "non principal.ml", line 6, characters 4-7:6 x.foo Warning 18 [not-principal]: this type-based field disambiguation isnot principal.type s { foo : int; bar : unit; }type t { foo : int; }val f : s - intThis example isn't principal, since the inferred type forinferred type ofx.bar,type can be calculated independently. If theofx.foois guided by thewhereas principal typing requires that each subexpression'sx.bar usef, its argument would be of type t and not type s.is removed from the de nitionYou can x this either by permuting the order of the type declarations, or by addingan explicit type annotation:type s { foo: int; bar: unit }type t { foo: int }let f (x:s) 30 Published online by Cambridge University Press

460The Compiler Frontend: Parsing and Type CheckingThere is now no ambiguity about the inferred types, since we've explicitly given theargument a type, and the order of inference of the subexpressions no longer matters. ocamlc -i -principal principal.mltype s { foo : int; bar : unit; }type t { foo : int; }val f : s - intThedune equivalent is to add the ag -principal to your build description.(executable(name principal)(flags :standard -principal)(modules principal))(executable(name non principal)(flags :standard -principal)(modules non principal))The:standard directive will include all the default ags, and then -principal willbe appended after those in the compiler build ags. dune build principal.exe dune build non principal.exeFile "non principal.ml", line 6, characters 4-7:6 x.foo Error (warning 18 [not-principal]): this type-based fielddisambiguation is not principal.[1]Ideally, all code should systematically use-principal.It reduces variance in typeinference and enforces the notion of a single known type. However, there are drawbacksto this mode: type inference is slower, and the cmi les become larger. This is generallyonly a problem if you extensively use objects, which usually have larger type signaturesto cover all their methods.If compiling in principal mode works, it is guaranteed that the program will passtype checking in non-principal mode, too. Bear in mind that thecmiles generatedin principal mode di er from the default mode. Try to ensure that you compile yourwhole project with it activated. Getting the les mixed up won't let you violate typesafety, but it can result in the type checker failing unexpectedly very occasionally. Inthis case, just recompile with a clean source tree.26.4.3Modules and Separate CompilationThe OCaml module system enables smaller components to be reused e ectively in largeprojects while still retaining all the bene ts of static type safety. We covered the basicsof using modules earlier in Chapter 5 (Files, Modules, and Programs). The modulelanguage that operates over these signatures also extends to functors and rst-classmodules, described in Chapter 11 (Functors) and Chapter 12 (First-Class 009129220.030 Published online by Cambridge University Press

26.4 De ning a Module Search Path461This section discusses how the compiler implements them in more detail. Modulesare essential for larger projects that consist of many source les (also known aspilation units).com-It's impractical to recompile every single source le when changingjust one or two les, and the module system minimizes such recompilation while stillencouraging code reuse.The Mapping Between Files and ModulesIndividual compilation units provide a convenient way to break up a big modulehierarchy into a collection of les. The relationship between les and modules can beexplained directly in terms of the module system.Create a le calledalice.ml with the following co

Stable releases as zip and tar archives from the OCaml download site 3 A Git repository with all the history and development branches included, browsable online at GitHub 4 The source tree is split up into subdirectories. The core compiler consists of: asmcomp/ Native-code compiler that converts OCaml into high perorfmance native code .