# ahk-custom-config

**Repository Path**: dkwd/ahk-custom-config

## Basic Information

- **Project Name**: ahk-custom-config
- **Description**: 使用ahk编写的自定义配置文件解析工具。此工具的目的是替代ini文件，提供更强大的语法和更简洁的api，且它的编写足够简单，可以轻松在记事本中编辑。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2024-07-30
- **Last Updated**: 2025-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AutoHotkey

## README

# 介绍

CustomFs.ahk，使用ahk编写的自定义配置文件解析工具。

此工具的目的是替代`ini`文件，提供更强大的语法和更简洁的api。

它的编写足够简单，可以轻松在记事本中编辑。

# 语法与设计

文件语法具有以下特点：
- 字段都是`KV`键值对
- 去除层级表示
- 键不区分大小写
- 键中不能有空格

下面是具体的语法描述。

# 注释

> 仅支持单行注释

注释以`#`或`---`开头，`#`形式支持尾随注释。

```text
# 注释
key : val # 

---
```

# 数据类型

- 基本（一对一）
- 数组（一对多，子项为基本类型）
- 对象（一对多，子项为键值类型）

## 1. 基本

使用`:`分隔，`:`左右的空格会被忽略。

```text
foo : bar # 字符串
```

## 2. 数组

数组键以`:`结尾，子项以`-`开头

> 子项必须连续，且子项不能为空值或没有子项

```text
arr :  # 数组
- item1
- item2
```

## 3. 对象

对象键以`:`结尾，子项以`+`开头

> 子项必须连续，且子项不能为空值或没有子项

```text
obj :
+ k1 : v1
+ k2 : v2
```

## 4. 压缩数组

压缩数组允许在一行内定义数组，此时数组子项无法设置注释。

除普通数组子项规则外，特殊字符`,[]`需要用引号包围，引号需要转义。

```
zipArr : [ abc, ', []`'', $A_User$ ]  # zip array
```


# 导入文件


导入以`@`符开头，导入语法分全局与局部。

全局导入必须在文档开头（数据之前）。
> 文件不可重复导入

```text
# 导入前可以写注释
@./1.txt  # 全局导入

foo: @./2.txt  # 局部导入
@./3.txt  # 错误
```

# 修饰符

## 重要符*

`*`符标记该数据为不可覆盖，限定不可再用此键命名。

```text
*foo : bar
```

## 原义符~

`~`符设置值为原义串，值部分无需转义.

> 此时`:`右边的空格会被当作值的一部分而不是忽略。

```text
~raw :: $#
```

# 函数

函数形式如下：

```
&func(a, b) : http://{a}:{b}
```

其中：

- `&`标识此行定义一个函数，
- `(a, b)`定义两个参数
- `http://{a}:{b}`定义方法体，在`{}`中填入参数

> 注意：
> `{`与`}`在方法体中是特殊字符，且没有为其设计转义语法。

## 使用函数

下面的例子定义一系列虚拟机ip及一些中间件，通过指定`A_URL`引用的值可以方便的切换使用的虚拟机：

```
vm-1  : 192.168.6.100
vm-2  : 192.168.6.101
A_URL : $vm-1$           # 设置当前ip

&http(_) : http://$A_URL$:{_}   # 函数，接受一个参数用来指定端口

rabbitmq : $http(15672)$   # 传递端口
minio    : $http(9090)$
```

> 脚本预设一些字符串操作函数，如uc表示StrUpper

因为使用函数的方式和引用变量的方式相同，所以要在函数调用的参数中使用引用会出现冲突；  
故设计：在函数调用的参数中使用`&`引用变量。

```
str : string
uc  : $uc(&str)$
```

# 引用

使用`$`包裹的内容会被当作引用字段。可以在所有值中引用，而键不可以。  

脚本提供一组预设的引用值，可以在脚本中引用，可用预设值包括但不限于：
```A_MyDocuments, A_UserName,A_Startup, A_Now, A_Desktop, A_ScriptDir, A_ScriptFullPath```

```text
foo : bar
baz : $foo$-baz  # bar-baz
```

## 复杂类型上的引用

使用`[]`引用复杂类型的子项。

> 引用的对象是复杂类型（对象或数组），将直接返回对象的引用。  

```text
# 使用 [] 引用复杂类型的子项
ref1 : 'hello $arr[1]$'  # 引用数组子项
ref2 : $obj[a]$  # 引用对象子项

# 直接引用复杂类型
refO : e$obj$  # 引用对象，e被忽略，并抛出警告
refA : $arr$e  # 引用数组，e被忽略（停止解析），并抛出警告
```


# 转义

使用\`(重音符)转义。
键中只有会造成混淆的关键字符需转义，如`-#+`；
值中出现的关键符大部分都需要转义。

最好的办法是在可能需要转义的地方都进行转义，因为转义普通字符不会造成任何错误。

```text
esc-1 : `'`$``  # '$`，确实需要转义的字符
esc-2 : `a`b`c  # abc，即使这些字符不需要转义
```

# 值中的空格

解析中使用空格作为停止解析的标志，所以在使用到空格的地方需要特别处理。

使用`'`包围使用空格的值，以下两种方式结果相同。

```text
foo : bar' 'baz  # bar baz
foo : 'bar baz'  # bar baz
```

# 自定义

可以修改几乎所有具有特殊意义的字符，这些符号在脚本中设置为变量。



# 两个版本的区别

目录下，有两个AHK脚本，其中一个带有`EX`后缀，代表具有更多的扩展功能。包括：

- 可以修改数据并写入到文件
- 可以格式化文档，使其更美观

> 因为实现上面的功能用了不少的代码，所以提供了两个版本。

另一个版本只能读取文件，而没有其他功能。

## 建议

在大多数情况下都是只有读取的需求，那么引入普通版本即可；  
而，当需要**修改**数据并写入到文件时，引入**EX**版本。

# 完善的示例

`test`目录下提供了完整的测试与案例。  
`misc`目录下提供了某些语法的demo实现。  
仓库`ahk-meow-tool`中大量使用了此配置文件脚本，是很好的参考。

# 结语

`2024/08/10`，完善了脚本的测试及README，此仓库将告一段落。