LanguagePrimitives.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using System.Collections;
using System.Collections.Generic;
using System.Collections.Specialized;
using System.ComponentModel;
using System.Data;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Linq.Expressions;
using System.Management.Automation.Internal;
using System.Management.Automation.Language;
using System.Management.Automation.Runspaces;
using System.Reflection;
using System.Reflection.Emit;
using System.Runtime.CompilerServices;
using System.Text;
using System.Text.RegularExpressions;
using System.Xml;

using Dbg = System.Management.Automation.Diagnostics;
using MethodCacheEntry = System.Management.Automation.DotNetAdapter.MethodCacheEntry;
#if !UNIX
using System.DirectoryServices;
using System.Management;
#endif

#pragma warning disable 1634, 1691 // Stops compiler from warning about unknown warnings
#pragma warning disable 56500

namespace System.Management.Automation
{
    #region public type converters
    /// <summary>
    /// Defines a base class implemented when you need to customize the type conversion for a target class.
    /// </summary>
    /// <remarks>
    /// There are two ways of associating the PSTypeConverter with its target class:
    ///     - Through the type configuration file.
    ///     - By applying a TypeConverterAttribute to the target class.
    ///
    /// Unlike System.ComponentModel.TypeConverter, PSTypeConverter can be applied to a family of types (like all types derived from System.Enum).
    /// PSTypeConverter has two main differences from TypeConverter:
    ///     - It can be applied to a family of types and not only the one type as in TypeConverter. In order to do that
    /// ConvertFrom and CanConvertFrom receive destinationType to know to which type specifically we are converting sourceValue.
    ///     - ConvertTo and ConvertFrom receive formatProvider and ignoreCase.
    /// Other differences to System.ComponentModel.TypeConverter:
    ///     - There is no ITypeDescriptorContext.
    ///     - This class is abstract
    /// </remarks>
    public abstract class PSTypeConverter
    {
        private static object GetSourceValueAsObject(PSObject sourceValue)
        {
            if (sourceValue == null)
            {
                return null;
            }

            if (sourceValue.BaseObject is PSCustomObject)
            {
                return sourceValue;
            }
            else
            {
                return PSObject.Base(sourceValue);
            }
        }

        /// <summary>
        /// Determines if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter.
        /// </summary>
        /// <param name="sourceValue">Value supposedly *not* of the types supported by this converted to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">One of the types supported by this converter to which the <paramref name="sourceValue"/> parameter should be converted.</param>
        /// <returns>True if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter, otherwise false.</returns>
        public abstract bool CanConvertFrom(object sourceValue, Type destinationType);

        /// <summary>
        /// Determines if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter.
        /// </summary>
        /// <param name="sourceValue">Value supposedly *not* of the types supported by this converted to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">One of the types supported by this converter to which the <paramref name="sourceValue"/> parameter should be converted.</param>
        /// <returns>True if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter, otherwise false.</returns>
        public virtual bool CanConvertFrom(PSObject sourceValue, Type destinationType)
        {
            return this.CanConvertFrom(GetSourceValueAsObject(sourceValue), destinationType);
        }

        /// <summary>
        /// Converts the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.
        /// </summary>
        /// <param name="sourceValue">Value supposedly *not* of the types supported by this converted to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">One of the types supported by this converter to which the <paramref name="sourceValue"/> parameter should be converted to.</param>
        /// <param name="formatProvider">The format provider to use like in IFormattable's ToString.</param>
        /// <param name="ignoreCase">True if case should be ignored.</param>
        /// <returns>The <paramref name="sourceValue"/> parameter converted to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.</returns>
        /// <exception cref="InvalidCastException">If no conversion was possible.</exception>
        public abstract object ConvertFrom(object sourceValue, Type destinationType, IFormatProvider formatProvider, bool ignoreCase);

        /// <summary>
        /// Converts the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.
        /// </summary>
        /// <param name="sourceValue">Value supposedly *not* of the types supported by this converted to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">One of the types supported by this converter to which the <paramref name="sourceValue"/> parameter should be converted to.</param>
        /// <param name="formatProvider">The format provider to use like in IFormattable's ToString.</param>
        /// <param name="ignoreCase">True if case should be ignored.</param>
        /// <returns>The <paramref name="sourceValue"/> parameter converted to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.</returns>
        /// <exception cref="InvalidCastException">If no conversion was possible.</exception>
        public virtual object ConvertFrom(PSObject sourceValue, Type destinationType, IFormatProvider formatProvider, bool ignoreCase)
        {
            return this.ConvertFrom(GetSourceValueAsObject(sourceValue), destinationType, formatProvider, ignoreCase);
        }

