# shell_modules

**Repository Path**: karl1864/shell_modules

## Basic Information

- **Project Name**: shell_modules
- **Description**: 自用的Bash Shell模块，类似于语言扩展库吧

支持类与对象、并发任务管理、参数解析等
- **Primary Language**: Shell
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-22
- **Last Updated**: 2022-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 正在维护

## README

# shell modules

## test
### basic test
运行基础测试
```sh
bash ./test_shell_modules.sh
```

### manual test
运行手动测试， 尾部带有::manual
```sh
bash ./test_shell_modules.sh --manual
```

### debuglog
启用调试日志
```sh
bash ./test_shell_modules.sh --debuglog
```

## API list
- ArgumentsV3
- DatabaseV3
- DatabaseV3Binding
- Git
- LineVisitor
- include
- FileLocker
- ObjectV5
- ObjectV6
- Output
- ParallelV2
- PythonV2
- regex
- test
- Updater
- Waiting
- YamlV2

没提到的低版本API就是已经废弃了，但是为了兼容就没去掉

### class ArgumentsV3

| 方法                                           | 含义                                         |
|------------------------------------------------|----------------------------------------------|
| `       ArgumentsV3::ArgumentsV3 args...`      | 创建一个参数解析器，需要args作为被解析的参数 |
| `bool   ArgumentsV3::IsEnd`                    | 是否遍历到末尾                               |
| `void   ArgumentsV3::GoNext`                   | 参数指针指向下一个参数                       |
| `void   ArgumentsV3::GoSkip`                   | 跳过一个参数                                 |
| `void   ArgumentsV3::GoSkipAll`                | 跳过所有剩下的参数                           |
| `string ArgumentsV3::Get`                      | 获取当前参数                                 |
| `bool   ArgumentsV3::IsKVOption`               | 是否是键值对选项                             |
| `bool   ArgumentsV3::IsOption`                 | 是否是选项                                   |
| `string ArgumentsV3::GetOption`                | 获取当前选项名                               |
| `string ArgumentsV3::GetKey`                   | 获取当前键值对选项的键                       |
| `string ArgumentsV3::GetVal`                   | 获取当前键值对选项的值                       |
| `string ArgumentsV3::GetSkipped`               | 获取当前已跳过的所有参数                     |
| `string ArgumentsV3::GetRest`                  | 获取剩下的参数                               |
| `void   ArgumentsV3::ProcessOption options...` | 自动化处理选项，详情见下方说明               |
| `void   ArgumentsV3::UseSkipped`               | 使用当前跳过的参数为新的待遍历的参数         |

### class DatabaseV3

| 方法                                        | 含义                           |
|---------------------------------------------|--------------------------------|
| `       DatabaseV3::DatabaseV3 path`        | 创建数据库时的数据库存储路径   |
| `bool   DatabaseV3::IsObject keys...`       | keys...项是否是一个对象        |
| `bool   DatabaseV3::IsArray  keys...`       | keys...项是否是一个数组        |
| `bool   DatabaseV3::IsExist  keys...`       | keys...项是否存在              |
| `string DatabaseV3::GetVal   keys...`       | 获取keys...项的值              |
| `void   DatabaseV3::SetVal   keys... val`   | 设置keys...项的值              |
| `void   DatabaseV3::Del      keys...`       | 删除keys...项                  |
| `void   DatabaseV3::EraseKey keys... index` | 移除keys...数组的下标index     |
| `void   DatabaseV3::EraseVal keys... val`   | 移除keys...数组中值为val的元素 |
| `string DatabaseV3::GetLen   keys...`       | 获取keys...数组的长度          |
| `string DatabaseV3::GetKeys  keys...`       | 获取keys...对象的所有键        |

### class DatabaseV3Binding

