Volume Number: 20 (2004)
Issue Number: 2
Column Tag: Programming

Casting Your .NET

by Andrew Troelsen

The SSCLI: Managed Languages, Samples and (more) Programming Utilities

Before we dig into the meat of this month's installment, allow me to address an issue regarding the process of building the SSCLI. Like myself, you may have purchased and installed Mac OS 10.3 (Panther) on your development machines. As you are aware, Panther upgrades numerous core Unix tools, including gcc (the GNU Compiler Collection). Given these changes, the Shared Source CLI will fail to build on new Panther machines, while upgrading an existing installation of Mac OS 10.2 to 10.3 may cause certain SSCLI command tools to become 'funky' (e.g., fail to execute).

Lucky for us, various independent patches do exist (as of today, no official patch from Microsoft exists, but check the SSCLI web site every now and again). The patch that I used to rebuild the SSCLI after installing Panther was developed by Dr Nigel Perry at the University of Canterbury. Now, given that your machine may have specific customizations, I cannot guarantee that the path I took to patch the SSCLI will be identical to your own. However here are the steps that worked for me:

• Download the patch (rotor_mark2_diffs.txt.gz) from http://www.mondrian-script.org/rotor/

• Run the gunzip utility to extract the patch file (panther_mark2_diffs.txt) and copy it to /sscli directory

• Apply the patch by changing to your /sscli directory and run the following Terminal command (Listing 1)

patch -p1 <panther_mark2_diffs.txt

At this point, you can rebuild the SSCLI as described in the November issue. It is worth noting that I needed to issue the './buildall' command more than once to fully rebuild the entire code base (while selectively ignoring non-critical build-errors). In any case, hopefully these instructions will do the trick. With this out of the way, let's dig deeper into the SSCLI.

As mentioned in a previous article, the SSCLI ships with various sample applications that illustrate numerous aspects of the CLI (Common Language Infrastructure) and Base Class Libraries (BCL), the full list of which can be viewed by opening /sscli/samples/samples_index.html. In this installment, I'll introduce you to some (but by no means all) intriguing sample applications, specifically:

• The JScript.NET, cLisp and myC compilers

• Codetohtml, corcls and typefinder

• Pigpad

Understand that the goal of this issue is not to dive into all the gory details of the underlying technologies surrounding these samples. Rather, here we will learn about a number of samples that either (a) explore the language and platform agnostic aspects of .NET or (b) showcase useful developer tools. Rest assured that the technologies used in these sample applications (such as reflection and dynamic code generation) will be explored at a later time.

Before we begin, recall that the /sscli/samples directory contains a majority of the SSCLI sample code. You may directly view, modify and compile these files at the command line using csc (detailed in the December issue). Also recall the SSCLI sample applications are compiled when you build the SSCLI and are placed under the /sscli/build/v1.ppcfstchk.rotor/samples directory. These applications are ready to run at the Terminal (or xterm) using the clix application launcher. Pick your poison, enable an SSCLI Terminal session, and read on.

In the .NET universe, the term managed language refers to a programming language which is .NET aware; meaning, the corresponding compiler (a.k.a. a managed compiler) has been updated to understand the .NET platform. Out of the box, the SSCLI ships with a total of five managed compilers (two of which are research-oriented in nature):

• The C# compiler (csc)

• The raw CIL compiler (ilasm)

• The JScript.NET compiler (jsc)

• An experimental LISP-based .NET compiler (cLisp)

• An experimental C-based .NET compiler (myC)

Given that the previous issue examined the basic details of working with csc and ilasm, let's take some time to examine the three remaining managed compilers of the SSCLI.

The JScript.NET compiler allows you to build .NET solutions using the syntax of the JScript (a.k.a. ECMA-script) language. Unlike traditional JScript however, the JScript.NET compiler (jsc) transforms the input *.js files into a true-blue .NET assembly rather than a simple blurb of code to be processed by a scripting engine. In addition to this compelling change, JScript.NET also supports the following enhancements to the original ECMA 262 specification:

• Support for strongly typed data

• Full-blown object-orientation

• Support for type partitioning via 'packages'

• Complete access to the .NET base class libraries