        /// <summary>
        /// Returns true if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter.
        /// </summary>
        /// <param name="sourceValue">Value supposedly from one of the types supported by this converter to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">Type to convert the <paramref name="sourceValue"/> parameter, supposedly not one of the types supported by the converter.</param>
        /// <returns>True if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter, otherwise false.</returns>
        public abstract bool CanConvertTo(object sourceValue, Type destinationType);

        /// <summary>
        /// Returns true if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter.
        /// </summary>
        /// <param name="sourceValue">Value supposedly from one of the types supported by this converter to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">Type to convert the <paramref name="sourceValue"/> parameter, supposedly not one of the types supported by the converter.</param>
        /// <returns>True if the converter can convert the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter, otherwise false.</returns>
        public virtual bool CanConvertTo(PSObject sourceValue, Type destinationType)
        {
            return this.CanConvertTo(GetSourceValueAsObject(sourceValue), destinationType);
        }

        /// <summary>
        /// Converts the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.
        /// </summary>
        /// <param name="sourceValue">Value supposedly from one of the types supported by this converter to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">Type to convert the <paramref name="sourceValue"/> parameter, supposedly not one of the types supported by the converter.</param>
        /// <param name="formatProvider">The format provider to use like in IFormattable's ToString.</param>
        /// <param name="ignoreCase">True if case should be ignored.</param>
        /// <returns>SourceValue converted to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.</returns>
        /// <exception cref="InvalidCastException">If no conversion was possible.</exception>
        public abstract object ConvertTo(object sourceValue, Type destinationType, IFormatProvider formatProvider, bool ignoreCase);

        /// <summary>
        /// Converts the <paramref name="sourceValue"/> parameter to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.
        /// </summary>
        /// <param name="sourceValue">Value supposedly from one of the types supported by this converter to be converted to the <paramref name="destinationType"/> parameter.</param>
        /// <param name="destinationType">Type to convert the <paramref name="sourceValue"/> parameter, supposedly not one of the types supported by the converter.</param>
        /// <param name="formatProvider">The format provider to use like in IFormattable's ToString.</param>
        /// <param name="ignoreCase">True if case should be ignored.</param>
        /// <returns>SourceValue converted to the <paramref name="destinationType"/> parameter using formatProvider and ignoreCase.</returns>
        /// <exception cref="InvalidCastException">If no conversion was possible.</exception>
        public virtual object ConvertTo(PSObject sourceValue, Type destinationType, IFormatProvider formatProvider, bool ignoreCase)
        {
            return this.ConvertTo(GetSourceValueAsObject(sourceValue), destinationType, formatProvider, ignoreCase);
        }
    }

    /// <summary>
    /// Enables a type that only has conversion from string to be converted from all other
    /// types through string.
    /// </summary>
    /// <remarks>
    /// It is permitted to subclass <see cref="ConvertThroughString"/>
    /// but there is no established scenario for doing this, nor has it been tested.
    /// </remarks>
    public class ConvertThroughString : PSTypeConverter
    {
        /// <summary>
        /// This will return false only if sourceValue is string.
        /// </summary>
        /// <param name="sourceValue">Value to convert from.</param>
        /// <param name="destinationType">Ignored.</param>
        /// <returns>False only if sourceValue is string.</returns>
        public override bool CanConvertFrom(object sourceValue, Type destinationType)
        {
            // This if avoids infinite recursion.
            if (sourceValue is string)
            {
                return false;
            }

            return true;
        }

        /// <summary>
        /// Converts to destinationType by first converting sourceValue to string
        /// and then converting the result to destinationType.
        /// </summary>
        /// <param name="sourceValue">The value to convert from.</param>
        /// <param name="destinationType">The type this converter is associated with.</param>
        /// <param name="formatProvider">The IFormatProvider to use.</param>
        /// <param name="ignoreCase">True if case should be ignored.</param>
        /// <returns>SourceValue converted to destinationType.</returns>
        /// <exception cref="PSInvalidCastException">When no conversion was possible.</exception>
        public override object ConvertFrom(object sourceValue, Type destinationType, IFormatProvider formatProvider, bool ignoreCase)
        {
            string sourceAsString = (string)LanguagePrimitives.ConvertTo(sourceValue, typeof(string), formatProvider);
            return LanguagePrimitives.ConvertTo(sourceAsString, destinationType, formatProvider);
        }

        /// <summary>
        /// Returns false, since this converter is not designed to be used to
        /// convert from the type associated with the converted to other types.
        /// </summary>
        /// <param name="sourceValue">The value to convert from.</param>
        /// <param name="destinationType">The value to convert from.</param>
        /// <returns>False.</returns>
        public override bool CanConvertTo(object sourceValue, Type destinationType)
        {
            return false;
        }

