Documentation

Monoid instance for Subject.

Extends the Semigroup instance by providing an identity element (mempty). The identity subject has a default identity (Symbol ""), empty labels, and empty properties, enabling identity-based operations and standard Monoid combinators (e.g., mconcat) while preserving the self-descriptive object model.

Identity Semantics

The Monoid instance provides an identity subject:

• **Identity subject**: `mempty = Subject (Symbol "") Set.empty empty`
• **Left identity**: `mempty <> s = s` for all subjects s
• **Right identity**: `s <> mempty = s` for all subjects s

Monoid Laws

The Monoid instance satisfies the standard monoid laws, which are verified through property-based testing in the test suite:

• *Left Identity Law**: For all subjects s :: Subject,

mempty <> s = s

• *Right Identity Law**: For all subjects s :: Subject,

s <> mempty = s

Examples

Identity subject:

>>> mempty :: Subject
Subject {identity = Symbol "", labels = fromList [], properties = fromList []}

Left identity law:

>>> mempty <> Subject (Symbol "n") (Set.fromList ["Person"]) empty
Subject {identity = Symbol "n", labels = fromList ["Person"], properties = fromList []}

Right identity law:

>>> Subject (Symbol "n") (Set.fromList ["Person"]) empty <> mempty
Subject {identity = Symbol "n", labels = fromList ["Person"], properties = fromList []}

Using mconcat to combine subjects:

>>> mconcat [Subject (Symbol "a") (Set.fromList ["A"]) empty, Subject (Symbol "b") (Set.fromList ["B"]) empty, Subject (Symbol "c") (Set.fromList ["C"]) empty]
Subject {identity = Symbol "a", labels = fromList ["A", "B", "C"], properties = fromList []}

Semigroup instance for Subject.

Combines two subjects by merging their components:

1. **Identity**: Takes the first subject's identity, unless it's the default empty identity (Symbol ""), in which case takes the second identity
2. **Labels**: Unions labels from both subjects (set union, no duplicates)
3. **Properties**: Unions property maps (left-biased: first subject's properties take precedence on conflicts)

This enables incremental subject construction using standard Haskell combinators like <>, sconcat, and stimes.

Examples

Combining subjects with different components:

>>> s1 = Subject (Symbol "n") (Set.fromList ["Person"]) (fromList [("name", VString "Alice")])
>>> s2 = Subject (Symbol "m") (Set.fromList ["Employee"]) (fromList [("age", VInteger 30)])
>>> s1 <> s2
Subject {identity = Symbol "n", labels = fromList ["Employee", "Person"], properties = fromList [("age",VInteger 30),("name",VString "Alice")]}

When first subject has default empty identity, second identity is used:

>>> mempty <> Subject (Symbol "n") (Set.fromList ["Person"]) empty
Subject {identity = Symbol "n", labels = fromList ["Person"], properties = fromList []}

Associativity

The operation is associative:

(s1 <> s2) <> s3 = s1 <> (s2 <> s3)

This is verified through property-based testing.

Show instance for Subject.

Provides a readable string representation of a Subject for debugging and display. The format shows all three components: identity, labels, and properties.

Examples

>>> show (Subject (Symbol "n") (Set.fromList ["Person"]) (fromList [("name", VString "Alice")]))
"Subject {identity = Symbol \"n\", labels = fromList [\"Person\"], properties = fromList [(\"name\",VString \"Alice\")]}"

Hashable instance for Subject.

Enables using subjects as keys in HashMap and elements in HashSet for efficient hash-based lookups and deduplication. The instance provides O(1) average-case performance compared to O(log n) for ordered containers.

Hash Semantics

The Hashable instance uses structure-preserving hashing: subjects are hashed based on their structure (identity, labels, and properties), ensuring that equal subjects (according to Eq) produce the same hash value while providing good distribution to minimize collisions.

Implementation

The implementation follows standard Haskell conventions:

hashWithSalt s (Subject ident lbls props) = s hashWithSalt ident hashWithSalt lbls hashWithSalt props

Where each component is hashed recursively using its own Hashable instance.

Examples

Hashing with default salt:

>>> hash (Subject (Symbol "n") (Set.fromList ["Person"]) empty)
<hash value>

Hashing with custom salt:

>>> hashWithSalt 42 (Subject (Symbol "n") (Set.fromList ["Person"]) empty)
<hash value>