# Grab文档

## Grab - 官方脚本安装器

### 用法

    grab [<选项>] <命令> ...

### 选项

*--cn*

    使用国内镜像进行下载. 若不指定此选项则默认从Github下载. 此选项可能只对(本仓库内的)官方包管用.

*--help* 

    显示帮助信息. (使用OpenOS提供的less程序)

*--version* 

    显示版本号.

*--router=\<路由文件>*

    加载一个文件,这个文件应返回如下类型的函数:
    function(仓库名称: string, 分支名称: string ,文件位置: string): string

*--proxy=\<代理文件>*

    加载一个文件,这个文件应返回如下类型的函数:
    function(网址 : string): boolean, string

*--bin=\<路径>*

    设置命令文件安装位置. 默认是 /usr/bin

*--lib=\<路径>*

    设置库文件安装位置. 默认是 /usr/lib

*-f* , *--force*

    强制覆盖已存在的文件

*-y* , *--yes*

    跳过交互式确认.
    仅当安装的包具有依赖库时才需要交互式确认
    
*--skip-install*

    指定此选项时, 包的安装脚本不会被调用. (仅下载)

*--refuse-license=\<协议>*

    通过此选项指定拒绝的协议. 用英文逗号分隔多个协议名称.

*--accept-license=\<协议>*

    通过此选项指定接受的协议. 用英文逗号分隔多个协议名称.

### 命令

**install \<包名> ...**

    安装对应的包. 依赖库会被自动下载并安装.

**uninstall \<包名> ...**

    卸载并删除对应的包. 依赖库不会被自动删除.

**verify \<程序列表> ...**

    验证程序列表的合法性.

**add \<程序列表> ...**

    将程序列表添加到Grab, 使得对应的包能通过grab install安装.

**update**

    更新程序列表.

**clear**

    清除程序列表.

**list**

    列出程序列表中全部的包.

**search \<包名 或 Lua正则表达式>**

    通过包名进行搜索.

**show \<包名>**

    列出对应包的详细信息.

**download \<文件名> ...**

    直接下载文件. (不推荐)

### 注意事项

#### 协议

下载和使用Grab表明您已同意 [MIT协议](https://github.com/Kiritow/OpenComputerScripts/blob/master/LICENSE).

官方仓库中的全部脚本都基于MIT协议.

在下载任何其他指定了协议的包之前, Grab会要求您同意对应的协议.

这个确认过程可以通过指定`--accept-license`选项来跳过.

例如:

    --accept-license=mit 表明您接受MIT协议.
    --refuse-license=mit 表明您拒绝MIT协议.
    --accept-license 表明您接受任何协议.
    --refuse-license 表明您拒绝任何协议.(此选项不会影响官方库的使用)

如果一个协议即被接受又被拒绝, 该协议将被拒绝.

#### 程序提供方

仅在一个包没有指定库和代理URL的时候才会被认为是官方包. 通常, 官方包仅会依赖官方包.

你可以使用Grab来安装非官方的包, 但Grab不会检查其安全性.

请注意, 通过Grab添加的程序列表不能覆盖官方包信息.

#### 路由和代理

    route_func(仓库名称: string, 分支名称: string ,文件位置: string): string

路由函数传入仓库名称、分支名称和文件位置, 传出一个网址. 例如, 通过重定向请求到镜像站可以加快下载速度.

由于路由函数可以重定向请求, 当使用`--router`选项时, Grab会给出一条警告信息.

    proxy_func(网址 : string): boolean, string

代理函数传入网址，至少返回两个值.

代理函数可处理不同协议的请求或底层网络操作. 例如通过socks5代理或游戏内网络下载数据.

若第一个返回值是true, 则下载成功, 此时第二个返回值是下载得到的数据.

若第一个返回值是false, 则下载失败, 此时第二个返回值是错误消息.

如果代理函数抛出异常, Grab会尝试使用默认下载器. (这样对某些不需要代理的网址就可以使用默认下载器)

由于代理函数可以进行底层网络操作, 当使用`--proxy`选项时, Grab会给出一条警告消息.

## 程序列表详解

官方会维护一份[官方程序列表](programs.info). 通过使用`grab update`命令可以使用官方程序列表更新您本地的程序列表.

您可以通过`grab add 程序列表`来添加程序列表中的程序到本地程序列表中. 给定的程序列表参数可以是本地文件名或网址.

参见[程序列表样例](programs_zhCN.info.example)获取更详细的信息.