        /// <summary>
        /// Throws NotSupportedException, since this converter is not designed to be used to
        /// convert from the type associated with the converted to other types.
        /// </summary>
        /// <param name="sourceValue">The value to convert from.</param>
        /// <param name="destinationType">The value to convert from.</param>
        /// <param name="formatProvider">The IFormatProvider to use.</param>
        /// <param name="ignoreCase">True if case should be ignored.</param>
        /// <returns>This method does not return a value.</returns>
        /// <exception cref="NotSupportedException">NotSupportedException is always thrown.</exception>
        public override object ConvertTo(object sourceValue, Type destinationType, IFormatProvider formatProvider, bool ignoreCase)
        {
            throw PSTraceSource.NewNotSupportedException();
        }
    }
    #endregion public type converters

    /// <summary>
    /// The ranking of versions for comparison purposes (used in overload resolution.)
    /// A larger value means the conversion is better.
    ///
    /// Note that the lower nibble is all ones for named conversion ranks.  This allows for
    /// conversions with rankings in between the named values.  For example, int=>string[]
    /// is value dependent, if the conversion from int=>string succeeds, then an array is
    /// created, otherwise we try some other conversion.  The int=>string[] conversion should
    /// be worse than int=>string, but it is probably better than many other conversions, so
    /// we want it to be only slightly worse than int=>string.
    /// </summary>
    /// <remarks>
    /// ValueDependent is a flag, but we don't mark the enum as flags because it really isn't
    /// a flags enum.
    /// To make debugging easier, the "in between" conversions are all named, though there are
    /// no references in the code.  They all use the suffix S2A which means "scalar to array".
    /// </remarks>
    internal enum ConversionRank
    {
        None = 0x0000,
        UnrelatedArraysS2A = 0x0007,
        UnrelatedArrays = 0x000F,
        ToStringS2A = 0x0017,
        ToString = 0x001F,
        CustomS2A = 0x0027,
        Custom = 0x002F,
        IConvertibleS2A = 0x0037,
        IConvertible = 0x003F,
        ImplicitCastS2A = 0x0047,
        ImplicitCast = 0x004F,
        ExplicitCastS2A = 0x0057,
        ExplicitCast = 0x005F,
        ConstructorS2A = 0x0067,
        Constructor = 0x006F,
        Create = 0x0073,
        ParseS2A = 0x0077,
        Parse = 0x007F,
        PSObjectS2A = 0x0087,
        PSObject = 0x008F,
        LanguageS2A = 0x0097,
        Language = 0x009F,
        NullToValue = 0x00AF,
        NullToRef = 0x00BF,
        NumericExplicitS2A = 0x00C7,
        NumericExplicit = 0x00CF,
        NumericExplicit1S2A = 0x00D7,
        NumericExplicit1 = 0x00DF,
        NumericStringS2A = 0x00E7,
        NumericString = 0x00EF,
        NumericImplicitS2A = 0x00F7,
        NumericImplicit = 0x00FF,
        AssignableS2A = 0x0107,
        Assignable = 0x010F,
        IdentityS2A = 0x0117,
        StringToCharArray = 0x011A,
        Identity = 0x011F,

        ValueDependent = 0xFFF7,
    }

    /// <summary>
    /// Defines language support methods.
    /// </summary>
    [SuppressMessage("Microsoft.Maintainability", "CA1506:AvoidExcessiveClassCoupling", Justification = "Refactoring LanguagePrimitives takes lot of dev/test effort. Since V1 code is already shipped, we tend to exclude this message.")]
    public static class LanguagePrimitives
    {
        [TraceSource("ETS", "Extended Type System")]
        private static PSTraceSource s_tracer = PSTraceSource.GetTracer("ETS", "Extended Type System");

        internal delegate void MemberNotFoundError(PSObject pso, DictionaryEntry property, Type resultType);

        internal delegate void MemberSetValueError(SetValueException e);

        internal const string OrderedAttribute = "ordered";
        internal const string DoublePrecision = "G15";
        internal const string SinglePrecision = "G7";

        internal static void CreateMemberNotFoundError(PSObject pso, DictionaryEntry property, Type resultType)
        {
            string availableProperties = GetAvailableProperties(pso);

            string message = StringUtil.Format(ExtendedTypeSystem.PropertyNotFound, property.Key.ToString(), resultType.FullName, availableProperties);

            typeConversion.WriteLine("Issuing an error message about not being able to create an object from hashtable.");
            throw new InvalidOperationException(message);
        }

        internal static void CreateMemberSetValueError(SetValueException e)
        {
            typeConversion.WriteLine("Issuing an error message about not being able to set the properties for an object.");
            throw e;
        }

