Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update old require-by-string RFCs with information about amendments #68

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update old require-by-string RFCs with information about amendments #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions docs/new-require-by-string-semantics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,7 @@ This would cause the following:

This behavior is [problematic](https://github.com/Roblox/luau/issues/959), and puts an unnecessary emphasis on the directory from which the Luau CLI is running. A better solution is to evaluate relative paths in relation to the file that is requiring them.

## Design

## Design

### Package management

Expand All @@ -56,6 +55,10 @@ For compatibility across platforms, we will automatically map `/` onto `\`.

### Path resolution

**This section is now obsoleted by [this RFC](https://github.com/luau-lang/rfcs/pull/56):**
The implicit resolution order described below is no longer supported.
If multiple files exist that could match a given `require` path, an error is thrown.

If we find files with the same name but different extensions, then we will attempt to require a file with the following extensions (in this order):
1. `.luau`
2. `.lua`
Expand All @@ -65,9 +68,11 @@ If the string resolves to a directory instead of a file, then we will attempt to
1. `init.luau`
2. `init.lua`


### Relative paths

**This section is now partially obsoleted by [this RFC](https://github.com/luau-lang/rfcs/pull/56):**
Relative paths *must* begin with either `./` or `../`, and the `paths` variable is no longer supported.

Modules can be required relative to the requiring file's location in the filesystem (note, this is different from the current implementation, which evaluates all relative paths in relation to the current working directory).

If we are trying to require a module called `MyModule.luau` in `C:/MyLibrary`:
Expand Down
173 changes: 89 additions & 84 deletions docs/require-by-string-aliases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,34 +10,6 @@ The Roblox engine does not currently support require-by-string. One motivation f

Luau itself currently supports a basic require-by-string syntax that allows for requiring Luau modules by relative or absolute path. Unfortunately, the current implementation does not support aliases.

## Design

Parts of this design are now obsoleted by [this RFC](https://github.com/luau-lang/rfcs/pull/56).

#### Aliases

Aliases can be used to bind an absolute or relative path to a convenient, case-insensitive name that can be required directly.

```json
"aliases": {
"Roact": "C:/LuauModules/Roact-v1.4.2"
}
```

Based on the alias map above, you would be able to require Roact directly with an `@` prefix:

```luau
local Roact = require("@Roact")
```

Or even a sub-module:

```luau
local createElement = require("@Roact/createElement")
```

Aliases are overrides. Whenever the first component of a path exactly matches a pre-defined alias, it will be replaced before the path is resolved to a file. Alias names are also restricted to the charset `[A-Za-z0-9.\-_]`. We restrict the charset and make them case insensitive because we envision alias names to be primarily used as package names, which tend to be case insensitive and alphanumeric. They also must be preceded by an `@` symbol.

### Package management

While package management itself is outside of the scope of this RFC, we want to make it possible for a package management solution to be developed in a way that integrates well with our require syntax.
Expand Down Expand Up @@ -65,88 +37,58 @@ local result = require("../../../../../HelperModules/graphing")
local result = require("@src/HelperModules/graphing")
```

##### Versioning

Aliases are simple bindings and aren't concerned with versioning. The intention is to allow package management software to leverage aliases by automatically adding and updating the alias map to reflect a package's dependencies. For manual versioning, a user could always "version" their aliases: `@MyModule-v1`, `@MyModule-v2`, etc.
## Design

##### Library root alias
### Aliases

In the past, it has been proposed to define an alias (e.g. "`@`") to represent the root directory of a file's encapsulating library.
- However, the concept of a "Luau library" and its root directory is not yet rigorously defined in Luau, in terms of folder/file structure.
- In the future, we may add a `package.json` file or something similar that marks the root directory of a library, but this is outside of the scope of this RFC, which primarily focuses on improving require-by-string.
- For the time being, this functionality will remain unimplemented for this reason. The alias "`@`" will remain reserved for now, meaning it cannot be overridden.

Of course, users can still use the alias map to explicitly define this behavior with a named alias:
Aliases can be used to bind an absolute or relative path to a convenient, case-insensitive name that can be required directly.

```json
"aliases": {
"src": "../"
"Roact": "C:/LuauModules/Roact-v1.4.2"
}
```

#### Paths

Similar to [paths in TypeScript](https://www.typescriptlang.org/tsconfig#paths), we will introduce a `paths` array that can be configured in `.luaurc` files. Whenever a path is passed to `require` and does not begin with `./` or `../`, the path will first be resolved relative to the requiring file. If this fails, we will attempt to resolve paths relative to each path in the `paths` array.

The `paths` array can contain absolute paths, and relative paths are resolved relative to `.luaurc` file in which they appear.

##### Example Definition
Based on the alias map above, you would be able to require Roact directly with an `@` prefix:

With the given `paths` definition (`.luaurc` file located in `/Users/johndoe/Projects/MyProject/src`):
```json
"paths": [
"../dependencies",
"/Users/johndoe/MyLuauLibraries",
"/Users/johndoe/MyOtherLuauLibraries",
]
```luau
local Roact = require("@Roact")
```

If `/Users/johndoe/Projects/MyProject/src/init.luau` contained the following code:
Or even a sub-module:

```luau
local graphing = require("graphing")
local createElement = require("@Roact/createElement")
```
We would search the following directories, in order:
- `/Users/johndoe/Projects/MyProject/src`
- `/Users/johndoe/Projects/MyProject/dependencies`
- `/Users/johndoe/MyLuauLibraries`
- `/Users/johndoe/MyOtherLuauLibraries`

### Paths array
Aliases are overrides. Whenever the first component of a path exactly matches a pre-defined alias, it will be replaced before the path is resolved to a file. Alias names are also restricted to the charset `[A-Za-z0-9.\-_]`. We restrict the charset and make them case insensitive because we envision alias names to be primarily used as package names, which tend to be case insensitive and alphanumeric. They also must be preceded by an `@` symbol.

The `paths` configuration variable provides convenience and allows Luau developers to build complex, well-organized libraries. Imagine the following project structure:
#### Versioning

```
luau-paths-project
├── .luaurc
├── dependencies
│ └── dependency.luau
└── src
└── module.luau
```
Aliases are simple bindings and aren't concerned with versioning. The intention is to allow package management software to leverage aliases by automatically adding and updating the alias map to reflect a package's dependencies. For manual versioning, a user could always "version" their aliases: `@MyModule-v1`, `@MyModule-v2`, etc.

If `.luaurc` contained the following `paths` array:
```json
{
"paths": ["./dependencies"]
}
```
#### Library root alias

Then, `module.luau` could simply require `dependency.luau` like this:
```luau
local dependency = require("dependency")
In the past, it has been proposed to define an alias (e.g. "`@`") to represent the root directory of a file's encapsulating library.
- However, the concept of a "Luau library" and its root directory is not yet rigorously defined in Luau, in terms of folder/file structure.
- In the future, we may add a `package.json` file or something similar that marks the root directory of a library, but this is outside of the scope of this RFC, which primarily focuses on improving require-by-string.
- For the time being, this functionality will remain unimplemented for this reason. The alias "`@`" will remain reserved for now, meaning it cannot be overridden.

-- Instead of: require("../dependencies/dependency")
```
Of course, users can still use the alias map to explicitly define this behavior with a named alias:

Using the `paths` array allows Luau developers to organize their projects however they like without compromising code readability.
```json
"aliases": {
"src": "../"
}
```

##### Current limitations of aliases
#### Current limitations of aliases

- Aliases cannot reference other aliases. (However, this is compatible with this proposal and will likely be implemented in the future.)
- Alias names cannot contain the directory separators `/` and `\`.
- Aliases can only occur at the beginning of a path.

##### Configuring alias maps: .luaurc
#### Configuring alias maps: .luaurc

As part of this proposal, alias maps will be configured in `.luaurc`, which follows a JSON-like syntax.

Expand All @@ -166,6 +108,36 @@ Additionally, if an alias is bound to a relative path, the path will be evaluate

Finally, providing support for alias maps within the Roblox engine is out of the scope of this RFC but is being considered internally.

### Paths

**This section is now obsoleted by [this RFC](https://github.com/luau-lang/rfcs/pull/56):**
The `paths` array described below is no longer supported.

Similar to [paths in TypeScript](https://www.typescriptlang.org/tsconfig#paths), we will introduce a `paths` array that can be configured in `.luaurc` files. Whenever a path is passed to `require` and does not begin with `./` or `../`, the path will first be resolved relative to the requiring file. If this fails, we will attempt to resolve paths relative to each path in the `paths` array.

The `paths` array can contain absolute paths, and relative paths are resolved relative to `.luaurc` file in which they appear.

#### Example Definition

With the given `paths` definition (`.luaurc` file located in `/Users/johndoe/Projects/MyProject/src`):
```json
"paths": [
"../dependencies",
"/Users/johndoe/MyLuauLibraries",
"/Users/johndoe/MyOtherLuauLibraries",
]
```

If `/Users/johndoe/Projects/MyProject/src/init.luau` contained the following code:
```luau
local graphing = require("graphing")
```
We would search the following directories, in order:
- `/Users/johndoe/Projects/MyProject/src`
- `/Users/johndoe/Projects/MyProject/dependencies`
- `/Users/johndoe/MyLuauLibraries`
- `/Users/johndoe/MyOtherLuauLibraries`

### Symlinks

Symlinks carry some security concerns; for example, a link's target might exist outside of the project folder in which the link was defined. For the first version of this implementation, symlinks will not be supported and will be treated as ordinary files.
Expand All @@ -177,6 +149,7 @@ Similar examples:
- https://webpack.js.org/configuration/resolve/#resolvesymlinks

## Use Cases

### Alias map

Using alias maps, Luau developers can require globally installed Luau libraries in their code without needing to specify their locations in Luau scripts.
Expand Down Expand Up @@ -206,6 +179,38 @@ local Component = require("@Roact/Component")

If we ever wanted to change the version of `Roact` used by `luau-aliases-project`, we would simply change the absolute path to `Roact` in `.luaurc`. By abstracting away the exact location of globally installed libraries like this, we get clean, readable code, and we make it easier for a future package manager to update dependencies by modifying `.luaurc` files.

### Paths array

**This section is now obsoleted by [this RFC](https://github.com/luau-lang/rfcs/pull/56):**
The `paths` array described below is no longer supported.

The `paths` configuration variable provides convenience and allows Luau developers to build complex, well-organized libraries. Imagine the following project structure:

```
luau-paths-project
├── .luaurc
├── dependencies
│ └── dependency.luau
└── src
└── module.luau
```

If `.luaurc` contained the following `paths` array:
```json
{
"paths": ["./dependencies"]
}
```

Then, `module.luau` could simply require `dependency.luau` like this:
```luau
local dependency = require("dependency")

-- Instead of: require("../dependencies/dependency")
```

Using the `paths` array allows Luau developers to organize their projects however they like without compromising code readability.

### Large-scale projects in Luau

For large-scale Luau projects, we might imagine that every dependency of the project is a Luau project itself. We might use an organizational structure like this to create a clean hierarchy:
Expand Down