如何在 PlantUML 中包含外部文件以实现甘特图自定义功能？

Question

我正在使用 PlantUML 制作甘特图。由于甘特图的性质，我需要一种将任意日期转换为

epoch_time

的方法。由于 PlantUML 似乎没有为此提供内置函数，因此我创建了一个自定义函数来处理转换。

这是我实现的功能：
https://gist.github.com/topchul/e635a3003ab1387d2fc9d92a09dc0249

我将该函数直接包含在

@startgantt

块中，并验证它是否按预期工作。但是，当我尝试使用

.pu

从多个

!include

文件引用此函数时，我遇到了问题。

问题来了：

• 将

  !include

  与本地文件一起使用时，会抛出错误。
• 将

  !include

  与原始 Gist URL 一起使用时，图表生成会停止，并且

  !dump_memory

  命令不会执行。

这是演示该问题的示例脚本：

@startuml test
' !include to_epoch_time.pu

[%filename() - 2 ]
[%file_exists("https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time.pu") - exists 1]
[%file_exists("https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time_1.pu") - exists 2]

' !include https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time.pu
' !include https://gist.githubusercontent.com/topchul/e635a3003ab1387d2fc9d92a09dc0249/raw/9a0cb98438d43c8099e0c1f2266b864eadbe2a17/to_epoch_time_1.pu
!dump_memory
[$to_epoch_time("2024-01-01")]
@enduml

问题：

1. 您能否提供一个如何在 PlantUML 中正确使用

   !include

   来处理外部文件的示例？
2. 是否有任何解决方法或最佳实践可以在多个

   .pu

   文件中包含像我这样的自定义函数？
3. 如果可以的话，您能帮助解决我面临的具体问题吗？

任何指导或建议将不胜感激。

谢谢！

Answer 1

查看原始代码后，我意识到问题的根本原因是缺少

!return

语句和关键的

!endfunction

声明。在我最初的实现中，这些在

@enduml

标签之前被省略了。不幸的是，PlantUML 在这种情况下没有提供有用的错误消息，这使得调试有点困难。这很好地提醒了我们客观地审查自己的代码是多么困难。

也就是说，我已经解决了这个问题！在此过程中，我还发现并修复了一个相关的错误：使用

%date("YYYY-MM-dd", %now())

时，未能使用正确的格式字符串 (

"yyyy-MM-dd"

) 可能会导致“2024-12-28”之后出现错误。这个问题已在我更新的代码中得到解决。

对于任何努力将日期转换为

epoch_time

的人来说，逻辑并不太复杂，但请随意参考下面我的解决方案。

资源：

• 稳定的要点代码：PlantUML 的甘特图实用程序

• !include

  用法示例：GRPlantUMLUtilities 测试用例
• 缺失的原始代码

  !endfunction

  ：有问题的要点

希望这可以帮助其他人避免类似的陷阱！