        static LanguagePrimitives()
        {
            RebuildConversionCache();
            InitializeGetEnumerableCache();

#if !CORECLR // AppDomain Not In CoreCLR
            AppDomain.CurrentDomain.AssemblyResolve += AssemblyResolveHelper;
#endif
        }

        internal static void UpdateTypeConvertFromTypeTable(string typeName)
        {
            lock (s_converterCache)
            {
                var toRemove = s_converterCache.Keys.Where(
                    conv => string.Equals(conv.to.FullName, typeName, StringComparison.OrdinalIgnoreCase) ||
                            string.Equals(conv.from.FullName, typeName, StringComparison.OrdinalIgnoreCase)).ToArray();
                foreach (var k in toRemove)
                {
                    s_converterCache.Remove(k);
                }

                // Note we do not clear possibleTypeConverter even when removing.
                //
                // The conversion cache and the possibleTypeConverter cache are process wide, but
                // the type table used for any specific conversion is runspace specific.
                s_possibleTypeConverter[typeName] = true;
            }
        }

        #region GetEnumerable/GetEnumerator

        /// <summary>
        /// This is a wrapper class that allows us to use the generic IEnumerable
        /// implementation of an object when we can't use it's non-generic
        /// implementation.
        /// </summary>
        private class EnumerableTWrapper : IEnumerable
        {
            private object _enumerable;
            private Type _enumerableType;
            private DynamicMethod _getEnumerator;

            internal EnumerableTWrapper(object enumerable, Type enumerableType)
            {
                _enumerable = enumerable;
                _enumerableType = enumerableType;
                CreateGetEnumerator();
            }

            private void CreateGetEnumerator()
            {
                _getEnumerator = new DynamicMethod("GetEnumerator", typeof(object),
                    new Type[] { typeof(object) }, typeof(LanguagePrimitives).Module, true);

                ILGenerator emitter = _getEnumerator.GetILGenerator();

                emitter.Emit(OpCodes.Ldarg_0);
                emitter.Emit(OpCodes.Castclass, _enumerableType);
                MethodInfo methodInfo = _enumerableType.GetMethod("GetEnumerator", new Type[] { });
                emitter.Emit(OpCodes.Callvirt, methodInfo);
                emitter.Emit(OpCodes.Ret);
            }

            #region IEnumerable Members

            public IEnumerator GetEnumerator()
            {
                return (IEnumerator)_getEnumerator.Invoke(null, new object[] { _enumerable });
            }

            #endregion
        }

        private static IEnumerable GetEnumerableFromIEnumerableT(object obj)
        {
            foreach (Type i in obj.GetType().GetInterfaces())
            {
                if (i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IEnumerable<>))
                {
                    return new EnumerableTWrapper(obj, i);
                }
            }

            return null;
        }

        private delegate IEnumerable GetEnumerableDelegate(object obj);
        private static Dictionary<Type, GetEnumerableDelegate> s_getEnumerableCache = new Dictionary<Type, GetEnumerableDelegate>(32);

        private static GetEnumerableDelegate GetOrCalculateEnumerable(Type type)
        {
            GetEnumerableDelegate getEnumerable = null;
            lock (s_getEnumerableCache)
            {
                if (!s_getEnumerableCache.TryGetValue(type, out getEnumerable))
                {
                    getEnumerable = CalculateGetEnumerable(type);
                    s_getEnumerableCache.Add(type, getEnumerable);
                }
            }

            return getEnumerable;
        }

        private static void InitializeGetEnumerableCache()
        {
            lock (s_getEnumerableCache)
            {
                // PowerShell doesn't treat strings as enumerables so just return null.
                // we also want to return null on common numeric types very quickly
                s_getEnumerableCache.Clear();
                s_getEnumerableCache.Add(typeof(string), LanguagePrimitives.ReturnNullEnumerable);
                s_getEnumerableCache.Add(typeof(int), LanguagePrimitives.ReturnNullEnumerable);
                s_getEnumerableCache.Add(typeof(double), LanguagePrimitives.ReturnNullEnumerable);
            }
        }

        internal static bool IsTypeEnumerable(Type type)
        {
            if (type == null) { return false; }

            GetEnumerableDelegate getEnumerable = GetOrCalculateEnumerable(type);
            return (getEnumerable != LanguagePrimitives.ReturnNullEnumerable);
        }

        /// <summary>
        /// Returns True if the language considers obj to be IEnumerable.
        /// </summary>
        /// <param name="obj">
        /// IEnumerable or IEnumerable-like object
        /// </param>
        [SuppressMessage("Microsoft.Naming", "CA1720:IdentifiersShouldNotContainTypeNames", MessageId = "obj", Justification = "Since V1 code is already shipped, excluding this message.")]
        public static bool IsObjectEnumerable(object obj)
        {
            return IsTypeEnumerable(PSObject.Base(obj)?.GetType());
        }

