suggest-require/suggest-require.lua

-- ||| Suggest-Require ||| -----------------------------------------------------

-- Version 1.0.0   ( 11. October 2017 )

-- This is a small library to discover which modules are importable using
-- `require`. It's useful for seeing which modules your Lua environment
-- can access. It's intended usage is in an auto-complete system for Lua.

-- Author:   Jmaa
-- Email:    jonjmaa@gmail.com
-- Website:  aanes.xyz

-- "THE BEER-WARE LICENSE" (Revision 42):
-- <jonjmaa@gmail.com> wrote this file.  As long as you retain this notice you
-- can do whatever you want with this stuff. If we meet some day, and you think
-- this stuff is worth it, you can buy me a beer in return.

-- TODO: Ensure it works under both Windows and MacOS.
-- TODO: Add support for alternative package.config

--------------------------------------------------------------------------------
-- Constants

local SCAN_DIR_TEMPLATE, SCAN_DIR_SEP_PATTERN

if package.config:sub(1, 1) == '/' then
	-- On unix
	SCAN_DIR_TEMPLATE   	= 'find -L "%s" -maxdepth 1 -mindepth 1 -print0'
	SCAN_DIR_SEP_PATTERN	= '%z'
else
	-- On windows
	SCAN_DIR_TEMPLATE   	= 'dir "%s" /b /ad'
	SCAN_DIR_SEP_PATTERN	= '\n'
end

--------------------------------------------------------------------------------
-- Util

local function get_module_paths (path_str)
	-- Gets the paths of contained in `path_str` based on the format in
	-- package.config.

	-- Error check
	local path_str = path_str or package.path
	assert(type(package.config) == 'string')
	assert(type(path_str) == 'string')

	-- Work work
	local paths  =  {}
	for path in path_str:gmatch '[^;]+' do
		paths[#paths+1] = path
	end
	-- Return
	return paths
end

local function get_modules_fitting_path (root_path, module_names)
	-- First builds up a list of paths to files in `root_path`, and then goes
	-- through and ensures they match the possible paths for modules.

	assert(type(root_path) == 'string')
	assert(type(module_names) == 'table')

    -- Use `find` to find files in folders below the given matching.
    local pfile   	= io.popen ('find -L "'..(root_path:match '^(.-)?' or root_path)..'" -type f -not -path \'*/\\.*\' -print0')
    local list_str	= pfile:read '*all'
                  	  pfile:close()

    -- Construct a pattern for the expected path of possible modules.
    local module_path_pattern = '^'
                      .. root_path:gsub('[%^%(%)%.%[%]%*%+%-]', function (a) return '%' .. a end)
                              :gsub('?', '(.+)')
                      .. '$'

    -- Look through the file list, and find importable modules.
	for path in list_str:gmatch '[^%z]+' do

		local matches  	= { path:match(module_path_pattern) }
		local identical	= #matches > 0

		for i = 1, #matches do
			if matches[1] ~= matches[i] then
				identical = false
				break
			end
		end

		-- Check if match
		if identical then
			module_names[#module_names+1] = matches[1]:gsub('/', '.')
		end
	end
end


--------------------------------------------------------------------------------
-- Finding Module Names

local function get_loaded_module_names ()
	-- Get the names of modules already loaded.
	local l = {}
	for k in pairs(package.loaded) do  l[#l+1] = k  end
	return l
end

local function get_preloaded_module_names ()
	-- Get the names of preloaded modules.
	local l = {}
	for k in pairs(package.loaded) do  l[#l+1] = k  end
	return l
end

local function get_module_names_from_path ()
	-- Get the names of modules not loaded yet.
	local paths = get_module_paths(package.path)

	local modules = {}
	for _, path in pairs(paths) do
		get_modules_fitting_path(path, modules)
	end

	return modules
end

local function get_c_module_names_from_path ()
	-- Get the names of c-modules not loaded yet.
	local paths = get_module_paths(package.cpath)

	local modules = {}
	for _, path in pairs(paths) do
		get_modules_fitting_path(path, modules)
	end

	return modules
end

local PACKAGE_SEARCH_METHODS = {
	get_loaded_module_names,
	get_preloaded_module_names,
	get_module_names_from_path,
	get_c_module_names_from_path,
}

local function get_available_module_names ()
	-- Searches through the package system to determine which modules can be
	-- imported by using `require`.

	-- Returns a sequence of strings, each of which can be directly used by
	-- `require` to import the module.

	assert(type(package) == 'table')

	-- Find and De-duplicate
	local dedub = {}
	for _, method in ipairs(PACKAGE_SEARCH_METHODS) do
		for _, name in ipairs(method()) do  dedub[name] = true  end
	end

	-- Sort
	local module_names = {}
	for name in pairs(dedub) do  module_names[#module_names+1] = name  end
	table.sort(module_names)

	-- Output assertions
	assert(type(module_names) == 'table')
	for i = 1, #module_names do
		assert(type(module_names[i]) == 'string')
	end

	-- Return
	return module_names
end

--------------------------------------------------------------------------------
-- Run or return

-- Can be run directly from the terminal to display the available modules, or
-- if imported using "require", will return itself as a library.

if ... then
	return get_available_module_names
else
	local names = get_available_module_names()
	io.write 'Following modules are available: \n'
	for _, module_name in ipairs(names) do
		io.write ' -  '
		io.write(module_name)
		io.write '\n'
	end
end