README

Traindown是一种受Markdown启发的语言，帮助运动员轻松记录他们的训练。

请访问网站以获取更多信息以及从用户角度如何使用它。

版本：此库目前旨在支持规范的v1.2.1版本。

进行中

请理解，此库仍在开发中，目前仅实现了规范和一些访问结果数据的基本功能。甚至还没有对其进行测试。

肯定还有待解决的问题。

未来的版本将包含更多功能来访问结果数据，并将其转换为其他格式，如JSON。

安装

composer install traindown/traindown-php

目前，唯一的要求是PHP > 8.0和Mbstring扩展。这并非一成不变。

使用

基本使用相当直观

$file = '
@ 2021-01-01

* This is an example note!

# example metadata key: value

Bench Press:
  500
';

$parser = new Parser();
$document = $parser->parse($file);

foreach($document->getSessions() as $session) {
    // do something... 
}

您可以在不创建新的Parser实例的情况下对多个文件运行$parser->parse($file)。内部状态将在每次调用时重置。

错误

在基本设置中，未知和意外的标记会被静默忽略，解析器将继续处理文档的其余部分。这些不良标记可以通过Parser对象本身访问

$parser->hasBadTokens(); // bool
$parser->getBadTokens(); // array of the bad tokens

例如，在解析字符串bw+25a时，生成了两个标记：一个值为'bw+25'的T_LOAD和一个值为'a'的T_UNKNOWN。这遵循了身体重量负载的规范，但与JS实现的行为有所不同，JS实现会接受'a'作为身体重量值的一部分。

如果您希望抛出异常，则在实例化Parser时传递true，任何不良标记都将立即抛出BadTokenException。

$file = '
# Bad metadata
';

$parser = new Parser(true);

$document = $parser->parse($file); // Throws BadTokenException

BadTokenException包含相关的标记。如果标记是TokenType::T_UNKNOWN，则它是一个'未知'标记，对词法分析器不可识别。如果标记是任何其他类型，则它是一个'意外'标记，出现在不应出现的位置。

Traindown对象

此库将Traindown字符串解析为一系列来自Traindown\Traindown命名空间的对象。

将其想象成一棵树，其中Document是根。它包含Sessions，其中包含Movements，其中包含Performances。所有这些都有元数据，形式为Notes（单行注释）和Data（键值对，规范中称为"元数据"）以及通过HasMetadata特质的相应getter和setter。

Document

Document具有以下方法

$document->getSessions(); // array of Session

$document->addSession(Session $session); // to add a single Session

Session

Session具有以下方法

$session->getDate(); // DateTime
$session->hasDefaultDate(); // bool, true if date failed to parse
$session->getMovements(); // array of Movement

$session->setDatetime(Token $token); // Takes a Token of TokenType::T_DATETIME
$session->addMovement(Movement $movement); // to add a single Movement

传入的T_DATETIME值（因此用户可以在其文档中输入）简单地通过new DateTime($value)进行解析，因此非常宽容。有关接受的格式的刷新信息，请参阅手册。如果值无法正确渲染，则设置datetime为now，并将defaultDate属性设置为true。

Movement

Movement具有以下方法

$movement->getName(); // string
$movement->isSuperset(); // bool
$movement->getSequence(); // int
$movement->getPerformances(); // array of Performance

$movement->addPerformance(Performance $performance); // to add a single Performance

Movement 构造函数接受一个 TokenType::T_MOVEMENT 和一个序列号以确定其在文档中的顺序。

性能

Performance 拥有以下方法

$performance->getLoad(); // ?float, default is null because it must be set
$performance->getReps(); // float, defaults to 1 if not set
$performance->getSets(); // float, defaults to 1 if not set
$performance->getFails(); // float, defaults to 0 if not set
$performance->getRaw(string $prop); // ?float, returns the property without default value, good for checking if a prop was manually set or not.

$performance->isValid(); // bool, returns true if load has been set

$performance->setLoad(Token $token); // Takes a token of TokenType::T_LOAD
$performance->setReps(Token $token); // Takes a token of TokenType::T_REPS
$performance->setSets(Token $token); // Takes a token of TokenType::T_SETS
$performance->setFails(Token $token); // Takes a token of TokenType::T_FAILS

数据

数据（在规范中称为元数据）有这些方法

$data->getKey(); // string
$data->getValue(); // string
$data->getDataPair(); // [$key => $value]

Data 构造函数接受一个 TokenType::T_METADATA 的令牌。

注意

Note 拥有以下方法

$note->getValue(); // string

Note 构造函数接受一个 TokenType::T_NOTE 的令牌。