        /// <summary>
        /// Retrieves the IEnumerable of obj or null if the language does not consider obj to be IEnumerable.
        /// </summary>
        /// <param name="obj">
        /// IEnumerable or IEnumerable-like object
        /// </param>
        [SuppressMessage("Microsoft.Naming", "CA1720:IdentifiersShouldNotContainTypeNames", MessageId = "obj", Justification = "Since V1 code is already shipped, excluding this message.")]
        public static IEnumerable GetEnumerable(object obj)
        {
            obj = PSObject.Base(obj);
            if (obj == null) { return null; }

            GetEnumerableDelegate getEnumerable = GetOrCalculateEnumerable(obj.GetType());
            return getEnumerable(obj);
        }

        private static IEnumerable ReturnNullEnumerable(object obj)
        {
            return null;
        }

        private static IEnumerable DataTableEnumerable(object obj)
        {
            return (((DataTable)obj).Rows);
        }

        private static IEnumerable TypicalEnumerable(object obj)
        {
            IEnumerable e = (IEnumerable)obj;
            try
            {
                // Some IEnumerable implementations just return null.  Others
                // raise an exception.  Either of these may have a perfectly
                // good generic implementation, so we'll try those if the
                // non-generic is no good.
                if (e.GetEnumerator() == null)
                {
                    return GetEnumerableFromIEnumerableT(obj);
                }

                return e;
            }
            catch (Exception innerException)
            {
                e = GetEnumerableFromIEnumerableT(obj);
                if (e != null)
                {
                    return e;
                }

                throw new ExtendedTypeSystemException(
                    "ExceptionInGetEnumerator",
                    innerException,
                    ExtendedTypeSystem.EnumerationException,
                    innerException.Message);
            }
        }

        private static GetEnumerableDelegate CalculateGetEnumerable(Type objectType)
        {
            if (typeof(DataTable).IsAssignableFrom(objectType))
            {
                return LanguagePrimitives.DataTableEnumerable;
            }

            // Don't treat IDictionary or XmlNode as enumerable...
            if (typeof(IEnumerable).IsAssignableFrom(objectType)
                && !typeof(IDictionary).IsAssignableFrom(objectType)
                && !typeof(XmlNode).IsAssignableFrom(objectType))
            {
                return LanguagePrimitives.TypicalEnumerable;
            }

            return LanguagePrimitives.ReturnNullEnumerable;
        }

        private static readonly CallSite<Func<CallSite, object, IEnumerator>> s_getEnumeratorSite =
            CallSite<Func<CallSite, object, IEnumerator>>.Create(PSEnumerableBinder.Get());

        /// <summary>
        /// Retrieves the IEnumerator of obj or null if the language does not consider obj as capable of returning an IEnumerator.
        /// </summary>
        /// <param name="obj">
        /// IEnumerable or IEnumerable-like object
        /// </param>
        /// <exception cref="ExtendedTypeSystemException">When the act of getting the enumerator throws an exception.</exception>
        [SuppressMessage("Microsoft.Naming", "CA1720:IdentifiersShouldNotContainTypeNames", MessageId = "obj", Justification = "Since V1 code is already shipped, excluding this message for backward compatibility reasons.")]
        public static IEnumerator GetEnumerator(object obj)
        {
            var result = s_getEnumeratorSite.Target.Invoke(s_getEnumeratorSite, obj);
            return (result is EnumerableOps.NonEnumerableObjectEnumerator) ? null : result;
        }

        #endregion GetEnumerable/GetEnumerator

        /// <summary>
        /// This method takes a an arbitrary object and wraps it in a PSDataCollection of PSObject.
        /// This simplifies interacting with the PowerShell workflow activities.
        /// </summary>
        /// <param name="inputValue"></param>
        /// <returns></returns>
        public static PSDataCollection<PSObject> GetPSDataCollection(object inputValue)
        {
            PSDataCollection<PSObject> result = new PSDataCollection<PSObject>();
            if (inputValue != null)
            {
                IEnumerator e = GetEnumerator(inputValue);
                if (e != null)
                {
                    while (e.MoveNext())
                    {
                        result.Add(e.Current == null ? null : PSObject.AsPSObject(e.Current));
                    }
                }
                else
                {
                    result.Add(PSObject.AsPSObject(inputValue));
                }
            }

            result.Complete();
            return result;
        }

        /// <summary>
        /// Used to compare two objects for equality converting the second to the type of the first, if required.
        /// </summary>
        /// <param name="first">First object.</param>
        /// <param name="second">Object to compare first to.</param>
        /// <returns>True if first is equal to the second.</returns>
        public static new bool Equals(object first, object second)
        {
            return Equals(first, second, false, CultureInfo.InvariantCulture);
        }

