/ 
Sidef-26.08
⭐ Starred 115 / Sidef::Object::Object

NAME

Sidef::Object::Object - Base class providing the common interface for all Sidef objects.

DESCRIPTION

This class is the base class for all Sidef objects. It provides fundamental methods for object introspection, cloning, metaprogramming, output, and smart matching, plus the fallback implicit-conversion and comparison protocol that every Sidef object gets for free unless it defines its own.

SYNOPSIS

var obj = Object()

INHERITS

Inherits methods from Sidef::Object::Convert

CONSTRUCTION

new

self.new

Creates and returns a new, empty Sidef::Object::Object instance (an object with no fields). Note that this constructor always blesses into the literal Sidef::Object::Object package itself, regardless of the invocant -- it is not polymorphic. In practice, essentially every built-in Sidef type overrides new with its own constructor; this base implementation only matters for a class that inherits new without providing its own.

bless

obj.bless(ref)

Blesses the raw reference ref into obj's own class (or, if obj is itself a bare typename, into that class directly) and returns the now-blessed reference. Unlike "new", this respects the actual invocant's class.

IMPLICIT CONVERSIONS AND COMPARISON

Every Sidef object gets the following fallback behavior for free (via Perl operator overloading), used whenever the language needs to treat an object as a boolean, a number, or a string, or needs to compare/order two objects and the object's own class doesn't define the relevant method itself:

  • Boolean context -- if the object defines a to_b method, that is used; otherwise, the object itself stands in as the boolean value (any object reference is truthy by default).

  • Numeric context (0+) -- if the object defines to_n, that is used; otherwise, the object itself stands in.

  • String context ("") -- if the object defines to_s, that is used; otherwise, the object itself stands in.

  • Three-way comparison (Perl's cmp, used as a fallback ordering) -- if both operands are the same class (or one is a subclass of the other) and that class defines an <=> method, that is used. Otherwise, two objects of the exact same class are ordered by their (arbitrary but stable) memory address, and objects of unrelated classes are ordered by comparing their class names as strings. This guarantees any two Sidef objects can be ordered, even if their own types don't otherwise support comparison.

  • Equality (Perl's eq, used as a fallback for ==) -- if both operands are the same class (or one is a subclass of the other) and that class defines an == method, that is used. Otherwise, falls back to the three-way comparison above (equal only if it returns 0).

These are internal fallbacks triggered by the language runtime, not methods meant to be called directly by name (there is no obj.cmp(...) or obj."0+"() in Sidef code).

OPERATORS

|>

a |> b

Pipeline operator. Calls b with a as its first argument and returns the result. If b is an array, its first element is used as the function/method and the rest of its elements are passed as additional arguments after a. If b is a string, it's treated as the name of a method to call on a.

&&

a && b

Logical AND. Returns b if a is truthy, otherwise returns a unchanged. Unlike "^", this returns one of the original operand values as-is (Perl-style short-circuit), not a coerced Bool.

||

a || b

Logical OR. Returns a if a is truthy, otherwise returns b. Like "&&", this returns one of the original operand values as-is, not a coerced Bool.

^

a ^ b

Logical XOR. Returns true if exactly one of a or b is truthy, otherwise returns false. Unlike && and ||, this always returns a proper Bool rather than one of the original operands.

\\

a \\ b

Defined-OR operator. Returns b if a is undefined, otherwise returns a unchanged.

:

a : b

Creates a Pair object from a and b. This is a deprecated alias for the pair operator, using the ASCII colon (U+003A).

：

a ： b

Creates a Pair object from a and b, using the fullwidth colon (U+FF1A).

⫶

a ⫶ b

Creates a NamedParam object from a (the name) and b (the value), using the triple colon operator (U+2AF6).

smartmatch

a.smartmatch(b)
a ~~ b

Performs a context-sensitive comparison between a and b, based on their types. The rules are checked in order, and the first one that applies wins:

  • Both a and b undefined: true.

  • Both a and b are bare typenames (unblessed strings, not object instances): true only if they are the exact same name (this is a plain string comparison, not a subclass check).

  • a is an object and b is a typename: true if a's type is b or a subclass of b.

  • a is a typename and b is an object: true if a names b's type or one of its superclasses.

  • String ~~ RangeString, or RangeString ~~ String: true if the string is contained in the range.

  • Number ~~ RangeNumber, or RangeNumber ~~ Number: true if the number is contained in the range.

  • String ~~ String: true if the strings are equal.

  • Array ~~ Array: true if the arrays are equal.

  • Array ~~ Regex, or Regex ~~ Array: true if any element of the array matches the regex.

  • Array ~~ Hash: true if the hash contains every element of the array as a key.

  • Hash ~~ Array: true if the array contains every key of the hash.

  • Hash ~~ Hash: true if the hashes are equal.

  • Hash ~~ Regex, or Regex ~~ Hash: true if any key of the hash matches the regex.

  • Regex ~~ Regex: true if the regexes are equal.

  • Any other value ~~ Array, or Array ~~ any other value: true if the array contains that value.

  • Any other value ~~ Hash, or Hash ~~ any other value: true if the hash has that value as a key.

  • Any other value ~~ Regex, or Regex ~~ any other value: true if the value matches the regex.

  • Any value (other than a Block) ~~ Block: calls the block with the value as its argument and returns the (boolean-coerced) result.

  • If exactly one of a/b is defined and the other isn't: false.

  • Anything else: falls back to generic equality between a and b (see "IMPLICIT CONVERSIONS AND COMPARISON").

Aliases: operator ~~

~~

a ~~ b

Operator form of "smartmatch".

Aliases: smartmatch

!~

a !~ b

Returns the negation of "smartmatch": true if a does not smart-match b.

TYPE INTROSPECTION

class

obj.class

Returns the short class name of the object (the part after the last ::). For example, an object of class Sidef::Types::Number::Number returns "Number". Also works when called on a bare typename string.

ref

obj.ref

Returns the full class (package) name of the object as a String -- for example, "Sidef::Types::Number::Number". If called on a bare typename string rather than an object instance, returns that typename unchanged.

is_a

self.is_a(class)

Returns true if the object is an instance of class, or of a subclass of class, otherwise false.

Aliases: is_an, kind_of

is_object

self.is_object

Returns true if the value is an instantiated object (a blessed reference), or false if it's a bare typename string.

is_typename

self.is_typename

Returns true if the value is a bare typename string (not an instantiated object), or false if it's an actual object instance. The logical complement of "is_object".

respond_to

self.respond_to(method)

Returns true if the object's class has a method with the given name (inherited methods count too), otherwise false.

object_type

self.object_type

Returns a String naming the object's underlying Perl reference type (e.g. "HASH", "ARRAY", "SCALAR").

Aliases: reftype

object_id

self.object_id

Returns a Number representing the memory address of the underlying object reference. Useful for comparing object identity (two variables refer to the same underlying object if their object_id values are equal).

Aliases: refaddr

parent_classes

obj.parent_classes

Returns an Array of all parent classes (superclasses) that the object's class inherits from, recursively walking the @ISA inheritance hierarchy. Each class is only listed once, even if it's reachable through more than one path (e.g. diamond inheritance).

CLONING AND SERIALIZATION

clone

obj.clone

Returns a shallow copy of the object. For hash-based objects, creates a new hash with the same key-value pairs; for array-based objects, creates a new array with the same elements. For any other underlying reference type (e.g. a scalar-based object), there is nothing to shallow-copy at this level, so the very same reference is returned unchanged.

dclone

self.dclone

Returns a deep copy of the object, recursively cloning nested hash and array structures. Circular references are handled by tracking already-cloned objects (so a cycle is reproduced in the copy rather than causing infinite recursion). Recursion only descends into nested values that are themselves hash- or array-based Sidef objects (i.e. instances of a class that inherits from Sidef::Object::Object); any other kind of value -- including plain Perl data or scalar-based Sidef objects -- is shared as-is between the original and the copy, not cloned.

Aliases: deep_clone

dump

self.dump

Returns a String representation of the object suitable for debugging. For hash-based objects, this includes every key/value pair, in the format ClassName(key: value, ...); a value that is itself an object with its own dump method is rendered by calling that method recursively, an undefined value is shown as nil, and any other value is stringified directly. For objects whose underlying reference type is not a hash (e.g. array- or scalar-based objects that don't provide their own dump), just the class's type name is returned, with no further detail. If the same object is encountered more than once while dumping (e.g. due to a circular reference), later occurrences are rendered as an abbreviated placeholder instead of being expanded again.

to_json

self.to_json

Converts the object to a JSON string. Internally, this serializes the object's raw underlying value (as returned by get_value), so a custom object will only serialize meaningfully if its underlying value (a hash, array, or scalar) is itself JSON-representable.

say(Hash("active" => true, "name" => "Sidef", "year" => 2013).to_json)

Output:

{"name":"Sidef","active":true,"year":2013}

interpolate

self.interpolate(*args)

Joins args into a single string and passes it to self's own new constructor, returning a new object of self's class. Used internally to implement string interpolation for classes such as String.

METAPROGRAMMING AND LAZY EVALUATION

lazy

self.lazy

Wraps the object in a Lazy object, which defers subsequent method calls on it until the result is actually needed.

method

self.method(name, *args)

Returns a LazyMethod object that, when invoked, calls the method named name on self with the given args. Useful for creating a bound method reference to pass around.

methods

self.methods(*args)

Returns a Hash mapping method names to LazyMethod objects (each bound to self, with args pre-filled as its arguments). Names starting with _ (private, by convention) or ( (internal overload-table entries) are excluded. Importantly, this only inspects methods defined directly in the object's own exact class -- inherited methods (defined only in a parent class) are not included, even though self can still be called with them directly.

def_method

self.def_method(name, block)

Defines a new method called name on the object's class (or, if self is a bare typename, on that class directly). Whenever the method is called, block is invoked with the receiver and all arguments forwarded to it unchanged. Returns self.

undef_method

self.undef_method(name)

Removes the method called name from the object's class. Returns self.

alias_method

self.alias_method(old, new)

Creates new as an alias for the existing method old on the object's class, so both names invoke the same underlying code. Dies if old does not already exist. Returns self.

OUTPUT

say

self.say

Prints the object to standard output, followed by a newline. Returns true on success, false on failure.

Aliases: println

print

self.print

Prints the object to standard output, without a trailing newline. Returns true on success, false on failure.

SEE ALSO

Sidef::Object::Convert