How to implement ResolveRequire if custom function is used in game

[vaderkos]

In Civilization 5 there is special function include instead of require(Which is not available in most contexts) used for importing and running lua files.

How could I use ResolveRequire to automatically resolve specified files. (I know how to find file by import name).

For Example:

include('TechHelpInclude.lua') -- instead of require('path/to/TechHelpInclude')

-- Here I need to have lua definitions from that file already loaded, instead of manually finding and opening file.

Here is how you could emulate include function:

	local EmulateInclude = (function()
		local function GetAvailablePaths()
			-- We are not inside Civ5 Lua but somewhere else...
			local hasOs = os and type(os.getenv) == 'function'

			if not hasOs then
				error('Error in include emulation: Cannot determine OS')
			end

			local isWindows = os.getenv('OS'):lower():match('window')
			local windowsCmd = 'dir /s /b *.lua'
			local linuxCmd = "find . -type f -name '*.lua'"

			local stream = io.popen(isWindows and windowsCmd or linuxCmd)
			local files = {}

			if stream == nil then
				return files
			end

			for line in stream:lines() do
				table.insert(files, line)
			end

			return files
		end

		--- @param filename string
		local function GetCandidatePath(filename)
			for _, path in next, GetAvailablePaths(), nil do
				if string.sub(path, - #filename) == filename then
					return path
				end
			end

			return filename
		end

		--- @param filename string
		return function(filename)
			if not filename:match('%.lua$') then
				filename = filename .. '.lua'
			end

			if type(dofile) ~= 'function' then
				error('Error in include emulation: dofile is not a function')
			end

			local success, result = pcall(dofile, GetCandidatePath(filename))

			if not success then
				if result:find('^cannot open') then
					return {}
				end

				error('Error in include emulation: ' .. result, 3)
			end

			return { filename }
		end
	end)()

[tomlau10]

AFAIK ResolveRequire has nothing to do with loading definition from that file. 😕
It just alters how LuaLS resolves a path with a custom logic.
From the demo in official wiki: https://luals.github.io/wiki/plugins/#resolverequire

• You can have it to resolve a path prefixed with @ => extract the file name and return it
• Without this custom logic, LuaLS will treat the prefixed @ as part of the file name
  => and will be unable to find the file in normal case

---

Here I need to have lua definitions from that file already loaded, instead of manually finding and opening file.

For your use case, I believe the most important thing is that you have to add your mod's path to workspace.library settings 🤔

• LuaLS will preload all files in your workspace + library paths
  and with runtime.pathStrict defaulted to false, LuaLS will automatically search that file in all subfolders
  https://luals.github.io/wiki/settings/#runtimepathstrict
• I assume that your Civ5 Lua files are outside the scope of your workspace directory?
  Thus LuaLS won't preload them automatically
  You have to add that directory to workspace.library first in your project's .luarc.json
  https://luals.github.io/wiki/settings/#workspacelibrary

{
  "workspace.library": [
    "/path/to/civ5lua",
  ]
}

• And you will need to change the runtime.path settings as well
  https://luals.github.io/wiki/settings/#workspacelibrary
  • because its default value is: ["?.lua", "?/init.lua"]
  • but you want to include a file by having the .lua suffix: include('TechHelpInclude.lua')
  • without changing this config, LuaLS will always find a file by [workspace|library]/TechHelpInclude.lua.lua / [workspace|library]/TechHelpInclude.lua/init.lua
  • You might need to change this config value to ["?.lua", "?/init.lua", "?"]
    => let LuaLS search by file name directly without appending .lua after it
• You might also need to change completion.requireSeparator to /
  https://luals.github.io/wiki/settings/#completionrequireseparator
  by default it is ., which means TechHelpInclude.lua => will be seen as TechHelpInclude/lua
  => will try to find a file TechHelpInclude/lua.lua in your workspace / library

a demo .luarc.json having the aforementioned configs

{
    "workspace.library": [
        "/path/to/civ5lua",
    ],
    "runtime.path": [
        "?.lua",
        "?/init.lua",
        "?"
    ],
    "completion.requireSeparator": "/",
    "runtime.special": {
        "include": "require"
    }
}

No need to write custom plugin with ResolveRequire I believe 🤔

still want to write a plugin using ResolveRequire ?

Ofc you can still have a custom plugin with ResolveRequire.
But the only benefit that I can think of, is that you don't need to change runtime.path and completion.requireSeparator ? 😕 😕

Here is a demo that you might want to try as a baseline:

local files = require 'files'
local furi = require 'file-uri'

---@param  uri  string # The URI of file
---@param  name string # Argument of require()
---@return string[]?
function ResolveRequire(uri, name)
    -- chec if ends with `.lua`
    if not name:match("%.lua$") then
        return nil
    end

    -- return path in specific directory
    -- here using `~/lib` as example: require('test.lua') => ~/lib/test.lua
    -- needs to encode it in `file://` uri format
    local fpath = '~/lib/' .. name
    return { furi.encode(files.normalize(fpath )) }
end

• if a require name ends with .lua => resolves it as ~/lib/<name>
• but again the most important thing is you have to add ~/lib in workspace.library config 👀
  otherwise even if the path is resolved, LuaLS won't preload this file

[vaderkos]

• LuaLS will preload all files in your workspace + library paths
  and with runtime.pathStrict defaulted to false, LuaLS will automatically search that file in all subfolders
  luals.github.io/wiki/settings#runtimepathstrict

• I assume that your Civ5 Lua files are outside the scope of your workspace directory?
  Thus LuaLS won't preload them automatically
  You have to add that directory to workspace.library first in your project's .luarc.json
  luals.github.io/wiki/settings#workspacelibrary

@tomlau10 These do not make sense, as Civ5 lua context is not same in every file. Each file has it's own globals.

All I need is to treat include(filename) as require(filename) with custom logic that maps filename to correct path of file to be required.

The problem with .lua extension is that Civ5 if I use include('TechHelpInclude') it can either load files TechHelpIncludeSomethingAAA.lua and TechHelpIncludeSomethingBBB.lua. It's specific of lua implementation in Civ5

[tomlau10]

as Civ5 lua context is not same in every file. Each file has it's own globals.

Then I am afraid this is not achievable in LuaLS currently, or at least it won't work in your expected way. ☹️
When LuaLS works in workspace mode, it treats every preloaded files under a single lua runtime.
You cannot dynamically require files / add the globals defined by that file to runtime on condition.

I believe the require() of LuaLS is designed for modularized libraries:

---@class mylib
local mylib = {}

function mylib.func1() end
function mylib.func2() end

return mylib

• and then in another file, one might do

local mylib = require "mylib" --> this will be `mylib` type, as it is "returned" from that module
mylib. -- trigger completion here will suggest `func1` / `func2`

• there is no separate globals / env for each file
  for example if you have a globals.lua in your workspace

GLOBAL_1 = 1
GLOBAL_2 = 2

even if none of your files contains a require "globals"
these globals will still present in LuaLS's runtime for your workspace

• unless you set this file in workspace.ignoreDir
  but then they will not appear in your workspace even if you do require "globals" 😇
  (until you manually open this ignored file, which will temporary add its type to current runtime, and this is the behavior that you are experiencing I believe)

---

Simply put, for a require statement, LuaLS only finds the file/module and returns the value that the file returns.
That's it.
LuaLS does not dofile() the module.
LuaLS global support works by statically analyzing all globals defined in preloaded files/libraries.
(This is my understanding and observation)