        /// <summary>
        /// Used to compare two objects for equality converting the second to the type of the first, if required.
        /// </summary>
        /// <param name="first">First object.</param>
        /// <param name="second">Object to compare first to.</param>
        /// <param name="ignoreCase">used only if first and second are strings
        /// to specify the type of string comparison </param>
        /// <returns>True if first is equal to the second.</returns>
        public static bool Equals(object first, object second, bool ignoreCase)
        {
            return Equals(first, second, ignoreCase, CultureInfo.InvariantCulture);
        }

        /// <summary>
        /// Used to compare two objects for equality converting the second to the type of the first, if required.
        /// </summary>
        /// <param name="first">First object.</param>
        /// <param name="second">Object to compare first to.</param>
        /// <param name="ignoreCase">used only if first and second are strings
        /// to specify the type of string comparison </param>
        /// <param name="formatProvider">the format/culture to be used. If this parameter is null,
        /// CultureInfo.InvariantCulture will be used.
        /// </param>
        /// <returns>True if first is equal to the second.</returns>
        public static bool Equals(object first, object second, bool ignoreCase, IFormatProvider formatProvider)
        {
            // If both first and second are null it returns true.
            // If one is null and the other is not it returns false.
            // if (first.Equals(second)) it returns true otherwise it goes ahead with type conversion operations.
            // If both first and second are strings it returns (string.Compare(firstString, secondString, ignoreCase) == 0).
            // If second can be converted to the type of the first, it does so and returns first.Equals(secondConverted)
            // Otherwise false is returned

            if (formatProvider == null)
            {
                formatProvider = CultureInfo.InvariantCulture;
            }

            var culture = formatProvider as CultureInfo;
            if (culture == null)
            {
                throw PSTraceSource.NewArgumentException("formatProvider");
            }

            first = PSObject.Base(first);
            second = PSObject.Base(second);

            if (first == null)
            {
                if (second == null) return true;
                return false;
            }

            if (second == null)
            {
                return false; // first is not null
            }

            string firstString = first as string;
            string secondString;
            if (firstString != null)
            {
                secondString = second as string ?? (string)LanguagePrimitives.ConvertTo(second, typeof(string), culture);
                return (culture.CompareInfo.Compare(firstString, secondString,
                                                    ignoreCase ? CompareOptions.IgnoreCase : CompareOptions.None) == 0);
            }

            if (first.Equals(second)) return true;

            Type firstType = first.GetType();
            Type secondType = second.GetType();
            int firstIndex = LanguagePrimitives.TypeTableIndex(firstType);
            int secondIndex = LanguagePrimitives.TypeTableIndex(secondType);
            if ((firstIndex != -1) && (secondIndex != -1))
            {
                return LanguagePrimitives.NumericCompare(first, second, firstIndex, secondIndex) == 0;
            }

            if (firstType == typeof(char) && ignoreCase)
            {
                secondString = second as string;
                if (secondString != null && secondString.Length == 1)
                {
                    char firstAsUpper = culture.TextInfo.ToUpper((char)first);
                    char secondAsUpper = culture.TextInfo.ToUpper(secondString[0]);
                    return firstAsUpper.Equals(secondAsUpper);
                }
                else if (secondType == typeof(char))
                {
                    char firstAsUpper = culture.TextInfo.ToUpper((char)first);
                    char secondAsUpper = culture.TextInfo.ToUpper((char)second);
                    return firstAsUpper.Equals(secondAsUpper);
                }
            }

            try
            {
                object secondConverted = LanguagePrimitives.ConvertTo(second, firstType, culture);
                return first.Equals(secondConverted);
            }
            catch (InvalidCastException)
            {
            }

            return false;
        }

        /// <summary>
        /// Helper method for [Try]Compare to determine object ordering with null.
        /// </summary>
        /// <param name="value">The numeric value to compare to null.</param>
        /// <param name="numberIsRightHandSide">True if the number to compare is on the right hand side if the comparison.</param>
        private static int CompareObjectToNull(object value, bool numberIsRightHandSide)
        {
            var i = numberIsRightHandSide ? -1 : 1;

            // If it's a positive number, including 0, it's greater than null
            // for everything else it's less than zero...
            switch (value)
            {
                case Int16 i16: return Math.Sign(i16) < 0 ? -i : i;
                case Int32 i32: return Math.Sign(i32) < 0 ? -i : i;
                case Int64 i64: return Math.Sign(i64) < 0 ? -i : i;
                case sbyte sby: return Math.Sign(sby) < 0 ? -i : i;
                case float f: return Math.Sign(f) < 0 ? -i : i;
                case double d: return Math.Sign(d) < 0 ? -i : i;
                case decimal de: return Math.Sign(de) < 0 ? -i : i;
                default: return i;
            }
        }

