clr

    Dark Mode

This module add Windows Common Language Runtime (CLR) support to Winim. So that we can use Nim to interact with Windows .NET frameworks.

This module heavily dependent on winim/com module. So please also read the document about it to help understanding the usage. Notice: int will be converted into int32 before passing to CLR even in 64-bit environment.

Examples:

proc example1() =
  ## Create a CLR object (aka. C# instance) and call the method
  var mscor = load("mscorlib")
  var rand = mscor.new("System.Random")
  echo rand.Next()

proc example2() =
  ## Create an type object and call the static method
  var mscor = load("mscorlib")
  var Int32 = mscor.GetType("System.Int32")
  echo @Int32.Parse("12345")

proc example3() =
  ## Compile some code and run it
  var code = """
    using System;
    public class Test {
      public void Hello() {
        Console.WriteLine("Hello, world");
      }
    }
    """
  var res = compile(code)
  var o = res.CompiledAssembly.new("Test")
  o.Hello()

Types

CLRError = object of CatchableError
  hresult*: HRESULT
Raised if an CLR error occurred.
CLRVariant = distinct variant
distinct variant to represent CLR object or value.
CLRType = distinct variant
distinct variant to represent CLR Type object.
CLRInterface = object
  obj*: CLRVariant
  intf*: CLRVariant
Represent CLR object with specified interface. Use {} to create interface object.

Procs

proc isNil(x: CLRVariant): bool {...}{.borrow.}
Check if CLRVariant is nil or not.
proc isNil(x: CLRType): bool {...}{.borrow.}
Check if CLRType is nil or not.
proc isNull(x: CLRVariant): bool {...}{.borrow.}
Check if CLRVariant is C# null or VB nothing.
proc unwrap(x: CLRVariant): VARIANT {...}{.borrow.}
Unwrap CLRVariant to VARIANT object.
proc `==`(x, y: CLRVariant): bool {...}{.borrow.}
Checks for equality between two CLRVariant variables.
proc toVariant(x: CLRVariant): variant {...}{.inline, raises: [], tags: [].}
Converts a CLRVariant x into a variant.
proc toCLRVariant[T](x: T): CLRVariant {...}{.inline.}
Converts any supported types into a CLRVariant.
proc toCLRVariant[T](x: openArray[T]; vt: VARENUM = VT_VARIANT): CLRVariant {...}{.inline.}
Converts any supported openArray types into a CLRVariant.
proc toCLRVariant(x: typeof(nil)): CLRVariant {...}{.inline, raises: [], tags: [].}
Converts nil into a CLRVariant.
proc fromCLRVariant[T](x: CLRVariant): T {...}{.inline.}
Converts a CLRVariant into any supported types.
proc isObject(v: CLRVariant): bool {...}{.raises: [Exception], tags: [RootEffect].}
Check if CLRVariant is CLR object or not.
proc isType(v: CLRVariant): bool {...}{.raises: [Exception], tags: [RootEffect].}
Check if CLRVariant is CLR Type object or not.
proc isStruct(v: CLRVariant): bool {...}{.inline, raises: [], tags: [].}
Check if CLRVariant is CLR struct type (returnd from CLR as VT_RECORD variant).
proc `@`(v: CLRVariant): CLRType {...}{.raises: [Exception, ValueError, CLRError],
                               tags: [RootEffect].}
Convert CLRVariant into CLRType so that static members can be invoked.
proc com(v: CLRVariant): com {...}{.raises: [Exception, ValueError, CLRError],
                           tags: [RootEffect].}
