// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license.
using System;
using System.Collections;
namespace Microsoft.ClearScript
{
///
/// Represents a script engine.
///
public interface IScriptEngine : IDisposable
{
///
/// Gets the name associated with the script engine instance.
///
string Name { get; }
///
/// Gets the script engine's recommended file name extension for script files.
///
string FileNameExtension { get; }
///
/// Allows script code to access non-host resources.
///
///
/// By setting this property to a type you declare that script code running in the current
/// script engine is to be treated as if it were part of that type's implementation. Doing
/// so does not expose any host resources to script code, but it affects which host
/// resources are importable and which members of exposed resources are accessible.
///
Type AccessContext { get; set; }
///
/// Gets or sets the default script access setting for all members of exposed objects.
///
///
/// Use , , or
/// their subclasses to override this property for individual types and members. Note that
/// this property has no effect on the method binding algorithm. If a script-based call is
/// bound to a method that is blocked by this property, it will be rejected even if an
/// overload exists that could receive the call.
///
ScriptAccess DefaultAccess { get; set; }
///
/// Enables or disables access restrictions for anonymous types.
///
///
/// Anonymous types are
/// internal
/// and therefore accessible only within the same assembly, but ClearScript 5.5.3 and
/// earlier permitted access to the properties of an object even if its type was
/// internal. Newer versions strictly enforce , but because
/// anonymous types are particularly useful for scripting, ClearScript by default continues
/// to expose their properties to external contexts. To override this behavior and enable
/// normal access restrictions for anonymous types, set this property to true.
///
bool EnforceAnonymousTypeAccess { get; set; }
///
/// Controls whether host objects provide access to the static members of their exposed types to script code.
///
bool ExposeHostObjectStaticMembers { get; set; }
///
/// Enables or disables extension method support.
///
bool DisableExtensionMethods { get; set; }
///
/// Enables or disables script code formatting.
///
///
/// When this property is set to true, the script engine may format script code
/// before executing or compiling it. This is intended to facilitate interactive debugging.
/// The formatting operation currently includes stripping leading and trailing blank lines
/// and removing global indentation.
///
bool FormatCode { get; set; }
///
/// Controls whether script code is permitted to use reflection.
///
///
/// When this property is set to true, script code running in the current script
/// engine is permitted to use reflection. This affects
/// Object.GetType(),
/// Exception.GetType(),
/// Exception.TargetSite,
/// Delegate.Method,
/// and .
/// By default, any attempt to invoke these members from script code results in an
/// exception.
///
bool AllowReflection { get; set; }
///
/// Enables or disables type restriction for field, property, and method return values.
///
///
/// When this property is set to true, script code running in the current script
/// engine has access to the runtime types of all exposed host resources, which by default
/// are restricted to their declared types. The default behavior is a general requirement
/// for correct method binding, so setting this property to true is not recommended.
///
///
bool DisableTypeRestriction { get; set; }
///
/// Enables or disables type restriction for array and list elements retrieved by index.
///
///
/// In ClearScript 5.4.4 and earlier, indexed array and list elements were exempt from type
/// restriction. ClearScript 5.4.5 introduced a breaking change to correct this, but you can
/// set this property to true to restore the exemption if you have older script code
/// that depends on it.
///
///
bool DisableListIndexTypeRestriction { get; set; }
///
/// Enables or disables null wrapping for field, property, and method return values.
///
///
/// When this property is set to true, all field, property, and method return values
/// are marshaled with full .NET type information even if they are null. Note that
/// such values will always fail equality comparison with JavaScript's
/// null,
/// VBScript's
/// Nothing,
/// and other similar values. Instead, use or
/// to perform such a comparison.
///
///
///
bool EnableNullResultWrapping { get; set; }
///
/// Enables or disables floating point narrowing.
///
///
/// When this property is set to true, no attempt is made to convert floating-point
/// values imported from the script engine to the narrowest equivalent .NET representation.
/// The default behavior is more likely to result in successful method binding in specific
/// scenarios, so setting this property to true is not recommended.
///
bool DisableFloatNarrowing { get; set; }
///
/// Enables or disables dynamic method binding.
///
///
/// When this property is set to true, the script engine bypasses the default method
/// binding algorithm and uses reflection-based method binding instead. This approach
/// abandons support for generic type inference and other features, but it avoids engaging
/// the dynamic infrastructure.
///
///
bool DisableDynamicBinding { get; set; }
///
/// Enables or disables the use of reflection-based method binding as a fallback.
///
///
///
/// When this property is set to true, the script engine attempts to use
/// reflection-based method binding when the default method binding algorithm fails. This
/// approach reduces type safety, but it may be useful for running legacy scripts that rely
/// on the specific behavior of reflection-based method binding.
///
///
/// This property has no effect when is set to
/// true.
///
///
bool UseReflectionBindFallback { get; set; }
///
/// Enables or disables automatic host variable tunneling for by-reference arguments to script functions and delegates.
///
///
/// When this property is set to true, the script engine replaces by-reference
/// arguments to script functions and delegates with host variables, allowing script code
/// to simulate output arguments if the script language does not support them natively.
///
///
bool EnableAutoHostVariables { get; set; }
///
/// Gets or sets the engine's undefined import value.
///
///
/// Some script languages support one or more special non-null values that represent
/// nonexistent, missing, unknown, or undefined data. When such a value is marshaled to the
/// host, the script engine maps it to the value of this property. The default value is
/// Undefined.Value.
///
object UndefinedImportValue { get; set; }
///
/// Gets or sets the engine's null export value.
///
///
///
/// When a null object reference is marshaled to script code, the script engine maps it to
/// the value of this property. The default value is simply null, which corresponds
/// to null or its closest equivalent in the script language. Other useful
/// possibilities include
/// Undefined.Value and
/// Nothing.Value.
///
///
/// Note that ,
/// , and
/// MarshalNullAsDispatch
/// all take precedence over this property.
///
///
object NullExportValue { get; set; }
///
/// Gets or sets the engine's void result export value.
///
///
/// Some script languages expect every subroutine call to return a value. When script code
/// written in such a language invokes a host method that explicitly returns no value (such
/// as a C#
/// void
/// method), the script engine returns the value of this property as a dummy result. The
/// default value is VoidResult.Value.
///
object VoidResultValue { get; set; }
///
/// Gets or sets a callback that can be used to halt script execution.
///
///
/// During script execution the script engine periodically invokes this callback to
/// determine whether it should continue. If the callback returns false, the script
/// engine terminates script execution and throws an exception.
///
ContinuationCallback ContinuationCallback { get; set; }
///
/// Allows the host to access script resources dynamically.
///
///
/// The value of this property is an object that is bound to the script engine's root
/// namespace. It dynamically supports properties and methods that correspond to global
/// script objects and functions.
///
dynamic Script { get; }
///
/// Allows the host to access script resources.
///
///
/// The value of this property is an object that is bound to the script engine's root
/// namespace. It allows you to access global script resources via the
/// class interface. Doing so is likely to perform better than
/// dynamic access via .
///
ScriptObject Global { get; }
///
/// Gets or sets the script engine's document settings.
///
DocumentSettings DocumentSettings { get; set; }
///
/// Exposes a host object to script code.
///
/// A name for the new global script item that will represent the object.
/// The object to expose.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddHostObject(string itemName, object target);
///
/// Exposes a host object to script code with the specified options.
///
/// A name for the new global script item that will represent the object.
/// A value that selects options for the operation.
/// The object to expose.
///
///
/// Once a host object is exposed to script code, its members are accessible via the script
/// language's native syntax for member access. The following table provides details about
/// the mapping between host members and script-accessible properties and methods.
///
///
///
///
/// Member Type
/// Exposed As
/// Remarks
///
///
/// Constructor
/// N/A
///
/// To invoke a constructor from script code, call
/// HostFunctions.newObj(T).
///
///
///
/// Property/Field
/// Property
/// N/A
///
///
/// Method
/// Method
///
/// Overloaded host methods are merged into a single script-callable method. At
/// runtime the correct host method is selected based on the argument types.
///
///
///
/// Generic Method
/// Method
///
/// The ClearScript library supports dynamic C#-like type inference when invoking
/// generic methods. However, some methods require explicit type arguments. To call
/// such a method from script code, you must place the required number of
/// host type objects
/// at the beginning of the argument list. Doing so for methods that do not require
/// explicit type arguments is optional.
///
///
///
/// Extension Method
/// Method
///
/// Extension methods are available if the type that implements them has been
/// exposed in the current script engine.
///
///
///
/// Indexer
/// Property
///
/// Indexers appear as properties named "Item" that accept one or more index values
/// as arguments. In addition, objects that implement expose
/// properties with numeric names that match their valid indices. This includes
/// one-dimensional host arrays and other collections. Multidimensional host arrays
/// do not expose functional indexers; you must use
/// Array.GetValue
/// and
/// Array.SetValue
/// instead.
///
///
///
/// Event
/// Property
///
/// Events are exposed as read-only properties of type .
///
///
///
///
///
void AddHostObject(string itemName, HostItemFlags flags, object target);
///
/// Exposes a host object to script code with the specified type restriction.
///
/// The type whose members are to be made accessible from script code.
/// A name for the new global script item that will represent the object.
/// The object to expose.
///
///
/// This method can be used to restrict script access to the members of a particular
/// interface or base class.
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddRestrictedHostObject(string itemName, T target);
///
/// Exposes a host object to script code with the specified type restriction and options.
///
/// The type whose members are to be made accessible from script code.
/// A name for the new global script item that will represent the object.
/// A value that selects options for the operation.
/// The object to expose.
///
///
/// This method can be used to restrict script access to the members of a particular
/// interface or base class.
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddRestrictedHostObject(string itemName, HostItemFlags flags, T target);
///
/// Creates a COM/ActiveX object and exposes it to script code. The registered class is
/// specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the object.
/// The programmatic identifier (ProgID) of the registered class to instantiate.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMObject(string itemName, string progID);
///
/// Creates a COM/ActiveX object on the specified server and exposes it to script code. The
/// registered class is specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the object.
/// The programmatic identifier (ProgID) of the registered class to instantiate.
/// The name of the server on which to create the object.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMObject(string itemName, string progID, string serverName);
///
/// Creates a COM/ActiveX object and exposes it to script code with the specified options.
/// The registered class is specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the object.
/// A value that selects options for the operation.
/// The programmatic identifier (ProgID) of the registered class to instantiate.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMObject(string itemName, HostItemFlags flags, string progID);
///
/// Creates a COM/ActiveX object on the specified server and exposes it to script code with
/// the specified options. The registered class is specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the object.
/// A value that selects options for the operation.
/// The programmatic identifier (ProgID) of the registered class to instantiate.
/// The name of the server on which to create the object.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMObject(string itemName, HostItemFlags flags, string progID, string serverName);
///
/// Creates a COM/ActiveX object and exposes it to script code. The registered class is
/// specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the object.
/// The class identifier (CLSID) of the registered class to instantiate.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMObject(string itemName, Guid clsid);
///
/// Creates a COM/ActiveX object on the specified server and exposes it to script code. The
/// registered class is specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the object.
/// The class identifier (CLSID) of the registered class to instantiate.
/// The name of the server on which to create the object.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMObject(string itemName, Guid clsid, string serverName);
///
/// Creates a COM/ActiveX object and exposes it to script code with the specified options.
/// The registered class is specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the object.
/// A value that selects options for the operation.
/// The class identifier (CLSID) of the registered class to instantiate.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMObject(string itemName, HostItemFlags flags, Guid clsid);
///
/// Creates a COM/ActiveX object on the specified server and exposes it to script code with
/// the specified options. The registered class is specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the object.
/// A value that selects options for the operation.
/// The class identifier (CLSID) of the registered class to instantiate.
/// The name of the server on which to create the object.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMObject(string itemName, HostItemFlags flags, Guid clsid, string serverName);
///
/// Exposes a host type to script code with a default name.
///
/// The type to expose.
///
///
/// This method uses 's name for the new global script item that
/// will represent it.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(Type type);
///
/// Exposes a host type to script code with a default name and the specified options.
///
/// A value that selects options for the operation.
/// The type to expose.
///
///
/// This method uses 's name for the new global script item that
/// will represent it.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(HostItemFlags flags, Type type);
///
/// Exposes a host type to script code.
///
/// A name for the new global script item that will represent the type.
/// The type to expose.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(string itemName, Type type);
///
/// Exposes a host type to script code with the specified options.
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The type to expose.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(string itemName, HostItemFlags flags, Type type);
///
/// Exposes a host type to script code. The type is specified by name.
///
/// A name for the new global script item that will represent the type.
/// The fully qualified name of the type to expose.
/// Optional generic type arguments.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(string itemName, string typeName, params Type[] typeArgs);
///
/// Exposes a host type to script code with the specified options. The type is specified by name.
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The fully qualified name of the type to expose.
/// Optional generic type arguments.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(string itemName, HostItemFlags flags, string typeName, params Type[] typeArgs);
///
/// Exposes a host type to script code. The type is specified by type name and assembly name.
///
/// A name for the new global script item that will represent the type.
/// The fully qualified name of the type to expose.
/// The name of the assembly that contains the type to expose.
/// Optional generic type arguments.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(string itemName, string typeName, string assemblyName, params Type[] typeArgs);
///
/// Exposes a host type to script code with the specified options. The type is specified by
/// type name and assembly name.
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The fully qualified name of the type to expose.
/// The name of the assembly that contains the type to expose.
/// Optional generic type arguments.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostType(string itemName, HostItemFlags flags, string typeName, string assemblyName, params Type[] typeArgs);
///
/// Exposes host types to script code.
///
/// The types to expose.
///
///
/// This method uses each specified type's name for the new global script item that will
/// represent it.
///
///
/// Host types are exposed to script code in the form of objects whose properties and
/// methods are bound to the type's static members and nested types. If the type has
/// generic parameters, the corresponding object will be invocable with type arguments to
/// yield a specific type.
///
///
/// For more information about the mapping between host members and script-callable
/// properties and methods, see .
///
///
void AddHostTypes(params Type[] types);
///
/// Imports a COM/ActiveX type and exposes it to script code. The registered class is
/// specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the type.
/// The programmatic identifier (ProgID) of the registered class to import.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMType(string itemName, string progID);
///
/// Imports a COM/ActiveX type from the specified server and exposes it to script code. The
/// registered class is specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the type.
/// The programmatic identifier (ProgID) of the registered class to import.
/// The name of the server from which to import the type.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMType(string itemName, string progID, string serverName);
///
/// Imports a COM/ActiveX type and exposes it to script code with the specified options.
/// The registered class is specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The programmatic identifier (ProgID) of the registered class to import.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMType(string itemName, HostItemFlags flags, string progID);
///
/// Imports a COM/ActiveX type from the specified server and exposes it to script code with
/// the specified options. The registered class is specified by programmatic identifier (ProgID).
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The programmatic identifier (ProgID) of the registered class to import.
/// The name of the server from which to import the type.
///
///
/// The argument can be a class identifier (CLSID) in standard
/// GUID format with braces (e.g., "{0D43FE01-F093-11CF-8940-00A0C9054228}").
///
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
///
void AddCOMType(string itemName, HostItemFlags flags, string progID, string serverName);
///
/// Imports a COM/ActiveX type and exposes it to script code. The registered class is
/// specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the type.
/// The class identifier (CLSID) of the registered class to import.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMType(string itemName, Guid clsid);
///
/// Imports a COM/ActiveX type from the specified server and exposes it to script code. The
/// registered class is specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the type.
/// The class identifier (CLSID) of the registered class to import.
/// The name of the server from which to import the type.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMType(string itemName, Guid clsid, string serverName);
///
/// Imports a COM/ActiveX type and exposes it to script code with the specified options.
/// The registered class is specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The class identifier (CLSID) of the registered class to import.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMType(string itemName, HostItemFlags flags, Guid clsid);
///
/// Imports a COM/ActiveX type from the specified server and exposes it to script code with
/// the specified options. The registered class is specified by class identifier (CLSID).
///
/// A name for the new global script item that will represent the type.
/// A value that selects options for the operation.
/// The class identifier (CLSID) of the registered class to import.
/// The name of the server from which to import the type.
///
/// For information about the mapping between host members and script-callable properties
/// and methods, see .
///
void AddCOMType(string itemName, HostItemFlags flags, Guid clsid, string serverName);
///
/// Executes script code.
///
/// The script code to execute.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as a statement.
///
///
/// If a debugger is attached, it will present the specified script code to the user as a
/// document with an automatically selected name. This document will not be discarded
/// after execution.
///
///
void Execute(string code);
///
/// Executes script code with an associated document name.
///
/// A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
/// The script code to execute.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as a statement.
///
///
/// If a debugger is attached, it will present the specified script code to the user as a
/// document with the specified name. This document will not be discarded after execution.
///
///
void Execute(string documentName, string code);
///
/// Executes script code with an associated document name, optionally discarding the document after execution.
///
/// A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
/// True to discard the script document after execution, false otherwise.
/// The script code to execute.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as a statement.
///
///
/// If a debugger is attached, it will present the specified script code to the user as a
/// document with the specified name. Discarding this document removes it from view but
/// has no effect on the script engine. Only Windows Script engines honor
/// .
///
///
void Execute(string documentName, bool discard, string code);
///
/// Executes script code with the specified document meta-information.
///
/// A structure containing meta-information for the script document.
/// The script code to execute.
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as a statement.
///
void Execute(DocumentInfo documentInfo, string code);
///
/// Loads and executes a script document.
///
/// A string specifying the document to be loaded and executed.
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets script code loaded from the specified document as a statement.
///
void ExecuteDocument(string specifier);
///
/// Loads and executes a document with the specified category.
///
/// A string specifying the document to be loaded and executed.
/// An optional category for the requested document.
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets script code loaded from the specified document as a statement.
///
void ExecuteDocument(string specifier, DocumentCategory category);
///
/// Loads and executes a document with the specified category and context callback.
///
/// A string specifying the document to be loaded and executed.
/// An optional category for the requested document.
/// An optional context callback for the requested document.
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets script code loaded from the specified document as a statement.
///
void ExecuteDocument(string specifier, DocumentCategory category, DocumentContextCallback contextCallback);
///
/// Executes script code as a command.
///
/// The script command to execute.
/// The command output.
///
/// This method is similar to but optimized for command
/// consoles. The specified command must be limited to a single expression or statement.
/// Script engines can override this method to customize command execution as well as the
/// process of converting the result to a string for console output.
///
string ExecuteCommand(string command);
///
/// Evaluates script code.
///
/// The script code to evaluate.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as an expression.
///
///
/// If a debugger is attached, it will present the specified script code to the user as a
/// document with an automatically selected name. This document will be discarded after
/// execution.
///
///
/// For information about the types of result values that script code can return, see
/// .
///
///
object Evaluate(string code);
///
/// Evaluates script code with an associated document name.
///
/// A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
/// The script code to evaluate.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as an expression.
///
///
/// If a debugger is attached, it will present the specified script code to the user as a
/// document with the specified name. This document will be discarded after execution.
///
///
/// For information about the types of result values that script code can return, see
/// .
///
///
object Evaluate(string documentName, string code);
///
/// Evaluates script code with an associated document name, optionally discarding the document after execution.
///
/// A document name for the script code. Currently this name is used only as a label in presentation contexts such as debugger user interfaces.
/// True to discard the script document after execution, false otherwise.
/// The script code to evaluate.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as an expression.
///
///
/// If a debugger is attached, it will present the specified script code to the user as a
/// document with the specified name. Discarding this document removes it from view but
/// has no effect on the script engine. Only Windows Script engines honor
/// .
///
///
/// The following table summarizes the types of result values that script code can return.
///
///
/// Type
/// Returned As
/// Remarks
///
///
/// String
/// System.String
/// N/A
///
///
/// Boolean
/// System.Boolean
/// N/A
///
///
/// Number
/// System.Int32 or System.Double
///
/// Other numeric types are possible. The exact conversions between script and .NET
/// numeric types are defined by the script engine.
///
///
///
/// Null Reference
/// null
/// N/A
///
///
/// Undefined
///
///
/// This represents JavaScript's
/// undefined,
/// VBScript's
/// Empty,
/// etc.
///
///
///
/// Void
///
///
/// This is returned when script code forwards the result of a host method that returns no value.
///
///
///
/// Host Object
/// Native .NET type
///
/// This includes all .NET types not mentioned above, including value types (enums,
/// structs, etc.), and instances of all other classes. Script code can only create
/// these objects by invoking a host method or constructor. They are returned to
/// the host in their native .NET form.
///
///
///
/// Script Object
///
///
/// This includes all native script objects that have no .NET representation. C#'s
/// dynamic
/// keyword provides a convenient way to access them.
///
///
///
/// Other
/// Unspecified
///
/// This includes host types and other ClearScript-specific objects intended for
/// script code use only. It may also include language-specific values that the
/// ClearScript library does not support.
///
///
///
///
///
object Evaluate(string documentName, bool discard, string code);
///
/// Evaluates script code with the specified document meta-information.
///
/// A structure containing meta-information for the script document.
/// The script code to evaluate.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets the specified script code as an expression.
///
///
/// For information about the types of result values that script code can return, see
/// .
///
///
object Evaluate(DocumentInfo documentInfo, string code);
///
/// Loads and evaluates a script document.
///
/// A string specifying the document to be loaded and evaluated.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets script code loaded from the specified document as an expression.
///
///
/// For information about the types of result values that script code can return, see
/// .
///
///
object EvaluateDocument(string specifier);
///
/// Loads and evaluates a document with the specified category.
///
/// A string specifying the document to be loaded and evaluated.
/// An optional category for the requested document.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets script code loaded from the specified document as an expression.
///
///
/// For information about the types of result values that script code can return, see
/// .
///
///
object EvaluateDocument(string specifier, DocumentCategory category);
///
/// Loads and evaluates a document with the specified category and context callback.
///
/// A string specifying the document to be loaded and evaluated.
/// An optional category for the requested document.
/// An optional context callback for the requested document.
/// The result value.
///
///
/// In some script languages the distinction between statements and expressions is
/// significant but ambiguous for certain syntactic elements. This method always
/// interprets script code loaded from the specified document as an expression.
///
///
/// For information about the types of result values that script code can return, see
/// .
///
///
object EvaluateDocument(string specifier, DocumentCategory category, DocumentContextCallback contextCallback);
///
/// Invokes a global function or procedure.
///
/// The name of the global function or procedure to invoke.
/// Optional invocation arguments.
/// The return value if a function was invoked, an undefined value otherwise.
object Invoke(string funcName, params object[] args);
///
/// Gets a string representation of the script call stack.
///
/// The script call stack formatted as a string.
///
/// This method returns an empty string if the script engine is not executing script code.
/// The stack trace text format is defined by the script engine.
///
string GetStackTrace();
///
/// Interrupts script execution and causes the script engine to throw an exception.
///
///
/// This method can be called safely from any thread.
///
void Interrupt();
///
/// Performs garbage collection.
///
/// True to perform exhaustive garbage collection, false to favor speed over completeness.
void CollectGarbage(bool exhaustive);
}
}