The JScript.NET compiler that ships with the SSCLI is very interesting in that the jsc code base (located under /sscli/jscript) is authored entirely in C#! Thus, given that jsc is in fact a .NET assembly, it must be executed via clix.

To view each of the options provided by the JScript.NET compiler, change to the directory containing jsc (/sscli/build/v1.ppcfstchk.rotor) and issue the following command from an SSCLI-enabled Terminal (Listing 2):

clix jsc

As you can see from the resulting output, many of the options provided by jsc are identical to those of csc. For example, jsc supports /output, /target and /reference flags as well as support for response files. One feature of jsc is unique however, and is described in Table 1.

The interesting option of jsc                  Meaning in Life  
autoref                            This option (which is enabled by default) informs the 
                                   compiler to automatically reference external assemblies 
                                   based on the list of import statements in your *.js 
                                   code files.

                                   Using this feature, you are not required to explicitly 
                                   specify assemblies using the /r flag (as you would need 
                                   to do in C#).

While this is not the place to examine each and every aspect of the JScript.NET programming language, Listing 3 provides some sample code to use throughout this article:

// 'import' is a JScript.NET specific 
// keyword use to reference .NET namespaces. 
import System;  

// A simple class type.
class Person
{
       // State data of the type. 
   private var mName : String;
   private var mAge : int;

       // Type constructor.
   function Person(name : String, age : int)
   {
      this.mName = name;
      this.mAge = age;
   }
       // A read-only 'property'
   function get Name() : String
   {
      return this.mName;
   }
       // Read-write property. 
   function get Age() : int
   {
      return this.mAge;
   }
   function set Age(newAge : int)
   {
      if ((newAge >= 0) && (newAge <= 130))
         this.mAge = newAge;
      else
      {
         Console.WriteLine("Ug...bad value...");
      }
   }
}

// Prompt user for information about this person. 
Console.WriteLine("**The Amazing JScript.NET App**");
Console.Write("Enter person's name: ");
var name : String = Console.ReadLine();
Console.Write("Enter initial age of person: ");
var age : int = int.Parse(Console.ReadLine());

// Now create a person using input. 
var myPerson : Person = new Person(name, age);

// print name using intrinsic JScript f(x). 
print(myPerson.Name);

// Base class library call. 
Console.WriteLine(myPerson.Age);

// Change age with Age property and reprint. 
chucky.Age = 26;
Console.WriteLine("{0} is now {1} years old.", 
  myPerson.Name, myPerson.Age);
Console.WriteLine("All done. See ya");

The first point of interest is the JScript.NET 'import' keyword, which is similar in function to the C# 'using' keyword in that it allows you to specify the name of the .NET namespaces this file is manipulating.

Next is the 'class' keyword of JScript.NET used to define a .NET class type named 'Person'. Note that type member variables are defined using the 'var' keyword and the following syntax (Listing 4).

class Person
{
   // AssessModifier var NameOfVariable : DataTypeOfVariable;
   private var mName : String;
   private var mAge : int;
...
}

Given that these data points have been defined as private, we need to provide a manner in which the object user can safely manipulate these values. Under the .NET platform, encapsulation services are provided (in part) by the use of type properties. Simply put, properties are get (accessor) and set (mutator) methods in disguise. Here, our Person class defines a read-only property termed Name and a read/write property named Age.

In JScript.NET, properties are declared using the 'function get' and 'function set' keywords. Like a traditional accessor/mutator pair, properties are used to control access to state data. In the case of our read-only Name property, we are returning a copy of the private mName member variable (Listing 5).

class Person
{
       // AssessModifier var NameOfVariable : DataTypeOfVariable;
   private var mName : String;
   private var mAge : int;
...
}

The Age property is a bit more interesting in that the function set method performs simple data validation on the incoming parameter (Listing 6).

// Note that properties must be defined
// with regard to the type of data they
// encapsulate.
function get Name() : String
{
   return this.mName;
}

The major benefit of using .NET properties, over accessor/mutator methods such as GetAge() and SetAge(), is the fact that it simplifies the syntax for the object user. Thus, rather than authoring the following Java-like code (Listing 7):

// Encapsulation using accessor/mutator methods. 
myPerson.SetAge(30);
var theAge : int = myPerson.GetAge();

We can simply write the following (Listing 8):

// Encapsulation using .NET properties.
myPerson.Age = 30; // Triggers set functionality.
var theAge : int = myPerson.Age; // Triggers get functionality.

Notice how properties provide the illusion that you are accessing a point of public data (which would be bad insofar the that would break encapsulation) while still honoring your data validation logic.

The final point is the block of 'freestanding' code at the end of the SimpleJScript.js file. Notice that we are blending the use of the .NET System.Console type as well as the JScript 'print' function to print our the values of the person to the Terminal window (Listing 9).

// Now create a person using input. 
var myPerson : Person = new Person(name, age);

// print name using intrinsic JScript f(x). 
print(myPerson.Name);

// Base class library call. 
Console.WriteLine(myPerson.Age);

Assuming you have saved the previous code to a file named SimpleJScript.js, you can compile this file into a .NET code library with the command shown in Listing 10 (assure the input file is in the same location as jsc. If not, supply the full path):

clix jsc SimpleJScript.js

You can now run your assembly as you would expect (Listing 11).

clix SimpleJScript 

Figure 1 illustrates one possible session.

If you have been playing around with the C# programming language, it may surprise you that JScript.NET allows programmers to define programming logic not contained within a type definition. C# (as well as most other .NET-aware languages) demand that all programming logic be contained within a type or type member definition. In reality, the same constraint is found with JScript.NET, however the compiler will take care of the details on your behalf. To illustrate, load your SimpleJScript.exe assembly into ildasm (Listing 12).

ildasm SimpleJScript 

As you look over the output, you will find that all of the global code has been automatically placed in a method named (surprise, surprise) 'Global Code', which is defined within a type named 'JScript 0'. This class type extends Microsoft.JScript.GlobalScope, which is defined within a helper assembly named Microsoft.JScript.dll (located under the /sscli/build/v1.ppcfstchk.rotor directory). Listing 13 shows the CIL of the type in question (edited for clarity).

.class public auto ansi 'JScript 0'
  extends [Microsoft.JScript]
Microsoft.JScript.GlobalScope
{
  .method public instance object 
    'Global Code'() cil managed
  {

    // All of your global code is placed here...
  }
}

In addition to the 'JScript 0' type, jsc also generates a class named 'JScript Main' that defines the application's entry point: Main(). The Main() method leverages several types within the Microsoft.JScript.dll assembly to execute the program. Listing 14 hits the highlights.

.class public auto ansi 'JScript Main'
  extends [mscorlib]System.Object
{
  .method public static void Main(string[] A_0) 
    cil managed
  {
    .entrypoint

    // Define a variable of type GlobalScope.
    .locals init (class [Microsoft.JScript]
      Microsoft.JScript.GlobalScope V_0)
...
    // Create the 'JScript 0' object.
    IL_001e: newobj instance void 
     'JScript 0'::.ctor(class[Microsoft.JScript]
     Microsoft.JScript.GlobalScope)
...
    // Now call the 'Global Code()' method.
    IL_0023:  call instance object 
      'JScript 0'::'Global Code'()
    IL_0028:  pop
    IL_0029:  ret
  }
}

This wraps up our exploration of the JScript sample application. If you are interested in exploring JScript.NET in greater detail, hundreds of articles and sample applications can be found online (just be sure to have a space between JScript and .NET when searching [JScript .NET not JScript.NET]).

The next sample application (cLisp) is a partial LISP compiler that targets the .NET platform. As mentioned, cLisp is more research-orientated in nature, in that it does not implement every aspect of the LISP programming language. However, the code base does provide an excellent foundation for those of you who are interested in extending cLisp with new functionality. As well, if you wish to build your own managed compiler that can function within the SSCLI, cLisp is a solid example to build upon.

Like the JScript.NET compiler, the cLisp compiler is authored in C#. If you navigate to the cLisp directory (/sscli/samples/compilers/clisp), you will find all of the necessary source code. As well, the cLisp directory contains a few *.lisp code files which can be used as input to the cLisp application. For example the fibo.lisp file computes a Fibonacci sequence (Listing 15).

(defun Fib (N)
  (if (<= N 0) 
      0 
    (if (= N 1) 
	1 
      (+ (Fib (- N 1)) (Fib (- N 2))
	 )
      )
    )
  )
(defun Fibo (N) (do ((count 0 (+ count 1))
		 (Fibo (car (Fib 0)) (cons Fibo (car (Fib count)))))
		((> count N)
		 Fibo)))
(Fibo 25)

Now, if you can't make heads or tails of the previous LISP code, don't sweat it. The point here is not to examine the syntactic details of LISP, but rather understand how LISP source code can be used to build a valid .NET image. To illustrate, navigate to the /sscli/build/v1.ppcfstchk.rotor/samples directory and compile fibo.lisp into an executable assembly using the following command (Listing 16).

clix clisp fibo.lisp

The resulting .NET assembly (fibo.exe) may now be launched using clix. Figure 2 shows the program's output.

Much like jsc, cLisp will auto-generate a class type and program entry point behind the scenes (this can be verified by loading Fibo.exe into ildasm). While this example is enticing, understand that given the fact that cLisp is an illustrative compiler, you do not have access to the BCL types.

Last but not least, it is worth pointing out that the SSCLI also ships with another research-oriented managed compiler named myC. This sample exposes a (very) limited subset of the C programming language to the .NET universe. Like cLisp, the sample code further illustrates the process of building a managed compiler. Sscli/samples/compilers/myc/myc.html describes the C# source code files used to build this managed compiler and I'll leave it to you to dig into the details if you so choose.

The .NET platform may be manipulated using numerous programming languages, far beyond those that ship with the SSCLI. In the initial issue of this series (October, 2003) I listed a subset of .NET-aware compilers. If you wish to see a more all-encompassing list, navigate to http://www12.brinkster.com/brianr/languages.aspx. Here you will find links to compilers as diverse as Ada, Forth, Fortran, Java, LOGO (yes, I am not kidding), Mixal and Ruby as well as fully functionally C and LISP compilers.

Keep in mind however that many of these offerings target production level .NET distributions such as Mono, Portable .NET and Microsoft's CLR, and therefore may require a bit of tweaking to execute under the SSCLI. In just a few short issues, we will move from the research-oriented world of the SSCLI to a production-level distribution of the CLI named Portable .NET. At that time I will revisit the use of 'alternative' .NET programming languages.

Code Documentation and Type Analysis Samples

Now that you have had a chance to check out the compiler-centric examples of the SSCLI, we'll examine samples of the code-formatting / assembly-investigation ilk. Each of the examples we will examine here are found under the /samples/utilities subdirectory. First up, codetohtml.exe

The codetohtml sample application (which is written in JScript.NET) generates HTML files representing C# or JScript.NET source code. To illustrate codetohtml in action, supply the SimpleJScript.js file created earlier as a command line argument (Listing 17).

clix codetohtml SimpleJScript.js

Figure 3 shows the default HTML format.

The runtime behavior of codetohtml is controlled by a set of initialization files, whose exact names are based on the language of the input file (for example, js_codetohtml.ini for JScript.NET and cs_codetohtml.ini for C#). Table 2 describes the role of each *.ini file.

CodeToHtml Initialization File          Meaning in Life
<lang>_codetohtml.ini                   This is the core file which specifies the names 
                                        of the other three related *.ini files as well 
                                        as the associated style sheet to use when generating 
                                        the HTML file.

<lang>_keywords.ini                     Contains a list of all active keywords for the 
                                        given language.

<lang>_futurereserved.ini               Contains a list of reserved keywords for the 
                                        given language.

<lang>_userdefined.ini                  Contains a list of user-defined types (such as 
                                        class names) to be recognized during the 
                                        formatting process.

Of course, each of these files may be modified to control the format of the resulting HTML. To begin, open up js_codetohtml.ini using your text editor of choice (Listing 18):

defstylesheet=codeblue.css
keywords=js_keywords.ini
userdefined=js_userdefined.ini
futurereserved=js_futurereserved.ini
replace=js_replace.ini
language=JScript

Note that the default style sheet is named codeblue.css. This may be changed to the other sample style sheet, codewhite.ccs, by updating the defstylesheet value. If you examine either file, you will find a set of styles used to format each token category (keywords, code comments, user defined types and so on). Listing 19 shows a partial listing.

div.code
{
	background-color: rgb(0,0,128);
	font-family: "Lucida Console", "courier new", courier;
	color: rgb(255,255,0);
	font-size: x-small;
	padding: 1em;
	margin: 1em;
}
...
div.code span.userdefined
{
	color: rgb(51, 51, 0);
	font-weight: bold
}
...

To spice things up a bit, edit js_codetohtml.ini file to point to the codewhite.css style sheet. Next, modify js_userdefined.ini to recognize the System.Console type of the base class libraries by adding Console to the end of the list. At this point, run codetohtml once again specifying SimpleJScript.js as the input file. Notice in Figure 4 that each occurrence of the Console type is rendered using the 'userdefined' style.

Beyond creating custom style sheets for use by codetohtml, you will also want to check out the JScript.NET source code for this example (codetohtml.js) as it illustrates a number of interesting .NET base class library types. As you already know how to interact with the JScript.NET compiler, feel free to hack away to your heart's content.

Corcls and typefinder are essentially object browsing utilities (written in C#) that provide a lightweight alternative to ildasm. The corcls utility can be helpful when you simply wish to view the C# definition of a given type, rather than the underlying CIL code. If you run corcls at the command line (via clix), you will see a list of all available options. Table 3 documents a partial listing.

Interesting Options of Corcls 	Meaning in Life

-w                               Generates output in HTML format.

-m nameOfAssemblyToSearch        By default, corcls only searches a core .NET BCL 
                                 assembly named mscorlib.dll.  If you wish to browse 
                                 other assemblies (including your custom assemblies), 
                                 use the -m flag.

-noinherit                       Prevents the display of inherited methods and fields.

-v                               Displays only output visible (public and protected) 
                                 classes, methods, or fields.

-p                               Displays only output public classes, methods, or fields.

Again, by default, corcls only searches the core .NET assembly, mscorlib.dll. If you wish to view definitions for types defined in other assemblies, you will need to specify the '-m' option. By way of a few examples, Listing 20 will display type information for System.String, Listing 21 displays the same type as HTML (via the '-w' option) and Listing 22 dumps information about the Person type defined within SimpleJScript.exe (originally defined in JScript.NET). Be aware that when you run load external modules with the '-m' option, you will need to ensure a copy of the binary file is in the same directory as corcls itself.

clix corcls System.String

clix corcls -w System.String

clix corcls -m SimpleJScript.exe Person

Figure 5 shows the result of executing Listing 22.

The functionality of typefinder is similar to that of corcls, however this tool allows you to get much more specific. Using a set of display options, you can view various aspects of a type such as the set of interfaces it supports, the methods it contains and so forth. I'll allow you to explore the full set of options via the findtype.html file located under /sscli/samples/utilities/typefinder, however to prime the pump, Table 4 lists some possibilities.

Typefinder Option        Meaning in Life

-d: NameOfDirectory      Used to specify a directory which contains the assembly 
                         you wish to investigate.

-x                       Used to specify the fully qualified name of the type 
                         in a given assembly.

-a                       Shows all information for a given type, including inherited 
                         members (very helpful).

-e, -f, -i, -m, -p       Shows the events, fields, interfaces, methods or properties 
                         of a given type.  These flags may be combined into a 
                         single commend.

-r                       Include base class information.

As an example, the command shown in Listing 23 yields the output seen in Listing 24.

clix typefinder -xip System.String

class      System.String
# Interfaces: 4
  interface System.IComparable
  interface System.ICloneable
  interface System.IConvertible
  interface System.Collections.IEnumerable
Properties
  Char Chars [Int32] 'get' 
  Int32 Length 'get'

When working with typefinder, be sure to check out the role of the '-d' option (as it will prove helpful when you wish to view types in external assemblies, such as SimpleJScript.exe).

To wrap up this installment, we will examine what could be the most inciting set of sample applications, the Platform Independent GUI (PIGUI). As mentioned earlier in this series, the SSCLI does not ship with an implementation of System.Windows.Forms (.NET's native GUI toolkit). However, to illustrate what can be done with the CLI, we are provided with a set of samples that leverage the tcl/tk libraries, represented on the Macintosh by two *.dylib files (libtcl8.4.dylib and libtk8.4.dylib). As a friendly reminder, recall that the process of installing tcl/tk was described in the November installment.

The SSCLI offers a handful of samples that leverage the tcl/tk libraries:

• Hello: A simple application illustrating GUI event handling

• PigPad: A text editor application

• Tk: This sample builds the required assembly (sharedsourcecli.tk.dll) that wraps a subset of the tcl/tk libraries

The Tk sample code is very illumining for a few reasons. First, the code base illustrates how the .NET platform can communicate with the API of the underlying operating system (as well as native libraries) using a specific attribute named DllImportAttribute (attributes enable aspect-oriented programming [AOP] techniques under .NET, the full details of which will be described at a later time).

On a more practical level, the assembly generated by the Tk sample (sharedsourcecli.tk.dll) is required by all other PIGUI examples. Given this, you must ensure that a copy of sharedsourcecli.tk.dll is placed within the same directory as the executing assembly. Furthermore, you will most likely want to copy the tcl/tk libraries are in the same directory of the pigui sample application you wish to run. If you installed tcl/tk using Fink Commander, they should be under /sw/lib.

To execute the PIGUI sample applications, you must initialize X11 (full screen or rootless), and run these SSCLI samples from an xterm session (as the Macintosh Terminal applet does not initialize the necessary X11 variables). Now, when you install Panther, you have the option to install X11, which it may be launched using the X11 applet located under the Applications/Utilities directory.

If you are not running Panther, you must obtain X11 from cyberspace. While there are numerous distributions of X11 for the Mac, I'd suggest you download and install Apple's office X11 implementation (consult http://www.apple.com for further details). For the remainder of this article, I will assume you are at least somewhat comfortable manipulating X11.

By default, Apple's X11 distribution makes use of the Quartz windows manager (quartz-wm), which can be verified by investigating your machine's .xinitrc file. Assuming you have activated X11, enable the SSCLI from an xterm window (via DoSscli) and navigate to the pigpad sample application located under the /sscli/build/v1.ppcfstchk.rotor/samples/pigui/pigpad directory. Finally, execute pigpad via clix. Figure 6 shows PIGUI running under the default Quartz windows manager.

If you edit your .xinitrc file to load an alternative window manager (which may be obtained via Fink Commander) you would find that pigpad takes on an entirely different look and feel. To prove the point, update .xinitrc to load your window manager of choice (Listing 24 illustrates the loading of Window Maker).

# The Apple WM.
# quartz-wm 

# Window Maker
exec /sw/bin/wmaker

Once you have updated and saved .xinitrc, close down and then restart X11. Now follow the previous steps to execute the pigpad sample application. Figure 7 shows the new look and feel.

Very cool! If you are interested in digging into the "who, what, where and why" of how pigui does it's magic, your first step is to examine the documentation of the Tk wrapper (/sscli/samples/pigui/tk/tk_wrapper.html). Once you have a general sense of the exposed functionality, you should be able to alter the code base of pigpad (or pighello) to your liking.

This installment rounded out your understanding of the SSCLI by showcasing a number of sample applications and managed languages. We began by exploring the JScript.NET programming language and learned how jsc can be used to build .NET assemblies using a scripting like syntax. We also took a very brief look at the cLisp and myC compilers, and examined a set of sample applications that allow you to explore the format of a given assembly in a more lightweight manner than ildasm. Finally, you had a chance to see how tcl/tk was used to build a platform independent GUI under the SSCLI.

The next issue marks a conceptual shift in this series. While these first issues concentrated on the overall nature of the .NET platform and the role of the SSCLI, the next several articles will pound of the syntax and semantics of C#, and see how this programming language expresses the type system (classes, interfaces, structures, enumerations and delegates) of .NET.

Andrew Troelsen is a seasoned .NET developer who has authored numerous books on the topic, including the award winning C# and the .NET Platform. He is employed as a full-time .NET trainer and consultant for Intertech Training (www.intertechtraining.com) who apologies for failing to submit his January article in time. You can contact (or scold) Andrew at atroelsen@mac.com.