Packages
CLR.CLS

CLR.CLS Overview

- Routines clr.addAssembly clr.box clr.createArray clr.createEventHandler clr.import clr.unbox clr.wrap
- Classes
  - CLR
    - Attributes: clr.object clr.type
    - Methods: init clr.dispatch clr.import string unknown
  - CLR_Proxy
    - Methods: init
  - CLRLogger
    - Attributes: doLogging logLevel logLevel logLevels
    - Methods: init unknown
  - CLRThread
    - Methods: run start
- Requires BSF.CLS

# CLR.CLS

ooRexx package which requires the BSF.CLS (ooRexx Java bridge) ooRexx package and the Java package "jni4net" in order to make all .Net classes on Windows (the Common Language Runtime, CLR) available to ooRexx programmers. ooRexx programmers will use the public ooRexx class "CLR" to instantiate any (fully qualified) CLR type and send the ooRexx proxy merely ooRexx messages (comparable to exploiting the public "BSF" class to interact with Java).
author: Manfred Raffel, original design and implementation, fall 2015
author: Rony G. Flatscher, updates, summer 2016
since: fall 2015
version: 100.20160812

#### Routine: clr.addAssembly

Routine that queries all exported types defined in the supplied assembly and caches their full names and assembly names in `.clr.dir~assemblyName`.
param: assemblyName the assembly name to work on
PARSE ARG assemblyName

#### Routine: clr.box

Boxes (wraps) a Rexx string representing a primitive type into a CLR object using a CLR wrapper class. Rexx strings are turned into CLR string objects (type: `System.String`).
param: typeIndicator one of the following strings:

- "System.String", "STring"
- "System.Boolean", "BOolean"
- "System.Byte", "BYte"
- "System.SByte", "SByte"
- "System.Char", "CHAR"
- "System.Decimal", "DEcimal"
- "System.Double", "DOuble"
- "System.Int16", "INT16"
- "System.UInt16", "UINT16"
- "System.Int32", "INT32"
- "System.UInt32", "UINT32"
- "System.Int64", "INT64"
- "System.UInt64", "UINT64"
- "System.Single", "SIngle"

param: strValue the Rexx string containing the primitive value or plain string to box/wrap/convert
return: the boxed CLR value, the CLR string value or `.nil` if `.nil` was supplied
USE ARG typeIndicator, strValue

#### Routine: clr.createArray

Utility routine that allows creating a single dimensioned CLR array with the supplied type and capacity.
param: typeName the fully qualified CLR type name
param: capacity the capacity (a non-negative whole number)
return: a System.Array instance (a CLR array object) of the specified type and capacity
USE ARG typeName, capacity

#### Routine: clr.createEventHandler

Creates an instance of "system.EventHandler" with the Rexx event handler object to handle any events.
param: rexxEventHandler a Rexx object that handles the events
param: rexxData an optional Rexx object that will be supplied with each event (last event argument, appended by BSF4ooRexx, which is a Rexx directory object; the "rexxData" object can be retrieved from it using as index the value "USERDATA"; cf. BSF4ooRexx)
return: an instance of "System.EventHandler", where the rexxEventHandler object will process the events
USE ARG rexxEventHandler, rexxData = .nil

#### Routine: clr.import

Routine to import a CLR/.Net class, the imported class understands the NEW-message.
param: typeName the fully qualified CLR/.net type name
param: rexxName4local the name to store in .local, defaults to `.nil`, which inhibits the default entry of the CLR::CLR_IMPORT
return: a Rexx class object, subclassing CLR_Class, proxying the CLR/.Net type object
USE ARG typeName, rexxName4local=.nil

#### Routine: clr.unbox

Routine to turn values of boxed/wrapped `CLR` primitive types or System.String values to Rexx strings, otherwise returns argument unchanged.
param: clrObject the CLR object to unbox or to turn into a Rexx string
return: a Rexx string or the argument unchanged, if `clrObject` does not represent a boxed CLR value or a CLR string
USE ARG clrObject

#### Routine: clr.wrap

Processes received parameter "value" depending on its type. Always returns a CLR. If a CLR object which is a system.Enum, but not an instance of the `CLR_Enum` class, then an instance of `CLR_Enum` will be created and returned using the CLR object's `clr.object` and `clr.type` attributes.

If a Rexx string is supplied which can be represented as a number, then a CLR object representing a wrapped system.Int32, system.Int64 or system.Decimal gets returned, depending on the value range. Otherwise a system.String object gets returned

If a BSF (Java proxy) object is supplied it will be wrapped either as a `CLR_Enum` or as a `CLR_Proxy` object.
param: value a CLR, a BSF or a Rexx string object
return: a CLR object wrapping up the supplied `value`

USE ARG value

#### Class: CLR

The class that represents CLR objects and which is responsible for interacting with the peer CLR object on behalf of the ooRexx programmer. An instance of this class holds a reference to the peer CLR object and a reference to that object's type to ease reflective interactions.

#### Attributes

- clr.object GETTER
  Getter attribute method to get the peer `clr.object`.
  return: the CLR object (a BSF object) that is a peer of the CLR object it represents

- clr.type GETTER
  Getter attribute method to get the `clr.type` of the `clr.object`.
  return: the CLR type object (a BSF object) that is the type of the `clr.object`