        /// <summary>
        /// Compare first and second, converting second to the
        /// type of the first, if necessary.
        /// </summary>
        /// <param name="first">First comparison value.</param>
        /// <param name="second">Second comparison value.</param>
        /// <returns>Less than zero if first is smaller than second, more than
        /// zero if it is greater or zero if they are the same.</returns>
        /// <exception cref="System.ArgumentException">
        /// <paramref name="first"/> does not implement IComparable or <paramref name="second"/> cannot be converted
        /// to the type of <paramref name="first"/>.
        /// </exception>
        public static int Compare(object first, object second)
        {
            return LanguagePrimitives.Compare(first, second, false, CultureInfo.InvariantCulture);
        }

        /// <summary>
        /// Compare first and second, converting second to the
        /// type of the first, if necessary.
        /// </summary>
        /// <param name="first">First comparison value.</param>
        /// <param name="second">Second comparison value.</param>
        /// <param name="ignoreCase">Used if both values are strings.</param>
        /// <returns>Less than zero if first is smaller than second, more than
        /// zero if it is greater or zero if they are the same.</returns>
        /// <exception cref="System.ArgumentException">
        /// <paramref name="first"/> does not implement IComparable or <paramref name="second"/> cannot be converted
        /// to the type of <paramref name="first"/>.
        /// </exception>
        public static int Compare(object first, object second, bool ignoreCase)
        {
            return LanguagePrimitives.Compare(first, second, ignoreCase, CultureInfo.InvariantCulture);
        }

        /// <summary>
        /// Compare first and second, converting second to the
        /// type of the first, if necessary.
        /// </summary>
        /// <param name="first">First comparison value.</param>
        /// <param name="second">Second comparison value.</param>
        /// <param name="ignoreCase">Used if both values are strings.</param>
        /// <param name="formatProvider">Used in type conversions and if both values are strings.</param>
        /// <returns>Less than zero if first is smaller than second, more than
        /// zero if it is greater or zero if they are the same.</returns>
        /// <exception cref="System.ArgumentException">
        /// <paramref name="first"/> does not implement IComparable or <paramref name="second"/> cannot be converted
        /// to the type of <paramref name="first"/>.
        /// </exception>
        public static int Compare(object first, object second, bool ignoreCase, IFormatProvider formatProvider)
        {
            if (formatProvider == null)
            {
                formatProvider = CultureInfo.InvariantCulture;
            }

            var culture = formatProvider as CultureInfo;
            if (culture == null)
            {
                throw PSTraceSource.NewArgumentException("formatProvider");
            }

            first = PSObject.Base(first);
            second = PSObject.Base(second);

            if (first == null)
            {
                return second == null ? 0 : CompareObjectToNull(second, true);
            }

            if (second == null)
            {
                return CompareObjectToNull(first, false);
            }

            if (first is string firstString)
            {
                string secondString = second as string;
                if (secondString == null)
                {
                    try
                    {
                        secondString = (string)LanguagePrimitives.ConvertTo(second, typeof(string), culture);
                    }
                    catch (PSInvalidCastException e)
                    {
                        throw PSTraceSource.NewArgumentException("second", ExtendedTypeSystem.ComparisonFailure,
                                                                 first.ToString(), second.ToString(), e.Message);
                    }
                }

                return culture.CompareInfo.Compare(firstString, secondString,
                                                   ignoreCase ? CompareOptions.IgnoreCase : CompareOptions.None);
            }

            Type firstType = first.GetType();
            Type secondType = second.GetType();
            int firstIndex = LanguagePrimitives.TypeTableIndex(firstType);
            int secondIndex = LanguagePrimitives.TypeTableIndex(secondType);
            if ((firstIndex != -1) && (secondIndex != -1))
            {
                return LanguagePrimitives.NumericCompare(first, second, firstIndex, secondIndex);
            }

            object secondConverted;
            try
            {
                secondConverted = LanguagePrimitives.ConvertTo(second, firstType, culture);
            }
            catch (PSInvalidCastException e)
            {
                throw PSTraceSource.NewArgumentException("second", ExtendedTypeSystem.ComparisonFailure,
                                                         first.ToString(), second.ToString(), e.Message);
            }

            if (first is IComparable firstComparable)
            {
                return firstComparable.CompareTo(secondConverted);
            }

            if (first.Equals(second))
            {
                return 0;
            }

            // At this point, we know that they aren't equal but we have no way of
            // knowing which should compare greater than the other so we throw an exception.
            throw PSTraceSource.NewArgumentException("first", ExtendedTypeSystem.NotIcomparable, first.ToString());
        }

