C# Script execution engine. Version 3.27.5.0.
Copyright (C) 2004-2017 Oleg Shilo.

Usage: cscs <switch 1> <switch 2> <file> [params] [//x]

<switch 1>

--help|-help|-? [command]
    Displays either generic or command specific help info.
    Reversed order of parameters for the command specific help is also acceptable. The all following argument combinations print the same help topic
    for 'cache' command:
       -help cache
       -? cache
       -cache help
       -cache ?

-e
    Compiles script into console application executable.

-ew
    Compiles script into Windows application executable.

-c[:<0|1>]
    Uses compiled file (cache file .compiled) if found (to improve performance).
       -c:1|-c  enable caching
       -c:0     disable caching (which might be enabled globally);

-ca
    Compiles script file into assembly (cache file .compiled) without execution.

-cd
    Compiles script file into assembly (.dll) without execution.

-check
    Checks script for errors without execution.

-proj
    Shows script 'project info' - script and all its dependencies.

-cache[:<ls|trim|clear>]
    Performs script cache operations.
     ls    - lists all cache items.
     trim  - removes all abandoned cache items.
     clear - removes all cache items.

-co:<options>
    Passes compiler options directly to the language compiler.
    (e.g.  -co:/d:TRACE pass /d:TRACE option to C# compiler
    or  -co:/platform:x86 to produce Win32 executable)

-s|-sample[:<C# version>]
    Prints content of sample script file.
     -s:7    - prints C# 7 sample. Otherwise it prints the default canonical 'Hello World' sample.
    (e.g. cscs -s:7 > sample.cs).

-wait[:prompt]
    Waits for user input after the execution before exiting.
    If specified the execution will proceed with exit only after any std input is received.
    Applicable for console mode only.
    prompt - if none specified 'Press any key to continue...' will be used

-ac|-autoclass[:<0|1|2|out>]
    
     -ac     - enables auto-class decoration (which might be disabled globally).
     -ac:0   - disables auto-class decoration (which might be enabled globally).
     -ac:1   - same as '-ac'
     -ac:2   - same as '-ac:1' and '-ac'
     -ac:out - prints auto-class decoration for a given script file. The argument must be followed by the path to script file.
     
    Automatically generates 'static entry point' class if the script doesn't define any.
     
        using System;
     
        void Main()
        {
            Console.WriteLine("Hello World!";
        }
     
    Using an alternative 'instance entry point' is even more convenient (and reliable).
    The acceptable 'instance entry point' signatures are:
     
        void main()
        void main(string[] args)
        int main()
        int main(string[] args)
     
    Note, having any active code above entry point is acceptable though it complicates the troubleshooting if such a code contains errors. (see
    https://github.com/oleg-shilo/cs-script/wiki/CLI---User-Guide#command-auto-class)
     
    By default CS-Script decorates the script by adding a class declaration statement to the start of the script routine and a class closing bracket
    to the end. This may have an unintended effect as any class declared in the script becomes a 'nested class'. While it is acceptable for
    practically all use-cases it may be undesired for just a few scenarios. For example, any class containing method extensions must be a top level
    static class, what conflicts with the auto-class decoration algorithm.
     
    The solution to this problem is to allow some user code to be protected from being included into the decorated code.
    User can achieve this by placing '//css_ac_end' statement into the code. Any user code below this statement will be excluded from the decoration
    and stay unchanged.

---------
<switch 2>

-dbg|-d
    Forces compiler to include debug information.

-l
    'local' (makes the script directory a 'current directory').

-v|-ver|--version
    Prints CS-Script version information.

-inmem[:<0|1>]
    Loads compiled script in memory before execution.
    This mode allows preventing locking the compiled script file. Can be beneficial for fine concurrency control as it allows changing and executing
    the scripts that are already loaded (being executed). This mode is incompatible with the scripting scenarios that require script assembly to be
    file based (e.g. advanced Reflection).
     -inmem:1   enable caching (which might be disabled globally);
     -inmem:0   disable caching (which might be enabled globally);

-dbgprint[:<0:1>]
    Controls whether to enable Python-like print methods (e.g. dbg.print(DateTime.Now)).
    This setting allows controlling dynamic inclusion of the embedded dbg.cs script containing implementation of Python-like print methods
    `dbg.print` and derived extension methods object.print() and object.dup(). While `dbg.print` is extremely useful it can and lead to some
    referencing challenges when the script being executed is referencing assemblies compiled with `dbg.print` already included. The simplest way o
    solve this problem is disable the `dbg.cs` inclusion.
     -dbgprint:1   enable `dbg.cs` inclusion; Same as `-dbgprint`;
     -dbgprint:0   disable `dbg.cs` inclusion;

-verbose
    Prints runtime information during the script execution.
    (applicable for console clients only)

-stop
    Stops all running instances of Roslyn sever (VBCSCompiler.exe).
    (applicable for .NET/Windows only)

-tc
    Trace compiler input produced by CS-Script code provider CSSRoslynProvider.dll.
    It's useful when troubleshooting custom compilers (e.g. Roslyn on Linux).

-config[:<option>]
    Performs various CS-Script config operations
     -config:none               - ignores config file (uses default settings)
     -config:create             - creates config file with default settings
     -config:default            - prints default config file
     -config:<raw|xml>          - prints current config file content
     -config[:ls]               - lists/prints current config values
     -config:get:name           - prints current config value
     -config:set:name=value     - sets current config value
     -config:set:name=add:value - updates the current config value content by appending the specified value.
     -config:set:name=del:value - updates the current config value content by removing all occurrences of the specified value.
     -config:set:roslyn         - enables Roslyn integration via configuration (C#7 support)
     -config:<file>             - uses custom config file
     
    Note: The property name in -config:set and -config:set is case insensitive and can also contain '_' as a token separator that is ignored during
    property lookup.
    (e.g. cscs -config:none sample.cs
          cscs -config:default > css_VB.xml
          cscs -config:set:inmem=true
          cscs -config:set:DefaultArguments=add:-ac
          cscs -config:set:default_arguments=del:-ac
          cscs -config:c:\cs-script\css_VB.xml sample.vb)

-out[:<file>]
    Forces the script to be compiled into a specific location.
    Used only for very fine hosting tuning.
    (e.g. cscs -out:%temp%\%pid%\sample.dll sample.cs

-sconfig[:file]
    Uses script config file or custom config file as a .NET app.config.
    This option might be useful for running scripts, which usually cannot be executed without configuration file (e.g. WCF, Remoting).
    (e.g. if -sconfig is used the expected config file name is <script_name>.cs.config or <script_name>.exe.configif -sconfig:myApp.config is used
    the expected config file name is myApp.config)

-r:<assembly 1>,<assembly N>
    Uses explicitly referenced assembly.
    It is required only for rare cases when namespace cannot be resolved into assembly.
    (e.g. cscs /r:myLib.dll myScript.cs).

-dir:<directory 1>,<directory N>
    Adds path(s) to the assembly probing directory list.
    You can use a reserved word 'show' as a directory name to print the configured probing directories.
    (e.g. cscs -dir:C:\MyLibraries myScript.cs cscs -dir:-show).

-precompiler[:<file 1>,<file N>]
    Specifies custom precompiler. This can be either script or assembly file.
    Alias - pc[:<file 1>,<file N>]
    If no file(s) specified prints the code template for the custom precompiler. The spacial value 'print' has the same effect (e.g. cscs -pc:print).
    There is a special reserved word 'nodefault' to be used as a file name. It instructs script engine to prevent loading any built-in precompilers
    like the one for removing shebang before the execution.
    (see http://www.csscript.net/help/precompilers.html)

-pvdr|-provider:<file>
    Location of the alternative/custom code provider assembly.
    Alias - pvdr:<file>
    If set it forces script engine to use an alternative code compiler.
    C#7 support is implemented via Roslyn based provider: '-pvdr:CSSRoslynProvider.dll'.If the switch is not specified CSSRoslynProvider.dll file
    will be use as a code provider if it is found in the same folder where the script engine is. Automatic CSSRoslynProvider.dll loading can be
    disabled with special 'none' argument: -pvdr:none.
    (see http://www.csscript.net/help/non_cs_compilers.html)

-syntax
    Prints documentation for CS-Script specific C# syntax.

-commands|-cmd
    Prints list of supported commands (arguments).

---------
file
    Specifies name of a script file to be run.

params
    Specifies optional parameters for a script file to be run.

//x
    Launch debugger just before starting the script.



**************************************
Script specific syntax
**************************************
 
Engine directives:
------------------------------------
//css_include <file>;
 
Alias - //css_inc
file - name of a script file to be included at compile-time.
 
This directive is used to include one script into another one. It is a logical equivalent of '#include' in C++. This directive is a full but more
convenient equivalent of //css_import <file>, preserve_main;
 
If a relative file path is specified with a single-dot prefix it will be automatically converted into the absolute path with respect to the location
of the file containing the directive being resolved.
 
Note if you use wildcard in the imported script name (e.g. *_build.cs) the directive will only import from the first probing directory where the
matching file(s) is found. Be careful with the wide wildcard as '*.cs' as they may lead to unpredictable behavior. For example they may match
everything from the very first probing directory, which is typically a current directory. Using more specific wildcards is arguably more practical
(e.g. 'utils/*.cs', '*Helper.cs', './*.cs')
------------------------------------
//css_import <file>[, preserve_main][, rename_namespace(<oldName>, <newName>)];
 
Alias - //css_imp
There are also another two aliases //css_include and //css_inc. They are equivalents of //css_import <file>, preserve_main
If $this (or $this.name) is specified as part of <file> it will be replaced at execution time with the main script full name (or file name only).
 
file            - name of a script file to be imported at compile-time.
<preserve_main> - do not rename 'static Main'
oldName         - name of a namespace to be renamed during importing
newName         - new name of a namespace to be renamed during importing
 
This directive is used to inject one script into another at compile time. Thus code from one script can be exercised in another one.'Rename' clause
can appear in the directive multiple times.
------------------------------------
 
//css_nuget [-noref] [-force[:delay]] [-ver:<version>] [-ng:<nuget arguments>] package0[,package1]..[,packageN];
 
Downloads/Installs the NuGet package. It also automatically references the downloaded package assemblies.
Note: The directive switches need to be in the order as above.
 
By default the package is not downloaded again if it was already downloaded.
If no version is specified then the highest downloaded version (if any) will be used.
Referencing the downloaded packages can only handle simple dependency scenarios when all downloaded assemblies are to be referenced.
You should use '-noref' switch and reference assemblies manually for all other cases. For example multiple assemblies with the same file name that
target different CLRs (e.g. v3.5 vs v4.0) in the same package.
Switches:
 -noref         - switch for individual packages if automatic referencing isn't desired. 
                  You can use 'css_nuget' environment variable for further referencing package content (e.g. //css_dir %css_nuget%\WixSharp\**)
 -force[:delay] - switch to force individual packages downloading even when they were already downloaded.
                  You can optionally specify delay for the next forced downloading by number of seconds since last download.
                  '-force:3600' will delay it for one hour. This option is useful for preventing frequent download interruptions during active script
                  development.
 -ver:<version> - switch to download/reference a specific package version.
 -ng:<args>     - switch to pass NuGet arguments for every individual package.
 
Example: //css_nuget cs-script;
         //css_nuget -ver:4.1.2 NLog
         //css_nuget -ver:"4.1.1-rc1" -ng:"-Pre -NoCache" NLog
 
This directive will install CS-Script NuGet package.
(see http://www.csscript.net/help/script_nugets.html)
------------------------------------
//css_args arg0[,arg1]..[,argN];
 
Embedded script arguments. The both script and engine arguments are allowed except "/noconfig" engine command switch.
Example: //css_args -dbg, -inmem;
This directive will always force script engine to execute the script in debug mode.
Note: the arguments must be coma separated.
------------------------------------
//css_reference <file>;
 
Alias - //css_ref
file - name of the assembly file to be loaded at run-time.
This directive is used to reference assemblies required at run time.
The assembly must be in GAC, the same folder with the script file or in the 'Script Library' folders (see 'CS-Script settings').
------------------------------------
//css_precompiler <file 1>,<file 2>;
 
Alias - //css_pc
file - name of the script or assembly file implementing precompiler.
 
This directive is used to specify the CS-Script precompilers to be loaded and exercised against script at run time just before compiling it.
Precompilers are typically used to alter the script coder before the execution. Thus CS-Script uses built-in precompiler to decorate classless
scripts executed with -autoclass switch.
(see http://www.csscript.net/help/precompilers.html
------------------------------------
//css_searchdir <directory>;
 
Alias - //css_dir
directory - name of the directory to be used for script and assembly probing at run-time.
 
This directive is used to extend set of search directories (script and assembly probing).
The directory name can be a wildcard based expression.In such a case all directories matching the pattern will be this case all directories will be
probed.
The special case when the path ends with '**' is reserved to indicate 'sub directories' case. Examples:
    //css_dir packages\ServiceStack*.1.0.21\lib\net40
    //css_dir packages\**
------------------------------------
//css_resource <file>[, <out_file>];
 
Alias - //css_res
file     - name of the compiled resource file (.resources) to be used with the script.
           Alternatively it can be the name of the XML resource file (.resx) that will be compiled on-fly.
out_file - Optional name of the compiled resource file (.resources) to be generated form the .resx input.If not supplied then the compiled file will
           have the same name as the input file but the file extension '.resx' changed to '.resources'.
 
This directive is used to reference resource file for script.
 Example: //css_res Scripting.Form1.resources;
          //css_res Resources1.resx;
          //css_res Form1.resx, Scripting.Form1.resources;
------------------------------------
//css_co <options>;
 
options - options string.
 
This directive is used to pass compiler options string directly to the language specific CLR compiler.
 Example: //css_co /d:TRACE pass /d:TRACE option to C# compiler
          //css_co /platform:x86 to produce Win32 executable
------------------------------------
//css_ignore_namespace <namespace>;
 
Alias - //css_ignore_ns
namespace - name of the namespace. Use '*' to completely disable namespace resolution
 
This directive is used to prevent CS-Script from resolving the referenced namespace into assembly.
------------------------------------
//css_ac_end
 
This directive is only applicable for class-less scripts executed with '-autoclass' CLI argument. It's nothing else but a marker indicating the end
of the code that needs to be decorated as (wrapped into) an auto-class.
This directive allows achieving top level static classes in the class-less scripts, which is required for implementing extension methods.
 
 //css_args -acutoclass
 using System;
 
 void main()
 {
     ...
 }
 
 //css_ac_end
 
 static class Extensions
 {
     static public void Convert(this string text)
     {
         ...
     }
 }
------------------------------------
//css_prescript file([arg0][,arg1]..[,argN])[ignore];
//css_postscript file([arg0][,arg1]..[,argN])[ignore];
 
Aliases - //css_pre and //css_post
file    - script file (extension is optional)
arg0..N - script string arguments
ignore  - continue execution of the main script in case of error
 
These directives are used to execute secondary pre- and post-execution scripts.
If $this (or $this.name) is specified as arg0..N it will be replaced at execution time with the main script full name (or file name only).
You may find that in many cases precompilers (//css_pc and -pc) are a more powerful and flexible alternative to the pre-execution script.
------------------------------------
//css_host [-version:<CLR_Version>] [-platform:<CPU>]
 
CLR_Version - version of CLR the script should be execute on (e.g. //css_host /version:v3.5)
CPU - indicates which platforms the script should be run on: x86, Itanium, x64, or anycpu.
Sample: //css_host /version:v2.0 /platform:x86;
 
Note this directive only supported on Windows due to the fact that on Linux the x86/x64 hosting implemented via runtime launcher 'mono'.
 
These directive is used to execute script from a surrogate host process. The script engine application (cscs.exe or csws.exe) launches the script
execution as a separate process of the specified CLR version and CPU architecture.
------------------------------------
 
Note the script engine always sets the following environment variables:
 'pid'                     - host processId (e.g. Environment.GetEnvironmentVariable("pid")
 'CSScriptRuntime'         - script engine version
 'CSScriptRuntimeLocation' - script engine location
 'cscs_exe_dir'            - script engine directory
 'EntryScript'             - location of the entry script
 'EntryScriptAssembly'     - location of the compiled script assembly
 'location:<assm_hash>'    - location of the compiled script assembly.
 
This variable is particularly useful as it allows finding the compiled assembly file from the inside of the script code. Even when the script loaded
in-memory (InMemoryAssembly setting) but not from the original file. (e.g. var location = Environment.GetEnvironmentVariable("location:" +
Assembly.GetExecutingAssembly().GetHashCode()); 
 
Note that by default setting of 'location:<assm_hash>' is disabled. You can enable it by calling  'CSScript.EnableScriptLocationReflection = true'.
 
The following is the optional set of environment variables that the script engine uses to improve the user experience:
 
 'CSS_NUGET' 
      location of the NuGet packages scripts can load/reference
 
 'CSSCRIPT_DIR'
      script engine location. Used by the engine to locate dependencies (e.g. resgen.exe). Typically this variable is during the CS-Script
      installation.
 
 'CSSCRIPT_CONSOLE_ENCODING_OVERWRITE'
      script engine output encoding if the one from the css_confix.xml needs to be overwritten.
 
 'CSSCRIPT_INC'
      a system wide include directory for the all frequently used user scripts.
---------
During the script execution CS-Script always injects a little object inspector class 'dbg'. This class contains static printing methods that mimic
Python's 'print()'. It is particularly useful for object inspection in the absence of a proper debugger.
 
Examples:
  dbg.print("Now:", DateTime.Now)        - prints concatenated objects.
  dbg.print(DateTime.Now)                - prints object and values of its properties.
  dbg.printf("Now: {0}", DateTime.Now)   - formats and prints object and values of its fields and properties.
---------
 
Any directive has to be written as a single line in order to have no impact on compiling by CLI compliant compiler.It also must be placed before any
namespace or class declaration.
 
---------
Example:
 
 //css_include web_api_host.cs;
 //css_reference media_server.dll;
 //css_nuget Newtonsoft.Json;
 
 using System;
 using static dbg;
 
 class MediaServer
 {
     static void Main(string[] args)
     {
         print(args);
 
         WebApi.SimpleHost(args)
               .StartAsConosle("http://localhost:8080");
   }
 }
 
Or shorter form:
 
 //css_args -ac
 //css_inc web_api_host.cs
 //css_ref media_server.dll
 //css_nuget Newtonsoft.Json
 
 using System;
 
 void main(string[] args)
 {
     print(args);
 
     WebApi.SimpleHost(args)
           .StartAsConosle("http://localhost:8080");
 }
 
---------
 Project Website: https://github.com/oleg-shilo/cs-script