[Puml Parser] Support free functions in class diagram

plantuml/parser/README.md

@@ -98,4 +98,5 @@ For the detailed design and users Guide, see `docs/README.md` in the source tree
 Authoring guides:
 
 - [`docs/element-identifiers.md`](docs/element-identifiers.md) — how element identifiers are constructed and how to link component, class, and sequence diagrams
+- [`docs/class-diagram.md`](docs/class-diagram.md) — class-diagram syntax and free-function conventions
 - [`docs/sequence-diagram.md`](docs/sequence-diagram.md) — supported sequence diagram syntax and semantics

plantuml/parser/docs/class-diagram.md

@@ -0,0 +1,54 @@
+<!-- ----------------------------------------------------------------------------
+  Copyright (c) 2026 Contributors to the Eclipse Foundation
+
+  See the NOTICE file(s) distributed with this work for additional
+  information regarding copyright ownership.
+
+  This program and the accompanying materials are made available under the
+  terms of the Apache License Version 2.0 which is available at
+  https://www.apache.org/licenses/LICENSE-2.0
+
+  SPDX-License-Identifier: Apache-2.0
+----------------------------------------------------------------------------- -->
+
+# Class Diagram Support Guide
+
+This guide describes class-diagram syntax that has specific semantic meaning in
+the PlantUML parser and resolver.
+
+## Free functions
+
+Use an `entity` with the `<<function>>` stereotype to group free functions.
+The entity is a syntactic container only and is omitted from the resolved
+class-diagram model. Its methods resolve as free functions in the enclosing
+namespace.
+
+```plantuml
+@startuml algorithms
+namespace amp {
+    namespace algorithm {
+        entity Placeholder <<function>> {
+            + clamp(value, min, max)
+            + max<T>(a, b)
+        }
+    }
+}
+@enduml
+```
+
+This resolves to the free functions `amp.algorithm.clamp` and `amp.algorithm.max`.
+Visibility markers such as `+` are accepted for PlantUML compatibility and do not
+affect free-function semantics.
+
+The parser currently preserves only the entity's name, namespace, package,
+stereotypes, and methods. Entity-level template parameters, `extends` and
+`implements` clauses, attributes, and `using` type aliases are not represented
+in the entity model. The grammar may accept these constructs, but the parser
+silently drops them, so do not rely on them. Use method-level template
+parameters for templated free functions.
+
+An `entity` without `<<function>>` is not modeled as a class-diagram entity.
+Use the corresponding PlantUML declaration (`class`, `interface`, or `struct`)
+to model those element kinds. The `entity <<function>>` handling is a focused
+extension for grouping free functions, not a general substitute for those
+declarations.

plantuml/parser/integration_test/class_diagram/free_function_entity/free_function_entity.puml

@@ -0,0 +1,29 @@
+' *******************************************************************************
+' Copyright (c) 2026 Contributors to the Eclipse Foundation
+'
+' See the NOTICE file(s) distributed with this work for additional
+' information regarding copyright ownership.
+'
+' This program and the accompanying materials are made available under the
+' terms of the Apache License Version 2.0 which is available at
+' https://www.apache.org/licenses/LICENSE-2.0
+'
+' SPDX-License-Identifier: Apache-2.0
+' *******************************************************************************
+
+@startuml free_function_entity
+
+namespace amp {
+    namespace algorithm {
+        entity Placeholder <<function>> {
+            + clamp(value, min, max)
+            + Submit<CallableType, ArgumentTypes...>(callable, arguments)
+        }
+    }
+}
+
+entity amp.algorithm.Qualified <<function>> {
+    + qualified()
+}
+
+@enduml

plantuml/parser/integration_test/class_diagram/free_function_entity/output.json

