From b0651082f472baee8f0fa8ec7ba95f433e2637bb Mon Sep 17 00:00:00 2001 From: SquidDev Date: Fri, 20 Nov 2020 19:36:28 +0000 Subject: [PATCH] Cleanup examples for the various modules --- build.gradle | 3 +- .../lua/rom/modules/main/cc/completion.lua | 19 +++- .../lua/rom/modules/main/cc/expect.lua | 27 +++++- .../lua/rom/modules/main/cc/pretty.lua | 20 +++- .../lua/rom/modules/main/cc/require.lua | 6 +- .../rom/modules/main/cc/shell/completion.lua | 91 ++++++++++--------- 6 files changed, 109 insertions(+), 57 deletions(-) diff --git a/build.gradle b/build.gradle index 5c36a17fd..4f698a445 100644 --- a/build.gradle +++ b/build.gradle @@ -342,7 +342,8 @@ task illuaminateDocs(type: Exec, dependsOn: [minifyWeb, luaJavadoc]) { group = "build" description = "Bundles JS into rollup" - inputs.files(fileTree("doc")).withPropertyName("sources") + inputs.files(fileTree("doc")).withPropertyName("docs") + inputs.files(fileTree("src/main/resources/data/computercraft/lua/rom")).withPropertyName("lua rom") inputs.file("illuaminate.sexp").withPropertyName("illuaminate.sexp") inputs.file("$buildDir/rollup/index.min.js").withPropertyName("scripts") inputs.file("src/web/styles.css").withPropertyName("styles") diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua index 01cc187b1..d07b09506 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua +++ b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua @@ -31,8 +31,9 @@ end -- @treturn { string... } A list of suffixes of matching strings. -- @usage Call @{_G.read}, completing the names of various animals. -- +-- local completion = require "cc.completion" -- local animals = { "dog", "cat", "lion", "unicorn" } --- read(nil, nil, function(text) return choice(text, animals) end) +-- read(nil, nil, function(text) return completion.choice(text, animals) end) local function choice(text, choices, add_space) expect(1, text, "string") expect(2, choices, "table") @@ -45,7 +46,9 @@ end -- @tparam string text The input string to complete. -- @tparam[opt] boolean add_space Whether to add a space after the completed name. -- @treturn { string... } A list of suffixes of matching peripherals. --- @usage read(nil, nil, peripheral) +-- @usage +-- local completion = require "cc.completion" +-- read(nil, nil, completion.peripheral) local function peripheral_(text, add_space) expect(1, text, "string") expect(2, add_space, "boolean", "nil") @@ -59,7 +62,9 @@ local sides = redstone.getSides() -- @tparam string text The input string to complete. -- @tparam[opt] boolean add_space Whether to add a space after the completed side. -- @treturn { string... } A list of suffixes of matching sides. --- @usage read(nil, nil, side) +-- @usage +-- local completion = require "cc.completion" +-- read(nil, nil, completion.side) local function side(text, add_space) expect(1, text, "string") expect(2, add_space, "boolean", "nil") @@ -71,7 +76,9 @@ end -- @tparam string text The input string to complete. -- @tparam[opt] boolean add_space Whether to add a space after the completed settings. -- @treturn { string... } A list of suffixes of matching settings. --- @usage read(nil, nil, setting) +-- @usage +-- local completion = require "cc.completion" +-- read(nil, nil, completion.setting) local function setting(text, add_space) expect(1, text, "string") expect(2, add_space, "boolean", "nil") @@ -85,7 +92,9 @@ local command_list -- @tparam string text The input string to complete. -- @tparam[opt] boolean add_space Whether to add a space after the completed command. -- @treturn { string... } A list of suffixes of matching commands. --- @usage read(nil, nil, command) +-- @usage +-- local completion = require "cc.completion" +-- read(nil, nil, completion.command) local function command(text, add_space) expect(1, text, "string") expect(2, add_space, "boolean", "nil") diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua index 24ca66d56..397be085e 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua +++ b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua @@ -1,7 +1,26 @@ ---- The @{cc.expect} library provides helper functions for verifying that --- function arguments are well-formed and of the correct type. --- --- @module cc.expect +--[[- The @{cc.expect} library provides helper functions for verifying that +function arguments are well-formed and of the correct type. + +@module cc.expect +@usage Define a basic function and check it has the correct arguments. + + local expect = require "cc.expect" + local expect, field = expect.expect, expect.field + + local function add_person(name, info) + expect(1, name, "string") + expect(2, info, "table", "nil") + + if info then + print("Got age=", field(info, "age", "number")) + print("Got gender=", field(info, "gender", "string", "nil")) + end + end + + add_person("Anastazja") -- `info' is optional + add_person("Kion", { age = 23 }) -- `gender' is optional + add_person("Caoimhin", { age = 23, gender = true }) -- error! +]] local native_select, native_type = select, type diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua index 1c782ecee..37a70a515 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua +++ b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua @@ -67,6 +67,9 @@ end -- @tparam[opt] number colour The colour this text should be printed with. If not given, we default to the current -- colour. -- @treturn Doc The document with the provided text. +-- @usage Write some blue text. +-- local pretty = require "cc.pretty" +-- pretty.print(pretty.text("Hello!", colours.blue)) local function text(text, colour) expect(1, text, "string") expect(2, colour, "number", "nil") @@ -101,8 +104,11 @@ end -- -- @tparam Doc|string ... The documents to concatenate. -- @treturn Doc The concatenated documents. --- @usage pretty.concat(doc1, " - ", doc2) --- @usage doc1 .. " - " .. doc2 +-- @usage +-- local pretty = require "cc.pretty" +-- local doc1, doc2 = pretty.text("doc1"), pretty.text("doc2") +-- print(pretty.concat(doc1, " - ", doc2)) +-- print(doc1 .. " - " .. doc2) -- Also supports .. local function concat(...) local args = table.pack(...) for i = 1, args.n do @@ -135,7 +141,9 @@ Doc.__concat = concat --- @local -- @tparam number depth The number of spaces with which the document should be indented. -- @tparam Doc doc The document to indent. -- @treturn Doc The nested document. --- @usage pretty.nest(2, pretty.text("foo\nbar")) +-- @usage +-- local pretty = require "cc.pretty" +-- print(pretty.nest(2, pretty.text("foo\nbar"))) local function nest(depth, doc) expect(1, depth, "number") if getmetatable(doc) ~= Doc then expect(2, doc, "document") end @@ -169,6 +177,12 @@ end -- -- @tparam Doc doc The document to group. -- @treturn Doc The grouped document. +-- @usage Uses group to show things being displayed on one or multiple lines. +-- +-- local pretty = require "cc.pretty" +-- local doc = pretty.group("Hello" .. pretty.space_line .. "World") +-- print(pretty.render(doc, 5)) -- On multiple lines +-- print(pretty.render(doc, 20)) -- Collapsed onto one. local function group(doc) if getmetatable(doc) ~= Doc then expect(1, doc, "document") end diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua index a90e189b8..c7b2e2741 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua +++ b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua @@ -9,9 +9,13 @@ -- @usage Construct the package and require function, and insert them into a -- custom environment. -- --- local env = setmetatable({}, { __index = _ENV }) -- local r = require "cc.require" +-- local env = setmetatable({}, { __index = _ENV }) -- env.require, env.package = r.make(env, "/") +-- +-- -- Now we have our own require function, separate to the original. +-- local r2 = env.require "cc.require" +-- print(r, r2) local expect = require and require("cc.expect") or dofile("rom/modules/main/cc/expect.lua") local expect = expect.expect diff --git a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua index 21c10ec34..06619c7f1 100644 --- a/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua +++ b/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua @@ -1,15 +1,28 @@ ---- A collection of helper methods for working with shell completion. --- --- Most programs may be completed using the @{build} helper method, rather than --- manually switching on the argument index. --- --- Note, the helper functions within this module do not accept an argument index, --- and so are not directly usable with the @{shell.setCompletionFunction}. Instead, --- wrap them using @{build}, or your own custom function. --- --- @module cc.shell.completion --- @see cc.completion For more general helpers, suitable for use with @{_G.read}. --- @see shell.setCompletionFunction +--[[- A collection of helper methods for working with shell completion. + +Most programs may be completed using the @{build} helper method, rather than +manually switching on the argument index. + +Note, the helper functions within this module do not accept an argument index, +and so are not directly usable with the @{shell.setCompletionFunction}. Instead, +wrap them using @{build}, or your own custom function. + +@module cc.shell.completion +@see cc.completion For more general helpers, suitable for use with @{_G.read}. +@see shell.setCompletionFunction + +@usage Register a completion handler for example.lua which prompts for a +choice of options, followed by a directory, and then multiple files. + + local completion = require "cc.shell.completion" + local complete = completion.build( + { completion.choice, { "get", "put" } }, + completion.dir, + { completion.file, many = true } + ) + shell.setCompletionFunction("example.lua", complete) + read(nil, nil, shell.complete, "example ") +]] local expect = require "cc.expect".expect local completion = require "cc.completion" @@ -69,37 +82,29 @@ local function program(shell, text) return shell.completeProgram(text) end ---- A helper function for building shell completion arguments. --- --- This accepts a series of single-argument completion functions, and combines --- them into a function suitable for use with @{shell.setCompletionFunction}. --- --- @tparam nil|table|function ... Every argument to @{build} represents an argument --- to the program you wish to complete. Each argument can be one of three types: --- --- - `nil`: This argument will not be completed. --- --- - A function: This argument will be completed with the given function. It is --- called with the @{shell} object, the string to complete and the arguments --- before this one. --- --- - A table: This acts as a more powerful version of the function case. The table --- must have a function as the first item - this will be called with the shell, --- string and preceding arguments as above, but also followed by any additional --- items in the table. This provides a more convenient interface to pass --- options to your completion functions. --- --- If this table is the last argument, it may also set the `many` key to true, --- which states this function should be used to complete any remaining arguments. --- --- @usage Prompt for a choice of options, followed by a directory, and then multiple --- files. --- --- complete.build( --- { complete.choice, { "get", "put" } }, --- complete.dir, --- { complete.file, many = true } --- ) +--[[- A helper function for building shell completion arguments. + +This accepts a series of single-argument completion functions, and combines +them into a function suitable for use with @{shell.setCompletionFunction}. + +@tparam nil|table|function ... Every argument to @{build} represents an argument +to the program you wish to complete. Each argument can be one of three types: + + - `nil`: This argument will not be completed. + + - A function: This argument will be completed with the given function. It is + called with the @{shell} object, the string to complete and the arguments + before this one. + + - A table: This acts as a more powerful version of the function case. The table + must have a function as the first item - this will be called with the shell, + string and preceding arguments as above, but also followed by any additional + items in the table. This provides a more convenient interface to pass + options to your completion functions. + + If this table is the last argument, it may also set the `many` key to true, + which states this function should be used to complete any remaining arguments. +]] local function build(...) local arguments = table.pack(...) for i = 1, arguments.n do