DS_Callable.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 com.sector91.delta.script.DScriptErr;
import com.sector91.delta.script.annotations.DSType;

/**
 * <p>Any {@link DS_Object} that can be called like a function.</p>
 * 
 * <p>A DS_Callable represents anything that can be passed arguments and
 * perform an action, including functions, closures, and Java methods.</p>
 * 
 * @author Adam R. Nelson
 * @version 4.13.11.0
 * @see DS_AnonymousCallable
 */
@DSType("Callable")
public interface DS_Callable extends DS_Object
{
    /**
     * <p>Executes this callable's action with the given arguments.</p>
     * 
     * <p>Most callables expect to be passed an exact number of arguments; if
     * the number of arguments passed does not match the value returned by
     * {@link #getArgCount()}, an exception may be thrown.</p>
     * 
     * @param args The arguments to pass to this callable, if any. Note that
     *             for most callables, the length of this array must be the
     *             <em>exact same</em> as the value of {@link #getArgCount()}.
     * @return The return value of the callable, or {@link DS_Blank#BLANK} if
     *         the callable did not return anything.
     * @throws DScriptErr If the number of arguments given is invalid,
     *                          or if an error occurs while executing this
     *                          callable's action.
     */
    public DS_Object call(DS_Object... args) throws DScriptErr;
    
    /**
     * <p>Returns an array of the names of the arguments that this callable
     * takes, if any. If you need the number of arguments, use
     * {@link #getArgCount()} instead.</p>
     * 
     * @return An array containing the names of this callable's arguments.
     */
    public String[] getArgNames();

    /**
     * <p>Returns the number of arguments that this callable takes.</p>
     * 
     * @return The exact number of arguments that this callable must be passed.
     * @see {@link #getArgNames()}
     */
    public int getArgCount();
}