16个版本
| 0.1.14 | 2024年7月9日 |
|---|---|
| 0.1.13 | 2024年2月9日 |
| 0.1.12 | 2024年1月30日 |
| 0.1.8 | 2023年11月15日 |
| 0.1.4 | 2022年11月6日 |
#252在解析器实现
每月206次下载
68KB
1.5K SLoC
gigtag
轻量级的文本标签系统，旨在为DJ管理自定义元数据。
结构
gig tag是一个具有以下预定义字段或组件的平面结构：
- 标签
- 方面（包括可选的日历日期）
- 属性
所有组件都是可选的，以下有一些限制：
- 有效的gig tag必须有一个标签或一个方面。
- 有效的gig tag只有方面，既没有标签也没有属性，如果方面有日期后缀，则是有效的
标签
标签是一个非空字符串，包含任意文本，没有前导/尾随空白。
标签应由用户编辑，并在UI中以原始形式显示。
示例
| 标签 | 评论 |
|---|---|
愿望清单 |
单个单词 |
地板填充物 |
以PascalCase连接的多个单词 |
地板填充物 |
以空格分隔的多个单词 |
方面
适用于标签的内容规则也适用于方面。此外，方面不得以反斜杠字符开始，否则会与序列化格式冲突（见下文）。
方面与标签具有不同的语义目的。它们用于分类、命名空间或对一组标签进行分组，或用于定义相关属性的上下文。
方面应表示预定义标识符，既不可编辑也不直接在UI中显示。
日期类型方面
可以保留后缀将日历日期编码到方面。
以8位十进制数字结束的方面，后面跟着一个@字符，被认为是日期类型方面。数字应编码ISO 8601日历日期，不包含时区，格式为yyyyMMdd。
即使8位十进制数字不编码有效日期，也视为日期类型。这种较宽松的约束是故意选择的，以便可以使用正则表达式识别日期类型方面。
日期后缀中的 @ 字符必须紧跟在前面文本之后，中间不能有空格。因此，在去除日期后缀后剩下的前缀仍然是有效的属性。
以下正则表达式可以用来
| 正则表达式 | 描述 |
|---|---|
(^|[^\s])@\d{8}$ |
识别日期类似的属性 |
[\s]+@\d{8}$ |
如果前面有空格，则拒绝具有日期后缀的属性 |
有效示例
| 方面 | 描述 |
|---|---|
spotify |
一个用于编码与 Spotify 相关属性的标签 |
@20220625 |
没有前缀的日期类似属性，表示任何时区的日历日 2022-06-25 |
wishlist@20220625 |
具有前缀 wishlist 的日期类似属性，表示任何时区的日历日 2022-06-25 |
@00000000 |
没有前缀和无效日期的日期类似属性 |
abc xyz@99999999 |
具有前缀 abc xyz 和无效日期的日期类似属性 |
无效示例
| 方面 | 描述 |
|---|---|
played@20220625 |
包含日期后缀之前有空格的前缀的无效日期类似属性 |
属性
可以将自定义 属性附加到标签上，简称 props。
属性以非空、有序的 列表 的形式表示。
名称 是非空字符串，包含任意文本，没有前导/尾随空格。没有对名称唯一性的限制，即允许重复名称。
值 是任意字符串，没有任何限制。允许空值。
应用程序负责在其相应上下文中解释名称和值。属性可以用于定义此上下文。
序列化
单个标签
单个标签编码为 URI。
URI = scheme ":" ["//" authority] path ["?" query] ["#" fragment]>authority = [userinfo "@"] host [":" port]
只有 路径、查询 和 片段 组件可以存在。所有其他组件都必须不存在，即 URI 字符串必须既不包含 方案 也不包含 授权 组件。
以下表格定义了组件映射
| 标签组件 | URI 组件 | 百分号编码字符集 |
|---|---|---|
| 标签 | 片段 | 片段百分号编码集 + '%' |
| 属性 | 路径 | 路径百分号编码集 + '%' |
| props（名称/值） | 查询 | 查询百分号编码集 + '%' + '&' + '=' |
标签及其各自的URI被序列化为文本，并按照RFC 2396/1738进行百分号编码。上述表格指定了每个标签组件需要编码的字符。属性名/值分别进行编码。
在解析URI字符串中的gig标签时，空组件被视为不存在。
示例
以下示例显示了空组件的编码字符串变异，这些空组件在解码URI时将被忽略。
| 编码 | 方面 | 日期 | 标签 | 属性：名称 | 属性：值 |
|---|---|---|---|---|---|
#MyTag?#MyTag |
MyTag |
||||
wishlist@20220625#为%20you |
wishlist@20220625 |
2022-06-25 | 为你 |
||
played@20220625played@20220625?played20220625#played@20220625?# |
played@20220625 |
2022-06-25 | |||
audio-features?energy=0.78&valence=0.61audio-features?energy=0.78&valence=0.61# |
audio-features |
energyvalence |
0.780.61 |
示例（无效）
以下令牌不代表有效的gig标签
| 编码 | 评论 |
|---|---|
https://#MyTag |
存在URL方案/权限 |
My%20Tag |
仅有一个没有日期的方面，既没有标签也没有属性 |
/my-facet#Label |
方面以/开头 |
wishlist%20@20220625#标签 |
方面中的日期后缀前有空白字符 |
?=val#标签 |
空属性名 |
?name=my+val#My label |
特殊字符如+和空白字符不进行百分号编码 |
# |
空标签被视为不存在 |
? |
空方面和属性被视为不存在 |
?# |
空方面、属性和标签被视为不存在 |
多个标签
格式化
通过连接相应的、编码的URI，对多个标签进行格式化和存储为文本。后续URI由空白字符分隔，例如单个ASCII空格字符。
后配
通常无法将编码的gig标签存储在预留字段中。在这种情况下，gig标签可以与任何文本字段一起附加，通过与前一个文本中的任意空白字符进行分隔。
解析
文本被分割成由空白字符分隔的令牌。解析从最后一个令牌开始，从后向前继续。它停止遇到一个无法解析为有效gig标签的令牌。
后配
第一个无法解析为有效gig标签的令牌被视为前一个文本的最后一个令牌。包括此令牌及其前第一个有效gig标签令牌之间的空白字符必须保留为未解码的前缀。
在重新编码gig标签时，在解析过程中捕获的未解码的前缀必须附加到重新编码的gig标签字符串前。此规则确保在解码/重新编码往返过程中只能丢失空白字符，即在不故意解析前一个文本中的任意单词作为有效gig标签（假阳性）时。
存储
文件元数据
包含编码gig标签的文本（通过空白字符分隔）附加到音频文件的内容组字段
- ID3v2:
GRP1（主要/首选）/TIT11（传统/备用） - Vorbis:
GROUPING - MPEG-4:
©grp
许可
根据Mozilla公共许可证2.0（MPL-2.0）许可（见MPL-2.0.txt或https://www.mozilla.org/MPL/2.0/）。
本开源许可证的权限取决于提供受许可文件的源代码及其修改版本，这些修改版本应使用相同的许可证（或在某些情况下，使用GNU许可证之一）。必须保留版权和许可证声明。贡献者提供专利权的明确授予。然而，使用许可作品的较大作品可能根据不同的条款进行分发，并且不提供较大作品中添加的文件的源代码。
贡献
您有意提交以包含在作品中的任何贡献均应按照Mozilla公共许可证2.0（MPL-2.0）进行许可。
必须在每个文件的顶部添加以下带有相应SPDX简短标识符的标题。
// SPDX-License-Identifier: MPL-2.0
依赖关系
约5-7MB
约151K SLoC