Implement autofilled source loc magic constants

[zth]

This is a retake on #7344, but simplified and as barebones as I could make it while still being useful enough.

This PR adds an opt-in way to automatically capture call site information at runtime. It does so by introducing two new builtin abstract types: sourceLocPos and sourceLocValuePath.

The opt-in is explicit at the function definition site: if you want one of these arguments to be compiler-filled, you declare it with %autofill, for example ~pos: sourceLocPos=%autofill. If %autofill is not present, the argument is just a regular argument. When the feature is enabled and such an argument is omitted at the call site, the compiler automatically injects information about the call site into it.

The two builtin types contain different kinds of call site information:

• sourceLocPos gives a string like <file>;<startLine>;<startCol>;<endLine>;<endCol>
• sourceLocValuePath gives a string like Module.Submodule.value.localBinding, pointing to the value path of the call in the file

Both of these types are abstract. To extract meaningful information from them, this PR also adds a new stdlib module, SourceLoc, with helpers for interacting with sourceLocPos and sourceLocValuePath. These helpers can turn the abstract values into their underlying strings, or decode them into richer structures.

This feature is intended for things like:

• logging
• test helpers
• error reporting
• tracing/debug output
• tooling in general

Configuration

This should eventually become a proper configuration, but for now it is opt-in and enabled by passing this to bsc:

-allow-autofill-source-loc

The two opt-in points are intentional:

• %autofill makes it obvious at a glance which arguments are intended to be compiler-filled
• -allow-autofill-source-loc enables the actual call-site injection

If -allow-autofill-source-loc is not enabled, omitted %autofill arguments fall back to an empty string representation instead of receiving injected call site information. So code using these values should handle the “off” case gracefully.

Examples

let log = (~pos: sourceLocPos=%autofill, msg) => {
  switch SourceLoc.Pos.decode(pos) {
  | Some({file, startLine, startCol, endLine, endCol}) =>
    Console.log5(file, startLine, startCol, endLine, endCol)
  | None => ()
  }
}

let log = (
  ~pos: sourceLocPos=%autofill,
  ~valuePath: sourceLocValuePath=%autofill,
  msg,
) => {
  switch SourceLoc.Pos.decode(pos) {
  | Some({file, startLine, startCol, endLine, endCol}) =>
    Console.log5(file, startLine, startCol, endLine, endCol)
  | None => ()
  }

  Console.log2(
    SourceLoc.ValuePath.segments(valuePath),
    SourceLoc.ValuePath.name(valuePath),
  )
}

What each type means:

• sourceLocPos is the exact source position of the call
• sourceLocValuePath is the lexical path of the call site, such as Auth.Api.run

[pkg-pr-new]

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript@8303

@rescript/darwin-arm64

npm i https://pkg.pr.new/@rescript/darwin-arm64@8303

@rescript/darwin-x64

npm i https://pkg.pr.new/@rescript/darwin-x64@8303

@rescript/linux-arm64

npm i https://pkg.pr.new/@rescript/linux-arm64@8303

@rescript/linux-x64

npm i https://pkg.pr.new/@rescript/linux-x64@8303

@rescript/runtime

npm i https://pkg.pr.new/@rescript/runtime@8303

@rescript/win32-x64

npm i https://pkg.pr.new/@rescript/win32-x64@8303

commit: 8f0ca7a