@@ -0,0 +1,81 @@
+{
+  "free_function_entity.puml": {
+    "name": "free_function_entity",
+    "entities": [],
+    "free_functions": [
+      {
+        "name": "clamp",
+        "enclosing_namespace_id": "amp.algorithm",
+        "return_type": null,
+        "parameters": [
+          {
+            "name": "value",
+            "param_type": null,
+            "is_variadic": false
+          },
+          {
+            "name": "min",
+            "param_type": null,
+            "is_variadic": false
+          },
+          {
+            "name": "max",
+            "param_type": null,
+            "is_variadic": false
+          }
+        ],
+        "template_parameters": null,
+        "source_location": {
+          "file": "",
+          "line": 19
+        }
+      },
+      {
+        "name": "Submit",
+        "enclosing_namespace_id": "amp.algorithm",
+        "return_type": null,
+        "parameters": [
+          {
+            "name": "callable",
+            "param_type": null,
+            "is_variadic": false
+          },
+          {
+            "name": "arguments",
+            "param_type": null,
+            "is_variadic": false
+          }
+        ],
+        "template_parameters": [
+          {
+            "Type": {
+              "name": "CallableType",
+              "is_pack": false
+            }
+          },
+          {
+            "Type": {
+              "name": "ArgumentTypes",
+              "is_pack": true
+            }
+          }
+        ],
+        "source_location": {
+          "file": "",
+          "line": 20
+        }
+      },
+      {
+        "name": "qualified",
+        "enclosing_namespace_id": "amp.algorithm",
+        "return_type": null,
+        "parameters": [],
+        "template_parameters": null,
+        "source_location": {
+          "file": "",
+          "line": 26
+        }
+      }
+    ]
+  }
+}

plantuml/parser/puml_parser/src/class_diagram/src/class_ast.rs

@@ -29,24 +29,27 @@ pub enum Visibility {
 pub enum Element {
     ClassDef(ClassDef),
     StructDef(StructDef),
-    EnumDef(EnumDef),
     InterfaceDef(InterfaceDef),
+    EntityDef(EntityDef),
+    EnumDef(EnumDef),
 }
 impl Element {
     pub fn set_namespace(&mut self, ns: String) {
         match self {
             Element::ClassDef(def) => def.namespace = ns,
             Element::StructDef(def) => def.namespace = ns,
-            Element::EnumDef(def) => def.namespace = ns,
             Element::InterfaceDef(def) => def.namespace = ns,
+            Element::EntityDef(def) => def.namespace = ns,
+            Element::EnumDef(def) => def.namespace = ns,
         }
     }
     pub fn set_package(&mut self, ns: String) {
         match self {
             Element::ClassDef(def) => def.package = ns,
             Element::StructDef(def) => def.package = ns,
-            Element::EnumDef(def) => def.package = ns,
             Element::InterfaceDef(def) => def.package = ns,
+            Element::EntityDef(def) => def.package = ns,
+            Element::EnumDef(def) => def.package = ns,
         }
     }
 }
@@ -268,6 +271,17 @@ impl TypeDef for InterfaceDef {
     }
 }
 
+#[derive(Debug, Default, Serialize, Deserialize, PartialEq)]
+pub struct EntityDef {
+    pub name: Name,
+    pub namespace: String,
+    pub package: String,
+    #[serde(default)]
+    pub stereotypes: Vec<String>,
+    pub methods: Vec<Method>,
+    pub source_location: SourceLocation,
+}
+
 #[derive(Debug, Default, Serialize, Deserialize, PartialEq)]
 pub struct EnumDef {
     pub name: Name,
@@ -481,6 +495,7 @@ mod tests {
             Element::StructDef(StructDef::default()),
             Element::EnumDef(EnumDef::default()),
             Element::InterfaceDef(InterfaceDef::default()),
+            Element::EntityDef(EntityDef::default()),
         ];
 
         for el in elements.iter_mut() {
@@ -493,6 +508,7 @@ mod tests {
                 Element::StructDef(d) => assert_eq!(d.namespace, "test_ns"),
                 Element::EnumDef(d) => assert_eq!(d.namespace, "test_ns"),
                 Element::InterfaceDef(d) => assert_eq!(d.namespace, "test_ns"),
+                Element::EntityDef(d) => assert_eq!(d.namespace, "test_ns"),
             }
         }
     }

