# Extends
## Overview
**Extends** is ParamML's mechanism for reusing and building upon existing objects. It implements **inheritance** - a core concept from Object-Oriented Programming (OOP).
**What you'll learn:**
* Basic Extends syntax
* Single and multiple inheritance
* Versioning library components
* Override mechanism (critical rules!)
* When to use Scoped="1"
* Top-level vs Group-level extends
* Type inheritance and compatibility
* Common patterns and best practices
***
## What is Extends?
The `Extends` attribute allows an object to inherit all parameters and sub-objects from one or more parent objects.
**Key concepts:**
* A **child** receives all parameters and sub-objects from its **parent(s)**
* Children can add new parameters and objects
* Children can override inherited content using `Override="1"`
* Extends is **transitive** (grandparent → parent → child)
* Extends supports **multiple inheritance** (multiple parents)
### Inheritance: The Underlying Concept
Inheritance means deriving a new object from an existing one. Think of it like:
* **Parent** = Base template
* **Child** = Specialized version with everything from parent + additions/changes
### Conceptual Example
```
Person
├── Employee
│ └── Engineer
└── Student
```
An **Engineer** includes all attributes from:
* Person (age, name)
* Employee (working\_hours, income)
* Engineer (field, position)
***
## Basic Syntax
Use the `Extends` attribute to inherit from another object:
```xml
```
**Critical rule:** Every object **must have** a `T` (Type) attribute, even when using Extends:
```xml
```
***
## Single Inheritance
### Example: Person → Employee → Engineer
**Base: Person**
```xml
```
**Child: Employee extends Person**
```xml
```
**Grandchild: Engineer extends Employee**
```xml
```
**Result:**
```
Person has: age, name
Employee has: age, name, working_hours, experience, income
Engineer has: age, name, working_hours, experience, income, field, position
```
***
## Multiple Inheritance
Use **array syntax** to extend from multiple parent objects:
```xml
```
### Example: Multiple Base Classes
```xml
```
**Best Practice:** Avoid duplicate parameter names across parent objects to prevent ambiguity.
***
## Versioning
Library components can have versions. Use `::v#` syntax:
```xml
```
### Version Syntax
```xml
```
**Rules:**
* ✅ Versioning applies **only to library components**
* ✅ No version = **latest version**
* ✅ Can mix versioned and non-versioned in array
* ❌ Cannot version local objects (in same file)
### Example
```xml
```
***
## Override="1"
`Override="1"` is used to **replace** content inherited from parent.
### Critical Rules
1. **Override is an object attribute** - can only be applied to objects, not parameters
2. **Two ways to override:**
* **A) Override at Extends level** (selective - only specified parameters)
* **B) Override named object in parent** (complete replacement - all parameters)
***
## Override at Extends Level (Selective Override)
When you use `Override="1"` at the Extends level, you **only override the parameters you define**. Other parameters are inherited as-is.
### Syntax
```xml
```
### Example
```xml
```
**Result:**
```
Child has:
- width = 150 (overridden)
- height = 200 (inherited)
- depth = 300 (inherited)
```
### Multiple Parameter Override
```xml
```
**Result:**
```
Child has:
- a = 10 (overridden)
- b = 2 (inherited)
- c = 30 (overridden)
- d = 4 (inherited)
```
***
## Override Named Object (Complete Replacement)
When you override a **named object** from the parent, you must **redefine all parameters** - nothing is inherited from the parent's version of that object.
### Syntax
```xml
```
### Example
```xml
```
**If you forget to redefine:**
```xml
```
**Result:** Employee.Info will only have `text`, not `status`.
***
## How to Override Parameters at Top Level
At `T="Project"` level, parameters cannot be overridden directly. You must:
1. **Group parameters in the parent**
2. **Override the group in the child**
### Wrong Approach
```xml
```
### Correct Approach
```xml
```
***
## Override Summary Table
| Override Location | Syntax | Must Redefine All? | Use Case |
| -------------------- | --------------------------------------------- | --------------------------- | --------------------- |
| **At Extends level** | `` | ❌ No - only what you define | Change few parameters |
| **Named object** | `` | ✅ Yes - all parameters | Replace entire object |
### Quick Decision Guide
**Want to change 1-2 parameters?**
```xml
```
**Want to completely replace an object?**
```xml
```
***
## Scoped="1"
`Scoped="1"` isolates the extended object's namespace.
### Rules
**Simple rule:**
* **Top level** (`T="Project"`): **No `Scoped="1"`**
* **Everything else**: **Use `Scoped="1"`**
### Top Level (No Scoped)
```xml
```
### Inside Objects (Use Scoped)
```xml
```
### Without Scoped (Top Level)
```xml
```
### With Scoped (Inside Object)
```xml
```
***
## When to Extend at Top vs Group Level
### Top Level (T="Project"): True Inheritance (IS-A)
Use when child **is a type of** parent:
```xml
```
**When to use:**
* True inheritance relationship
* Child is a specialized version of parent
* Type compatibility needed (see Type Inheritance and example below)
***
#### Type Compatibility Through Base Classes
A key reason for top-level inheritance is creating **type compatibility** - allowing input parameters to accept multiple related component types.
**The Problem**
```xml
```
**The Solution: Base Class**
Create a **base class** that both girder types extend:
```xml
```
**Usage**
```xml
```
**Why This Works**
```
Type hierarchy:
- BaseGirder
├── SteelIGirder (types: BaseGirder, SteelIGirder)
└── PrecastIGirder (types: BaseGirder, PrecastIGirder)
Parameter constraint: T="BaseGirder"
Accepts: Any object with BaseGirder type
Result: Both SteelIGirder and PrecastIGirder accepted ✅
```
**Pattern Summary**
**When you need a parameter to accept multiple component types:**
1. ✅ Create a **base class** with common interface (exported parameters)
2. ✅ Extend base class to specialized types
3. ✅ Use base class as parameter type: `T="BaseClass"`
4. ✅ All specialized types now accepted by parameter
**Benefits:**
* Single parameter definition works with multiple component types
* Type safety maintained (can't pass unrelated components)
* Common interface guaranteed through base class exports
* Easy to add new specialized types later
***
### Group Level (T="Group"): Reusing Logic (HAS-A)
Use when object **uses** parent's calculations:
```xml
```
**When to use:**
* Reusing calculations from library
* Not a true inheritance relationship
* Want to namespace the extended content
***
### Decision Guide
| Scenario | Use | Example |
| --------------------------- | ----------- | -------------------------------------- |
| Child is specialized parent | Top level | `SteelBeam` extends `Beam` |
| Using calculation library | Group level | Using `AASHTOCode` in `ColumnCheck` |
| Need type compatibility | Top level | `BaseGirder` accepted by `Cross_Frame` |
| Namespacing needed | Group level | Multiple calculations in same object |
***
## Transitive Inheritance
Inheritance is **transitive** - children inherit from entire ancestor chain.
### Example
```xml
```
**Result:**
```
Base has: a
Middle has: a, b
Child has: a, b, c
```
### With Overrides
```xml
```
**Result:**
```
Base.Config.value = 100
Middle.Config.value = 200
Child.Config.value = 300
```
**Process:**
1. Base is created
2. Middle extends Base, applies overrides
3. Child extends Middle (with its overrides), applies its own overrides
***
## Type Inheritance
A child inherits all **types** from its parent.
### Type Chain
```xml
```
### Why This Matters
Parameters with type constraints accept compatible types:
```xml
```
**Rule:** Child types are **compatible** with parent types (polymorphism).
***
## Extending Objects Inside Other Objects
You can extend objects at any level, not just top level.
### Example: Extending Inside Volume
```xml
```
***
## Common Patterns
### Pattern 1: Base Class with Specializations
```xml
```
### Pattern 2: Reusing Calculation Logic
```xml
```
### Pattern 3: Selective Parameter Override
```xml
```
### Pattern 4: Multiple Base Classes for Modularity
```xml
```
### Pattern 5: Version-Specific Extensions
```xml
```
***
## Extends vs Instances
**Critical distinction:**
| Feature | Extends (Inheritance) | T="..." (Instances) |
| ---------------- | -------------------------- | ------------------- |
| **Purpose** | Inherit structure | Create instance |
| **Syntax** | `Extends="Parent"` | `T="ComponentName"` |
| **Use with** | Core objects | Library components |
| **Common types** | `T="Project"`, `T="Group"` | User components |
| **Can combine?** | ❌ No | ❌ No |
### Extends (Inheritance)
```xml
```
**Use for:**
* ✅ True inheritance (is-a relationship)
* ✅ Reusing calculation logic
* ✅ Core objects (`T="Project"`, `T="Group"`, `T="Section"`)
### Instances (T="...")
```xml
```
**Use for:**
* ✅ Creating instances of library components
* ✅ Building compositions (has-a relationship)
* ✅ User-developed components
### Cannot Combine
```xml
```
**Rule:** Use **either** `Extends` (inheritance) **or** `T="ComponentName"` (instance), never both.
***
## Best Practices
### 1. Avoid Parameter Name Conflicts
**❌ Bad - duplicate parameters:**
```xml
```
**✅ Good - unique parameters:**
```xml
```
### 2. Use Scoped="1" Consistently
```xml
```
### 3. Use Versioning for Stability
```xml
```
### 4. Choose Override Strategy Wisely
```xml
```
### 5. Group Parameters for Overriding
```xml
```
### 6. Document Inheritance Chains
```xml
```
### 7. Choose Inheritance Level Wisely
```xml
```
### 8. Keep Inheritance Hierarchies Shallow
```xml
Base → Middle → Child
Base → L1 → L2 → L3 → L4 → L5 → Child
```
Deep hierarchies are harder to understand and maintain.
### 9. Remember Override Rules
**Quick reference card:**
```
Override at Extends level:
← Only overrides param1
← Other parameters inherited
Override named object:
← Must define param1
← Must define param2
← Nothing inherited from parent's Config
```
***
## Common Mistakes
### ❌ Mistake 1: Missing T Attribute
```xml
```
### ❌ Mistake 2: Trying to Override Parameters Directly
```xml
```
### ❌ Mistake 3: Forgetting to Redefine All When Overriding Object
```xml
```
### ❌ Mistake 4: Missing Scoped="1" Inside Objects
```xml
```
### ❌ Mistake 5: Combining Extends and Instance Creation
```xml
```
***
## Summary
### Key Concepts
| Concept | Description |
| -------------------- | -------------------------------------------------------- |
| **Extends** | Inherit parameters and objects from parent |
| **Multiple** | `Extends="[A, B, C]"` - inherit from multiple parents |
| **Versioning** | `Extends="Component::v3"` - use specific version |
| **Override="1"** | Replace inherited content (objects only, not parameters) |
| **Scoped="1"** | Namespace extended content (use except top level) |
| **Transitive** | Child gets everything from entire ancestor chain |
| **Type inheritance** | Child carries all parent types |
### Override Rules (Critical!)
| Override Type | Syntax | Redefine All? | Use When |
| ----------------- | ----------------------------------- | ---------------- | --------------------- |
| **Extends level** | `` | ❌ No - selective | Change few parameters |
| **Named object** | `` | ✅ Yes - complete | Replace entire object |
### When to Use
| Use Case | Syntax | Example |
| ------------------ | ---------------------- | ------------------------------ |
| True inheritance | Top-level Extends | `Column` extends `Base_Column` |
| Reuse calculations | Group-level Extends | Using `AASHTOCode` |
| Multiple bases | Array syntax | `Extends="[A, B, C]"` |
| Specific version | Version syntax | `Extends="Base::v5"` |
| Change few params | Extends-level Override | `` |
| Replace object | Named Override | `` |
### Rules to Remember
1. **Must have T attribute** - every object needs `T`, even with Extends
2. **Override is for objects** - cannot override parameters directly
3. **Two override behaviors** - selective (Extends level) vs complete (named object)
4. **Cannot combine** `Extends` and `T="ComponentName"` (instance)
5. **Use `Scoped="1"`** except at top level (`T="Project"`)
6. **Avoid conflicts** in multiple inheritance
7. **Version for stability**, latest for development
8. **Transitive** - inherit entire ancestor chain
9. **Type compatible** - child accepted where parent expected
***