| 方法                                                                             | 含义                                                                |
|----------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `DatabaseV3Binding::DatabaseV3Binding databasev3object target_class target_name` | 用databasev3object创建一个target_class类的对象target_name           |
|                                                                                  | 然后用databasev3object数据库读入target_class类的数据填充target_name |
|                                                                                  | 最后给target_name绑定databasev3object数据库                         |
| `DatabaseV3Binding::~DatabaseV3Binding`                                          | 删除在target_name上的数据库绑定                                     |

### class Git

术语:
- position: 可以是分支名{master, origin/master}、分支名的相对位置{master^, master~2}、标签{tag}等

| 方法                                  | 含义                                                         |
|---------------------------------------|--------------------------------------------------------------|
| `       Git::Git gitpath`             | 打开gitpath为Git仓库                                         |
| `bool   Git::IsModified`              | Git仓库是否有变更                                            |
| `bool   Git::IsValid`                 | 是否是合法的Git仓库                                          |
| `string Git::GetHash position`        | 获得position的hash值                                         |
| `string Git::GetRemoteHash`           | 获得origin/master的hash值                                    |
| `string Git::GetBranchName position`  | 获得position的分支名                                         |
| `void   Git::Checkout branch`         | 切换到branch分支                                             |
| `void   Git::MoveTo position`         | 移动当前分支到position                                       |
| `void   Git::Fetch [remote] [branch]` | 拉取远程remote的变更，并关注分支branch，默认是origin和master |
| `void   Git::SubmoduleUpdate`         | 更新子模块                                                   |

### class LineVisitor
LineVisitor是一个输出行遍历器，能够接受输出，然后逐行遍历输出

OnProcessOutput是处理输出内容的函数变量，输出将从标准输入传入

OnProcessLine是处理行的函数变量，传入的参数有
- $1: line(行的数据)
- $2: count(行数)

| 方法                            | 含义                          |
|---------------------------------|-------------------------------|
| `void AppendLine out...`             | 追加输出(不含换行，自动追加)  |
| `void ProcessOutput OnProcessOutput` | 用OnProcessOutput函数处理输出 |
| `void Visit OnProcessLine`           | 用OnProcessLine函数遍历输出   |

#### example
```sh
LineVisitor visitor
LineVisitor::AppendLine visitor "2 c d"
LineVisitor::AppendLine visitor "1 a b"
LineVisitor::AppendLine visitor "1 a b"

function MyOnProcessOutput()
{
    sort | uniq
}
LineVisitor::ProcessOutput visitor MyOnProcessOutput

function MyOnProcessLine()
{
    echo "MyOnProcessLine: '$1'"
    echo "MyOnProcessLine: '$2'"
}

LineVisitor::Visit visitor MyOnProcessLine
# MyOnProcessLine: '1 a b'
# MyOnProcessLine: '1'
# MyOnProcessLine: '2 c d'
# MyOnProcessLine: '2'
```

### module include

| 方法                                  | 含义                        |
|---------------------------------------|-----------------------------|
| `void include file`                   | 加载file文件                |
| `void include::research_path_add dir` | 增加dir到搜索路径里         |
| `void define_empty_function`          | 定义空函数                  |
| `void assert_fail message`            | 打印断言失败信息并dumpstack |
| `void call func args...`              | 尝试调用func args...函数    |
| `void slient args...`                 | 静音执行args...             |

### class FileLocker

| 方法                              | 含义               |
|-----------------------------------|--------------------|
| `FileLocker::FileLocker filepath` | 给filepath文件加锁 |
| `FileLocker::~FileLocker`         | 解开以前加的锁     |

### class ObjectV5

| 方法                                             | 含义                                     |
|--------------------------------------------------|------------------------------------------|
| `void ObjectV5::DefineClass classname statement` | 定义类classname                          |
| `void classname::AddProxy proxyfunc`             | 给类classname的对象增加代理函数proxyfunc |
| `void classname::DelProxy proxyfunc`             | 删除类classname的对象代理函数proxyfunc   |

### class ObjectV6

在ObjectV6::Call调用的函数里可以使用This系列调用，默认指代Call的对象

