refs.items

Module nustd.mem.refs.items.

Dict substrate item refs: typed value holders in nested dicts.

ItemRef combines the shape MutableItemRef blueprint (slot-level CRUD) with RefBase (dict navigation). Typed refs (IntRef, StrRef, ...) add the matching primitive Form so the value carries its full operator interface.

BoolRef

A bool slot in the dict substrate, carrying the whole Bool surface.

BoolRef(address, parent_ref=None, owner_shape=None)

Path nustd.mem.BoolRef. Kind Ref, sort ref, cardinality scalar.

Notes

• An unwritten slot reads EMPTY, which is not False; use .exists() when the difference matters.

Example

class User(nu.Shape):
    active = nustd.mem.BoolRef.slot()
ctx = nu.Context().bind(dict, {"active": True}, User)
nu.run(User.active.not_(), ctx)[0]

False

Inherited methods

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.primitives.bool_.Bool:

From nu.lang.forms.Form:

BytesRef

A bytes slot in the dict substrate, carrying the whole Bytes surface.

BytesRef(address, parent_ref=None, owner_shape=None)

Path nustd.mem.BytesRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as raw bytes, so a data dict holding one is no longer JSON-serialisable as it stands.

Example

class Blob(nu.Shape):
    body = nustd.mem.BytesRef.slot()
ctx = nu.Context().bind(dict, {"body": b"hi"}, Blob)
nu.run(Blob.body.decode(), ctx)[0]

'hi'

Inherited methods

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.primitives.bytes_.Bytes:

From nu.lang.forms.Form:

FloatRef

A float slot in the dict substrate, carrying the whole Float surface.

FloatRef(address, parent_ref=None, owner_shape=None)

Path nustd.mem.FloatRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Nothing coerces on write: an int written here comes back an int.

Example

class User(nu.Shape):
    score = nustd.mem.FloatRef.slot()
ctx = nu.Context().bind(dict, {"score": 1.5}, User)
nu.run(User.score * 2, ctx)[0]

3.0

Inherited methods

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.primitives.float_.Float:

From nu.lang.forms.Form:

IntRef

An int slot in the dict substrate, carrying the whole Int surface.

IntRef(address, parent_ref=None, owner_shape=None)

Path nustd.mem.IntRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Every Int call is available on it, so the ref itself is an operand: User.age + 1 builds arithmetic over the read.
• The value is stored as a plain int, so the data dict stays JSON-shaped.

Example

class User(nu.Shape):
    age = nustd.mem.IntRef.slot()
ctx = nu.Context().bind(dict, {"age": 41}, User)
nu.run(User.age + 1, ctx)[0]

42

Methods

.inc(step=1)

Add step to the stored int and write the result back.

Builds None_.

Arguments

Notes

• Read and write are two touches of the slot, not one atomic step; wrap it in a transaction when something else may write in between.
• On an unwritten slot the read is EMPTY, so the addition is INVALID and that is what gets stored.

Example

class User(nu.Shape):
    age = nustd.mem.IntRef.slot()
data = {"age": 41}
ctx = nu.Context().bind(dict, data, User)
_ = nu.run(User.age.inc(), ctx)
data

{'age': 42}

.dec(step=1)

Subtract step from the stored int and write the result back.

Builds None_.

Arguments

Notes

• Same two-touch read-then-write as inc.

Example

class User(nu.Shape):
    age = nustd.mem.IntRef.slot()
data = {"age": 41}
ctx = nu.Context().bind(dict, data, User)
_ = nu.run(User.age.dec(2), ctx)
data

{'age': 39}

Inherited methods

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.primitives.int_.Int:

From nu.lang.forms.Form:

ItemRef

A single stored value in the dict substrate, with no value interface.

ItemRef(address, value_type, value_value_type, parent_ref=None, owner_shape=None)

Path nustd.mem.ItemRef. Kind Ref, sort ref, cardinality scalar.

The untyped leaf: it reads, writes and erases one key, and carries the element type as metadata for whoever needs it, but exposes none of the operators a typed ref does. Reach for it when the held type is decided by a container above (ListRef[i] and DictRef[k] both descend into one) rather than declared on a Shape.

Notes

• The type carried is metadata only: nothing coerces or rejects a value on write, and nothing checks what comes back on read.

Example

class Port(nu.Shape):
    tags = nustd.mem.ListRef.slot(str)
ctx = nu.Context().bind(dict, {"tags": ["a", "b"]}, Port)
nu.run(Port.tags[1], ctx)[0]

'b'

Inherited methods

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.lang.forms.Form:

StrRef

A str slot in the dict substrate, carrying the whole Str surface.

StrRef(address, parent_ref=None, owner_shape=None)

Path nustd.mem.StrRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Every Str call is available on it, so User.name.upper() reads the slot and builds the string op over it.

Example

class User(nu.Shape):
    name = nustd.mem.StrRef.slot()
ctx = nu.Context().bind(dict, {"name": "ada"}, User)
nu.run(User.name.upper(), ctx)[0]

'ADA'

Inherited methods

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nu.forms.primitives.str_.Str:

From nu.lang.forms.Form: