winim/clr

This module adds Windows Common Language Runtime (CLR) support for Winim. It allows Nim to interact with the Windows .NET Framework.

This module depends heavily on the winim/com module. Please also read its documentation to understand how to use it. Note: int is converted to int32 before being passed to the CLR, even in a 64-bit environment.

Example:

import winim/clr
proc example1() =
  ## Creates a CLR object (also known as a C# instance) and calls the method.
  var mscor = load("mscorlib")
  var rand = mscor.new("System.Random")
  echo rand.Next()

proc example2() =
  ## Creates a type object and calls a static method.
  var mscor = load("mscorlib")
  var Int32 = mscor.GetType("System.Int32")
  echo @Int32.Parse("12345")

proc example3() =
  ## Compiles some code and runs 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()

Imports

ole, com

Types

CLRError = object of CatchableError
  hresult*: HRESULT
Raised when a CLR error occurs. 
CLRInterface = object
  obj*: CLRVariant
  intf*: CLRVariant
Represents a CLR object with a specified interface. Use {} to create an interface object. 
CLRType = distinct variant
A distinct variant representing a CLR type object. 
CLRVariant = distinct variant
A distinct variant representing a CLR object or value.

Consts

CSharpCodeProvider = "Microsoft.CSharp.CSharpCodeProvider"
VBCodeProvider = "Microsoft.VisualBasic.VBCodeProvider"

Procs

proc `$`(v: CLRType): string {....raises: [COMError, Exception, CLRError,
                                        VariantConversionError],
                               tags: [RootEffect], forbids: [].}
$ operator for CLRType. 
proc `$`(v: CLRVariant): string {....raises: [COMError, Exception, CLRError,
    VariantConversionError], tags: [RootEffect], forbids: [].}
$ operator for CLRVariant. 
proc `==`(x, y: CLRVariant): bool {.borrow, ...raises: [], tags: [], forbids: [].}
Checks for equality between two CLRVariant values. 
proc `@`(v: CLRType): CLRType {.inline, ...raises: [], tags: [], forbids: [].}
Leaves a CLRType unchanged so type conversion is idempotent. 
proc `@`(v: CLRVariant): CLRType {....raises: [Exception, CLRError],
                                   tags: [RootEffect], forbids: [].}
Converts a CLRVariant to CLRType so static members can be invoked. 
proc `[]`(v: CLRVariant; i: SomeOrdinal): CLRVariant
Index operator for CLRVariant via the IList interface. 
proc `[]`(v: CLRVariant; name: string): CLRVariant {.
    ...raises: [Exception, CLRError, VariantConversionError], tags: [RootEffect],
    forbids: [].}
Returns the specified field as a CLRVariant from a CLR struct type. 
proc `[]`[T: variant | SomeNumber | string | proc | array | seq](x: T): CLRVariant
Syntactic sugar for x.toObject(). 
proc `[]`[T](x: T; typ: CLRType): CLRVariant {.inline.}
Syntactic sugar for x.toObject(CLRType). 
proc `[]`[T](x: T; typ: CLRVariant): CLRVariant {.inline.}
Syntactic sugar for x.toObject(CLRVariant). 
proc clrClose() {....raises: [], tags: [], forbids: [].}
Releases the CLR COM proxies cached by the current thread. The automatic COM apartment remains available until the thread exits. 
proc clrStart(version = ""): CLRVariant {.discardable, ...raises: [Exception,
    CLRError, ValueError, COMError, VariantConversionError], tags: [RootEffect],
    forbids: [].}
Starts the specified CLR and returns its AppDomain. If omitted, version is selected as the numerically highest installed CLR. The current thread is initialized automatically by the COM bridge. 
proc com(v: CLRVariant): com {....raises: [Exception, CLRError, COMError],
                               tags: [RootEffect], forbids: [].}
Converts a CLRVariant to Winim's com object, a COM callable wrapper (CCW). 
proc compile(code: string; references: openArray[string] = ["System.dll"];
             filename = ""; compilerOptions = ""; provider = CSharpCodeProvider;
             debug = false): CLRVariant {.discardable, ...raises: [Exception,
    CLRError, ValueError, COMError, VariantConversionError],
    tags: [RootEffect, ReadDirEffect], forbids: [].}