| 方法                                     | 含义                                         |
|------------------------------------------|----------------------------------------------|
| `void ObjectV6::NewId var type`          | 给`type`类型对象`var`分配ID                  |
| `void ObjectV6::SetProp var key val`     | 给对象`var`设置属性key=val                   |
| `void ObjectV6::GetProp var &key`        | 获取对象`var`属性key的值，值存在key里        |
| `void ObjectV6::SetFunc var name func`   | 给对象`var`设置函数name=func                 |
| `void ObjectV6::Call var name [args...]` | 调用对象`var`的函数name, 会修改This指向var   |
| `void ObjectV6::Typeof var &typename`    | 获取对象`var`的类型名，类型名存在typename里  |
| `bool ObjectV6::Instanceof var typename` | 判断对象`var`是否为`typename`类型            |
| `void ObjectV6::SetThisProp key val`     | 给对象`This`设置属性key=val                  |
| `void ObjectV6::GetThisProp &key`        | 获取对象`This`属性key的值，值存在key里       |
| `void ObjectV6::SetThisFunc name func`   | 给对象`This`设置函数name=func                |
| `void ObjectV6::CallThis name [args...]` | 调用对象`This`的函数name, 不会修改This指向                   |
| `void ObjectV6::TypeofThis &typename`    | 获取对象`This`的类型名，类型名存在typename里 |
| `bool ObjectV6::InstanceofThis typename` | 判断对象`This`是否为`typename`类型           |

### module Output

| 方法                                   | 含义                                           |
|----------------------------------------|------------------------------------------------|
| `string cctl str`                      | 输出控制颜色的函数ColorControl                 |
| `void   log_depth_inc`                 | 增加log输出的上升层级                          |
| `void   log_depth_dec`                 | 减少log输出的上升层级                          |
| `void   logd fmt args...`              | 以debug的等级打印log                           |
| `void   logi fmt args...`              | 以info的等级打印log                            |
| `void   logw fmt args...`              | 以warning的等级打印log                         |
| `void   loge fmt args...`              | 以error的等级打印log                           |
| `void   debuglog fmt args...`          | 打印debug日志，可在测试中开启                  |
| `void   print_code id file line range` | 打印编号为id，file的第line行上下range行的代码  |
| `string print_source number code`      | 输出code变量删除前number个空格的代码           |
| `void   dumpstack`                     | 打印调用栈                                     |
| `void   report action args...`         | 执行args...、打印action的前后、成功与失败的log |

### class ParallelV2

| 方法                                                             | 含义                                         |
|------------------------------------------------------------------|----------------------------------------------|
| `       ParallelV2::ParallelV2 [ncpu] [on_success] [on_failure]` | 创建并行结构obj，并行进程数量为ncpu，默认为4 |
| `void   ParallelV2::AddCommand name command`                     | 增加要执行的命令                             |
| `void   ParallelV2::Run`                                         | 运行并行结构                                 |
| `string ParallelV2::GetSuccessTasks`                             | 返回执行成功的task id列表                    |
| `string ParallelV2::GetFailureTasks`                             | 返回执行失败的task id列表                    |

#### ParallelV2Task结构含义说明
| 类型   | 成员    | 含义         |
|--------|---------|--------------|
| string | index   | 任务下标     |
| string | name    | 任务名       |
| string | outfile | 任务标准输出 |
| string | errfile | 任务错误输出 |
| array  | command | 任务命令     |
| string | pid     | 任务进程ID   |
| string | success | 任务是否成功 |

### class PythonV2

| 方法                                 | 含义                             |
|--------------------------------------|----------------------------------|
| `void PythonV2::StartServer`         | 启动python服务器                 |
| `void PythonV2::Exec code`           | 执行python代码code并且有返回消息 |
| `void PythonV2::ExecNoResponse code` | 执行python代码code但没有返回消息 |

### module regex