        /// <summary>
        /// Tries to compare first and second, converting second to the type of the first, if necessary.
        /// If a conversion is needed but fails, false is return.
        /// </summary>
        /// <param name="first">First comparison value.</param>
        /// <param name="second">Second comparison value.</param>
        /// <param name="result">Less than zero if first is smaller than second, more than
        /// zero if it is greater or zero if they are the same.</param>
        /// <returns>True if the comparison was successful, false otherwise.</returns>
        public static bool TryCompare(object first, object second, out int result)
        {
            return TryCompare(first, second, ignoreCase: false, CultureInfo.InvariantCulture, out result);
        }

        /// <summary>
        /// Tries to compare first and second, converting second to the type of the first, if necessary.
        /// If a conversion is needed but fails, false is return.
        /// </summary>
        /// <param name="first">First comparison value.</param>
        /// <param name="second">Second comparison value.</param>
        /// <param name="ignoreCase">Used if both values are strings.</param>
        /// <param name="result">Less than zero if first is smaller than second, more than zero if it is greater or zero if they are the same.</param>
        /// <returns>True if the comparison was successful, false otherwise.</returns>
        public static bool TryCompare(object first, object second, bool ignoreCase, out int result)
        {
            return TryCompare(first, second, ignoreCase, CultureInfo.InvariantCulture, out result);
        }

        /// <summary>
        /// Tries to compare first and second, converting second to the type of the first, if necessary.
        /// If a conversion is needed but fails, false is return.
        /// </summary>
        /// <param name="first">First comparison value.</param>
        /// <param name="second">Second comparison value.</param>
        /// <param name="ignoreCase">Used if both values are strings.</param>
        /// <param name="formatProvider">Used in type conversions and if both values are strings.</param>
        /// <param name="result">Less than zero if first is smaller than second, more than  zero if it is greater or zero if they are the same.</param>
        /// <returns>True if the comparison was successful, false otherwise.</returns>
        /// <exception cref="ArgumentException">The parameter <paramref name="formatProvider"/> is not a <see cref="CultureInfo"/>.</exception>
        public static bool TryCompare(object first, object second, bool ignoreCase, IFormatProvider formatProvider, out int result)
        {
            result = 0;
            if (formatProvider == null)
            {
                formatProvider = CultureInfo.InvariantCulture;
            }

            if (!(formatProvider is CultureInfo culture))
            {
                throw PSTraceSource.NewArgumentException("formatProvider");
            }

            first = PSObject.Base(first);
            second = PSObject.Base(second);

            if (first == null && second == null)
            {
                result = 0;
                return true;
            }

            if (first == null)
            {
                result = CompareObjectToNull(second, true);
                return true;
            }

            if (second == null)
            {
                // If it's a positive number, including 0, it's greater than null
                // for everything else it's less than zero...
                result = CompareObjectToNull(first, false);
                return true;
            }

            if (first is string firstString)
            {
                if (!(second is string secondString))
                {
                    if (!TryConvertTo(second, culture, out secondString))
                    {
                        return false;
                    }
                }

                result = culture.CompareInfo.Compare(firstString, secondString, ignoreCase ? CompareOptions.IgnoreCase : CompareOptions.None);
                return true;
            }

            Type firstType = first.GetType();
            Type secondType = second.GetType();
            int firstIndex = TypeTableIndex(firstType);
            int secondIndex = TypeTableIndex(secondType);
            if (firstIndex != -1 && secondIndex != -1)
            {
                result = NumericCompare(first, second, firstIndex, secondIndex);
                return true;
            }

            if (!TryConvertTo(second, firstType, culture, out object secondConverted))
            {
                return false;
            }

            if (first is IComparable firstComparable)
            {
                result = firstComparable.CompareTo(secondConverted);
                return true;
            }

            if (first.Equals(second))
            {
                result = 0;
                return true;
            }

            // At this point, we know that they aren't equal but we have no way of
            // knowing which should compare greater than the other so we return false.
            return false;
        }

        /// <summary>
        /// Returns true if the language considers obj to be true.
        /// </summary>
        /// <param name="obj">Obj to verify if it is true.</param>
        /// <returns>True if obj is true.</returns>
        [SuppressMessage("Microsoft.Naming", "CA1720:IdentifiersShouldNotContainTypeNames", MessageId = "obj", Justification = "Since V1 code is already shipped, excluding this message for backward compatibility reasons")]
        public static bool IsTrue(object obj)
        {
            // null is a valid argument - it converts to false...
            if (obj == null || obj == AutomationNull.Value)
                return false;

            obj = PSObject.Base(obj);

            Type objType = obj.GetType();

            if (objType == typeof(bool))
            {
                return (bool)obj;