#### Methods

- init
  Constructor method.
  param: typeName the fully qualified name of a CLR type to instantiate
  param: param optionally one or more paramaters to pass on to the CLR constructor
  USE ARG typeName, param = .nil, ...

- clr.dispatch
  Directly forwards a message to the "unknown" method of this CLR. This is needed if a method on .NET side is to be called which is named like a method on the ooRexx side. Examples are the ooRexx methods "class", "start" or "init" (inherited from the ooRexx root class `.Object`).
  param: messageName the name of the .NET message
  PARSE ARG messageName

- clr.import CLASS
  Class method to import a CLR type into ooRexx and allow that type to be treated as an ooRexx class that possesses the `new` class method to create instances of the CLR type it represents.
  param: typeName the fully qualified type name which should be imported into ooRexx as an ooRexx class proxy
  param: rexxName4Local optional string which gets used to store the imported class proxy in the `.local` directory. Prepending a dot to that name (using it as an environment symbol) will cause ooRexx to automatically search for this entry in `.nil`. If this argument is given and set to `.nil`, then no entry will be created in the ooRexx `.local` directory.
  return: the ooRexx class object representing the CLR type, i.e. an instance of class `"CLR_Class"`
  USE ARG typeName, rexxName4Local=(typeName)

- string
  The method that renders the CLR proxy object in a format that indicates its type by including the CLR type name.
  return: a string representing the CLR proxy object

- unknown
  The unknown method tries to find methods, properties, fields or events (in that order) that match the unknown message name. It will carry out the appropriate operation. The implementation allows also to assign new values to CLR properties, if the ooRexx programmer employs them like an ooRexx attribute. In addition it allows for adding an event handler to an event object by the name of the message.
  param: msgName the name of the message that was not understood (no method by that name was found)
  param: msgArgs an array containing the arguments supplied with the message, if any
  return: returns the appropriate object or .nil, if appropriate
  USE ARG msgName, msgArgs

#### Constants

No Constants

#### Class: CLR_Proxy

Sub-Class: CLR
This class serves as a proxy for CLR/.Net objects of any type, returned from CLR/.Net. The routine `clr.wrap()` will use this class, if a pure BSF (Java) object is supplied, assuming it is from CLR/.Net.
author: Rony G. Flatscher
since: 2016-06-18

#### Attributes

No Attributes

#### Methods

- init
  Constructor.
  param: argObj mandatory object, can be a CLR or BSF object
  param: argType optional object, if supplied, must be a BSF object
  USE ARG argObj, argType=.nil

#### Constants

No Constants

#### Class: CLRLogger

Utility class to allow logging merely by sending the messages "FATAL", "ERROR", "WARN", "INFO", "DEBUG" or "TRACE" with the log text as argument to the class object `.CLRLogger`. All interaction is with the class object directly, there is no instance one is allowed to create.

#### Attributes

- doLogging GETTER CLASS
  Getter attribute method that indicates whether log messages get processed.
  return: `.true` if logging is active, `.false` if not

- logLevel GETTER CLASS
  Getter attribute method that returns the current `logLevel` setting.
  return: one of the strings: "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"

- logLevel SETTER CLASS
  Setter attribute method that returns a copy of the log levels directory. If set to "OFF", then the attribute `doLogging` is set to `.false`, otherwise to `.true`.
  param: desiredLevel, one of "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG" and "TRACE".
  PARSE ARG desiredLevel

- logLevels GETTER CLASS
  Getter attribute method that returns a copy of the log levels directory.
  return: copy of `logLevels` directory object

#### Methods

- init CLASS
  Constructor, defining the log levels "OFF", "FATAL", "ERROR", * "WARN", "INFO", "DEBUG" and "TRACE", setting the attribute `logLevel` to "OFF". Determines whether the ooRexx version in use has the `.traceOutput` stream, if not the `.error` stream is used for log output instead.

- unknown CLASS
  Unknown method that handles the messages "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE", depending on the value of the attribute `logLevel`. The handling is determined by the following relation: `"OFF" < "FATAL" < "ERROR" < "WARN" < "INFO" < "DEBUG" < "TRACE"`. Hence, if the attribute `logLevel` is set to `"OFF"`no log messages get displayed. By contrast, if `logLevel` is set to `"TRACE"`all log messages get displayed.
  param: levelName the unknown message name
  param: args an array object containing the arguments supplied with the unknown message
  ``````
  USE ARG levelName, args

#### Constants

No Constants

#### Class: CLRThread

A class that uses "java.lang.Thread" to create a thread for executing Rexx code in the context of CLR/.Net concurrently. To take advantage of this ooRexx class it is necessary to subclass it, and to implement the abstract method "run".

#### Attributes

No Attributes

#### Methods

- run ABSTRACT
  Abstract method that needs to be implemented in the subclassed Rexx class.

- start
  This method creates a new thread.
  param: rexxData optional, if supplied this Rexx object gets supplied, if a Java method invocation causes any Rexx method of the subclassed Rexx class to be executed. In that case BSF4ooRexx will append a "slotDir" Rexx directory argument to the Java arguments, that will have an entry "USERDATA" returning this Rexx object "rexxData"
  USE ARG rexxData = .nil

#### Constants

No Constants

## Requires

BSF.CLS