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