Compiles the specified code and returns the CompilerResults object. 
proc fromCLRVariant[T](x: CLRVariant): T {.inline.}
Converts a CLRVariant to any supported type. 
proc getType(assembly: CLRVariant; name: string): CLRType {.
    ...raises: [Exception, CLRError, VariantConversionError, COMError],
    tags: [RootEffect], forbids: [].}

Gets a type from this assembly as a typed CLRType proxy.

The capitalized GetType spelling remains the dynamic CLR member call and continues to return CLRVariant for backwards compatibility.

proc invoke(v: CLRInterface; name: string; flags: int;
            vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {.discardable,
    ...raises: [Exception, CLRError, VariantConversionError, COMError],
    tags: [RootEffect], forbids: [].}
Low-level invoke for CLRInterface. 
proc invoke(v: CLRType; name: string; flags: int;
            vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {.discardable,
    ...raises: [Exception, CLRError, VariantConversionError, COMError],
    tags: [RootEffect], forbids: [].}
Low-level invoke for CLRType, equivalent to CLRType.InvokeMember(...). 
proc invoke(v: CLRVariant; name: string; flags: int;
            vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {.discardable,
    ...raises: [Exception, CLRError, VariantConversionError, COMError],
    tags: [RootEffect], forbids: [].}
Low-level invoke for CLRVariant, equivalent to CLRVariant.GetType().InvokeMember(...). 
proc isNil(x: CLRType): bool {.borrow, ...raises: [], tags: [], forbids: [].}
Checks whether CLRType is nil. 
proc isNil(x: CLRVariant): bool {.borrow, ...raises: [], tags: [], forbids: [].}
Checks whether a CLRVariant is nil. 
proc isNull(x: CLRVariant): bool {.borrow, ...raises: [], tags: [], forbids: [].}
Checks whether a CLRVariant is C# null or VB Nothing. 
proc isObject(v: CLRVariant): bool {....raises: [Exception], tags: [RootEffect],
                                     forbids: [].}
Checks whether a CLRVariant is a CLR object. 
proc isStruct(v: CLRVariant): bool {.inline, ...raises: [], tags: [], forbids: [].}
Checks whether a CLRVariant is a CLR struct type returned as a VT_RECORD variant. 
proc isType(v: CLRVariant): bool {....raises: [Exception], tags: [RootEffect],
                                   forbids: [].}
Checks whether a CLRVariant is a CLR type object. 
proc load(data: COMBinary): CLRVariant {.discardable, ...raises: [Exception,
    CLRError, ValueError, COMError, VariantConversionError], tags: [RootEffect],
    forbids: [].}
Loads an assembly from a Common Object File Format (COFF)-based image. 
proc load(data: openArray[byte]): CLRVariant {.discardable, ...raises: [Exception,
    CLRError, ValueError, COMError, VariantConversionError], tags: [RootEffect],
    forbids: [].}
Loads an assembly from a Common Object File Format (COFF)-based image. 
proc load(name: string): CLRVariant {.discardable, ...raises: [Exception, CLRError,
    ValueError, COMError, VariantConversionError, Exception, COMError,
    VariantConversionError, CLRError], tags: [RootEffect, ReadDirEffect],
                                      forbids: [].}
Loads an assembly from a file or the global assembly cache using a partial name. 
proc new(assembly: CLRVariant; name: string;
         vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {.discardable,
    ...raises: [Exception, CLRError, VariantConversionError, COMError],
    tags: [RootEffect], forbids: [].}
Creates an instance of a type in this assembly by name (case-sensitive). 
proc new(typ: CLRType; vargs: varargs[CLRVariant, toCLRVariant]): CLRVariant {.
    discardable, ...raises: [Exception, CLRError, VariantConversionError, COMError,
                          ValueError], tags: [RootEffect, ReadDirEffect],
    forbids: [].}
Creates an instance of this type. 
proc reclaim() {....raises: [Exception, CLRError, VariantConversionError, COMError,
                          ValueError], tags: [RootEffect, ReadDirEffect],
                 forbids: [].}
Forces an immediate garbage collection. 
proc repr(v: CLRType): string {....raises: [COMError, Exception, CLRError,
    VariantConversionError], tags: [RootEffect], forbids: [].}
repr operator for CLRType. 
proc repr(v: CLRVariant): string {....raises: [COMError, Exception, CLRError,
    VariantConversionError], tags: [RootEffect], forbids: [].}
repr operator for CLRVariant. 
proc toCLRVariant(x: typeof(nil)): CLRVariant {.inline, ...raises: [], tags: [],
    forbids: [].}
Converts nil to a CLRVariant. 
proc toCLRVariant[T](x: openArray[T]; vt: VARENUM = VT_VARIANT): CLRVariant {.
    inline.}
Converts any supported openArray type to a CLRVariant. 
proc toCLRVariant[T](x: T): CLRVariant {.inline.}
Converts any supported type to a CLRVariant. 
proc toObject(x: pointer | proc): CLRVariant
Converts a pointer or proc to a System.IntPtr object. 
proc toObject[T](x: T): CLRVariant
proc toObject[T](x: T; typ: CLRType): CLRVariant {.inline.}
Converts a value to an object of the specified CLRType. 
proc toObject[T](x: T; typ: CLRVariant): CLRVariant
Tries to convert any value or struct to an object of the specified CLR type. Conversion failures retain the original CLR diagnostics. 
proc toObject[T](x: T; typ: string): CLRVariant
Tries to convert any value or struct to an object of the named CLR type. Type lookup and conversion failures retain the original CLR diagnostics. 
proc toVariant(x: CLRVariant): variant {.inline, ...raises: [], tags: [],
    forbids: [].}
Converts a CLRVariant to a variant. 
proc unwrap(x: CLRVariant): VARIANT {.borrow, ...raises: [], tags: [], forbids: [].}
Unwraps a CLRVariant to a VARIANT object. 
proc `{}`(v, i: CLRVariant): CLRInterface {.inline, ...raises: [], tags: [],
    forbids: [].}
Syntactic sugar for creating a CLRInterface (requires a Nim compiler version >= 1.2.0).

Iterators

iterator clrVersions(): string {....raises: [Exception, CLRError],
                                 tags: [RootEffect], forbids: [].}
Iterates over all installed .NET Framework CLR versions. Enumeration order is unspecified; clrStart() compares numeric fields when selecting the highest version. 
iterator fieldPairs(v: CLRVariant): tuple[name: string, value: CLRVariant] {.
    ...raises: [Exception, CLRError, VariantConversionError], tags: [RootEffect],
    forbids: [].}
Iterates over all fields of a CLR struct type, returning each name and value. 
iterator fields(v: CLRVariant): string {....raises: [Exception, CLRError],
    tags: [RootEffect], forbids: [].}
Iterates over all fields of a CLR struct type. 
iterator items(v: CLRVariant): CLRVariant {....raises: [Exception, CLRError,
    VariantConversionError, COMError, ValueError],
    tags: [RootEffect, ReadDirEffect], forbids: [].}
Iterates over all members of a CLRVariant. Supports System.Array, enumerable, and collection types. 
iterator pairs(v: CLRVariant): (int, CLRVariant) {....raises: [Exception, CLRError,
    VariantConversionError, COMError, ValueError, Exception,
    VariantConversionError, ValueError, COMError, CLRError],
    tags: [RootEffect, ReadDirEffect], forbids: [].}
Iterates over all members of a CLRVariant, yielding (int, CLRVariant) pairs. Supports System.Array, enumerable, and collection types.

Converters

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

Macros

macro `.`(v: CLRInterface; name: untyped; vargs: varargs[untyped]): untyped
Dot operator for CLRInterface. 
macro `.`(v: CLRType; name: untyped; vargs: varargs[untyped]): untyped
Dot operator for CLRType: invokes static methods and gets static properties or fields. 
macro `.`(v: CLRVariant; name: untyped; vargs: varargs[untyped]): untyped
Dot operator for CLRVariant: invokes methods and gets properties or fields. 
macro `.=`(v: CLRInterface; name: untyped; vargs: varargs[untyped]): untyped
Dot-assignment operator for CLRInterface. 
macro `.=`(v: CLRType; name: untyped; vargs: varargs[untyped]): untyped
Dot-assignment operator for CLRType: sets a static property or field. 
macro `.=`(v: CLRVariant; name: untyped; vargs: varargs[untyped]): untyped
Dot-assignment operator for CLRVariant: sets a property or field. 
macro clrScript(x: untyped): untyped
Extends .= to allow assignments such as a.b(c, d) = e.

Made with Nim.