docs reference

[[clone-object]]

Clone_object

By Goblin Docs ~ 9 min read

clone_object creates a new object from an existing object.

Overview

Use clone_object when you want a fresh object with the same class and field values as an existing object:

copy | clone_object(original)

copy | clone_object(original)

The clone is a separate object. It gets a new runtime UUID and is stored as its own object in Goblin's object store.

What Gets Copied

clone_object copies the object's:

Part	Copied?
Class	yes
Field values	yes
Readonly field markers	yes
Trait field markers	yes
Runtime UUID	no, a new one is generated
`owner_id`	no, it is cleared

Example:

copy | clone_object(original)

:say(copy.uuid)

copy | clone_object(original)

:say(copy.uuid)

The clone has its own uuid, so Goblin can track it separately from the source object.

Clearing Ownership

clone_object clears the clone's owner_id field:

copy | clone_object(original)

:say(copy.owner_id)  /// ""

copy | clone_object(original)

:say(copy.owner_id)  /// ""

That means the clone does not automatically belong to the same owner as the original.

This matters for ownership trees. A clone starts detached; attach it intentionally if it should belong somewhere.

What Does Not Get Copied

clone_object is a shallow object clone. It does not clone the surrounding object graph.

It does not copy:

Thing	Result
Owned child objects	The clone starts without cloned children.
Ownership tree	`owner_id` is cleared.
Active overlays	Overlays are not duplicated onto the clone.
Links	Links are not duplicated onto the clone.

If you need a full tree copy, clone each object and rebuild ownership links yourself.

Source Forms

clone_object can receive an object directly:

copy | clone_object(original)

copy | clone_object(original)

It can also receive a string that identifies the source object:

copy | clone_object(source_uuid)

copy | clone_object(source_uuid)

When the string points to a referenced object in the current environment, Goblin resolves that reference before cloning.

Return Value

clone_object returns the cloned object:

copy | clone_object(original)

:say(copy.vt)    /// object
:say(copy.uuid)  /// the clone's new UUID

copy | clone_object(original)

:say(copy.vt)    /// object
:say(copy.uuid)  /// the clone's new UUID

The clone is also added to the object store.

Identity Notes

The clone gets a new runtime uuid:

copy | clone_object(original)

:say(original.uuid == copy.uuid)  /// false

copy | clone_object(original)

:say(original.uuid == copy.uuid)  /// false

The ordinary field values are copied from the source. If your class has a separate id field, treat it as field data unless your object model says otherwise.

For most object-store work, use uuid as the runtime identity.

Signature

clone_object(source)

clone_object(source)

Argument	Type	Description
`source`	object or string	The object to clone, or a string that identifies one.

Returns the cloned object.

Errors

clone_object expects an object source:

clone_object(42)
/// error: A0414 clone-object-bad-source

clone_object(42)
/// error: A0414 clone-object-bad-source

If the source cannot be found in the object store, Goblin raises a not-found error:

clone_object("missing-object")
/// error: A0416 clone-object-not-found

clone_object("missing-object")
/// error: A0416 clone-object-not-found