How to Include External Files in PlantUML for Gantt Diagram Custom Functions?

I am working on a Gantt diagram using PlantUML. Due to the nature of Gantt charts, I needed a way to convert arbitrary dates into epoch_time. Since PlantUML doesn’t seem to provide a built-in function for this, I created a custom function to handle the conversion.

Here is the function I implemented:
https://gist.github.com/topchul/e635a3003ab1387d2fc9d92a09dc0249

I included the function directly inside an @startgantt block and verified that it works as expected. However, when I try to reference this function from multiple .pu files using !include, I encounter issues.

Here’s the problem:

• When using !include with a local file, it throws an error.
• When using !include with the raw Gist URL, the diagram generation halts, and the !dump_memory command doesn’t execute.

Here is a sample script demonstrating the issue:

@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

Questions:

1. Can you provide an example of how to properly use !include for external files in PlantUML?
2. Is there any workaround or best practice to include a custom function like mine across multiple .pu files?
3. If possible, could you help resolve the specific issue I am facing?

Any guidance or recommendations would be greatly appreciated.

Thank you!

After reviewing my original code, I realized the root cause of the issue was a missing !return statement and the critical !endfunction declaration. These were omitted right before the @enduml tag in my initial implementation. Unfortunately, PlantUML doesn't provide a helpful error message in this case, which made debugging a bit challenging. It was a good reminder of how tricky it can be to review one's own code objectively.

That said, I’ve resolved the issue! Along the way, I also identified and fixed a related bug: when using %date("YYYY-MM-dd", %now()), failing to use the correct format string ("yyyy-MM-dd") could lead to errors after "2024-12-28". This issue has been addressed in my updated code.

For anyone struggling with converting dates to epoch_time, the logic isn’t overly complex, but feel free to refer to my solution below.

Resources:

• Stable Gist Code: Gantt Utilities for PlantUML
• Example of !include Usage: GRPlantUMLUtilities Test Cases
• Original Code with Missing !endfunction: Problematic Gist

Hopefully, this helps others avoid similar pitfalls!