1
0

Better documentation, and a preamble with license.

This commit is contained in:
Jon Michael Aanes 2017-10-11 11:57:42 +02:00
parent 2d66b5d216
commit 05d5a494f8

View File

@ -1,10 +1,25 @@
-- This is a tiny library to discover which modules can be imported using -- ||| Suggest-Require ||| -----------------------------------------------------
-- `require`. It's intended to be included in an auto-complete system for Lua.
-- Not sure if it works on a system without GNU find -- 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 -- Constants
local SCAN_DIR_TEMPLATE, SCAN_DIR_SEP_PATTERN local SCAN_DIR_TEMPLATE, SCAN_DIR_SEP_PATTERN
@ -19,14 +34,12 @@ else
SCAN_DIR_SEP_PATTERN = '\n' SCAN_DIR_SEP_PATTERN = '\n'
end end
-- TODO: Improve Windows support --------------------------------------------------------------------------------
-- TODO: Make sure works on MacOS.
--------------
-- Util -- Util
local function get_module_paths (path_str) local function get_module_paths (path_str)
-- TODO: Add support for alternative package.config -- Gets the paths of contained in `path_str` based on the format in
-- package.config.
-- Error check -- Error check
local path_str = path_str or package.path local path_str = path_str or package.path
@ -43,6 +56,9 @@ local function get_module_paths (path_str)
end end
local function get_modules_fitting_path (root_path, module_names) 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(root_path) == 'string')
assert(type(module_names) == 'table') assert(type(module_names) == 'table')
@ -50,21 +66,25 @@ local function get_modules_fitting_path (root_path, module_names)
local pfile = io.popen ('find -L "'..(root_path:match '^(.-)?' or root_path)..'" -type f -not -path \'*/\\.*\' -print0') local pfile = io.popen ('find -L "'..(root_path:match '^(.-)?' or root_path)..'" -type f -not -path \'*/\\.*\' -print0')
local list_str = pfile:read '*all' local list_str = pfile:read '*all'
pfile:close() pfile:close()
-- Construct a pattern for the expected path of possible modules. -- Construct a pattern for the expected path of possible modules.
local module_path_pattern = '^' local module_path_pattern = '^'
.. root_path:gsub('[%^%(%)%.%[%]%*%+%-]', function (a) return '%' .. a end) .. root_path:gsub('[%^%(%)%.%[%]%*%+%-]', function (a) return '%' .. a end)
:gsub('?', '(.+)') :gsub('?', '(.+)')
.. '$' .. '$'
-- Look through the file list, and find importable modules. -- Look through the file list, and find importable modules.
for path in list_str:gmatch '[^%z]+' do for path in list_str:gmatch '[^%z]+' do
local matches = { path:match(module_path_pattern) } local matches = { path:match(module_path_pattern) }
local identical = #matches > 0 local identical = #matches > 0
for i = 1, #matches do if matches[1] ~= matches[i] then for i = 1, #matches do
identical = false; break if matches[1] ~= matches[i] then
end end identical = false
break
end
end
-- Check if match -- Check if match
if identical then if identical then
@ -74,7 +94,7 @@ local function get_modules_fitting_path (root_path, module_names)
end end
-------------- --------------------------------------------------------------------------------
-- Finding Module Names -- Finding Module Names
local function get_loaded_module_names () local function get_loaded_module_names ()
@ -92,6 +112,7 @@ local function get_preloaded_module_names ()
end end
local function get_module_names_from_path () local function get_module_names_from_path ()
-- Get the names of modules not loaded yet.
local paths = get_module_paths(package.path) local paths = get_module_paths(package.path)
local modules = {} local modules = {}
@ -103,6 +124,7 @@ local function get_module_names_from_path ()
end end
local function get_c_module_names_from_path () 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 paths = get_module_paths(package.cpath)
local modules = {} local modules = {}
@ -121,14 +143,15 @@ local PACKAGE_SEARCH_METHODS = {
} }
local function get_available_module_names () local function get_available_module_names ()
-- Searches through the package system to determine which modules can be -- Searches through the package system to determine which modules can be
-- imported by using `require`. Returns a sequence of strings, each of which -- imported by using `require`.
-- can be directly used by `require` to import the module.
-- Returns a sequence of strings, each of which can be directly used by
-- `require` to import the module.
assert(type(package) == 'table') assert(type(package) == 'table')
-- Find and Dedub -- Find and De-duplicate
local dedub = {} local dedub = {}
for _, method in ipairs(PACKAGE_SEARCH_METHODS) do for _, method in ipairs(PACKAGE_SEARCH_METHODS) do
for _, name in ipairs(method()) do dedub[name] = true end for _, name in ipairs(method()) do dedub[name] = true end
@ -149,7 +172,11 @@ local function get_available_module_names ()
return module_names return module_names
end 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 if ... then
return get_available_module_names return get_available_module_names