diff --git a/DOC_Grab.md b/DOC_Grab.md new file mode 100644 index 0000000..1eab37c --- /dev/null +++ b/DOC_Grab.md @@ -0,0 +1,138 @@ +# Grab Documentation + +## Grab - Official OpenComputerScripts Installer + +### Usage + + grab [] ... + +### Options + +*--cn* + + Use mirror site in China. By default grab will download from Github. This might be useful for only official packages. + +*--help* + + Display this help page. + +*--version* + + Display version and exit. + +*--router=\* + + Given a file which will be loaded and returns a route function like: + function(RepoName: string, Branch: string ,FileAddress: string): string + +*--proxy=\* + + Given a file which will be loaded and returns a proxy function like: + function(Url : string): boolean, string + +*--skip-install* + + Library installers will not be executed. + +*--refuse-license=\* + + Set refused license. Separate multiple values with ',' + +*--accept-license=\ * + + Set accepted license. Separate multiple values with ',' + +### Command + +**install \ ...** + + Install projects. Dependency will be downloaded automatically. + +**verify \ ...** + + Verify program provider info. + +**add \ ...** + + Add program provider info. + +**update** + + Update program info. + +**clear** + + Clear program info. + +**list** + + List available projects. + +**search \** + + Search projects by name + +**show \** + + Show more info about project. + +**download \ ...** + + Directly download files. (Not recommended) + +### Notice + +#### License + +By downloading and using Grab, you are indicating your agreement to [MIT license](https://github.com/Kiritow/OpenComputerScripts/blob/master/LICENSE) + +All scripts in official OpenComputerScript repository are under MIT license. + +Before downloading any package under other licenses, Grab will ask you to agree with it. + +This confirmation can be skipped by calling Grab with --accept-license. + +Example: + + --accept-license=mit means MIT License is accepted. + --refuse-license=mit means MIT License is refused. + --accept-license means all licenses are accepted. + --refuse-license means all licenses are refused. (Official packages are not affected.) + +If a license is both accepted and refused, it will be refused. + +#### Program Provider + +A package is considered to be official only if it does not specified repo and proxy. Official packages usually only depend on official packages. + +You can also install packages from unofficial program provider with Grab, but Grab will not check its security. +Notice that override of official packages is not allowed. + +#### Router and Proxy + + route_func(RepoName: string, Branch: string ,FileAddress: string): string + +A route function takes repo, branch and file address as arguments, and returns a resolved url. +It can be used to boost downloading by redirecting requests to mirror site. + +As router functions can be used to redirect requests, Grab will give an warning if --router option presents. + + proxy_func(Url : string): boolean, string + +A proxy function takes url as argument, and returns at least 2 values. + +It can be used to handle different protocols or low-level network operations like downloading files via SOCKS5 proxy or in-game modem network. + +The first returned value is true if content is downloaded successfully. Thus, the second value will be the downloaded content. + +If the first value is false, the downloading is failed. The second value will then be the error message. + +If proxy functions throw an error, Grab will try the default downloader. + +## Explaination of programs list + +An official programs list is maintained as [programs.info](programs.info). You can keep your local programs list up to date by running `grab update`. + +You can add third party program providers to grab with `grab add `. The provider argument can be the name of a local file or an url. + +See [example programs list](programs.info.example) for more detailed information. \ No newline at end of file diff --git a/README.md b/README.md index 1e6d4b0..af02c90 100644 --- a/README.md +++ b/README.md @@ -28,3 +28,5 @@ or Then start it with: `grab` + +For more information about Grab, see [Grab Documentation](DOC_Grab.md) \ No newline at end of file diff --git a/grab.lua b/grab.lua index 324fc30..96c40b1 100644 --- a/grab.lua +++ b/grab.lua @@ -9,7 +9,7 @@ local event=require('event') local term=require('term') local args,options=shell.parse(...) -local grab_version="Grab v2.4.3-alpha" +local grab_version="Grab v2.4.4-alpha" local usage_text=[===[Grab - Official OpenComputerScripts Installer Usage: @@ -152,7 +152,7 @@ if(options["version"]) then end local function check_internet() - if(not options["proxy"] and not component.internet) then + if(not options["proxy"] and not component.list("internet")()) then print("Error: An internet card is required to run this program.") return false else @@ -162,7 +162,7 @@ local function check_internet() end local function default_downloader(url) - if(not component.internet) then + if(not component.list("internet")()) then return false,"No internet card found." end @@ -229,6 +229,7 @@ else print("[WARN] Router presents. Be aware of security issues.") end + local download if(not options["proxy"]) then download=default_downloader @@ -238,9 +239,17 @@ else if(not fn) then error(xerr) else - download=fn() - if(type(download)~="function") then - error("Loaded proxy returns " .. type(download) .. " instead of a function.") + tmp=fn() + if(type(tmp)~="function") then + error("Loaded proxy returns " .. type(tmp) .. " instead of a function.") + end + download=function(url) + local pok,ok,data=pcall(tmp,url) + if(pok) then + return ok,data + else + return default_downloader(url) + end end end end) @@ -266,6 +275,7 @@ end local function IsTrusted(tb_package) if(tb_package.provider) then -- TODO: Check Provider by comparing with online trusted list. + return false else return false end @@ -298,7 +308,7 @@ local function VerifyDB(this_db) return false,"Library " .. k .. " file " .. kk .. " has invalid value type " .. type(vv) end else - return fale,"Library " .. k .. " file has invalid key type " .. type(kk) + return false,"Library " .. k .. " file has invalid key type " .. type(kk) end end if(t.requires) then @@ -315,6 +325,11 @@ local function VerifyDB(this_db) return false,"Library " .. k .. " has invalid license url type " .. type(t.license.url) end end + if(t.provider) then + if(type(t.provider)~="string") then + return false,"Library " .. k .. " has invalid provider type " .. type(t.provider) + end + end end return true,"No error detected." @@ -894,6 +909,7 @@ if(args[1]=="show") then if(this_info.precheck) then print("Precheck: Yes") end if(this_info.installer) then print("Installer: Yes") end if(this_info.proxy) then print("Proxy: Yes") end + if(this_info.provider) then print("Provider: " .. this_info.provider) end if(this_info.license) then print("License: " .. this_info.license.name) diff --git a/programs.info.example b/programs.info.example new file mode 100644 index 0000000..41694ff --- /dev/null +++ b/programs.info.example @@ -0,0 +1,78 @@ +{ + -- This is an example of programs list. + -- Please don't include any comments in distributed programs list. + + -- This file contains a table. + -- Each key of it is considered as a package id. Its type must be "string". + -- Each element of it is considered as a package info. Its type must be "table". + -- The package id should not contain space characters. + -- The package id should be unique. Packages info with the same package id will be overwritten. + + ["PackageNameHere"]={ + title="Long package name here", + info="A short information which will be shown when `grab show PackageNameHere` is called", + + files={ + -- Key is number, and value is string. File $value will be downloaded to current directory and named $value. + "somefile.lua", + + -- Key is string, and value is string. File $key will be downloaded to $value. + ["anotherfile.lua"]="/tmp/place_it_here.lua", + + -- Key is string, and value is table. + -- File $key will be downloaded and Grab will try to save it as an element specified in $value. + ["otherfile.lua"]={ + "/etc/somedir/some_name.lua", + "/tmp/another_name.lua", + }, + + -- file can also be placed in directory + "placed/here/my_source.lua" + }, + + -- Optional. + -- Place depended library id here. + requires={ + "libevent" + }, + + -- Optional. Used by `grab show`. + author="Author name here", + contact="Author contact here", + + -- Optional + -- Fill this field if this package is stored in another repository on Github. + repo="Maybe/AnotherRepo", + + -- Optional + -- Fill this field if this package is stored in another branch of the repository on Github. + branch="branch_name_here", + + -- Optional + -- If presents, Grab will follow it to generate downloading url. + -- __repo__ will be replaced by repo or Official OpenComputerScripts repository name. + -- __branch__ will be replaced by branch or "master" + -- __file__ will be replaced by name of downloaded files. + proxy="http://SomeServer.com/__repo__/__branch__/__file__", + + -- Optional + -- If presents, Grab will load and run it after downloading. + -- The installer must be in files table. + installer="somefile.lua", + + -- Optional (but important) + -- If presents, Grab will ask user to agree with it before downloading files. + -- If not presents, the package is considered under The Unlicense (http://unlicense.org/) + -- Notice that all files in Official OpenComputerScripts repository is under the MIT License (https://github.com/Kiritow/OpenComputerScripts/blob/master/LICENSE) + license={ + name="MIT", + url="Url to the license file" + } + }, + + ["AnotherPackage"]={ + ... + }, + + ... +} \ No newline at end of file