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