////
  // Copyright (c) 2021, 2026 Contributors to the Eclipse Foundation
  //
  // This program and the accompanying materials are made
  // available under the terms of the Eclipse Public License 2.0
  // which is available at https://www.eclipse.org/legal/epl-2.0/
  //
  // SPDX-License-Identifier: EPL-2.0
////

include::_initCommon.adoc[]

== Parameterized Activities Details
Parameterized activities allow defining reusable templates with configurable parameters for resources, positions, actions, and more. This improves flexibility, maintainability, and readability.

=== Defining Parameterized Activities
[source]
----
activity AnActivity(robot1:Robot1, position:SymbolicPosition, action:Action){
  prerequisites { robot1.M at position }
  actions {
    C: claim robot1
    R: release robot1
    A1: action
    ...
  }
  ...
}
----

=== Parameter Types
[cols="1,2", options="header"]
|===
|Type |Description
|`<Resource>` |Specific resource type (e.g., Robot1)
|`Resource` |Any resource
|`SymbolicPosition` |Position in a Peripheral
|`Distance` |Distance in a Peripheral
|`Action` |Peripheral Action
|`Profile` |Speed Profile
|`Event` |Event to Raise or Require
|`<Product>` |Specific product type
|===

=== Using Parameterized Activities
[source]
----
activities {
  AnActivity[robot1=a, position=Above_Right, action=Robot1.a.C.clamp]
}
----

=== Parameter Assignment Styles
[cols="1,2", options="header"]
|===
|Style |Example
|Named |`AnActivity[robot1=a, position=Above_Right]`
|Positional |`AnActivity[a, Robot2, Above_Right]`
|Full Path |`AnActivity[action=Robot2.C.unclamp, ...]`
|Simplified |`AnActivity[action=unclamp, ...]` (if unique)
|Item Name Only |`AnActivity[robot1=b, ...]`
|===

[IMPORTANT]
Once you use a named parameter, all subsequent parameters must also be named.

=== Best Practices
* Match positional order to declaration.
* Prefer named parameters for clarity.
* Use descriptive names.

=== Examples
[source]
----
AnActivity[robot1=a, position=Above_Right, action=Robot1.a.C.unclamp]
AnActivity[a, Above_Right, Robot1.a.C.unclamp] // positional
----

=== Benefits
* **Reuse**: Define once, use many times.
* **Maintainability**: Update in one place.
* **Flexibility**: Adapt without duplication.

=== Common Issues
* Type mismatch
* Missing parameters
* Ambiguous references
* Incorrect positional order
* Mixed styles after named parameter

=== Validation Rules
[cols="1,2", options="header"]
|===
|Rule |Message
|Missing parameter |`No item specified for '<paramName>:<expectedType>'`
|Extra parameter |`Unnecessary parameter specified. Please remove it`
|Type mismatch |`expecting '<ExpectedType>' but got '<ActualType>'`
|Ordering |`Machine 'Resource' parameters must precede 'Action' parameters`
|Named vs positional | Scoping errors
|Scoping |Action must belong to claimed resource
|Unique names |`Duplicate parameter name <name>`
|Unused parameter |`<name> not used`
|Mixing params & incomplete resources |`Activity <name> has incomplete resource items AND parameters`
|Resource without items |`Resource <name> has no resource items`
|Path completeness |Resource → `Robot1.a`, Action → `Robot1.a.C.clamp`
|Short vs full path |Short allowed if unique; full always valid
|Passive claim |`Claim <C> can be made passive. There are no actions for resource <resourceName>`
|===

=== Quick Syntax Examples

For activity:
[source]
----
activity AnActivity(resource:Resource, action:Action){
    ...
}
----

✔ Correct:
[source]
----
AnActivity[resource=Robot1.a, action=Robot1.a.C.clamp]
AnActivity[Robot2, Robot2.C.clamp] // positional allowed if none named before
----

✘ Incorrect:
[source]
----
AnActivity[action=Robot1.a.C.clamp, resource=Robot2] // Resource after Action
AnActivity[resource=Robot1.a] // Missing action
AnActivity[resource=Robot2, action=Robot2.C] // action ends at Peripheral
AnActivity[resource=Robot2, action=Robot2.C.clamp, extra=a] // Extra param
----
