DS_Object.java

/* --------------------------------------------------------- *
 *    __________    D E L T A S C R I P T                    *
 *   (_________()                                            *
 *    /  ===   /   - A fast, dynamic scripting language      *
 *   |  ==    |    - Version 4.13.11.0                       *
 *   /  ===   /    - Developed by Adam R. Nelson             *
 *  |  =  =  |     - 2011-2013                               *
 *  /  ===   /     - Distributed under GNU LGPL v3           *
 * (________()     - http://github.com/ar-nelson/deltascript *
 *                                                           *
 * --------------------------------------------------------- */

package com.sector91.delta.script.objects;

import java.util.Set;

import com.sector91.delta.script.DScriptErr;
import com.sector91.delta.script.DeltaScript;
import com.sector91.delta.script.Operator;
import com.sector91.delta.script.annotations.DSType;

/**
 * <p>A DeltaScript object; that is, any object that can be accessed or
 * manipulated from DeltaScript.</p>
 * 
 * <p>In order to use an object in a DeltaScript script, the object must either
 * implement {@code DS_Object} or be <i>boxed</i> in a {@code DS_Object}, using
 * {@link DeltaScript#box(Object)}.</p>
 * 
 * <p>If you want to create your own DeltaScript objects, consider extending
 * {@link DS_AbstractObject} instead, which will make this task much simpler.
 * </p>
 * 
 * @author Adam R. Nelson
 * @version 4.13.11.0
 */
@DSType("Object")
public interface DS_Object extends Cloneable, Identity
{
    /**
     * <p>Returns a Java representation of this {@code DS_Object}.</p>
     * 
     * <p>If this {@code DS_Object} does not represent any Java object beyond
     * itself, this method should consist only of {@code return this;}. This
     * method should never return null unless this {@code DS_Object} is actually
     * meant to represent a null value.</p>
     */
    Object unbox();
    
    /**
     * <p>Returns a {@link String} representing this object's type.</p>
     * 
     * <p>This string is displayed in DeltaScript error messages, and is
     * returned by {@code ..typeOf()<} in DeltaScript.</p>
     */
    String getTypeName();
    
    /**
     * <p>Returns a set containing the names of all members of this object --
     * that is, all names for which {@link #dotGet(DS_Tag)} will not throw an
     * exception.</p>
     * 
     * <p>Every name in this set must be a valid argument for
     * {@link #dotGet(DS_Tag)}, and every valid argument for
     * {@link #dotGet(DS_Tag)} must be included in it. It must also contain
     * every valid argument for {@link #dotSet(DS_Tag, DS_Object)}, though not
     * every name in the set need be a valid argument for that method.</p>
     */
    Set<DS_Tag> getMembers();
    
    /**
     * <p>Called when a member of this object is accessed with the dot operator
     * (e.g., <{@code a.b}), except for assignments ({@code a.b = c}), which are
     * handled by {@link #dotSet(DS_Tag, DS_Object)}.</p>
     * 
     * <p>If the member being accessed does not exist, this method should throw
     * an exception.</p>
     * 
     * @param prop The name of the member being accessed.
     * @return The value of the member being accessed.
     * @throws DScriptErr If the member being accessed does not exist,
     *     or another error occurs.
     */
    DS_Object dotGet(DS_Tag prop) throws DScriptErr;
    
    /**
     * <p>Called when a member of this object (accessed with the {@code .}
     * operator) is assigned to with the {@code =} operator (e.g.,
     * "{@code a.b = c}").</p>
     * 
     * <p>If the member being assigned to does not exist or cannot be altered,
     * this method should throw an exception.</p>
     * 
     * @param prop The name of the member being assigned to.
     * @param value The value to assign to the member.
     * @throws DScriptErr If the member being assigned to does not exist
     *     or cannot be altered, or another error occurs.
     */
    void dotSet(DS_Tag prop, DS_Object value) throws DScriptErr;
    
    /**
     * <p>Applies an operator to this {@code DS_Object} and (optionally) another
     * {@code DS_Object}, and returns the result, or throws an exception if the
     * operator is invalid somehow.</p>
     * 
     * @param op The operator, as it appears in DeltaScript code.
     * @param other The second object that this operator is being applied to.
     *     Can be {@code null}, if the operator is unary.
     * @return The results of applying the operator to the {@code DS_Object}(s).
     * @throws DScriptErr If the operator is unrecognized or invalid for
     *     this {@code DS_Object}, or if another error occurs.
     */
    DS_Object operator(Operator op, DS_Object other)
            throws DScriptErr;
    
    int compare(DS_Object other) throws DScriptErr;
   
    /**
     * <p>Returns a {@code boolean} representation of this {@code DS_Object}.
     * </p>
     * 
     * <p>This should never throw an error, and should provide a sensible result
     * for use in {@code if} statements and loops. Generally, it should return
     * {@code false} for values representing empty lists, strings, etc. and null
     * or zero values, and {@code true} otherwise. If in doubt, it should
     * probably return {@code true}.</p>
     */
    boolean booleanValue();
    
    boolean equals(DS_Object other);
    
    /**
     * <p>Creates and returns a clone of this DeltaScript object. For singleton
     * objects ({@code true}, {@code false}, etc.), it should return
     * {@code this}. This method is used by the DeltaScript Standard Library
     *  method {@code ..clone()}.</p>
     * 
     * @throws CloneNotSupportedException If no valid clone of this DeltaScript
     *                                    object can be created.
     */
    DS_Object clone() throws CloneNotSupportedException;
}