From 74cd1a76a7930a211029c065bc7e58cb62c40cf6 Mon Sep 17 00:00:00 2001 From: Andy Friesen Date: Thu, 27 Mar 2025 15:24:41 -0700 Subject: [PATCH] Add a description of abstract module paths per feedback from @vrn-sn. --- ...bstract-module-paths-and-init-dot-luau.md} | 28 +++++++++++++++---- 1 file changed, 23 insertions(+), 5 deletions(-) rename docs/{adjust-meaning-of-init-dot-luau.md => abstract-module-paths-and-init-dot-luau.md} (78%) diff --git a/docs/adjust-meaning-of-init-dot-luau.md b/docs/abstract-module-paths-and-init-dot-luau.md similarity index 78% rename from docs/adjust-meaning-of-init-dot-luau.md rename to docs/abstract-module-paths-and-init-dot-luau.md index dbb617a..9cb925a 100644 --- a/docs/adjust-meaning-of-init-dot-luau.md +++ b/docs/abstract-module-paths-and-init-dot-luau.md @@ -1,4 +1,4 @@ -# Adjust the meaning of `init.luau` +# Abstract module paths and `init.luau` ## Summary @@ -65,9 +65,27 @@ project, we would like to rectify this. ## Design -Luau will no longer consider relative requires from a package `init.luau` file -to resolve relative to the script itself. It will instead resolve relative to the -script's parent, i.e. the folder containing the module. +First, we introduce a new abstraction: a _module path_. Module paths refer +either to _modules_ or _directories_. + +For the purposes of navigation, both modules and directories are functionally +identical: modules and directories can both have children, which could +themselves be modules or directories, and both types can have at most one +parent, which could also be either a module or a directory. + +The thing that separates a module from a directory is precisely that modules +represent source code that can be imported via the `require()` function. +Directories, by contrast, are merely organizational units. + +The central feature of this RFC is about how module paths correspond to +filesystem paths: A module path refers to a module if it corresponds either to a +`.luau` file or to a directory that contains a file named `init.luau`. A module +path refers to a directory if it refers to a filesystem directory that lacks an +`init.luau` file. + +More concretely, Luau will no longer consider relative requires from a package +`init.luau` file to resolve relative to the script itself. It will instead +resolve relative to the script's parent, i.e. the folder containing the module. Secondly, we recognize an unfortunate side effect of this change: code within `package/init.luau` is forced to write `require('./package/dependency')` when it @@ -75,7 +93,7 @@ specifically wants to carry out the ordinary task of importing a subordinate module. We propose to alleviate this with a special import alias `@self` that resolves -to the current module. +to the path to the current module. ```lua -- package/init.luau