man/csharp.1

   1 .de Sp \" Vertical space (when we can't use .PP)
   2 .if t .sp .5v
   3 .if n .sp
   4 ..
   5 .TH csharp 1 "4 September 2008"
   6 .SH NAME
   7 csharp, gsharp \- Interactive C# Shell
   8 .SH SYNOPSIS
   9 .B csharp [--attach PID] [-e EXPRESSION] [file1 [file2]]
  10 [options]
  11 .P
  12 .B gsharp [file1 [file2]]
  13 .SH DESCRIPTION
  14 The
  15 .I csharp
  16 is an interactive C# shell that allows the user to enter and evaluate
  17 C# statements and expressions from the command line.   The regular
  18 .I mcs
  19 command line options can be used in this version of the compiler.
  20 .PP
  21 The
  22 .I gsharp
  23 command is a GUI version of the C# interpreter that uses Gtk# and
  24 provides an area to attach widgets as well.      This version can be
  25 attached to other Gtk# applications in a safe way as it injects itself
  26 into the main loop of a Gtk# application, avoiding any problems
  27 arising from the multi-threaded nature of injecting itself into a
  28 target process.
  29 .PP
  30 Files specified in the command line will be loaded and executed as
  31 scripts.
  32 .PP
  33 Starting with Mono 2.10, the
  34 .I csharp
  35 command can be used as an interpreter executed by executables flagged
  36 with the Unix execute attribute.   To do this, make the first line of
  37 your C# source code look like this:
  38 .nf
  39 "#!/usr/bin/csharp"
  40 Console.WriteLine ("Hello, World");
  41 .fi
  42 .SH OPTIONS
  43 The commands accept all of the commands that are available to the
  44 .I mcs
  45 command, so you can reference assemblies, specify paths, language
  46 level and so on from the command line.   In addition, the following
  47 command line options are supported:
  48 .TP
  49 .I "\-\-attach"
  50 This is an advanced option and should only be used if you have a deep
  51 understanding of multi-threading.     This option is availble on the
  52 .I csharp
  53 command and allows the compiler to be injected into other processes.
  54 This is done by injecting the C# shell in a separate thread that runs
  55 concurrently with your application.  This means that you must take
  56 special measures to avoid crashing the target application while using
  57 it.  For example, you might have to take the proper locks before
  58 issuing any commands that might affect the target process state, or
  59 sending commands through a method dispatcher.
  60 .TP
  61 .I "\-e" EXPRESSION
  62 This will evaluate the specified C# EXPRESSION and exit
  63 .SH OPERATION
  64 Once you launch the csharp command, you will be greeted with the
  65 interactive prompt:
  66 .PP
  67 .nf
  68 $ csharp
  69 Mono C# Shell, type "help;" for help
  70
  71 Enter statements below.
  72 csharp>
  73 .fi
  74 .PP
  75 A number of namespaces are pre-defined with C# these include System,
  76 System.Linq, System.Collections and System.Collections.Generic.
  77 Unlike the compiled mode, it is possible to add new using statements
  78 as you type code, for example:
  79 .PP
  80 .nf
  81 csharp> new XmlDocument ();
  82 <interactive>(1,6): error CS0246: The type or namespace name `XmlDocument' could not be found. Are you missing a using directive or an assembly reference?
  83 csharp> using System.Xml;
  84 csharp> new XmlDocument ();
  85 System.Xml.XmlDocument
  86 .fi
  87 .PP
  88 Every time a command is typed, the scope of that command is one of a
  89 class that derives from the class Mono.CSharp.InteractiveBase.   This
  90 class defines a number of static properties and methods.   To display
  91 a list of available commands access the `help' property:
  92 .nf
  93 csharp> help;
  94 "Static methods:
  95   LoadPackage (pkg); - Loads the given Package (like -pkg:FILE)
  96   [...]
  97   ShowVars ();       - Shows defined local variables.
  98   ShowUsing ();      - Show active using decltions.
  99   help;
 100 "
 101 csharp>
 102 .fi
 103 .PP
 104 When expressions are entered, the C# shell will display the result of
 105 executing the expression:
 106 .PP
 107 .nf
 108 csharp> Math.Sin (Math.PI/4);
 109 0.707106781186547
 110 csharp> 1+1;
 111 2
 112 csharp> "Hello, world".IndexOf (',');
 113 5
 114 .fi
 115 .PP
 116 The C# shell uses the ToString() method on the returned object to
 117 display the object, this sometimes can be limiting since objects that
 118 do not override the ToString() method will get the default behavior
 119 from System.Object which is merely to display their type name:
 120 .PP
 121 .nf
 122 csharp> var a = new XmlDocument ();
 123 csharp> a;
 124 System.Xml.Document
 125 csharp> csharp> a.Name;
 126 "#document"
 127 csharp>
 128 .fi
 129 .PP
 130 A few datatypes are handled specially by the C# interactive shell like
 131 arrays, System.Collections.Hashtable, objects that implement
 132 System.Collections.IEnumerable and IDictionary and are rendered
 133 specially instead of just using ToString ():
 134 .PP
 135 .nf
 136 csharp> var pages = new Hashtable () {
 137       >  { "Mono",    "http://www.mono-project.com/" },
 138       >  { "Linux",   "http://kernel.org" } };
 139 csharp> pages;
 140 {{ "Mono", "http://www.mono-project.com/" }, { "Linux", "http://kernel.org" }}
 141 .fi
 142 .PP
 143 It is possible to use LINQ directly in the C# interactive shell since
 144 the System.Linq namespace has been imported at startup.   The
 145 following sample gets a list of all the files that have not been
 146 accessed in a week from /tmp:
 147 .PP
 148 .nf
 149 csharp> using System.IO;
 150 csharp> var last_week = DateTime.Now - TimeSpan.FromDays (7);
 151 csharp> var old_files = from f in Directory.GetFiles ("/tmp")
 152       >   let fi = new FileInfo (f)
 153       >   where fi.LastAccessTime < LastWeek select f;
 154 csharp>
 155 .fi
 156 .PP
 157 You can of course print the results in a single statement as well:
 158 .PP
 159 .nf
 160 csharp> using System.IO;
 161 csharp> var last_week = DateTime.Now - TimeSpan.FromDays (7);
 162 csharp> from f in Directory.GetFiles ("/tmp")
 163       >   let fi = new FileInfo (f)
 164       >   where fi.LastAccessTime < last_week select f;
 165 [...]
 166 csharp>
 167 .fi
 168 .PP
 169 LINQ and its functional foundation produce on-demand code for
 170 IEnumerable return values.  For instance, the return value from a
 171 using `from' is an IEnumerable that is evaluated on demand.   The
 172 automatic rendering of IEnumerables on the command line will trigger
 173 the IEnumerable pipeline to execute at that point instead of having
 174 its execution delayed until a later point.
 175 .PP
 176 If you want to avoid having the IEnumerable rendered at this point,
 177 simply assign the value to a variable.
 178 .PP
 179 Unlike compiled C#, the type of a variable can be changed if a new
 180 declaration is entered, for example:
 181 .PP
 182 .nf
 183 csharp> var a = 1;
 184 csharp> a.GetType ();
 185 System.Int32
 186 csharp> var a = "Hello";
 187 csharp> a.GetType ();
 188 System.String
 189 csharp> ShowVars ();
 190 string a = "Hello"
 191 .fi
 192 .PP
 193 In the case that an expression or a statement is not completed in a
 194 single line, a continuation prompt is displayed, for example:
 195 .PP
 196 .nf
 197 csharp> var protocols = new string [] {
 198       >    "ftp",
 199       >    "http",
 200       >    "gopher"
 201       > };
 202 csharp> protocols;
 203 { "ftp", "http", "gopher" }
 204 .fi
 205 .PP
 206 Long running computations can be interrupted by using the Control-C
 207 sequence:
 208 .PP
 209 .nf
 210 csharp> var done = false;
 211 csharp> while (!done) { }
 212 Interrupted!
 213 System.Threading.ThreadAbortException: Thread was being aborted
 214   at Class1.Host (System.Object& $retval) [0x00000]
 215   at Mono.CSharp.InteractiveShell.ExecuteBlock (Mono.CSharp.Class host, Mono.CSharp.Undo undo) [0x00000]
 216 csharp>
 217 .fi
 218 .PP
 219 .SH INTERACTIVE EDITING
 220 The C# interactive shell contains a line-editor that provides a more
 221 advanced command line editing functionality than the operating system
 222 provides.   These are available in the command line version, the GUI
 223 versions uses the standard Gtk# key bindings.
 224 .PP
 225 The command set is similar to many other applications (cursor keys)
 226 and incorporates some of the Emacs commands for editing as well as a
 227 history mechanism to
 228 .PP
 229 .PP
 230 The following keyboard input is supported:
 231 .TP
 232 .I Home Key, Control-a
 233 Goes to the beginning of the line.
 234 .TP
 235 .I End Key, Control-e
 236 Goes to the end of the line.
 237 .TP
 238 .I Left Arrow Key, Control-b
 239 Moves the cursor back one character.
 240 .TP
 241 .I Right Arrow Key, Control-f
 242 Moves the cursor forward one character.
 243 .TP
 244 .I Up Arrow Key, Control-p
 245 Goes back in the history, replaces the current line with the previous
 246 line in the history.
 247 .TP
 248 .I Down Arrow Key, Control-n
 249 Moves forward in the history, replaces the current line with the next
 250 lien in the history.
 251 .TP
 252 .I Return
 253 Executes the current line if the statement or expression is complete,
 254 or waits for further input.
 255 .TP
 256 .I Control-C
 257 Cancel the current line being edited.  This will kill any currently
 258 in-progress edits or partial editing and go back to a toplevel
 259 definition.
 260 .TP
 261 .I Backspace Key
 262 Deletes the character before the cursor
 263 .TP
 264 .I Delete Key, Control-d
 265 Deletes the character at the current cursor position.
 266 .TP
 267 .I Control-k
 268 Erases the contents of the line until the end of the line and places
 269 the result in the cut and paste buffer.
 270 .TP
 271 .I Alt-D
 272 Deletes the word starting at the cursor position and appends into the
 273 cut and paste buffer.    By pressing Alt-d repeatedly, multiple words
 274 can be appended into the paste buffer.
 275 .TP
 276 .I Control-Y
 277 Pastes the content of the kill buffer at the current cursor position.
 278 .TP
 279 .I Control-Q
 280 This is the quote character.   It allows the user to enter
 281 control-characters that are otherwise taken by the command editing
 282 facility.   Press Control-Q followed by the character you want to
 283 insert, and it will be inserted verbatim into the command line.
 284 .TP
 285 .I Control-D
 286 Terminates the program.   This terminates the input for the program.
 287 .SH STATIC PROPERTIES AND METHODS
 288 Since the methods and properties of the base class from where the
 289 statements and expressions are executed are static, they can be
 290 invoked directly from the shell.   These are the available properties
 291 and methods:
 292 .TP
 293 .I void LoadAssembly(string assembly)
 294 Loads the given assembly.   This is equivalent to passing the compiler
 295 the -r: flag with the specified string.
 296 .TP
 297 .I void LoadPackage(string package)
 298 Imports the package specified.   This is equivalent to invoking the
 299 compiler with the -pkg: flag with the specified string.
 300 .TP
 301 .I string Prompt { get; set }
 302 The prompt used by the shell.  It defaults to the value "csharp> ".
 303 .I string ContinuationPrompt { get; set; }
 304 The prompt used by the shell when further input is required to
 305 complete the expression or statement.
 306 .TP
 307 .I void ShowVars()
 308 Displays all the variables that have been defined so far and their
 309 types.    In the csharp shell declaring new variables will shadow
 310 previous variable declarations, this is different than C# when
 311 compiled.
 312 .I void ShowUsing()
 313 Displays all the using statements in effect.
 314 .I TimeSpan Time (Action a)
 315 Handy routine to time the time that some code takes to execute.   The
 316 parameter is an Action delegate, and the return value is a TimeSpan.
 317 For example:
 318 .PP
 319 .nf
 320 csharp> Time (() => { for (int i = 0; i < 5; i++) Console.WriteLine (i);});
 321 0
 322 1
 323 2
 324 3
 325 4
 326 00:00:00.0043230
 327 csharp>
 328 .fi
 329 .PP
 330 The return value is a TimeSpan, that you can store in a variable for
 331 benchmarking purposes.
 332 .SH GUI METHODS AND PROPERTIES
 333 In addition to the methods and properties available in the console
 334 version there are a handful of extra properties available on the GUI
 335 version.   For example a "PaneContainer" Gtk.Container is exposed that
 336 you can use to host Gtk# widgets while prototyping or the "MainWindow"
 337 property that gives you access to the current toplevel window.
 338 .SH STARTUP FILES
 339 The C# shell will load all the Mono assemblies and C# script files
 340 located in the ~/.config/csharp directory on Unix.  The assemblies are
 341 loaded before the source files are loaded.
 342 .PP
 343 C# script files are files
 344 that have the extension .cs and they should only contain statements
 345 and expressions, they can not contain full class definitions (at least
 346 not as of Mono 2.0).  Full class definitions should be compiled into
 347 dlls and stored in that directory.
 348 .SH AUTHORS
 349 The Mono C# Compiler was written by Miguel de Icaza, Ravi Pratap,
 350 Martin Baulig, Marek Safar and Raja Harinath.  The development was
 351 funded by Ximian, Novell and Marek Safar.
 352 .SH LICENSE
 353 The Mono Compiler Suite is released under the terms of the GNU GPL or
 354 the MIT X11.  Please read the accompanying `COPYING' file for details.
 355 Alternative licensing for the compiler is available from Novell.
 356 .SH SEE ALSO
 357 gmcs(1), mcs(1), mdb(1), mono(1), pkg-config(1)
 358 .SH BUGS
 359 To report bugs in the compiler, you must file them on our bug tracking
 360 system, at:
 361 http://www.mono-project.com/Bugs
 362 .SH MAILING LIST
 363 The Mono Mailing lists are listed at http://www.mono-project.com/Mailing_Lists
 364 .SH MORE INFORMATION
 365 The Mono C# compiler was developed by Novell, Inc
 366 (http://www.novell.com, http) and is based on the
 367 ECMA C# language standard available here:
 368 http://www.ecma.ch/ecma1/STAND/ecma-334.htm
 369 .PP
 370 The home page for the Mono C# compiler is at
 371 http://www.mono-project.com/CSharp_Compiler  information about the
 372 interactive mode for C# is available in http://mono-project.com/CsharpRepl