Dv4lua

介绍

这个工具主要功能是用来方便的执行一系列操作，如：自动化任务、文件备份、应用管理、执行命令，配置文件管理等。 由于自定义执行逻辑以配置文件的形式呈现过于复杂，本工具选择与Lua结合，以全局变量dv的形式提供API接口。

Note:

• 🚧：表示该功能尚未实现或存在问题

API

UM

UM类提供了用户管理的功能，主要用于添加用户。

以下是UM类的定义和成员函数：

---@class UM
---@field add_cur fun(this: UM, cfg: table)  # 声明方法
---@field add_ssh fun(this: UM, uid: string, cfg: table)  # 声明方法

cfg参数为用户配置表，可以任意添加字段。可以影响dv的行为字段如下：

Example:

dv.um:add_cur({
    mount = "~/.local/share/dv",
    os = "linux"
})
dv.um:add_ssh("remote_user", {
    hid = "remote_machine",
    mount = "~/.local/share/dv",
    os = "linux"
})

Note:

• 即便设置了os，dv仍然会尝试探测用户的操作系统，并在必要时覆盖该值。目前ssh用户的操作系统探测只支持linux（且需要先设置os为linux），其他操作系统的探测为TODO状态。

Op

Op类提供了一系列操作方法，主要用于执行命令、文件操作等。

以下是Op类的定义和成员函数：

---@class Op  # 定义 `Op` 类
---@field copy fun(this: Op, src: string, src_paths: string|table, dst: string, dst_paths: string|table, confirm: string?)
---@field exec fun(this: Op, uid: string, cmd: string, shell: string?)
---@field os fun(this: Op, uid: string)

Example:

dv.op:copy("this", "a/b/c", "remote_user", "a/b/c", "y") -- 拷贝文件
dv.op:copy("this", {"a/b/c", "a/b/d"}, "remote_user", {"a/b/c", "a/b/d"}, "u") -- 拷贝多个文件
dv.op:exec("this", "echo hello") -- 执行命令
dv.op:exec("this", "echo hello", "bash") -- 使用 bash 执行命令
local os = dv.op:os("this") -- 获取用户的操作系统

路径首先会尝试使用variable与环境变量展开，格式为${var}，如果是相对路径，则会尝试使用mount展开。

复制文件路径决定行为规则如下：

confirm为y（覆盖），u（更新），n（不变）组成的字符串。

Check

根据源文件与目标文件状态，检查可执行操作的类型。

Match

根据confirm参数，按顺序匹配可执行操作的类型。

Example:

如果可以确定result则执行result操作，否则进入交互模式。

Dot

Dot类提供了配置文件的管理功能，主要用于加载配置文件、备份配置文件等。 以下是Dot类的定义和成员函数：

---@class Dot
---@field confirm fun(this: Dot, default: string)
---@field add_schema fun(this: Dot, name: string, path: string)
---@field add_source fun(this: Dot, name: string, path: string)
---@field sync fun(this: Dot, apps: table, uid: string)

confirm方法用于配置复制文件时的默认方式，参见Op

Schema格式举例如下：

name = "default"

[schemas.fish.repo.linux.paths]
default = ["~/.config/fish"]

[schemas.alacritty.repo.windows.paths]
default = ["${APPDATA}/alacritty/alacritty.toml"]

[schemas.alacritty.repo.unix.paths]
default = [
  "${XDG_CONFIG_HOME}/alacritty/alacritty.toml",
  "${XDG_CONFIG_HOME}/alacritty.toml",
  "~/.config/alacritty/alacritty.toml",
  "~/.alacritty.toml",
]

[schemas.fcitx5.repo.linux.paths]
data = ["~/.local/share/fcitx5"]
default = ["~/.config/fcitx5"]

name为配置文件的名称，paths中每一项为一个配置文件的所有可能路径。 对于以上配置文件，解析如下：

• fish配置文件在linux下的配置文件default路径为~/.config/fish
• alacritty配置文件在windows下的配置文件default路径为${APPDATA}/alacritty/alacritty.toml，注意${APPDATA}将会被展开
• alacritty配置文件在unix下的配置文件default路径有四个可能的路径
• fcitx5配置文件在linux下的配置文件data路径为~/.local/share/fcitx5，default路径为~/.config/fcitx5

add_schema方法用于添加配置文件的schema，目前只支持以uid和path为参数加载配置文件

Source格式与Schema相同，举例如下：

name = "default"

[schemas.fish.repo.linux.paths]
default = ["fish"]

[schemas.alacritty.repo.unknown.paths]
default = ["alacritty/alacritty.toml"]

[schemas.fcitx5.repo.linux.paths]
default = ["fcitx5/config"]
data = ["fcitx5/data"]

add_source方法用于添加配置文件的源，目前只支持以uid和path为参数加载配置文件。 默认会加载path目录下config.toml文件作为配置文件，所有paths会被以path为前缀进行拼接。

sync方法用于同步配置文件到指定用户，apps参数为一个列表，每个元素为一个配置文件的名称，uid参数为用户的id。

Example:

dv.dot:add_schema("default", "path/to/schema.toml")
dv.dot:add_source("default", "path/to/source")
dv.dot:sync({"fish", "alacritty", "fcitx5"}, "remote_user")

Pm

Pm类提供了一些包管理器的功能，主要用于安装、更新软件包。

以下是Pm类的定义和成员函数：

---@class Pm
---@field install fun(this: Pm, hid: string, pkg: string, yes: boolean?)
---@field update fun(this: Pm, hid: string, yes: boolean?)
---@field upgrade fun(this: Pm, hid: string, yes: boolean?)

install方法用于安装软件包，pkg参数为软件包名称（可以是多个软件包，用空格分隔），yes参数为是否自动确认安装。

对包管理器的支持如下：

• apt（Debian/Ubuntu）
• apk（Alpine）
• yay（Arch Based Linux）
• dnf（Fedora）🚧
• pacman（Arch Based Linux）
• paru（Arch Based Linux）
• winget（Windows）🚧

Note：注意需要的是设备hid，而不是用户的uid。

Example:

dv.um:add_ssh("remote_user", {
    hid = "remote_machine",
    mount = "~/.local/share/dv",
    os = "linux"
})
dv.pm:install("remote_machine", "git neovim", true) -- 安装 git 和 vim
dv.pm:update("remote_machine", true) -- 更新软件包
dv.pm:upgrade("remote_machine", true) -- 升级软件包

CLI

dv4lua命令行工具的使用方法如下：

Simple CLI to use dv-api with lua

Usage: dv4lua [OPTIONS] [ENTRY] [RARGS]...

Arguments:
  [ENTRY]     The entry point of the script [default: Main]
  [RARGS]...  Arguments to pass to the entry point

Options:
  -b, --dbpath <DBPATH>        cache database path [default: $directory/.cache]
  -c, --config <CONFIG>        The config file to use [default: $directory/config.lua]
  -d, --directory <DIRECTORY>  The directory to use for the config and cache [default: /home/km/.config/dv/]
  -n, --dry-run                Do not actually modify anything
  -h, --help                   Print help
  -V, --version                Print version