plantuml/parser/puml_parser/src/class_diagram/src/class_parser.rs

@@ -11,9 +11,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // *******************************************************************************
 use crate::class_ast::{
-    Arrow, Attribute, ClassDef, ClassUmlFile, ClassUmlTopLevel, Element, EnumDef, EnumItem,
-    EnumValue, InterfaceDef, Method, Name, Namespace, Package, Param, Relationship, StructDef,
-    TypeAlias, Visibility,
+    Arrow, Attribute, ClassDef, ClassUmlFile, ClassUmlTopLevel, Element, EntityDef, EnumDef,
+    EnumItem, EnumValue, InterfaceDef, Method, Name, Namespace, Package, Param, Relationship,
+    StructDef, TypeAlias, Visibility,
 };
 use crate::class_traits::{TypeDef, WritableName};
 use crate::source_map::{
@@ -747,31 +747,30 @@ impl ClassParseSession<'_> {
         let implements_targets = collect_implements_targets(pair.clone());
 
         match kind.as_str() {
-            "abstract class" => {
+            "abstract class" | "class" => {
                 let mut def = self.parse_type_def_into::<ClassDef>(pair)?;
-                def.source_location = source_location;
-                def.is_abstract = true;
                 def.template_parameters = resolve_type_template_parameters(
                     explicit_template_parameters,
                     &def.name,
                     &raw_type_def,
                 );
-                def.extends = extends_targets;
-                def.implements = implements_targets;
-                Ok(Element::ClassDef(def))
-            }
-            "class" => {
-                let mut def = self.parse_type_def_into::<ClassDef>(pair)?;
                 def.source_location = source_location;
-                def.template_parameters = resolve_type_template_parameters(
-                    explicit_template_parameters,
-                    &def.name,
-                    &raw_type_def,
-                );
+                def.is_abstract = kind == "abstract class";
                 def.extends = extends_targets;
                 def.implements = implements_targets;
                 Ok(Element::ClassDef(def))
             }
+            "entity" => {
+                let def = self.parse_type_def_into::<ClassDef>(pair)?;
+                Ok(Element::EntityDef(EntityDef {
+                    name: def.name,
+                    namespace: def.namespace,
+                    package: def.package,
+                    stereotypes: def.stereotypes,
+                    methods: def.methods,
+                    source_location,
+                }))
+            }
             "struct" => {
                 let mut def = self.parse_type_def_into::<StructDef>(pair)?;
                 def.source_location = source_location;
@@ -1567,6 +1566,7 @@ mod tests {
                     Element::ClassDef(def) => &def.name,
                     Element::StructDef(def) => &def.name,
                     Element::InterfaceDef(def) => &def.name,
+                    Element::EntityDef(def) => &def.name,
                     Element::EnumDef(def) => &def.name,
                 };
                 assert_eq!(name.internal, spelling, "`{keyword} {spelling}`");

plantuml/parser/puml_parser/src/class_diagram/src/lib.rs

@@ -16,8 +16,8 @@ mod class_traits;
 mod source_map;
 
 pub use class_ast::{
-    Attribute, ClassDef, ClassUmlFile, ClassUmlTopLevel, Element, EnumDef, EnumItem, EnumValue,
-    InterfaceDef, Method, Name, Namespace, Package, Param, Relationship, StructDef, TypeAlias,
-    Visibility,
+    Attribute, ClassDef, ClassUmlFile, ClassUmlTopLevel, Element, EntityDef, EnumDef, EnumItem,
+    EnumValue, InterfaceDef, Method, Name, Namespace, Package, Param, Relationship, StructDef,
+    TypeAlias, Visibility,
 };
 pub use class_parser::{ClassError, PumlClassParser};

plantuml/parser/puml_parser/src/class_diagram/test/integration_test.rs

@@ -105,6 +105,16 @@ fn test_ignored_visibility_statements() {
     run_class_diagram_parser_case("ignored_visibility_statements");
 }
 
+#[test]
+fn test_free_function_entity() {
+    run_class_diagram_parser_case("free_function_entity");
+}
+
+#[test]
+fn test_keyword_prefixed_relationship() {
+    run_class_diagram_parser_case("keyword_prefixed_relationship");
+}
+
 #[test]
 fn test_method_modifier_placement() {
     run_class_diagram_parser_case("method_modifier_placement");

plantuml/parser/puml_parser/src/grammar/activity.pest

@@ -94,8 +94,6 @@ swimlane_text = @{
     (!("|" | NEWLINE) ~ ANY)+
 }
 
-keyword_boundary = _{ !ASCII_ALPHANUMERIC }
-
 control_stmt = { "break" | "kill" | "detach" }
 
 // Action

plantuml/parser/puml_parser/src/grammar/class.pest

@@ -139,7 +139,8 @@ type_def = { type_def_with_body | type_def_decl }
 unsupported_object_def = { object_def_with_body | object_def_decl }
 
 type_def_decl = { type_kind ~ named ~ type_decl_suffix* }
-object_def_decl = { "object" ~ named ~ type_decl_suffix* }
+object_def_decl = { object_keyword ~ named ~ type_decl_suffix* }
+object_keyword = @{ "object" ~ keyword_boundary }
 type_decl_suffix = _{ extends_clause | implements_clause | link_annotation | stereotype | color }
 template_param = @{ identifier ~ varargs? }
 template_param_list = _{ "<" ~ template_param ~ ("," ~ template_param)* ~ ">" }
@@ -152,11 +153,15 @@ implements_target = { class_name_path }
 
 type_def_with_body = { type_def_decl ~ &(EOL* ~ "{") ~ EOL* ~ class_body ~ ";"? }
 object_def_with_body = { object_def_decl ~ &(EOL* ~ "{") ~ EOL* ~ class_body ~ ";"? }
-type_kind = {
-      "abstract" ~ "class"
-    | "class"
-    | "struct"
-    | "interface"
+type_kind = @{
+    (
+          "abstract" ~ WHITESPACE+ ~ "class"
+        | "class"
+        | "entity"
+        | "struct"
+        | "interface"
+    )
+    ~ keyword_boundary
 }
 
 class_body = { "{" ~ EOL* ~ (ignored_mock_method_stmt | class_member | class_body_separator)* ~ EOL* ~ "}" }
@@ -438,7 +443,8 @@ varargs = { "..." }
 ///////////////////////////////////////////////////////////////
 // type definition
 ///////////////////////////////////////////////////////////////
-enum_def = { "enum" ~ named ~ stereotype? ~ enum_body? ~ ";"? }
+enum_def = { enum_keyword ~ named ~ stereotype? ~ enum_body? ~ ";"? }
+enum_keyword = @{ "enum" ~ keyword_boundary }
 
 enum_body = { "{" ~ EOL* ~ enum_item* ~ EOL* ~ "}" }
 

plantuml/parser/puml_parser/src/grammar/common.pest

@@ -66,6 +66,7 @@ diagram_id = @{ (ASCII_ALPHANUMERIC | "_" | "-" | "." | "@" | " ")+ }
 puml_name  = { STRING | diagram_id }
 
 identifier = @{ (ASCII_ALPHANUMERIC | "_")+ }
+keyword_boundary = _{ !identifier }
 empty_line = { WHITESPACE* ~ EOL }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -379,5 +380,5 @@ arrow_mid_decor = @{ "(0)" | "(0" | "0)" | "()" | "(" | ")" | "0" }
 // ---------- Direction ----------
 arrow_direction = @{
     ("up" | "u" | "right" | "ri" | "r" | "down" | "do" | "d" | "left" | "le" | "l")
-    ~ !(ASCII_ALPHANUMERIC | "_")
+    ~ keyword_boundary
 }