{"article":{"slug":"ml-modules-for-mere-mortals","title":"ML Modules for Mere Mortals","subtitle":null,"summary":"An approachable introduction to the ML module system: structures, signatures, and functors, and how signatures act as encapsulation boundaries that let code be reasoned about and refactored modularly.","content_type":"tutorial","language":"en","canonical_url":"https://thunderseethe.dev/posts/ml-modules-for-mere-mortals/intro/","author":{"name":"Thunderseethe","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"Thunderseethe's Devlog","url":"https://thunderseethe.dev/","listing_slug":null,"listing":null},"topics":[{"name":"programming-languages","slug":"programming-languages","url":"https://listedarticles.com/topics/programming-languages"},{"name":"programming","slug":"programming","url":"https://listedarticles.com/topics/programming"},{"name":"compilers","slug":"compilers","url":"https://listedarticles.com/topics/compilers"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":2881,"reading_minutes":13,"published_at":"2026-11-12T00:00:00.000Z","added_at":"2026-11-13T14:10:25.457Z","updated_at":"2026-11-13T14:10:25.457Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/ml-modules-for-mere-mortals","markdown_url":"https://listedarticles.com/articles/ml-modules-for-mere-mortals.md","example":false,"citation":"Thunderseethe, Thunderseethe's Devlog. \"ML Modules for Mere Mortals.\" 12 Nov 2026. https://thunderseethe.dev/posts/ml-modules-for-mere-mortals/intro/ (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://thunderseethe.dev/posts/ml-modules-for-mere-mortals/intro/"},"body_markdown":"# [ML Modules for Mere Mortals](https://thunderseethe.dev/posts/ml-modules-for-mere-mortals/intro/)\n\nNovember 12, 2026\nNovember 13, 2026\n14-minute read\n2946 words\n\n[Programming Languages](https://thunderseethe.dev/tags/programming-languages/)\n•\n[Modules](https://thunderseethe.dev/tags/modules/)\n\nI think everyone can agree code needs to be modular.\nModularity lets us reason locally about our code no matter how big it grows.\nHowever, no one seems to agree on *how* code should be modular.\nThere are a bunch of different approaches and each new language seems to bring their own spin on it.\n\nToday we’re going to talk about a pretty old spin: ML Modules.\nML here stands for Meta Language, as seen in SML and OCaml (and not machine learning).\nDespite SML first appearing in 1983, ML Modules have not caught on.\nOCaml is the sole production language you’ll find with an ML module system, and at the height of its popularity it’s niche.\n\nThis is a shame because ML modules have a lot to offer.\nWe’re going to talk about what ML modules are and then touch a little on why ML modules are.\nWho better after all to explain modules, than the guy who doesn’t know [what’s in a module](https://thunderseethe.dev/posts/whats-in-a-module/)?  \n…On second thought, don’t answer that.  \n…I already wrote the blog post.\n\nModules exist to make our code modular, duh, but what does that mean in practice?\nI think most programmers have some intuitive sense of modularity:\n\n- Bundle up related logic as one “thing”\n- Encapsulate invariants\n- Decouple from dependencies\n\nMost languages have a way to do this, and if they don’t, one gets created for them (looking at you JavaScript).\n\n## Modules Bundle Functions [Link to heading](#modules-bundle-functions)\n\nML modules achieves this with, you guessed it, the Module.\nML modules, however, are a little different from the modules we know and love.\nTo explain their differences, we’ll lean on a made-up Rust-inspired syntax.\nIt will start off looking a little weird and gradually, as we introduce concepts, end up looking really weird (but hopefully more familiar than SML syntax).\nWe’ll start by defining a module with just functions:\n\n```\nmod AModule {\n  fn add(a: i32, b: i32) -> i32 {\n    a + b\n  }\n\n  fn sub(a: i32, b: i32) -> i32 {\n    a - b\n  }\n\n  // mult, div, etc...\n}\n```\n\n`AModule` bundles together related arithmetic functions as one thing we can reason about.\nEach function can see every other function in the module.\nThis is useful, but any language with namespaces offers this.\n\n## Modules (also) Bundle Types [Link to heading](#modules-also-bundle-types)\n\nA little more unique is that ML modules will let us put not only function definitions in modules, but also type definitions:\n\n```\nmod Set {\n  type Set = Vec<i32>;\n\n  fn new() -> Set {\n    vec![]\n  }\n\n  fn index_of(this: &Set, ele: &i32) -> Result<usize, usize> {\n    this.binary_search(ele)\n  }\n\n  fn insert(this: Set, ele: i32) -> Set {\n    match index_of(&ele) {\n      Ok(_) => {} // we're done the element is already present\n      Err(indx) => {\n        this.insert(indx, ele);\n      }\n    }\n    this\n  }\n\n  fn contains(this: &Set, ele: &i32) -> bool {\n    index_of(this, ele).is_ok()\n  }\n\n  fn remove(this: Set, ele: &i32) -> Set {\n    match index_of(this, ele) {\n      Err(_) => {}, // we're done the element is already removed\n      Ok(indx) => {\n        this.remove(indx)\n      }\n    }\n    this\n  }\n}\n```\n\nHere we have a `Set` module with a `Set` type, which is a sorted `Vec<i32>`.\nOur module’s functions can refer to the type definitions much the same way they can refer to their module’s function definitions.\nOkay but that’s not that crazy, still well within the realm of Rust modules.\n\n## The Type of a Module is a Signature [Link to heading](#the-type-of-a-module-is-a-signature)\n\nNot only can modules contain type definitions.\nModules themselves have types.\nA module type is called a signature (so we don’t get it confused with “normal” types).\nThe signature of our `Set` module is:\n\n```\nsig FullSetSig {\n  type Set = Vec<i32>;\n\n  fn new() -> Set;\n  fn index_of(&Set, &i32) -> Result<usize, usize>;\n  fn insert(Set, i32) -> Set;\n  fn contains(&Set, &i32) -> bool;\n  fn remove(&Set, &i32) -> Set\n}\n```\n\nA module signature declares every definition of a module alongside its type.\nThis might look similar to the way we define a trait in Rust.\nThat’s because much like traits act as interfaces in Rust, signatures act as interfaces in ML Modules.\nModules having signatures is the single most important thing to understand about ML Modules.\nAll the complexity and expressiveness of modules results from them having signatures and the wonderful wacky things that enables.\n\n# Signatures Support Encapsulation [Link to heading](#signatures-support-encapsulation)\n\nSignatures resemble the way a C/C++ implementation file conforms to its header.\nModules, unlike `.cc` files, aren’t in a 1:1 relationship with signatures.\nOur `Set` module can conform to *any* signature that it matches.\nA module matches a signature when it defines every declaration in the signature and they agree on type.\n\nMatching a signature provides [Encapsulation](https://en.wikipedia.org/wiki/Encapsulation_%28computer_programming%29), hiding internal details of our module from our public API.\nTake a look at `FullSetSig`.\nDo callers of `Set` really need to know about `index_of`?\nEncapsulation advocates shout a resounding no: `index_of` is an implementation detail of `Set.Set` being a `Vec<i32>` and not integral to our `Set` API.\n\nWe can encapsulate `index_of` by matching our `Set` module to a new signature:\n\n```\nsig SetSig {\n  type Set = Vec<i32>;\n\n  fn new() -> Set;\n  // index_of is missing.\n  fn insert(Set, i32) -> Set;\n  fn contains(&Set, &i32) -> bool;\n  fn remove(&Set, &i32) -> Set\n}\n```\n\n`SetSig` removes `index_of`, hiding the implementation detail.\nWe can then ascribe our signature to our `Set` module:\n\n```\nmod Set : SetSig {\n    // Our module implementation stays unchanged...\n}\n```\n\nNow the rest of our code sees `Set` as `SetSig` without `index_of`.\nImportantly, our `Set` module hasn’t changed.\n`index_of` is still available inside the module.\nAscribing the signature only changes the public view of the module, similar to a private function in Rust.\n\nA module’s definition isn’t the only place we can ascribe a signature.\nWe can also make a “new” module by matching an old module to a new signature.\nLet’s say we want an `InsertOnlySet` (never you mind why I need that):\n\n```\nsig InsertOnlySetSig {\n  type Set = Vec<i32>;\n\n  fn new() -> Set;\n  fn insert(Set, i32) -> Set;\n}\n```\n\nWe can create that from our `Set` module purely by matching the signature:\n\n```\nmod InsertOnlySet: InsertOnlySetSig = Set;\n```\n\nNow `InsertOnlySet` is effectively a whole new module, despite the underlying implementation being shared with `Set`.\nThis is what’s cool about modules.\nWe can repurpose modules “for free” simply by giving them a different signature.\nIf we want to do this in an OO language, we’d have to add a new interface in our class definitiion.\nBut we can slap one of these bad boys anywhere in our codebase.\n\n## Sealed Types Seal Encapsulation [Link to heading](#sealed-types-seal-encapsulation)\n\nAscribing a signature to a module lets us hide implementation details, but there’s a bit of a glaring hole here.\nSure we’ve hidden away `index_of`, but our module broadcasts to the world that `type Set` is a `Vec<i32>`!\nSet relies on our vector being kept in sorted order, but anybody is free to write a function:\n\n```\nfn whoops() {\n    let mut set = Set::new();\n    // teehee\n    set.extend([3, 2, 1]);\n    // 💥\n    let uh_oh = Set::insert(set, 1);\n    // Now our set is [1, 3, 2, 1]\n}\n```\n\nNothing but a small flesh wound in our encapsulation.\nFortunately, ML modules foresaw this problem and provided a solution using signatures.\n\nMuch the same way a signature lets us hide functions, it also lets us hide types.\nML Modules call this an abstract type.\nIf we update `SetSig` to be:\n\n```\nsig SetSig {\n  type Set;\n\n  fn new() -> Set;\n  fn insert(Set, i32) -> Set;\n  fn contains(&Set, &i32) -> bool;\n  fn remove(&Set, &i32) -> Set\n}\n```\n\nOur signature no longer broadcasts that `type Set` is `Vec<i32>`.\nWithin the `Set` module we’re free to use `type Set` as `Vec<i32>`, but everywhere outside the module `type Set` is now some unknown type.\nBecause callers know nothing about our newly abstract `Set` type, all they can do is pass it to and from the methods provided by the `Set` module.\nAs long as we keep our underlying `Vec<i32>` sorted within `Set`, we know no one else is able to mess with it.\nThey simply don’t know enough about the type!\n\n## Module’s Version of Generics [Link to heading](#modules-version-of-generics)\n\nOur Set module is nearing perfection, but it still leaves a little to be desired: it only works for `i32`.\nNow we could of course write a new module `SetU64`, `SetString`, on and on everytime we need one, but c’mon there’s gotta be a better way.\nThis isn’t Go.\n\nGenerics is the go-to solution for this problem.\nHeck we’ve even used it ourselves with `Vec<i32>`.\nML Modules, however, have a more *modular* solution.\nYou can parameterize a module by another a module.\n\nInfo\n\nParameterized modules are sometimes called functors, but that name is confusing and you can’t make me use it.\n\nThink of a parameterized module as a function that takes a module and returns another module.\nTo make our `Set` accept any type and not just `i32`, we parameterize it by a module that provides the type of our Set’s elements:\n\n```\nmod Set: SetSig (sig Elem {\n  type T\n}) {\n  type Set = Vec<Elem.T>;\n\n  fn new() -> Set {\n    vec![]\n  }\n\n  fn index_of(this: &Set, ele: &Elem.T) -> Result<usize, usize> {\n    // ...\n  }\n\n  fn insert(this: Set, ele: &Elem.T) -> Set {\n    // ...\n  }\n\n  fn contains(this: &Set, ele: &Elem.T) -> bool {\n    index_of(this, ele).is_ok()\n  }\n\n  fn remove(this: Set, ele: &Elem.T) -> Set {\n    // ...\n  }\n}\n```\n\nOur newly parameterized `Set` accepts any module that conforms to `Elem`.\nAny module can match `Elem` as long as it has at least a `T` definition.\n\n## A Teensy Problem [Link to heading](#a-teensy-problem)\n\nWith that our `Set` module supports any type.\nExcept for one teensy detail.\nI’ve deceived you with some tactical `// ...`s.\nIf we actually try to implement `index_of`, we quickly encounter a problem:\n\n```\nfn index_of(this: &Set, ele: &Elem.T) -> Result<usize, usize> {\n  this.binary_search_by(|a| ele ??? a)\n}\n```\n\nWe don’t know how to compare `T`’s.\nRust’s `Ord` would solve this, of course, but ML modules have modules not traits.\n`Set` doesn’t take in just a type, however, it takes in a full module.\nIf we need to know how to compare `T`’s, we can just ask our `Elem` module:\n\n```\nmod Set: SetSig (sig Elem {\n  type T;\n  fn cmp(&T, &T) -> Ordering;\n}) {\n  // ...\n}\n```\n\nNow it’s clear how to implement `index_of`:\n\n```\nfn index_of(this: &Set, ele: &Elem.T) -> Result<usize, usize> {\n  this.binary_search_by(|a| Elem::cmp(ele, a))\n}\n```\n\nWith our parameterized module implemented, we can create new `Set` modules by applying them to new argument modules:\n\n```\nmod SetU32 = Set(mod U32 {\n  type T = u32;\n  fn cmp(a: &T, b: &T) { a < b }\n});\n```\n\n`SetU32.Set` is a `Vec<u32>` and provides an interface that takes and returns `u32` instead of `i32`.\nWe can do it again as easy as:\n\n```\nmod SetString = Set(mod String {\n  type T = String;\n  fn cmp(a: &T, b: &T) { /* lexographic ordering probably... */ }\n});\n```\n\nJust like that, a whole new module.\nThis time a set of Strings.\nI could do this all day.\n\nBecause we accept a module, we can request anything a module can hold (even a whole other submodule or parameterized module!).\nThe downside is that we have to specify the whole module every time.\nWe *have* to specify `cmp` every time we apply our `Set` module.\nRust traits let us write `Ord` for a type once and use it everywhere implicitly.\n\n## Include Keeps Modules Small [Link to heading](#include-keeps-modules-small)\n\nIn practice, we don’t actually repeat how to order our type every time we want a `Set`.\nRecall that a signature will match *any* module that provides what it needs.\nIf we make a big module called `U64`:\n\n```\nmod U64 {\n  type T = u64;\n\n  fn cmp(a: &u64, b: &u64) { a < b }\n\n  fn add(a: u64, b: u64) -> u64 { a + b }\n  fn sub(a: u64, b: u64) -> u64 { a - b }\n  // ...\n}\n```\n\nThen we can use that as our argument to Set:\n\n```\nmod SetU64 = Set(U64);\n```\n\nBut hang on, we got into this whole Module business to break up our code.\nNow we’ve got to dump everything into one module just in case we need it later?\nThat’s not very cash modular of us.\n\nML modules have a final feature to get us the best of both worlds: `include`.\n`include` expands a module inline within another module.\nWe’re free to split up our `U64` module into various submodules: `U64Order`, `U64Arithmetic`, etc.\nOur final `U64` module only has to include these submodules:\n\n```\nmod U64 {\n  type T = u64;\n\n  include U64Order;\n  include U64Arithmetic;\n  // ...\n}\n```\n\nModules can be organized into logical components and then combined later to provide convenience (wow!).\nWe’re free to cut up and reassemble modules at the whims’ of the wind.\nWe can even apply a module and include it inline:\n\n```\nmod ABunchOfSetForSomeReason {\n  mod SetU64 = Set(U64);\n  include SetU64;\n\n  mod SetString = Set(String);\n  include SetString;\n}\n```\n\nWhy do you need one module that’s a bunch of overlapping Sets?\nI don’t know!\nI’m not your supervisor.\nEither way, modules will happily let you do it.\n\n## Putting It All Together [Link to heading](#putting-it-all-together)\n\nWe’ve covered the basics of modules.\nLet’s take a look at a more involved examples to get a sense of what modules can offer.\nWe’re gonna use modules to assemble a little build executor.\nOut build step will be a parameterized module:\n\n```\nmod BuildStep(sig Env {\n  mod Cache: CacheSig;\n  mod Runner: RunnerSig;\n}) {\n  // ...\n}\n```\n\nWhere `CacheSig` represents a cache of build steps and `RunnerSig` represents running some command:\n\n```\nsig CacheSig {\n  fn is_cached(inputs: &[String], output: &Path) -> bool;\n  fn store(inputes: &[String], output: &Path);\n}\n\nsig RunnerSig {\n  fn run(inputs: &[String], output: &Path);\n}\n```\n\nFor brevity we’ll keep these pretty simple, but hopefully you can imagine how these might expand.\nWe can then implement `BuildSet` in terms of our input modules:\n\n```\nmod BuildSet(...) {\n  fn run_cached(inputs: &[String], output: &Path) {\n    if !Env::Cache::is_cached(inputs, output) {\n      Env::Runner::run(inputs, output);\n      Env::Cache::store(inputs, output);\n    }\n  }\n\n  fn compile(src: String) -> String {\n    let obj = PathBuf::from(format!(\"{src}.o\"));\n    run_cached(&[src], &obj);\n    obj.display().to_string()\n  }\n\n  fn build(srcs: &[String], output: &Path) {\n    let objs: Vec<String> = srcs.iter().map(compile).collect();\n    run_cached(objs, output)\n  }\n}\n```\n\nOur `build` functions takes a list of source files, compiles them, and then links the object files into a final binary.\nHow does `run` tell when it’s compiling and when it’s linking?\nDon’t worry about it!\nNow that we’ve set that up we can toggle the functionality of our build by controlling what modules we pass to `BuildStep`.\nFor a real build, we’ll want something like an in-memory cache:\n\n```\nmod MemCache {\n  // Pretend this works without locking for multithreading\n  static ENTRIES: Vec<(Vec<String>, PathBuf)> = vec![];\n\n  fn is_cached(inputs: &[String], output: &Path) {\n    ENTRIES.iter().any(|(cached_inputs, cached_outputs)| {\n      inputs == cached_inputs && output == cached_outputs\n    })\n  }\n\n  fn store(inputs: &[String], output: &Path) {\n    ENTRIES.push((inputs.to_vec(), PathBuf::from(output)))\n  }\n}\n```\n\nNext we’ll want something that runs our commands:\n\n```\nmod ShellRunner {\n  fn run(inputs: &[String], output: &Path) {\n    let cmd = // magically pick between `cc` and `lld`;\n    let output = format!(\"-o {}\", output.display());\n    Command::new(cmd)\n      .args(inputs)\n      .args(output)\n      .output()\n      .expect(\"All our commands work first try\");\n  }\n}\n```\n\nWe can then assemble our build system via:\n\n```\nmod CachedBuild = BuildStep(mod Env {\n  mod Cache = MemCache;\n  mod Runner = ShellRunner;\n});\n```\n\nBut maybe we don’t always want caching.\nMaybe we want a build that always reruns actions for local testing.\nWe simply swap out our cache module:\n\n```\nmod NoCache {\n  fn is_cached(inputs: &[String], outputs: &Path) -> bool {\n    false\n  }\n\n  fn store(inputs: &[String], outputs: &Path) {\n    // nothing to do here\n  }\n}\n\nmod LocalBuild = BuildStep(mod Env {\n  mod Cache = NoCache;\n  mod Runner = ShellRunner;\n});\n```\n\nOur build system works first try.\nWe wouldn’t write the code bad, of course, but just in case we might want to test it.\nA `FakeRunner` will let us do just that:\n\n```\nmod FakeRunner() {\n  static COMMANDS: Vec<(Vec<String>, PathBuf)> = vec![];\n\n  fn run(inputs: &[String], output: &Path) {\n    COMMANDS.push((inputs.to_vec(), PathBuf::from(output)));\n  }\n\n  // A test only helper.\n  fn contains_command(inputs: &[String], output: &Path) -> bool {\n    // ...\n  }\n}\n```\n\nBecause `FakeRunner` is a parameterize module, we can create a new module (and a new empty `COMMANDS`) every time we apply it:\n\n```\nmod Tests {\n  mod TestRunner = FakeRunner();\n  mod TestBuild = BuildStep(mod Env {\n    mod Cache = MemCache;\n    mod Runner = TestRunner\n  });\n\n  // Write tests against TestBuild using `TestRunner::contains_command`...\n}\n```\n\nIf we want to check that caching works we can extend our tests with a new fake runner and compare their commands:\n\n```\nmod Tests {\n  // TestBuild setup...\n\n  mod UncachedTestRunner = FakeRunner();\n  mod UncachedTestBuild = BuildStep(mod Env {\n    mod Cache = NoCache;\n    mod Runner = UncachedTestRunner;\n  })\n\n  // Compare the results of `TestRunner::contains_command` and `UncachedTestRunner::contains_command`...\n}\n```\n\nThis isn’t earth shattering stuff.\nIf we wanted to replicate this setup in an OO language, however, we would need runtime objects or, heaven forbid, a DI framework.\nHere we can do it all by wiring up modules statically.\n\nHopefully this has helped you see what’s cool about modules.\nModule’s power lies in their signatures.\nWhat would require a newtype wrapper or a visibility change in other languages can be accomplished by simply changing the signature a module is viewed at.\n\nWith abstract types, this allows for constructing webs of encapsulation where each piece knows precisely what it needs to about its neighbor and no more.\nSignatures act as this encapsulation boundary, freeing us to reason about our code modularly.\nAs long as our module conforms to the expected signature we can contort and refactor it to our wildest whims and trust that it will continue to integrate into our system as expected.\nML Modules are neat and I think they deserve more love and exploration in programming languages.\n","body_html":"<h1 id=\"ml-modules-for-mere-mortals\"><a href=\"https://thunderseethe.dev/posts/ml-modules-for-mere-mortals/intro/\" rel=\"nofollow ugc noopener\">ML Modules for Mere Mortals</a></h1>\n<p>November 12, 2026\nNovember 13, 2026\n14-minute read\n2946 words</p>\n<p><a href=\"https://thunderseethe.dev/tags/programming-languages/\" rel=\"nofollow ugc noopener\">Programming Languages</a>\n•\n<a href=\"https://thunderseethe.dev/tags/modules/\" rel=\"nofollow ugc noopener\">Modules</a></p>\n<p>I think everyone can agree code needs to be modular.\nModularity lets us reason locally about our code no matter how big it grows.\nHowever, no one seems to agree on <em>how</em> code should be modular.\nThere are a bunch of different approaches and each new language seems to bring their own spin on it.</p>\n<p>Today we’re going to talk about a pretty old spin: ML Modules.\nML here stands for Meta Language, as seen in SML and OCaml (and not machine learning).\nDespite SML first appearing in 1983, ML Modules have not caught on.\nOCaml is the sole production language you’ll find with an ML module system, and at the height of its popularity it’s niche.</p>\n<p>This is a shame because ML modules have a lot to offer.\nWe’re going to talk about what ML modules are and then touch a little on why ML modules are.\nWho better after all to explain modules, than the guy who doesn’t know <a href=\"https://thunderseethe.dev/posts/whats-in-a-module/\" rel=\"nofollow ugc noopener\">what’s in a module</a>?<br />\n…On second thought, don’t answer that.<br />\n…I already wrote the blog post.</p>\n<p>Modules exist to make our code modular, duh, but what does that mean in practice?\nI think most programmers have some intuitive sense of modularity:</p>\n<ul><li>Bundle up related logic as one “thing”</li><li>Encapsulate invariants</li><li>Decouple from dependencies</li></ul>\n<p>Most languages have a way to do this, and if they don’t, one gets created for them (looking at you JavaScript).</p>\n<h2 id=\"modules-bundle-functions-link-to-heading\">Modules Bundle Functions <a href=\"#modules-bundle-functions\">Link to heading</a></h2>\n<p>ML modules achieves this with, you guessed it, the Module.\nML modules, however, are a little different from the modules we know and love.\nTo explain their differences, we’ll lean on a made-up Rust-inspired syntax.\nIt will start off looking a little weird and gradually, as we introduce concepts, end up looking really weird (but hopefully more familiar than SML syntax).\nWe’ll start by defining a module with just functions:</p>\n<pre><code>mod AModule {\n  fn add(a: i32, b: i32) -&gt; i32 {\n    a + b\n  }\n\n  fn sub(a: i32, b: i32) -&gt; i32 {\n    a - b\n  }\n\n  // mult, div, etc...\n}</code></pre>\n<p><code>AModule</code> bundles together related arithmetic functions as one thing we can reason about.\nEach function can see every other function in the module.\nThis is useful, but any language with namespaces offers this.</p>\n<h2 id=\"modules-also-bundle-types-link-to-heading\">Modules (also) Bundle Types <a href=\"#modules-also-bundle-types\">Link to heading</a></h2>\n<p>A little more unique is that ML modules will let us put not only function definitions in modules, but also type definitions:</p>\n<pre><code>mod Set {\n  type Set = Vec&lt;i32&gt;;\n\n  fn new() -&gt; Set {\n    vec![]\n  }\n\n  fn index_of(this: &amp;Set, ele: &amp;i32) -&gt; Result&lt;usize, usize&gt; {\n    this.binary_search(ele)\n  }\n\n  fn insert(this: Set, ele: i32) -&gt; Set {\n    match index_of(&amp;ele) {\n      Ok(_) =&gt; {} // we&#39;re done the element is already present\n      Err(indx) =&gt; {\n        this.insert(indx, ele);\n      }\n    }\n    this\n  }\n\n  fn contains(this: &amp;Set, ele: &amp;i32) -&gt; bool {\n    index_of(this, ele).is_ok()\n  }\n\n  fn remove(this: Set, ele: &amp;i32) -&gt; Set {\n    match index_of(this, ele) {\n      Err(_) =&gt; {}, // we&#39;re done the element is already removed\n      Ok(indx) =&gt; {\n        this.remove(indx)\n      }\n    }\n    this\n  }\n}</code></pre>\n<p>Here we have a <code>Set</code> module with a <code>Set</code> type, which is a sorted <code>Vec&lt;i32&gt;</code>.\nOur module’s functions can refer to the type definitions much the same way they can refer to their module’s function definitions.\nOkay but that’s not that crazy, still well within the realm of Rust modules.</p>\n<h2 id=\"the-type-of-a-module-is-a-signature-link-to-heading\">The Type of a Module is a Signature <a href=\"#the-type-of-a-module-is-a-signature\">Link to heading</a></h2>\n<p>Not only can modules contain type definitions.\nModules themselves have types.\nA module type is called a signature (so we don’t get it confused with “normal” types).\nThe signature of our <code>Set</code> module is:</p>\n<pre><code>sig FullSetSig {\n  type Set = Vec&lt;i32&gt;;\n\n  fn new() -&gt; Set;\n  fn index_of(&amp;Set, &amp;i32) -&gt; Result&lt;usize, usize&gt;;\n  fn insert(Set, i32) -&gt; Set;\n  fn contains(&amp;Set, &amp;i32) -&gt; bool;\n  fn remove(&amp;Set, &amp;i32) -&gt; Set\n}</code></pre>\n<p>A module signature declares every definition of a module alongside its type.\nThis might look similar to the way we define a trait in Rust.\nThat’s because much like traits act as interfaces in Rust, signatures act as interfaces in ML Modules.\nModules having signatures is the single most important thing to understand about ML Modules.\nAll the complexity and expressiveness of modules results from them having signatures and the wonderful wacky things that enables.</p>\n<h1 id=\"signatures-support-encapsulation-link-to-heading\">Signatures Support Encapsulation <a href=\"#signatures-support-encapsulation\">Link to heading</a></h1>\n<p>Signatures resemble the way a C/C++ implementation file conforms to its header.\nModules, unlike <code>.cc</code> files, aren’t in a 1:1 relationship with signatures.\nOur <code>Set</code> module can conform to <em>any</em> signature that it matches.\nA module matches a signature when it defines every declaration in the signature and they agree on type.</p>\n<p>Matching a signature provides <a href=\"https://en.wikipedia.org/wiki/Encapsulation_%28computer_programming%29\" rel=\"nofollow ugc noopener\">Encapsulation</a>, hiding internal details of our module from our public API.\nTake a look at <code>FullSetSig</code>.\nDo callers of <code>Set</code> really need to know about <code>index_of</code>?\nEncapsulation advocates shout a resounding no: <code>index_of</code> is an implementation detail of <code>Set.Set</code> being a <code>Vec&lt;i32&gt;</code> and not integral to our <code>Set</code> API.</p>\n<p>We can encapsulate <code>index_of</code> by matching our <code>Set</code> module to a new signature:</p>\n<pre><code>sig SetSig {\n  type Set = Vec&lt;i32&gt;;\n\n  fn new() -&gt; Set;\n  // index_of is missing.\n  fn insert(Set, i32) -&gt; Set;\n  fn contains(&amp;Set, &amp;i32) -&gt; bool;\n  fn remove(&amp;Set, &amp;i32) -&gt; Set\n}</code></pre>\n<p><code>SetSig</code> removes <code>index_of</code>, hiding the implementation detail.\nWe can then ascribe our signature to our <code>Set</code> module:</p>\n<pre><code>mod Set : SetSig {\n    // Our module implementation stays unchanged...\n}</code></pre>\n<p>Now the rest of our code sees <code>Set</code> as <code>SetSig</code> without <code>index_of</code>.\nImportantly, our <code>Set</code> module hasn’t changed.\n<code>index_of</code> is still available inside the module.\nAscribing the signature only changes the public view of the module, similar to a private function in Rust.</p>\n<p>A module’s definition isn’t the only place we can ascribe a signature.\nWe can also make a “new” module by matching an old module to a new signature.\nLet’s say we want an <code>InsertOnlySet</code> (never you mind why I need that):</p>\n<pre><code>sig InsertOnlySetSig {\n  type Set = Vec&lt;i32&gt;;\n\n  fn new() -&gt; Set;\n  fn insert(Set, i32) -&gt; Set;\n}</code></pre>\n<p>We can create that from our <code>Set</code> module purely by matching the signature:</p>\n<pre><code>mod InsertOnlySet: InsertOnlySetSig = Set;</code></pre>\n<p>Now <code>InsertOnlySet</code> is effectively a whole new module, despite the underlying implementation being shared with <code>Set</code>.\nThis is what’s cool about modules.\nWe can repurpose modules “for free” simply by giving them a different signature.\nIf we want to do this in an OO language, we’d have to add a new interface in our class definitiion.\nBut we can slap one of these bad boys anywhere in our codebase.</p>\n<h2 id=\"sealed-types-seal-encapsulation-link-to-heading\">Sealed Types Seal Encapsulation <a href=\"#sealed-types-seal-encapsulation\">Link to heading</a></h2>\n<p>Ascribing a signature to a module lets us hide implementation details, but there’s a bit of a glaring hole here.\nSure we’ve hidden away <code>index_of</code>, but our module broadcasts to the world that <code>type Set</code> is a <code>Vec&lt;i32&gt;</code>!\nSet relies on our vector being kept in sorted order, but anybody is free to write a function:</p>\n<pre><code>fn whoops() {\n    let mut set = Set::new();\n    // teehee\n    set.extend([3, 2, 1]);\n    // 💥\n    let uh_oh = Set::insert(set, 1);\n    // Now our set is [1, 3, 2, 1]\n}</code></pre>\n<p>Nothing but a small flesh wound in our encapsulation.\nFortunately, ML modules foresaw this problem and provided a solution using signatures.</p>\n<p>Much the same way a signature lets us hide functions, it also lets us hide types.\nML Modules call this an abstract type.\nIf we update <code>SetSig</code> to be:</p>\n<pre><code>sig SetSig {\n  type Set;\n\n  fn new() -&gt; Set;\n  fn insert(Set, i32) -&gt; Set;\n  fn contains(&amp;Set, &amp;i32) -&gt; bool;\n  fn remove(&amp;Set, &amp;i32) -&gt; Set\n}</code></pre>\n<p>Our signature no longer broadcasts that <code>type Set</code> is <code>Vec&lt;i32&gt;</code>.\nWithin the <code>Set</code> module we’re free to use <code>type Set</code> as <code>Vec&lt;i32&gt;</code>, but everywhere outside the module <code>type Set</code> is now some unknown type.\nBecause callers know nothing about our newly abstract <code>Set</code> type, all they can do is pass it to and from the methods provided by the <code>Set</code> module.\nAs long as we keep our underlying <code>Vec&lt;i32&gt;</code> sorted within <code>Set</code>, we know no one else is able to mess with it.\nThey simply don’t know enough about the type!</p>\n<h2 id=\"module-s-version-of-generics-link-to-heading\">Module’s Version of Generics <a href=\"#modules-version-of-generics\">Link to heading</a></h2>\n<p>Our Set module is nearing perfection, but it still leaves a little to be desired: it only works for <code>i32</code>.\nNow we could of course write a new module <code>SetU64</code>, <code>SetString</code>, on and on everytime we need one, but c’mon there’s gotta be a better way.\nThis isn’t Go.</p>\n<p>Generics is the go-to solution for this problem.\nHeck we’ve even used it ourselves with <code>Vec&lt;i32&gt;</code>.\nML Modules, however, have a more <em>modular</em> solution.\nYou can parameterize a module by another a module.</p>\n<p>Info</p>\n<p>Parameterized modules are sometimes called functors, but that name is confusing and you can’t make me use it.</p>\n<p>Think of a parameterized module as a function that takes a module and returns another module.\nTo make our <code>Set</code> accept any type and not just <code>i32</code>, we parameterize it by a module that provides the type of our Set’s elements:</p>\n<pre><code>mod Set: SetSig (sig Elem {\n  type T\n}) {\n  type Set = Vec&lt;Elem.T&gt;;\n\n  fn new() -&gt; Set {\n    vec![]\n  }\n\n  fn index_of(this: &amp;Set, ele: &amp;Elem.T) -&gt; Result&lt;usize, usize&gt; {\n    // ...\n  }\n\n  fn insert(this: Set, ele: &amp;Elem.T) -&gt; Set {\n    // ...\n  }\n\n  fn contains(this: &amp;Set, ele: &amp;Elem.T) -&gt; bool {\n    index_of(this, ele).is_ok()\n  }\n\n  fn remove(this: Set, ele: &amp;Elem.T) -&gt; Set {\n    // ...\n  }\n}</code></pre>\n<p>Our newly parameterized <code>Set</code> accepts any module that conforms to <code>Elem</code>.\nAny module can match <code>Elem</code> as long as it has at least a <code>T</code> definition.</p>\n<h2 id=\"a-teensy-problem-link-to-heading\">A Teensy Problem <a href=\"#a-teensy-problem\">Link to heading</a></h2>\n<p>With that our <code>Set</code> module supports any type.\nExcept for one teensy detail.\nI’ve deceived you with some tactical <code>// ...</code>s.\nIf we actually try to implement <code>index_of</code>, we quickly encounter a problem:</p>\n<pre><code>fn index_of(this: &amp;Set, ele: &amp;Elem.T) -&gt; Result&lt;usize, usize&gt; {\n  this.binary_search_by(|a| ele ??? a)\n}</code></pre>\n<p>We don’t know how to compare <code>T</code>’s.\nRust’s <code>Ord</code> would solve this, of course, but ML modules have modules not traits.\n<code>Set</code> doesn’t take in just a type, however, it takes in a full module.\nIf we need to know how to compare <code>T</code>’s, we can just ask our <code>Elem</code> module:</p>\n<pre><code>mod Set: SetSig (sig Elem {\n  type T;\n  fn cmp(&amp;T, &amp;T) -&gt; Ordering;\n}) {\n  // ...\n}</code></pre>\n<p>Now it’s clear how to implement <code>index_of</code>:</p>\n<pre><code>fn index_of(this: &amp;Set, ele: &amp;Elem.T) -&gt; Result&lt;usize, usize&gt; {\n  this.binary_search_by(|a| Elem::cmp(ele, a))\n}</code></pre>\n<p>With our parameterized module implemented, we can create new <code>Set</code> modules by applying them to new argument modules:</p>\n<pre><code>mod SetU32 = Set(mod U32 {\n  type T = u32;\n  fn cmp(a: &amp;T, b: &amp;T) { a &lt; b }\n});</code></pre>\n<p><code>SetU32.Set</code> is a <code>Vec&lt;u32&gt;</code> and provides an interface that takes and returns <code>u32</code> instead of <code>i32</code>.\nWe can do it again as easy as:</p>\n<pre><code>mod SetString = Set(mod String {\n  type T = String;\n  fn cmp(a: &amp;T, b: &amp;T) { /* lexographic ordering probably... */ }\n});</code></pre>\n<p>Just like that, a whole new module.\nThis time a set of Strings.\nI could do this all day.</p>\n<p>Because we accept a module, we can request anything a module can hold (even a whole other submodule or parameterized module!).\nThe downside is that we have to specify the whole module every time.\nWe <em>have</em> to specify <code>cmp</code> every time we apply our <code>Set</code> module.\nRust traits let us write <code>Ord</code> for a type once and use it everywhere implicitly.</p>\n<h2 id=\"include-keeps-modules-small-link-to-heading\">Include Keeps Modules Small <a href=\"#include-keeps-modules-small\">Link to heading</a></h2>\n<p>In practice, we don’t actually repeat how to order our type every time we want a <code>Set</code>.\nRecall that a signature will match <em>any</em> module that provides what it needs.\nIf we make a big module called <code>U64</code>:</p>\n<pre><code>mod U64 {\n  type T = u64;\n\n  fn cmp(a: &amp;u64, b: &amp;u64) { a &lt; b }\n\n  fn add(a: u64, b: u64) -&gt; u64 { a + b }\n  fn sub(a: u64, b: u64) -&gt; u64 { a - b }\n  // ...\n}</code></pre>\n<p>Then we can use that as our argument to Set:</p>\n<pre><code>mod SetU64 = Set(U64);</code></pre>\n<p>But hang on, we got into this whole Module business to break up our code.\nNow we’ve got to dump everything into one module just in case we need it later?\nThat’s not very cash modular of us.</p>\n<p>ML modules have a final feature to get us the best of both worlds: <code>include</code>.\n<code>include</code> expands a module inline within another module.\nWe’re free to split up our <code>U64</code> module into various submodules: <code>U64Order</code>, <code>U64Arithmetic</code>, etc.\nOur final <code>U64</code> module only has to include these submodules:</p>\n<pre><code>mod U64 {\n  type T = u64;\n\n  include U64Order;\n  include U64Arithmetic;\n  // ...\n}</code></pre>\n<p>Modules can be organized into logical components and then combined later to provide convenience (wow!).\nWe’re free to cut up and reassemble modules at the whims’ of the wind.\nWe can even apply a module and include it inline:</p>\n<pre><code>mod ABunchOfSetForSomeReason {\n  mod SetU64 = Set(U64);\n  include SetU64;\n\n  mod SetString = Set(String);\n  include SetString;\n}</code></pre>\n<p>Why do you need one module that’s a bunch of overlapping Sets?\nI don’t know!\nI’m not your supervisor.\nEither way, modules will happily let you do it.</p>\n<h2 id=\"putting-it-all-together-link-to-heading\">Putting It All Together <a href=\"#putting-it-all-together\">Link to heading</a></h2>\n<p>We’ve covered the basics of modules.\nLet’s take a look at a more involved examples to get a sense of what modules can offer.\nWe’re gonna use modules to assemble a little build executor.\nOut build step will be a parameterized module:</p>\n<pre><code>mod BuildStep(sig Env {\n  mod Cache: CacheSig;\n  mod Runner: RunnerSig;\n}) {\n  // ...\n}</code></pre>\n<p>Where <code>CacheSig</code> represents a cache of build steps and <code>RunnerSig</code> represents running some command:</p>\n<pre><code>sig CacheSig {\n  fn is_cached(inputs: &amp;[String], output: &amp;Path) -&gt; bool;\n  fn store(inputes: &amp;[String], output: &amp;Path);\n}\n\nsig RunnerSig {\n  fn run(inputs: &amp;[String], output: &amp;Path);\n}</code></pre>\n<p>For brevity we’ll keep these pretty simple, but hopefully you can imagine how these might expand.\nWe can then implement <code>BuildSet</code> in terms of our input modules:</p>\n<pre><code>mod BuildSet(...) {\n  fn run_cached(inputs: &amp;[String], output: &amp;Path) {\n    if !Env::Cache::is_cached(inputs, output) {\n      Env::Runner::run(inputs, output);\n      Env::Cache::store(inputs, output);\n    }\n  }\n\n  fn compile(src: String) -&gt; String {\n    let obj = PathBuf::from(format!(&quot;{src}.o&quot;));\n    run_cached(&amp;[src], &amp;obj);\n    obj.display().to_string()\n  }\n\n  fn build(srcs: &amp;[String], output: &amp;Path) {\n    let objs: Vec&lt;String&gt; = srcs.iter().map(compile).collect();\n    run_cached(objs, output)\n  }\n}</code></pre>\n<p>Our <code>build</code> functions takes a list of source files, compiles them, and then links the object files into a final binary.\nHow does <code>run</code> tell when it’s compiling and when it’s linking?\nDon’t worry about it!\nNow that we’ve set that up we can toggle the functionality of our build by controlling what modules we pass to <code>BuildStep</code>.\nFor a real build, we’ll want something like an in-memory cache:</p>\n<pre><code>mod MemCache {\n  // Pretend this works without locking for multithreading\n  static ENTRIES: Vec&lt;(Vec&lt;String&gt;, PathBuf)&gt; = vec![];\n\n  fn is_cached(inputs: &amp;[String], output: &amp;Path) {\n    ENTRIES.iter().any(|(cached_inputs, cached_outputs)| {\n      inputs == cached_inputs &amp;&amp; output == cached_outputs\n    })\n  }\n\n  fn store(inputs: &amp;[String], output: &amp;Path) {\n    ENTRIES.push((inputs.to_vec(), PathBuf::from(output)))\n  }\n}</code></pre>\n<p>Next we’ll want something that runs our commands:</p>\n<pre><code>mod ShellRunner {\n  fn run(inputs: &amp;[String], output: &amp;Path) {\n    let cmd = // magically pick between `cc` and `lld`;\n    let output = format!(&quot;-o {}&quot;, output.display());\n    Command::new(cmd)\n      .args(inputs)\n      .args(output)\n      .output()\n      .expect(&quot;All our commands work first try&quot;);\n  }\n}</code></pre>\n<p>We can then assemble our build system via:</p>\n<pre><code>mod CachedBuild = BuildStep(mod Env {\n  mod Cache = MemCache;\n  mod Runner = ShellRunner;\n});</code></pre>\n<p>But maybe we don’t always want caching.\nMaybe we want a build that always reruns actions for local testing.\nWe simply swap out our cache module:</p>\n<pre><code>mod NoCache {\n  fn is_cached(inputs: &amp;[String], outputs: &amp;Path) -&gt; bool {\n    false\n  }\n\n  fn store(inputs: &amp;[String], outputs: &amp;Path) {\n    // nothing to do here\n  }\n}\n\nmod LocalBuild = BuildStep(mod Env {\n  mod Cache = NoCache;\n  mod Runner = ShellRunner;\n});</code></pre>\n<p>Our build system works first try.\nWe wouldn’t write the code bad, of course, but just in case we might want to test it.\nA <code>FakeRunner</code> will let us do just that:</p>\n<pre><code>mod FakeRunner() {\n  static COMMANDS: Vec&lt;(Vec&lt;String&gt;, PathBuf)&gt; = vec![];\n\n  fn run(inputs: &amp;[String], output: &amp;Path) {\n    COMMANDS.push((inputs.to_vec(), PathBuf::from(output)));\n  }\n\n  // A test only helper.\n  fn contains_command(inputs: &amp;[String], output: &amp;Path) -&gt; bool {\n    // ...\n  }\n}</code></pre>\n<p>Because <code>FakeRunner</code> is a parameterize module, we can create a new module (and a new empty <code>COMMANDS</code>) every time we apply it:</p>\n<pre><code>mod Tests {\n  mod TestRunner = FakeRunner();\n  mod TestBuild = BuildStep(mod Env {\n    mod Cache = MemCache;\n    mod Runner = TestRunner\n  });\n\n  // Write tests against TestBuild using `TestRunner::contains_command`...\n}</code></pre>\n<p>If we want to check that caching works we can extend our tests with a new fake runner and compare their commands:</p>\n<pre><code>mod Tests {\n  // TestBuild setup...\n\n  mod UncachedTestRunner = FakeRunner();\n  mod UncachedTestBuild = BuildStep(mod Env {\n    mod Cache = NoCache;\n    mod Runner = UncachedTestRunner;\n  })\n\n  // Compare the results of `TestRunner::contains_command` and `UncachedTestRunner::contains_command`...\n}</code></pre>\n<p>This isn’t earth shattering stuff.\nIf we wanted to replicate this setup in an OO language, however, we would need runtime objects or, heaven forbid, a DI framework.\nHere we can do it all by wiring up modules statically.</p>\n<p>Hopefully this has helped you see what’s cool about modules.\nModule’s power lies in their signatures.\nWhat would require a newtype wrapper or a visibility change in other languages can be accomplished by simply changing the signature a module is viewed at.</p>\n<p>With abstract types, this allows for constructing webs of encapsulation where each piece knows precisely what it needs to about its neighbor and no more.\nSignatures act as this encapsulation boundary, freeing us to reason about our code modularly.\nAs long as our module conforms to the expected signature we can contort and refactor it to our wildest whims and trust that it will continue to integrate into our system as expected.\nML Modules are neat and I think they deserve more love and exploration in programming languages.</p>","headings":[{"level":1,"text":"ML Modules for Mere Mortals","id":"ml-modules-for-mere-mortals"},{"level":2,"text":"Modules Bundle Functions Link to heading","id":"modules-bundle-functions-link-to-heading"},{"level":2,"text":"Modules (also) Bundle Types Link to heading","id":"modules-also-bundle-types-link-to-heading"},{"level":2,"text":"The Type of a Module is a Signature Link to heading","id":"the-type-of-a-module-is-a-signature-link-to-heading"},{"level":1,"text":"Signatures Support Encapsulation Link to heading","id":"signatures-support-encapsulation-link-to-heading"},{"level":2,"text":"Sealed Types Seal Encapsulation Link to heading","id":"sealed-types-seal-encapsulation-link-to-heading"},{"level":2,"text":"Module’s Version of Generics Link to heading","id":"module-s-version-of-generics-link-to-heading"},{"level":2,"text":"A Teensy Problem Link to heading","id":"a-teensy-problem-link-to-heading"},{"level":2,"text":"Include Keeps Modules Small Link to heading","id":"include-keeps-modules-small-link-to-heading"},{"level":2,"text":"Putting It All Together Link to heading","id":"putting-it-all-together-link-to-heading"}]}}