Convert CLRVariant to winim's com object, aka. COM callable wrapper (CCW).
proc invoke(v: CLRVariant; name: string; flags: int;
           vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {...}{.discardable,
    raises: [ValueError, CLRError, Exception, VariantConversionError],
    tags: [RootEffect].}
Low level invoke for CLRVariant. Equal to CLRVariant.GetType().InvokeMember(...)
proc invoke(v: CLRType; name: string; flags: int;
           vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {...}{.discardable,
    raises: [ValueError, CLRError, Exception, VariantConversionError],
    tags: [RootEffect].}
Low level invoke for CLRType. Equal to CLRType.InvokeMember(...)
proc invoke(v: CLRInterface; name: string; flags: int;
           vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {...}{.discardable,
    raises: [ValueError, CLRError, Exception, VariantConversionError],
    tags: [RootEffect].}
Low level invoke for CLRInterface.
proc `[]`(v: CLRVariant; name: string): CLRVariant {...}{.
    raises: [ValueError, CLRError, Exception, VariantConversionError],
    tags: [RootEffect].}
Returns specified field as CLRVariant from CLR struct type.
proc `$`(v: CLRVariant): string {...}{.raises: [Exception, ValueError, CLRError,
                                      VariantConversionError], tags: [RootEffect].}
$ operator for CLRVariant.
proc repr(v: CLRVariant): string {...}{.raises: [Exception, ValueError, CLRError,
                                       VariantConversionError],
                               tags: [RootEffect].}
repr operator for CLRVariant.
proc clrStart(version = ""): CLRVariant {...}{.discardable, raises: [Exception, ValueError,
    CLRError, IndexDefect, VariantConversionError], tags: [RootEffect].}
Start the specified CLR and return its AppDomain. This call can be omitted if last version of runtime is required.
proc load(name: string): CLRVariant {...}{.discardable, raises: [Exception, ValueError,
    CLRError, IndexDefect, VariantConversionError, ValueError,
    VariantConversionError, Exception, CLRError], tags: [RootEffect].}
Loads an assembly from file or from the global assembly cache using a partial name.
proc load(data: COMBinary): CLRVariant {...}{.discardable, raises: [Exception, ValueError,
    CLRError, IndexDefect, VariantConversionError], tags: [RootEffect].}
Loads the assembly with a common object file format (COFF)-based image.
proc load(data: openArray[byte]): CLRVariant {...}{.discardable, raises: [Exception,
    ValueError, CLRError, IndexDefect, VariantConversionError], tags: [RootEffect].}
Loads the assembly with a common object file format (COFF)-based image.
proc new(assembly: CLRVariant; name: string; vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {...}{.
    discardable,
    raises: [ValueError, CLRError, Exception, VariantConversionError],
    tags: [RootEffect].}
Create an instance from this assembly by name (case-sensitive).
proc new(typ: CLRType; vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {...}{.
    discardable, raises: [ValueError, CLRError, Exception, VariantConversionError,
                        IndexDefect], tags: [RootEffect].}
Create an instance of this type
proc compile(code: string; references: openArray[string] = ["System.dll"];
            filename = ""; compilerOptions = "";
            provider = "Microsoft.CSharp.CSharpCodeProvider"; debug = false): CLRVariant {...}{.
    discardable, raises: [Exception, ValueError, CLRError, IndexDefect,
                        VariantConversionError], tags: [RootEffect].}
Compiles the specified code. Returns the CompilerResults object.
proc reclaim() {...}{.raises: [ValueError, CLRError, Exception, VariantConversionError,
                       IndexDefect], tags: [RootEffect].}
Forces an immediate garbage collection.
proc toObject(x: pointer | proc): CLRVariant
Converts pointer or proc into a System.IntPtr object.
proc toObject[T](x: T): CLRVariant
Try to convert any value types or struct types into a CLR object.
proc toObject[T](x: T; typ: string): CLRVariant
Try to convert any value types or struct types into CLR object of specified type.
proc toObject[T](x: T; typ: CLRVariant): CLRVariant
Try to convert any value types or struct types into CLR object of specified type.
proc `[]`[T](x: T): CLRVariant
Syntax sugar for x.toObject().
proc `[]`[T](x: T; typ: string): CLRVariant {...}{.inline.}
Syntax sugar for x.toObject(string).
proc `[]`[T](x: T; typ: CLRVariant): CLRVariant {...}{.inline.}
Syntax sugar for x.toObject(CLRVariant).
proc `{}`(v, i: CLRVariant): CLRInterface {...}{.inline, raises: [], tags: [].}
Syntax suger to create CLRInterface (require nim compiler version >= 1.2.0).

Iterators

iterator items(v: CLRVariant): CLRVariant {...}{.raises: [ValueError,
    VariantConversionError, Exception, CLRError], tags: [RootEffect].}
Iterates over every member of CLRVariant via IEnumerable interface.
iterator pairs(v: CLRVariant): (int, CLRVariant) {...}{.
    raises: [ValueError, VariantConversionError, Exception, CLRError],
    tags: [RootEffect].}
Iterates over every member of CLRVariant. Yields (int, CLRVariant) pairs.
iterator fields(v: CLRVariant): string {...}{.raises: [ValueError, CLRError, Exception],
                                     tags: [RootEffect].}
Iterates over every field of CLR struct type.
iterator fieldPairs(v: CLRVariant): tuple[name: string, value: CLRVariant] {...}{.
    raises: [ValueError, CLRError, Exception, VariantConversionError],
    tags: [RootEffect].}
Iterates over every field of CLR struct type returning their name and value.
iterator clrVersions(): string {...}{.raises: [Exception, ValueError, CLRError, IndexDefect],
                              tags: [RootEffect].}
Iterates over every CLR version installed on a computer..

Converters

converter clrVariantToVariant(x: CLRVariant): variant {...}{.raises: [], tags: [].}
Converts CLRVariant into variant automatically.
converter clrVariantToString(x: CLRVariant): string {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into string automatically.
converter clrVariantToCString(x: CLRVariant): cstring {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into cstring automatically.
converter clrVariantToMString(x: CLRVariant): mstring {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into mstring automatically.
converter clrVariantToWString(x: CLRVariant): wstring {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into wstring automatically.
converter clrVariantToChar(x: CLRVariant): char {...}{.raises: [VariantConversionError],
    tags: [].}
Converts CLRVariant into char automatically.
converter clrVariantToBool(x: CLRVariant): bool {...}{.raises: [VariantConversionError],
    tags: [].}
Converts CLRVariant into bool automatically.
converter clrVariantToPtrIDispatch(x: CLRVariant): ptr IDispatch {...}{.
    raises: [VariantConversionError, Exception], tags: [RootEffect].}
Converts CLRVariant into ptr IDispatch automatically.
converter clrVariantToPtrIUnknown(x: CLRVariant): ptr IUnknown {...}{.
    raises: [VariantConversionError, Exception], tags: [RootEffect].}
Converts CLRVariant into ptr IUnknown automatically.
converter clrVariantToPointer(x: CLRVariant): pointer {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into ptr IUnknown automatically.
converter clrVariantToInt(x: CLRVariant): int {...}{.raises: [VariantConversionError],
    tags: [].}
Converts CLRVariant into int automatically.
converter clrVariantToUint(x: CLRVariant): uint {...}{.raises: [VariantConversionError],
    tags: [].}
Converts CLRVariant into uint automatically.
converter clrVariantToInt8(x: CLRVariant): int8 {...}{.raises: [VariantConversionError],
    tags: [].}
Converts CLRVariant into int8 automatically.
converter clrVariantToUint8(x: CLRVariant): uint8 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into uint8 automatically.
converter clrVariantToInt16(x: CLRVariant): int16 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into int16 automatically.
converter clrVariantToUInt16(x: CLRVariant): uint16 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into uint16 automatically.
converter clrVariantToInt32(x: CLRVariant): int32 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into int32 automatically.
converter clrVariantToUInt32(x: CLRVariant): uint32 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into uint32 automatically.
converter clrVariantToInt64(x: CLRVariant): int64 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into int64 automatically.
converter clrVariantToUInt64(x: CLRVariant): uint64 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into uint64 automatically.
converter clrVariantToFloat32(x: CLRVariant): float32 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into float32 automatically.
converter clrVariantToFloat64(x: CLRVariant): float64 {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into float64 automatically.
converter clrVariantToVARIANTRaw(x: CLRVariant): VARIANT {...}{.raises: [], tags: [].}
Converts CLRVariant into VARIANT automatically.
converter clrVariantToCOMArray1D(x: CLRVariant): COMArray1D {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into COMArray1D automatically.
converter clrVariantToCOMArray2D(x: CLRVariant): COMArray2D {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into COMArray2D automatically.
converter clrVariantToCOMArray3D(x: CLRVariant): COMArray3D {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into COMArray3D automatically.
converter clrVariantToCOMBinary(x: CLRVariant): COMBinary {...}{.
    raises: [VariantConversionError], tags: [].}
Converts CLRVariant into COMBinary automatically.

Macros

macro `.`(v: CLRVariant; name: untyped; vargs: varargs[untyped]): untyped
Dot operator for CLRVariant. Invoke a method, get a property, or get a field.
macro `.=`(v: CLRVariant; name: untyped; vargs: varargs[untyped]): untyped
Dot assignment operator for CLRVariant. Set a property or field.
macro `.`(v: CLRType; name: untyped; vargs: varargs[untyped]): untyped
Dot operator for CLRType. Invoke a static method, get a static property, or get a static field.
macro `.=`(v: CLRType; name: untyped; vargs: varargs[untyped]): untyped
Dot assignment operator for CLRType. Set a static property or field.
macro `.`(v: CLRInterface; name: untyped; vargs: varargs[untyped]): untyped
Dot operator for CLRInterface.
macro `.=`(v: CLRInterface; name: untyped; vargs: varargs[untyped]): untyped
Dot assignment operator for CLRInterface.
macro clrScript(x: untyped): untyped
Nim's dot operators .= only allow "a.b = c". With this macro, "a.b(c, d) = e" is allowed. Some assignment needs this macro to work.