// Copyright (c) Microsoft Corporation. All rights reserved.

// Licensed under the MIT license.

using System;

using System.Diagnostics.CodeAnalysis;

using System.Dynamic;

using System.Globalization;

using System.Linq;

using System.Linq.Expressions;

using System.Runtime.InteropServices;

using Microsoft.ClearScript.Util;

using Microsoft.ClearScript.Util.COM;

namespace Microsoft.ClearScript

{

/// <summary>

/// Provides optional script-callable utility functions.

/// </summary>

/// <remarks>

/// Use <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see> to expose a

/// <c>HostFunctions</c> instance to script code. Each instance can only be exposed in one

/// script engine.

/// </remarks>

public class HostFunctions : IScriptableObject

{

private ScriptEngine engine;

// ReSharper disable EmptyConstructor

/// <summary>

/// Initializes a new <see cref="HostFunctions"/> instance.

/// </summary>

public HostFunctions()

{

// the help file builder (SHFB) insists on an empty constructor here

}

// ReSharper restore EmptyConstructor

#region script-callable interface

// ReSharper disable InconsistentNaming

/// <summary>

/// Creates an empty host object.

/// </summary>

/// <returns>A new empty host object.</returns>

/// <remarks>

/// This function is provided for script languages that do not support external

/// instantiation. It creates an object that supports dynamic property addition and

/// removal. The host can manipulate it via the <see cref="IPropertyBag"/> interface.

/// </remarks>

/// <example>

/// The following code creates an empty host object and adds several properties to it.

/// It assumes that an instance of <see cref="HostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// var item = host.newObj();

/// item.label = "Widget";

/// item.weight = 123.45;

/// </code>

/// </example>

public PropertyBag newObj()

{

return new PropertyBag();

}

/// <summary>

/// Creates a host object of the specified type. This version is invoked if the specified

/// type can be used as a type argument.

/// </summary>

/// <typeparam name="T">The type of object to create.</typeparam>

/// <param name="args">Optional constructor arguments.</param>

/// <returns>A new host object of the specified type.</returns>

/// <remarks>

/// <para>

/// This function is provided for script languages that do not support external

/// instantiation. It is overloaded with <see cref="newObj(object, object[])"/> and

/// selected at runtime if <typeparamref name="T"/> can be used as a type argument.

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see

/// <see cref="ScriptEngine.AddHostObject(string, HostItemFlags, object)">AddHostObject</see>.

/// </para>

/// </remarks>

/// <example>

/// The following code imports the <see cref="System.Random"/> class, creates an

/// instance using the

/// <see href="https://docs.microsoft.com/en-us/dotnet/api/system.random.-ctor#System_Random__ctor_System_Int32_">Random(Int32)</see>

/// constructor, and calls the <see cref="System.Random.NextDouble"/> method.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// var RandomT = host.type("System.Random");

/// var random = host.newObj(RandomT, 100);

/// var value = random.NextDouble();

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public T newObj<T>(params object[] args)

{

return (T)typeof(T).CreateInstance(args);

}

/// <summary>

/// Creates a host object of the specified type. This version is invoked if the specified

/// type cannot be used as a type argument.

/// </summary>

/// <param name="type">The type of object to create.</param>

/// <param name="args">Optional constructor arguments.</param>

/// <returns>A new host object of the specified type.</returns>

/// <remarks>

/// <para>

/// This function is provided for script languages that do not support external

/// instantiation. It is overloaded with <see cref="newObj{T}"/> and selected at runtime if

/// <paramref name="type"/> cannot be used as a type argument. Note that this applies

/// to some host types that support instantiation, such as certain COM/ActiveX types.

/// </para>

/// <para>

/// For information about the mapping between host members and script-callable properties

/// and methods, see

/// <see cref="ScriptEngine.AddHostObject(string, HostItemFlags, object)">AddHostObject</see>.

/// </para>

/// </remarks>

public object newObj(object type, params object[] args)

{

return GetUniqueHostType(type, "type").CreateInstance(args);

}

/// <summary>

/// Performs dynamic instantiation.

/// </summary>

/// <param name="target">The dynamic host object that provides the instantiation operation to perform.</param>

/// <param name="args">Optional instantiation arguments.</param>

/// <returns>The result of the operation, which is usually a new dynamic host object.</returns>

/// <remarks>

/// This function is provided for script languages that do not support external

/// instantiation.

/// </remarks>

public object newObj(IDynamicMetaObjectProvider target, params object[] args)

{

MiscHelpers.VerifyNonNullArgument(target, nameof(target));

if (target.GetMetaObject(Expression.Constant(target)).TryCreateInstance(args, out var result))

{

return result;

}

throw new InvalidOperationException("Invalid dynamic instantiation");

}

/// <summary>

/// Creates a host array with the specified element type.

/// </summary>

/// <typeparam name="T">The element type of the array to create.</typeparam>

/// <param name="lengths">One or more integers representing the array dimension lengths.</param>

/// <returns>A new host array with the specified element type.</returns>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see

/// <see cref="ScriptEngine.AddHostObject(string, HostItemFlags, object)">AddHostObject</see>.

/// </remarks>

/// <example>

/// The following code creates a 5x3 host array of strings.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// var StringT = host.type("System.String");

/// var array = host.newArr(StringT, 5, 3);

/// </code>

/// </example>

/// <seealso cref="HostFunctions.newArr(int[])"/>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object newArr<T>(params int[] lengths)

{

return Array.CreateInstance(typeof(T), lengths);

}

/// <summary>

/// Creates a host array with <see cref="System.Object"/> as the element type.

/// </summary>

/// <param name="lengths">One or more integers representing the array dimension lengths.</param>

/// <returns>A new host array with <see cref="System.Object"/> as the element type.</returns>

/// <remarks>

/// For information about the mapping between host members and script-callable properties

/// and methods, see

/// <see cref="ScriptEngine.AddHostObject(string, HostItemFlags, object)">AddHostObject</see>.

/// </remarks>

/// <seealso cref="HostFunctions.newArr{T}(int[])"/>

public object newArr(params int[] lengths)

{

return newArr<object>(lengths);

}

/// <summary>

/// Creates a host variable of the specified type.

/// </summary>

/// <typeparam name="T">The type of variable to create.</typeparam>

/// <param name="initValue">An optional initial value for the variable.</param>

/// <returns>A new host variable of the specified type.</returns>

/// <remarks>

/// <para>

/// A host variable is a strongly typed object that holds a value of the specified type.

/// Host variables are useful for passing method arguments by reference. In addition to

/// being generally interchangeable with their stored values, host variables support the

/// following properties:

/// </para>

/// <para>

/// <list type="table">

/// <listheader>

/// <term>Property</term>

/// <term>Access</term>

/// <description>Description</description>

/// </listheader>

/// <item>

/// <term><c>value</c></term>

/// <term>read-write</term>

/// <description>The current value of the host variable.</description>

/// </item>

/// <item>

/// <term><c>out</c></term>

/// <term>read-only</term>

/// <description>A reference to the host variable that can be passed as an <c><see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/out-parameter-modifier">out</see></c> argument.</description>

/// </item>

/// <item>

/// <term><c>ref</c></term>

/// <term>read-only</term>

/// <description>A reference to the host variable that can be passed as a <c><see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/ref">ref</see></c> argument.</description>

/// </item>

/// </list>

/// </para>

/// </remarks>

/// <example>

/// The following code demonstrates using a host variable to invoke a method with an

/// <c>out</c> parameter.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import a dictionary type

/// var StringT = host.type("System.String");

/// var StringDictT = host.type("System.Collections.Generic.Dictionary", StringT, StringT);

/// // create and populate a dictionary

/// var dict = host.newObj(StringDictT);

/// dict.Add("foo", "bar");

/// dict.Add("baz", "qux");

/// // look up a dictionary entry

/// var result = host.newVar(StringT);

/// var found = dict.TryGetValue("baz", result.out);

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object newVar<T>(T initValue = default)

{

return new HostVariable<T>(initValue);

}

/// <summary>

/// Creates a delegate that invokes a script function.

/// </summary>

/// <typeparam name="T">The type of delegate to create.</typeparam>

/// <param name="scriptFunc">The script function for which to create a delegate.</param>

/// <returns>A new delegate that invokes the specified script function.</returns>

/// <remarks>

/// If the delegate signature includes parameters passed by reference, the corresponding

/// arguments to the script function will be <see cref="newVar{T}">host variables</see>.

/// The script function can set the value of an output argument by assigning the

/// corresponding host variable's <c>value</c> property.

/// </remarks>

/// <example>

/// The following code demonstrates delegating a callback to a script function.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // create and populate an array of integers

/// var EnumerableT = host.type("System.Linq.Enumerable", "System.Core");

/// var array = EnumerableT.Range(1, 5).ToArray();

/// // import the callback type required to call Array.ForEach

/// var Int32T = host.type("System.Int32");

/// var CallbackT = host.type("System.Action", Int32T);

/// // use Array.ForEach to calculate a sum

/// var sum = 0;

/// var ArrayT = host.type("System.Array");

/// ArrayT.ForEach(array, host.del(CallbackT, function (value) { sum += value; }));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, string, object[])"/>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public T del<T>(object scriptFunc)

{

return DelegateFactory.CreateDelegate<T>(GetEngine(), scriptFunc);

}

/// <summary>

/// Creates a delegate that invokes a script function and returns no value.

/// </summary>

/// <param name="argCount">The number of arguments to pass to the script function.</param>

/// <param name="scriptFunc">The script function for which to create a delegate.</param>

/// <returns>A new delegate that invokes the specified script function and returns no value.</returns>

/// <remarks>

/// This function creates a delegate that accepts <paramref name="argCount"/> arguments and

/// returns no value. The type of all parameters is <see cref="System.Object"/>. Such a

/// delegate is often useful in strongly typed contexts because of

/// <see href="https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/covariance-contravariance/">contravariance</see>.

/// </remarks>

/// <example>

/// The following code demonstrates delegating a callback to a script function.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // create and populate an array of strings

/// var StringT = host.type("System.String");

/// var array = host.newArr(StringT, 3);

/// array.SetValue("first", 0);

/// array.SetValue("second", 1);

/// array.SetValue("third", 2);

/// // use Array.ForEach to generate console output

/// var ArrayT = host.type("System.Array");

/// var ConsoleT = host.type("System.Console");

/// ArrayT.ForEach(array, host.proc(1, function (value) { ConsoleT.WriteLine(value); }));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

/// <seealso cref="newArr{T}"/>

public object proc(int argCount, object scriptFunc)

{

return DelegateFactory.CreateProc(GetEngine(), scriptFunc, argCount);

}

/// <summary>

/// Creates a delegate that invokes a script function and returns a value of the specified type.

/// </summary>

/// <typeparam name="T">The return value type.</typeparam>

/// <param name="argCount">The number of arguments to pass to the script function.</param>

/// <param name="scriptFunc">The script function for which to create a delegate.</param>

/// <returns>A new delegate that invokes the specified script function and returns a value of the specified type.</returns>

/// <remarks>

/// This function creates a delegate that accepts <paramref name="argCount"/> arguments and

/// returns a value of the specified type. The type of all parameters is

/// <see cref="System.Object"/>. Such a delegate is often useful in strongly typed contexts

/// because of

/// <see href="https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/covariance-contravariance/">contravariance</see>.

/// </remarks>

/// <example>

/// The following code demonstrates delegating a callback to a script function.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // create and populate an array of strings

/// var StringT = host.type("System.String");

/// var array = host.newArr(StringT, 3);

/// array.SetValue("first", 0);

/// array.SetValue("second", 1);

/// array.SetValue("third", 2);

/// // import LINQ extensions

/// var EnumerableT = host.type("System.Linq.Enumerable", "System.Core");

/// // use LINQ to create an array of modified strings

/// var selector = host.func(StringT, 1, function (value) { return value.toUpperCase(); });

/// array = array.Select(selector).ToArray();

/// </code>

/// </example>

/// <seealso cref="HostFunctions.func(int, object)"/>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

/// <seealso cref="ExtendedHostFunctions.type(string, string, object[])"/>

public object func<T>(int argCount, object scriptFunc)

{

return DelegateFactory.CreateFunc<T>(GetEngine(), scriptFunc, argCount);

}

/// <summary>

/// Creates a delegate that invokes a script function and returns its result value.

/// </summary>

/// <param name="argCount">The number of arguments to pass to the script function.</param>

/// <param name="scriptFunc">The script function for which to create a delegate.</param>

/// <returns>A new delegate that invokes the specified script function and returns its result value.</returns>

/// <remarks>

/// <para>

/// This function creates a delegate that accepts <paramref name="argCount"/> arguments and

/// returns the result of invoking <paramref name="scriptFunc"/>. The type of all

/// parameters and the return value is <see cref="System.Object"/>. Such a delegate is

/// often useful in strongly typed contexts because of

/// <see href="https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/covariance-contravariance/">contravariance</see>.

/// </para>

/// <para>

/// For information about the types of result values that script code can return, see

/// <see cref="ScriptEngine.Evaluate(string, bool, string)"/>.

/// </para>

/// </remarks>

/// <seealso cref="HostFunctions.func{T}(int, object)"/>

public object func(int argCount, object scriptFunc)

{

return func<object>(argCount, scriptFunc);

}

/// <summary>

/// Gets the <see cref="System.Type"/> for the specified host type. This version is invoked

/// if the specified object can be used as a type argument.

/// </summary>

/// <typeparam name="T">The host type for which to get the <see cref="System.Type"/>.</typeparam>

/// <returns>The <see cref="System.Type"/> for the specified host type.</returns>

/// <remarks>

/// <para>

/// This function is similar to C#'s

/// <c><see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/typeof">typeof</see></c>

/// operator. It is overloaded with <see cref="typeOf(object)"/> and selected at runtime if

/// <typeparamref name="T"/> can be used as a type argument.

/// </para>

/// <para>

/// This function throws an exception if the script engine's

/// <see cref="ScriptEngine.AllowReflection"/> property is set to <c>false</c>.

/// </para>

/// </remarks>

/// <example>

/// The following code retrieves the assembly-qualified name of a host type.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// var StringT = host.type("System.String");

/// var name = host.typeOf(StringT).AssemblyQualifiedName;

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public Type typeOf<T>()

{

GetEngine().CheckReflection();

return typeof(T);

}

/// <summary>

/// Gets the <see cref="System.Type"/> for the specified host type. This version is invoked

/// if the specified object cannot be used as a type argument.

/// </summary>

/// <param name="value">The host type for which to get the <see cref="System.Type"/>.</param>

/// <returns>The <see cref="System.Type"/> for the specified host type.</returns>

/// <remarks>

/// <para>

/// This function is similar to C#'s

/// <c><see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/typeof">typeof</see></c>

/// operator. It is overloaded with <see cref="typeOf{T}"/> and selected at runtime if

/// <paramref name="value"/> cannot be used as a type argument. Note that this applies to

/// some host types; examples are static types and overloaded generic type groups.

/// </para>

/// <para>

/// This function throws an exception if the script engine's

/// <see cref="ScriptEngine.AllowReflection"/> property is set to <c>false</c>.

/// </para>

/// </remarks>

/// <example>

/// The following code retrieves the assembly-qualified name of a host type.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// var ConsoleT = host.type("System.Console");

/// var name = host.typeOf(ConsoleT).AssemblyQualifiedName;

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public Type typeOf(object value)

{

GetEngine().CheckReflection();

return GetUniqueHostType(value, "value");

}

/// <summary>

/// Determines whether an object is compatible with the specified host type.

/// </summary>

/// <typeparam name="T">The host type with which to test <paramref name="value"/> for compatibility.</typeparam>

/// <param name="value">The object to test for compatibility with the specified host type.</param>

/// <returns><c>True</c> if <paramref name="value"/> is compatible with the specified type, <c>false</c> otherwise.</returns>

/// <remarks>

/// This function is similar to C#'s

/// <c><see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/is">is</see></c>

/// operator.

/// </remarks>

/// <example>

/// The following code defines a function that determines whether an object implements

/// <see cref="System.IComparable"/>.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// function isComparable(value)

/// {

/// var IComparableT = host.type("System.IComparable");

/// return host.isType(IComparableT, value);

/// }

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public bool isType<T>(object value)

{

return value is T;

}

/// <summary>

/// Casts an object to the specified host type, returning <c>null</c> if the cast fails.

/// </summary>

/// <typeparam name="T">The host type to which to cast <paramref name="value"/>.</typeparam>

/// <param name="value">The object to cast to the specified host type.</param>

/// <returns>The result of the cast if successful, <c>null</c> otherwise.</returns>

/// <remarks>

/// This function is similar to C#'s

/// <c><see href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/as">as</see></c>

/// operator.

/// </remarks>

/// <example>

/// The following code defines a function that disposes an object if it implements

/// <see cref="System.IDisposable"/>.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// function dispose(value)

/// {

/// var IDisposableT = host.type("System.IDisposable");

/// var disposable = host.asType(IDisposableT, value);

/// if (disposable) {

/// disposable.Dispose();

/// }

/// }

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object asType<T>(object value) where T : class

{

return HostItem.Wrap(GetEngine(), value as T, typeof(T));

}

/// <summary>

/// Casts an object to the specified host type.

/// </summary>

/// <typeparam name="T">The host type to which to cast <paramref name="value"/>.</typeparam>

/// <param name="value">The object to cast to the specified host type.</param>

/// <returns>The result of the cast.</returns>

/// <remarks>

/// If the cast fails, this function throws an exception.

/// </remarks>

/// <example>

/// The following code casts a floating-point value to a 32-bit integer.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// var Int32T = host.type("System.Int32");

/// var intValue = host.cast(Int32T, 12.5);

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object cast<T>(object value)

{

return HostItem.Wrap(GetEngine(), value.DynamicCast<T>(), typeof(T));

}

/// <summary>

/// Determines whether an object is a host type. This version is invoked if the specified

/// object cannot be used as a type argument.

/// </summary>

/// <param name="value">The object to test.</param>

/// <returns><c>True</c> if <paramref name="value"/> is a host type, <c>false</c> otherwise.</returns>

/// <remarks>

/// This function is overloaded with <see cref="isTypeObj{T}"/> and selected at runtime if

/// <paramref name="value"/> cannot be used as a type argument. Note that this applies to

/// some host types; examples are static types and overloaded generic type groups.

/// </remarks>

public bool isTypeObj(object value)

{

return value is HostType;

}

// ReSharper disable UnusedTypeParameter

/// <summary>

/// Determines whether an object is a host type. This version is invoked if the specified

/// object can be used as a type argument.

/// </summary>

/// <typeparam name="T">The host type (ignored).</typeparam>

/// <returns><c>True</c>.</returns>

/// <remarks>

/// This function is overloaded with <see cref="isTypeObj(object)"/> and selected at

/// runtime if <typeparamref name="T"/> can be used as a type argument. Because type

/// arguments are always host types, this method ignores its type argument and always

/// returns <c>true</c>.

/// </remarks>

public bool isTypeObj<T>()

{

return true;

}

// ReSharper restore UnusedTypeParameter

/// <summary>

/// Determines whether the specified value is <c>null</c>.

/// </summary>

/// <param name="value">The value to test.</param>

/// <returns><c>True</c> if <paramref name="value"/> is <c>null</c>, <c>false</c> otherwise.</returns>

/// <remarks>

/// Use this function to test field, property, and method return values when <c>null</c>

/// result wrapping is in effect (see

/// <see cref="ScriptMemberFlags.WrapNullResult"/> and

/// <see cref="ScriptEngine.EnableNullResultWrapping"/>).

/// </remarks>

/// <seealso cref="ScriptMemberFlags.WrapNullResult"/>

/// <seealso cref="ScriptEngine.EnableNullResultWrapping"/>

public bool isNull(object value)

{

return value == null;

}

/// <summary>

/// Creates a strongly typed flag set.

/// </summary>

/// <typeparam name="T">The type of flag set to create.</typeparam>

/// <param name="args">The flags to include in the flag set.</param>

/// <returns>A strongly typed flag set containing the specified flags.</returns>

/// <remarks>

/// This function throws an exception if <typeparamref name="T"/> is not a flag set type.

/// </remarks>

/// <example>

/// The following code demonstrates using a strongly typed flag set.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import URI types

/// var UriT = host.type("System.Uri", "System");

/// var UriFormatT = host.type("System.UriFormat", "System");

/// var UriComponentsT = host.type("System.UriComponents", "System");

/// // create a URI

/// var uri = host.newObj(UriT, "http://www.example.com:8080/path/to/file/sample.htm?x=1&amp;y=2");

/// // extract URI components

/// var components = host.flags(UriComponentsT.Scheme, UriComponentsT.Host, UriComponentsT.Path);

/// var result = uri.GetComponents(components, UriFormatT.Unescaped);

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, string, object[])"/>

public T flags<T>(params T[] args)

{

var type = typeof(T);

if (!type.IsFlagsEnum())

{

throw new InvalidOperationException(MiscHelpers.FormatInvariant("{0} is not a flag set type", type.GetFullFriendlyName()));

}

try

{

return args.Aggregate(0UL, (flags, arg) => flags | Convert.ToUInt64(arg, CultureInfo.InvariantCulture)).DynamicCast<T>();

}

catch (OverflowException)

{

return args.Aggregate(0L, (flags, arg) => flags | Convert.ToInt64(arg, CultureInfo.InvariantCulture)).DynamicCast<T>();

}

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.SByte"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.SByte"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.SByte"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.SByte"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.SByte"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.SByte");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toSByte(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toSByte(IConvertible value)

{

return HostObject.Wrap(Convert.ToSByte(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Byte"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Byte"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Byte"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.Byte"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.Byte"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.Byte");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toByte(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toByte(IConvertible value)

{

return HostObject.Wrap(Convert.ToByte(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Int16"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Int16"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Int16"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.Int16"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.Int16"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.Int16");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toInt16(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toInt16(IConvertible value)

{

return HostObject.Wrap(Convert.ToInt16(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.UInt16"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.UInt16"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.UInt16"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.UInt16"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.UInt16"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.UInt16");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toUInt16(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toUInt16(IConvertible value)

{

return HostObject.Wrap(Convert.ToUInt16(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Char"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Char"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Char"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.Char"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.Char"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.Char");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toChar(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toChar(IConvertible value)

{

return HostObject.Wrap(Convert.ToChar(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Int32"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Int32"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Int32"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.Int32"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.Int32"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.Int32");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toInt32(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toInt32(IConvertible value)

{

return HostObject.Wrap(Convert.ToInt32(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.UInt32"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.UInt32"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.UInt32"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.UInt32"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.UInt32"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.UInt32");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toUInt32(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toUInt32(IConvertible value)

{

return HostObject.Wrap(Convert.ToUInt32(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Int64"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Int64"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Int64"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.Int64"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.Int64"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.Int64");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toInt64(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toInt64(IConvertible value)

{

return HostObject.Wrap(Convert.ToInt64(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.UInt64"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.UInt64"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.UInt64"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.UInt64"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.UInt64"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.UInt64");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toUInt64(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toUInt64(IConvertible value)

{

return HostObject.Wrap(Convert.ToUInt64(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Single"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Single"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Single"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may

/// be useful for passing arguments to <see cref="System.Single"/> parameters if the script

/// engine does not support that type natively.

/// </remarks>

/// <example>

/// The following code adds an element of type <see cref="System.Single"/> to a strongly

/// typed list.

/// It assumes that an instance of <see cref="ExtendedHostFunctions"/> is exposed under

/// the name "host"

/// (see <see cref="ScriptEngine.AddHostObject(string, object)">AddHostObject</see>).

/// <code lang="JavaScript">

/// // import types

/// var ElementT = host.type("System.Single");

/// var ListT = host.type("System.Collections.Generic.List", ElementT);

/// // create a list

/// var list = host.newObj(ListT);

/// // add a list element

/// list.Add(host.toSingle(42));

/// </code>

/// </example>

/// <seealso cref="ExtendedHostFunctions.type(string, object[])"/>

public object toSingle(IConvertible value)

{

return HostObject.Wrap(Convert.ToSingle(value));

}

/// <summary>

/// Converts the specified value to a strongly typed <see cref="System.Double"/> instance.

/// </summary>

/// <param name="value">The value to convert.</param>

/// <returns>An object that can be passed to a parameter of type <see cref="System.Double"/>.</returns>

/// <remarks>

/// This function converts <paramref name="value"/> to <see cref="System.Double"/> and

/// packages the result to retain its numeric type across the host-script boundary. It may