Update Grab

Fix small bugs.
Better documentation.
This commit is contained in:
Kirigaya Kazuto 2018-12-03 16:58:54 +08:00
parent 8e43cee6a0
commit be34e758d0
4 changed files with 241 additions and 7 deletions

138
DOC_Grab.md Normal file
View File

@ -0,0 +1,138 @@
# Grab Documentation
## Grab - Official OpenComputerScripts Installer
### Usage
grab [<options>] <command> ...
### 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=\<Router File>*
Given a file which will be loaded and returns a route function like:
function(RepoName: string, Branch: string ,FileAddress: string): string
*--proxy=\<Proxy File>*
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=\<License>*
Set refused license. Separate multiple values with ','
*--accept-license=\<License> *
Set accepted license. Separate multiple values with ','
### Command
**install \<Project> ...**
Install projects. Dependency will be downloaded automatically.
**verify \<Provider> ...**
Verify program provider info.
**add \<Provider> ...**
Add program provider info.
**update**
Update program info.
**clear**
Clear program info.
**list**
List available projects.
**search \<Name or Pattern>**
Search projects by name
**show \<Project>**
Show more info about project.
**download \<Filename> ...**
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 <Provider>`. 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.

View File

@ -28,3 +28,5 @@ or
Then start it with:
`grab`
For more information about Grab, see [Grab Documentation](DOC_Grab.md)

View File

@ -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)

78
programs.info.example Normal file
View File

@ -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"]={
...
},
...
}