Update of /project/rdnzl/cvsroot/RDNZL/doc In directory common-lisp:/tmp/cvs-serv4420/doc
Modified Files: index.html Log Message: 0.9.0 release
--- /project/rdnzl/cvsroot/RDNZL/doc/index.html 2006/01/13 07:06:34 1.4 +++ /project/rdnzl/cvsroot/RDNZL/doc/index.html 2006/02/01 01:00:57 1.5 @@ -1,1082 +1,1081 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> -<html> - -<head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <title>RDNZL - A .NET layer for Common Lisp</title> - <style type="text/css"> - pre { padding:5px; background-color:#e0e0e0 } - a { text-decoration: none; } - a.noborder { border:0px } - a.noborder:hover { border:0px } - a.none { border:1px solid white; } - a.none:hover { border:1px solid white; } - a { border:1px solid white; } - a:hover { border: 1px solid black; } - </style> -</head> - -<body bgcolor=white> - -<h2>RDNZL - A .NET layer for Common Lisp</h2> - -<blockquote> -<br> <br><h3><a name=abstract class=none>Abstract</a></h3> - -<a href="http://globalia.net/donlope/fz/songs/RDNZL.html">RDNZL</a> (pronounced "Redunzl") enables Common Lisp applications to interact with <a href="http://en.wikipedia.org/wiki/Microsoft_.NET">.NET</a> -libraries. It's more or less a foreign function interface for .NET -languages like <a href="http://en.wikipedia.org/wiki/C_Sharp_programming_language">C#</a> built atop the C foreign function interface. - -<p> - -RDNZL comes with a <a -href="http://www.opensource.org/licenses/bsd-license.php%22%3EBSD-style -license</a> so you can basically do with it whatever you want. - -<p> -<font color=red>Download shortcut:</font> <a href="http://weitz.de/files/RDNZL.tar.gz">http://weitz.de/files/RDNZL.tar.gz</a>. - -</blockquote> - -<center> -<a class=none title="Apropos Example" href="#apropos"><img src="apropos.png" border=0 width=624 height=411></a> -</center> - -<br> <br><h3><a class=none name="contents">Contents</a></h3> -<ol> - <li><a href="#examples">Examples</a> - <li><a href="#download">Download and installation</a> - <li><a href="#mail">Support and mailing lists</a> - <li><a href="#implementations">Supported Lisp implementations</a> - <li><a href="#dictionary">The RDNZL dictionary</a> - <ol> - <li><a href="#objects">Representation and creation of .NET objects</a> - <ol> - <li><a href="#container-p"><code>container-p</code></a> - <li><a href="#box"><code>box</code></a> - <li><a href="#unbox"><code>unbox</code></a> - <li><a href="#new"><code>new</code></a> - <li><a href="#cast"><code>cast</code></a> - <li><a href="#make-null-object"><code>make-null-object</code></a> - </ol> - <li><a href="#methods">Accessing .NET methods, properties, and fields</a> - <ol> - <li><a href="#invoke"><code>invoke</code></a> - <li><a href="#property"><code>property</code></a> - <li><a href="#field"><code>field</code></a> - <li><a href="#ref"><code>ref</code></a> - </ol> - <li><a href="#arrays">Arrays and enumerations</a> - <ol> - <li><a href="#aref*"><code>aref*</code></a> - <li><a href="#do-rdnzl-array"><code>do-rdnzl-array</code></a> - <li><a href="#list-to-rdnzl-array"><code>list-to-rdnzl-array</code></a> - <li><a href="#rdnzl-array-to-list"><code>rdnzl-array-to-list</code></a> - <li><a href="#integer-to-enum"><code>integer-to-enum</code></a> - <li><a href="#enum-to-integer"><code>enum-to-integer</code></a> - <li><a href="#or-enums"><code>or-enums</code></a> - </ol> - <li><a href="#exceptions">Handling of .NET exceptions</a> - <ol> - <li><a href="#rdnzl-error"><code>rdnzl-error</code></a> - <li><a href="#rdnzl-error-exception"><code>rdnzl-error-exception</code></a> - <li><a href="#rdnzl-handler-case"><code>rdnzl-handler-case</code></a> - </ol> - <li><a href="#types">Type names and assemblies</a> - <ol> - <li><a href="#import-type"><code>import-type</code></a> - <li><a href="#load-assembly"><code>load-assembly</code></a> - <li><a href="#import-assembly"><code>import-assembly</code></a> - <li><a href="#import-types"><code>import-types</code></a> - <li><a href="#use-namespace"><code>use-namespace</code></a> - <li><a href="#unuse-namespace"><code>unuse-namespace</code></a> - <li><a href="#unuse-all-namespaces"><code>unuse-all-namespaces</code></a> - </ol> - <li><a href="#reader">Special reader syntax</a> - <ol> - <li><a href="#enable-rdnzl-syntax"><code>enable-rdnzl-syntax</code></a> - <li><a href="#disable-rdnzl-syntax"><code>disable-rdnzl-syntax</code></a> - </ol> - <li><a href="#direct">Direct calls</a> - <ol> - <li><a href="#define-rdnzl-call"><code>define-rdnzl-call</code></a> - </ol> - <li><a href="#delivery">Saving images and application delivery</a> - <ol> - <li><a href="#shutdown-rdnzl"><code>shutdown-rdnzl</code></a> - <li><a href="#init-rdnzl"><code>init-rdnzl</code></a> - </ol> - </ol> - <li><a href="#details">Implementation details and things to watch out for</a> - <li><a href="#ack">Acknowledgements</a> -</ol> - -<br> <br><h3><a class=none name="examples">Examples</a></h3> - -Here's a short example session (using <a href="#implementations">AllegroCL</a>): - -<pre> -<img alt="The Message Box" title="The Message Box" align=right border=0 vspace=10 hspace=10 width=185 height=100 src="box.png">CL-USER(1): <a class=noborder href="#download">(load "/home/lisp/RDNZL/load.lisp")</a> -<font color=orange>; Loading C:\home\lisp\RDNZL\load.lisp -; Fast loading C:\home\lisp\RDNZL\packages.fasl -; Fast loading C:\home\lisp\RDNZL\specials.fasl -; Fast loading C:\home\lisp\RDNZL\util.fasl -; Fast loading C:\home\lisp\RDNZL\port-acl.fasl -; Fast loading from bundle code\IORDEFS.fasl. -; Fast loading from bundle code\EFMACS.fasl. -; Fast loading C:\home\lisp\RDNZL\ffi.fasl -; Foreign loading RDNZL.dll. -; Fast loading C:\home\lisp\RDNZL\container.fasl -; Fast loading C:\home\lisp\RDNZL\reader.fasl -; Fast loading C:\home\lisp\RDNZL\arrays.fasl -; Fast loading C:\home\lisp\RDNZL\adapter.fasl -; Fast loading C:\home\lisp\RDNZL\import.fasl</font> -T -CL-USER(2): (use-package :rdnzl) -T -CL-USER(3): (<a class=noborder href="#enable-rdnzl-syntax">enable-rdnzl-syntax</a>) -CL-USER(4): (<a class=noborder href="#import-types">import-types</a> "System.Windows.Forms" - "MessageBox" "MessageBoxButtons" "DialogResult") -NIL -CL-USER(5): (<a class=noborder href="#use-namespace">use-namespace</a> "System.Windows.Forms") -CL-USER(6): (defun message-box (text &optional (caption "RDNZL")) - <font color=orange>;; check if the "OK" button was pressed</font> - [Equals [MessageBox.Show text caption - <font color=orange>;; we want the message box to have "OK" and "Cancel" buttons</font> - [$MessageBoxButtons.OKCancel]] - [$DialogResult.OK]]) -MESSAGE-BOX -CL-USER(7): (message-box "Hello World!") <font color=orange>;; user presses "OK" button</font> -T -CL-USER(8): (message-box "Hello World!") <font color=orange>;; user presses "Cancel" button</font> -NIL -</pre> - -(Note: All examples shown here are included in the <code>examples</code> folder of the distribution.) -<p> -For a more interesting example which interacts with custom .NET code -and demonstrates callbacks into Lisp consider the .NET library -<code>AproposGUI.dll</code> (put it into your Lisp's application folder) created -with this C# code: - -<pre> -// compile this with: -// csc.exe /target:library AproposGui.cs - -using System; -using System.Collections; -using System.ComponentModel; -using System.Drawing; -using System.Data; -using System.Windows.Forms; - -namespace AproposGUI { - public class AproposControl : System.Windows.Forms.UserControl { - public System.Windows.Forms.TextBox textBox; - public System.Windows.Forms.TextBox listBox; - private System.Windows.Forms.Label label; - public System.Windows.Forms.Label title; - private delegate string callback(string input); - - private System.ComponentModel.Container components = null; - - public AproposControl() { - InitializeComponent(); - } - - protected override void Dispose(bool disposing) { - if (disposing) { - if (components != null) - components.Dispose(); - } - base.Dispose(disposing); - } - - private void InitializeComponent() { - this.textBox = new System.Windows.Forms.TextBox(); - this.listBox = new System.Windows.Forms.TextBox(); - this.label = new System.Windows.Forms.Label(); - this.title = new System.Windows.Forms.Label(); - this.SuspendLayout(); - - this.textBox.Location = new System.Drawing.Point(16, 344); - this.textBox.Name = "textBox"; - this.textBox.Size = new System.Drawing.Size(584, 20); - this.textBox.TabIndex = 0; - this.textBox.Text = ""; - - this.listBox.Location = new System.Drawing.Point(16, 56); - this.listBox.Multiline = true; - this.listBox.Name = "listBox"; - this.listBox.ReadOnly = true; - this.listBox.ScrollBars = System.Windows.Forms.ScrollBars.Vertical; - this.listBox.Size = new System.Drawing.Size(584, 248); - this.listBox.TabIndex = 1; - this.listBox.Text = ""; - - this.label.Location = new System.Drawing.Point(24, 312); - this.label.Name = "label"; - this.label.Size = new System.Drawing.Size(576, 23); - this.label.TabIndex = 2; - this.label.Text = "Enter text below and press RETURN"; - this.label.TextAlign = System.Drawing.ContentAlignment.MiddleCenter; - - this.title.Font = new System.Drawing.Font("Microsoft Sans Serif", 12F, System.Drawing.FontStyle.Bold, System.Drawing.GraphicsUnit.Point, ((System.Byte)(0))); - this.title.Location = new System.Drawing.Point(24, 16); - this.title.Name = "title"; - this.title.Size = new System.Drawing.Size(568, 24); - this.title.TabIndex = 3; - this.title.Text = "RDNZL Apropos Demo"; - this.title.TextAlign = System.Drawing.ContentAlignment.MiddleCenter; - - this.Controls.Add(this.title); - this.Controls.Add(this.label); - this.Controls.Add(this.listBox); - this.Controls.Add(this.textBox); - this.Name = "MainControl"; - this.Size = new System.Drawing.Size(616, 384); - this.ResumeLayout(false); - } - } -} -</pre> - -Now load <a class=none name="apropos"><code>examples/apropos.lisp</code></a> which looks like this: - -<pre> -<img alt="Another Message Box" title="Another Message Box" align=right border=0 vspace=10 hspace=10 width=308 height=100 src="box2.png">(in-package :cl-user) - -(use-package :rdnzl) - -(<a class=noborder href="#enable-rdnzl-syntax">enable-rdnzl-syntax</a>) - -(<a class=noborder href="#import-types">import-types</a> "System.Windows.Forms" - "Application" "DockStyle" "Form" "MessageBox" "KeyPressEventHandler" "TextBox") - -(import-types "AproposGUI" - "AproposControl") - -(<a class=noborder href="#use-namespace">use-namespace</a> "System.Windows.Forms") -(use-namespace "AproposGUI") - -(defun copy-to-clipboard (text-box) - (let ((selection-start [%SelectionStart text-box]) - (selection-length [%SelectionLength text-box]) - (text-length [%Length (box [%Text text-box])])) - (setf [%SelectionStart text-box] 0 - [%SelectionLength text-box] text-length) - [Copy text-box] - (setf [%SelectionStart text-box] selection-start - [%SelectionLength text-box] selection-length))) - -(let (message-shown) - (defun fill-list-box (object event) - (when (char= [%KeyChar event] #\Return) - (cast object "TextBox") - (let* ((input-string [%Text object]) - (input-length (length input-string))) - (when (plusp input-length) - (let ((apropos-text - (with-output-to-string (*standard-output*) - (apropos input-string))) - (list-box [$listBox (cast [%Parent object] "AproposControl")])) - (setf [%Text list-box] apropos-text) - (copy-to-clipboard list-box) - (unless message-shown - [MessageBox.Show "The output of APROPOS has been copied to the clipboard." - "RDNZL"] - (setq message-shown t))) - (setf [%SelectionStart object] 0 - [%SelectionLength object] input-length)))))) - -(defun run-apropos-form () - (let* ((control (new "AproposControl")) - (form (new "Form"))) - (setf [%Dock control] [$DockStyle.Fill] - [%ClientSize form] [%ClientSize control] - [%Text form] "RDNZL Apropos Demo" - [%Text [$title control]] - (format nil "RDNZL Apropos Demo (~A)" - (lisp-implementation-type))) - [+KeyPress [$textBox control] - (new "KeyPressEventHandler" #'fill-list-box)] - [Add [%Controls form] control] - [Application.Run form])) - -(<a class=noborder href="#disable-rdnzl-syntax">disable-rdnzl-syntax</a>) -</pre> - -and evaluate <code>(RUN-APROPOS-FORM)</code>. If you want to try this -several times, start the function in its own thread. In AllegroCL or LispWorks -that'd be: - -<pre> -(mp:process-run-function "apropos" #+:lispworks nil #'run-apropos-form) -</pre> - -The last example shows how easy it is to access web pages using the -.NET standard library: - -<pre> -CL-USER(9): (<a class=noborder href="#import-types">import-types</a> "System" "Net.WebClient") -NIL -CL-USER(10): (defun download-url (url) - (let ((web-client (new "System.Net.WebClient"))) - [GetString (new "System.Text.ASCIIEncoding") - [DownloadData web-client url]])) -DOWNLOAD-URL -CL-USER(11): (download-url "http://nanook.agharta.de/") -"<HTML> -<HEAD> -<META HTTP-EQUIV="refresh" CONTENT="5;URL=http://www.weitz.de/%5C%22%3E; -</HEAD> -<BODY><center> -<table border=3 bordercolor=green cellpadding=5 cellspacing=5><tr><td align=center> -<pre> -Linux nanook 2.6.7 #1 Thu Jul 22 01:01:58 CEST 2004 i686 GNU/Linux - - 01:23:23 up 100 days, 19:43, 0 users, load average: 0.00, 0.00, 0.00 - -</pre> - </td></tr></table></center> - -</BODY> -</HTML> -" -</pre> - -A bit more evolved: - -<pre> -CL-USER(12): (<a class=noborder href="#import-types">import-types</a> "System" "Net.WebException") -NIL -CL-USER(13): (<a class=noborder href="#use-namespace">use-namespace</a> "System.Net") -CL-USER(14): (defun download-url (url) - (<a class=noborder href="#rdnzl-handler-case">rdnzl-handler-case</a> - (let ((web-client (new "WebClient"))) - [GetString (new "System.Text.ASCIIEncoding") - [DownloadData web-client url]]) - ("WebException" (e) - (warn "Ooops, probably a typo: ~A" [%Message e]) - nil))) -DOWNLOAD-URL -CL-USER(15): (download-url "http://nanook.aharta.de/") -Warning: Ooops, probably a typo: - The underlying connection was closed: The remote name could not be resolved. -NIL -</pre> - -This'll also work with https URLs. - - - -<br> <br><h3><a class=none name="download">Download and installation</a></h3> - -RDNZL together with this documentation can be downloaded from -<a href="http://weitz.de/files/RDNZL.tar.gz">http://weitz.de/files/RDNZL.tar.gz</a>, the current version is 0.8.0. It -doesn't depend on any other Lisp libraries. The C++ source for the -shared library <code>RDNZL.dll</code> can be downloaded separately from -<a href="http://weitz.de/files/RDNZL_cpp.tar.gz">http://weitz.de/files/RDNZL_cpp.tar.gz</a> but you don't need this archive -to deploy RDNZL - <code>RDNZL.tar.gz</code> already contains <code>RDNZL.dll</code>. -You can also access the current RDNZL source code (Lisp and C++) via <a href="http://common-lisp.net/cgi-bin/viewcvs.cgi/?cvsroot=rdnzl">CVS</a>. -<p> -Before you load RDNZL make sure you have the <a href="http://msdn.microsoft.com/netframework/downloads/framework1_1/">.NET framework</a> installed. -Then move the file <code>RDNZL.dll</code> to a location where your Lisp's FFI will -find it - the folder where your Lisp executable is located is -generally a good place for that. -<p> -Now, to compile and load RDNZL just <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_load.htm"><code>LOAD</code></a> the file <code>load.lisp</code> - that's -all. (Or alternatively use <a href="http://www.cliki.net/asdf">ASDF</a> if you like - RDNZL comes with a -system definition for ASDF.) -<p> -Oh, and - for the moment - <em>don't</em> use <a -href="http://common-lisp.net/project/slime/%22%3ESLIME</a> together with -LispWorks when loading RDNZL - see <a href="http://common-lisp.net/pipermail/slime-devel/2004-December/002877.html">this message</a> for an explanation. - - -<br> <br><h3><a name="mail" class=none>Support and mailing lists</a></h3>
[1766 lines skipped]
-
eweitz