| 变量              | 含义       | 例子       |
|-------------------|------------|------------|
| regex_id          | 标识符     | regex_id   |
| regex_issue       | issue名    | I51LYO     |
| regex_dec_integer | 十进制整数 | 30, 29, -1 |
| regex_date        | 日期       | 2022-04-25 |
| regex_time        | 时间       | 19:11      |

### module test

术语:
- 断言: 必须成功，不成功就退出
- 期望: 应该成功，不成功就记录

| 方法                                            | 含义                                                      |
|-------------------------------------------------|-----------------------------------------------------------|
| `void   test::register_test testfunc`           | 注册测试函数testfunc                                      |
| `void   test::run_cmd cmd args...`              | 运行命令cmd args...并保存结果                             |
| `void   test::should_be str`                    | 期望上一次运行结果和str一样                               |
| `void   test::run_snapshot cmd args...`         | 期望运行命令cmd args...的结果和上一次运行结果(在目录)一样 |
| `void   test::must_be str`                      | 断言上一次运行结果和str一样                               |
| `void   test::should_return retval cmd args...` | 静音运行命令cmd args...并期望返回值为retval               |
| `void   test::should_return_true cmd args...`   | 静音运行命令cmd args...并期望返回值为0                    |
| `void   test::should_return_false cmd args...`  | 静音运行命令cmd args...并期望返回值不为0                  |
| `void   test::var_should_be var content`        | 期望变量var的内容和content一样                            |
| `void   test::run_tests options...`             | 带着options...运行所有注册函数                            |
| `string test::get_temp_path [testname]`         | 为testname生成临时文件名，默认testname为test              |

### Updater

| 方法                                     | 含义                                     |
|------------------------------------------|------------------------------------------|
| `bool Updater::IsValid`                  | 是否是合法的git仓库                      |
| `bool Updater::IsNew`                    | 是否有新版本                             |
| `bool Updater::CheckBranch branch_regex` | 检查分支是否满足branch_regex的正则表达式 |
| `bool Updater::CheckModify`              | 检查git仓库是否有修改                    |
| `void Updater::Update`                   | 更新已拉取到的新版本                     |
| `void Updater::Fetch`                    | 拉取git仓库的新版本                      |

### Waiting

| 方法                                 | 含义                                       |
|--------------------------------------|--------------------------------------------|
| `bool       Waiting::RunTask [cmd]` | 运行任务cmd，返回false就说明被SIGINT打断了 |
| `void       Waiting::KillTask`       | 停止任务                                   |
| `exitstatus Waiting::GetTaskStatus`  | 获取任务退出状态                           |

#### example
```sh
Waiting waiting
Waiting::RunTask waiting "sleep 10; exit 1"
if Waiting::IsInt waiting; then
    Waiting::KillTask
else
    if Waiting::GetTaskStatus waiting; then
        # ...
    else
        # ...
    fi
fi
```

### YamlV2

| 方法                               | 含义                      |
|------------------------------------|---------------------------|
| `       YamlV2::YamlV2 yamlpath`   | 打开在yamlpath的yaml文件  |
| `bool   YamlV2::IsValid`           | 是否是有效的yaml文件      |
| `bool   YamlV2::IsExists  keys...` | 检查是否存在keys...项     |
| `bool   YamlV2::IsArray   keys...` | 检查keys...项是否是数组   |
| `bool   YamlV2::IsObject  keys...` | 检查keys...项是否是对象   |
| `bool   YamlV2::IsString  keys...` | 检查keys...项是否是字符串 |
| `bool   YamlV2::IsBool    keys...` | 检查keys...项是否是布尔量 |
| `bool   YamlV2::IsInteger keys...` | 检查keys...项是否是整数   |
| `bool   YamlV2::IsFloat   keys...` | 检查keys...项是否是浮点数 |
| `bool   YamlV2::IsNull    keys...` | 检查keys...项是否是空值   |
| `string YamlV2::GetKeys   keys...` | 获取keys...对象的所有键   |
| `string YamlV2::GetVal    keys...` | 获取keys...项的值         |
| `string YamlV2::GetLen    keys...` | 获取keys...数组的长度     |