mcs/class/Mono.Options/Documentation/en/Mono.Options/Command.xml

   1 <Type Name="Command" FullName="Mono.Options.Command">
   2   <TypeSignature Language="C#" Value="public class Command" />
   3   <TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit Command extends System.Object" />
   4   <AssemblyInfo>
   5     <AssemblyName>Mono.Options</AssemblyName>
   6     <AssemblyVersion>0.2.3.0</AssemblyVersion>
   7   </AssemblyInfo>
   8   <ThreadingSafetyStatement>
   9     Public <c>static</c> members of this type are thread safe.
  10     Any instance members are not guaranteed to be thread safe.
  11   </ThreadingSafetyStatement>
  12   <Base>
  13     <BaseTypeName>System.Object</BaseTypeName>
  14   </Base>
  15   <Interfaces />
  16   <Docs>
  17     <summary>
  18       Represents a program command.
  19     </summary>
  20     <remarks>
  21       <para>
  22         Many command-line utilities are <i>suites</i> of commands, with a single
  23         "outer" command and multiple commands. Examples of this style of
  24         utility includes <b>git</b>, <b>svn</b>, and <b>mdoc</b>.
  25       </para>
  26       <para>
  27         A <c>Command</c> represents a specific command in such a suite.
  28         It has a <see cref="P:Mono.Options.Command.Name" /> which is the
  29         command name for invocation purposes, optional help text through
  30         the <see cref="P:Mono.Options.Command.Help" /> property, an optional
  31         <see cref="T:Mono.Options.OptionSet" /> accessible through the
  32         <see cref="P:Mono.Options.Command.Options" /> property for command-line
  33         parsing, and two ways to have code executed when a command is
  34         invoked: the <see cref="P:Mono.Options.Command.Run" /> property and
  35         the <see cref="M:Mono.Options.Command.Invoke" /> method.
  36       </para>
  37     </remarks>
  38   </Docs>
  39   <Members>
  40     <Member MemberName=".ctor">
  41       <MemberSignature Language="C#" Value="public Command (string name, string help = null);" />
  42       <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string name, string help) cil managed" />
  43       <MemberType>Constructor</MemberType>
  44       <AssemblyInfo>
  45         <AssemblyVersion>0.2.3.0</AssemblyVersion>
  46       </AssemblyInfo>
  47       <Parameters>
  48         <Parameter Name="name" Type="System.String" />
  49         <Parameter Name="help" Type="System.String" />
  50       </Parameters>
  51       <Docs>
  52         <param name="name">
  53           A <see cref="T:System.String" /> which is the command name.
  54         </param>
  55         <param name="help">
  56           A <see cref="T:System.String" /> which is the command help text.
  57         </param>
  58         <summary>
  59           Creates and initializes a new instance of the <c>Command</c> class.
  60         </summary>
  61         <remarks>
  62           <para>
  63           This constructor initializes the
  64           <see cref="P:Mono.Options.Command.Name" /> property of the new
  65           instance using <paramref name="name" /> and initializes the
  66           <see cref="P:Mono.Options.Command.Help" /> property of the new
  67           instance using <paramref name="help" />.
  68         </para>
  69         </remarks>
  70         <exception cref="T:System.ArgumentNullException">
  71           <paramref name="name" /> is <see langword="null" />.
  72         </exception>
  73       </Docs>
  74     </Member>
  75     <Member MemberName="CommandSet">
  76       <MemberSignature Language="C#" Value="public Mono.Options.CommandSet CommandSet { get; }" />
  77       <MemberSignature Language="ILAsm" Value=".property instance class Mono.Options.CommandSet CommandSet" />
  78       <MemberType>Property</MemberType>
  79       <AssemblyInfo>
  80         <AssemblyVersion>0.2.3.0</AssemblyVersion>
  81       </AssemblyInfo>
  82       <ReturnValue>
  83         <ReturnType>Mono.Options.CommandSet</ReturnType>
  84       </ReturnValue>
  85       <Docs>
  86         <summary>
  87           A <see cref="T:Mono.Options.CommandSet" /> instance which owns the
  88           <c>Command</c>.
  89         </summary>
  90         <value>
  91           A <see cref="T:Mono.Options.CommandSet" /> instance which owns the
  92           <c>Command</c>.
  93         </value>
  94         <remarks>
  95           <para>
  96             A <c>Command</c> instance may belong to only one
  97             <see cref="T:Mono.Options.CommandSet" /> instance.
  98             The <c>CommandSet</c> property is set upon calling
  99             <see cref="M:Mono.Options.CommandSet.Add(Mono.Options.Command)" />.
 100           </para>
 101           <para>
 102             If the <c>Command</c> instance has not yet been added to a
 103             <c>CommandSet</c>, then this property is <see langword="null" />.
 104           </para>
 105           <para>
 106             Use the <c>CommandSet</c> instance from either the
 107             <see cref="P:Mono.Options.Command.Run" /> property or an overridden
 108             <see cref="M:Mono.Options.Command.Invoke" /> method to access
 109             localization facilities through
 110             <see cref="P:Mono.Options.CommandSet.MessageLocalizer" />, the
 111             preferred message output stream through
 112             <see cref="P:Mono.Options.CommandSet.Out" />, and other features.
 113           </para>
 114         </remarks>
 115       </Docs>
 116     </Member>
 117     <Member MemberName="Help">
 118       <MemberSignature Language="C#" Value="public string Help { get; }" />
 119       <MemberSignature Language="ILAsm" Value=".property instance string Help" />
 120       <MemberType>Property</MemberType>
 121       <AssemblyInfo>
 122         <AssemblyVersion>0.2.3.0</AssemblyVersion>
 123       </AssemblyInfo>
 124       <ReturnValue>
 125         <ReturnType>System.String</ReturnType>
 126       </ReturnValue>
 127       <Docs>
 128         <summary>
 129           A short, one-line, description of the <c>Command</c>.
 130         </summary>
 131         <value>
 132           A <see cref="T:System.String" /> containing the optional help text
 133           of the <c>Command</c>.
 134         </value>
 135         <remarks>
 136           <para>
 137             The <c>Help</c> property text is shown when the <c>help</c>
 138             command is invoked.
 139           </para>
 140         </remarks>
 141       </Docs>
 142     </Member>
 143     <Member MemberName="Invoke">
 144       <MemberSignature Language="C#" Value="public virtual int Invoke (System.Collections.Generic.IEnumerable&lt;string&gt; arguments);" />
 145       <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance int32 Invoke(class System.Collections.Generic.IEnumerable`1&lt;string&gt; arguments) cil managed" />
 146       <MemberType>Method</MemberType>
 147       <AssemblyInfo>
 148         <AssemblyVersion>0.2.3.0</AssemblyVersion>
 149       </AssemblyInfo>
 150       <ReturnValue>
 151         <ReturnType>System.Int32</ReturnType>
 152       </ReturnValue>
 153       <Parameters>
 154         <Parameter Name="arguments" Type="System.Collections.Generic.IEnumerable&lt;System.String&gt;" />
 155       </Parameters>
 156       <Docs>
 157         <param name="arguments">
 158           A <see cref="T:System.Collections.Generic.IEnumerable{System.String}" />
 159           which contains the unprocessed command-line arguments.
 160         </param>
 161         <summary>
 162           Invoked by <see cref="M:Mono.Options.CommandSet.Run" /> when a command
 163           has been executed.
 164         </summary>
 165         <returns>
 166           A <see cref="T:System.Int32" /> which should be treated as the process
 167           exit value.
 168         </returns>
 169         <remarks>
 170           <para>
 171             The value returned by <c>Invoke()</c> is the return value of
 172             <see cref="M:Mono.Options.CommandSet.Run" />, and should be treated
 173             as a possible process exit value.
 174           </para>
 175           <block subset="none" type="behaviors">
 176             <para>
 177               If the <c>Invoke()</c> method is not overridden by a subclass,
 178               the <c>Invoke()</c> method will use
 179               <see cref="P:Mono.Options.Command.Options" /> to parse
 180               <paramref name="arguments" />, and pass any un-processed values
 181               on to <see cref="P:Mono.Options.Command.Run" />.
 182             </para>
 183             <para>
 184               If the <c>Options</c> property is <see langword="null" />, then no
 185               option processing will occur, and <paramref name="arguments" />
 186               will be provided to the <c>Run</c> property as-is.
 187             </para>
 188             <para>
 189               If the <c>Run</c> property is <see langword="null" />, then
 190               no further processing occurs.
 191             </para>
 192           </block>
 193           <block subset="none" type="overrides">
 194             <para>
 195               Method overrides do not need to call the base class method.
 196             </para>
 197           </block>
 198         </remarks>
 199       </Docs>
 200     </Member>
 201     <Member MemberName="Name">
 202       <MemberSignature Language="C#" Value="public string Name { get; }" />
 203       <MemberSignature Language="ILAsm" Value=".property instance string Name" />
 204       <MemberType>Property</MemberType>
 205       <AssemblyInfo>
 206         <AssemblyVersion>0.2.3.0</AssemblyVersion>
 207       </AssemblyInfo>
 208       <ReturnValue>
 209         <ReturnType>System.String</ReturnType>
 210       </ReturnValue>
 211       <Docs>
 212         <summary>
 213           The name of the <c>Command</c>, which is used for command invocation.
 214         </summary>
 215         <value>
 216           A <see cref="T:System.String" /> which is the name of the <c>Command</c>.
 217         </value>
 218         <remarks>
 219           <para>
 220             The <c>Name</c> value must be unique across all <c>Commmand</c> instances
 221             referred to by a <see cref="T:Mono.Options.CommandSet" />.
 222           </para>
 223         </remarks>
 224       </Docs>
 225     </Member>
 226     <Member MemberName="Options">
 227       <MemberSignature Language="C#" Value="public Mono.Options.OptionSet Options { get; set; }" />
 228       <MemberSignature Language="ILAsm" Value=".property instance class Mono.Options.OptionSet Options" />
 229       <MemberType>Property</MemberType>
 230       <AssemblyInfo>
 231         <AssemblyVersion>0.2.3.0</AssemblyVersion>
 232       </AssemblyInfo>
 233       <ReturnValue>
 234         <ReturnType>Mono.Options.OptionSet</ReturnType>
 235       </ReturnValue>
 236       <Docs>
 237         <summary>
 238           Optional command-line option information.
 239         </summary>
 240         <value>
 241           A <see cref="T:Mono.Options.OptionSet" /> instance which contains the
 242           available command-line options for the <c>Command</c>.
 243         </value>
 244         <remarks>
 245           <para>
 246             If the <c>Options</c> property is not <see langword="null" /> when
 247             the command is processed,
 248             <see cref="M:Mono.Options.OptionSet.Parse" /> will be invoked on
 249             the <c>Options</c> instance, and the return value of
 250             <c>OptionSet.Parse()</c> will be forwarded to
 251             <see cref="M:Mono.Options.Command.Invoke" />.
 252           </para>
 253         </remarks>
 254       </Docs>
 255     </Member>
 256     <Member MemberName="Run">
 257       <MemberSignature Language="C#" Value="public Action&lt;System.Collections.Generic.IEnumerable&lt;string&gt;&gt; Run { get; set; }" />
 258       <MemberSignature Language="ILAsm" Value=".property instance class System.Action`1&lt;class System.Collections.Generic.IEnumerable`1&lt;string&gt;&gt; Run" />
 259       <MemberType>Property</MemberType>
 260       <AssemblyInfo>
 261         <AssemblyVersion>0.2.3.0</AssemblyVersion>
 262       </AssemblyInfo>
 263       <ReturnValue>
 264         <ReturnType>System.Action&lt;System.Collections.Generic.IEnumerable&lt;System.String&gt;&gt;</ReturnType>
 265       </ReturnValue>
 266       <Docs>
 267         <summary>
 268           Optional command handler.
 269         </summary>
 270         <value>
 271           A <see cref="T:System.Action{System.Collections.Generic.IEnumerable{System.String}}" />
 272           delegate which is executed by
 273           <see cref="M:Mono.Options.Command.Invoke" />.
 274         </value>
 275         <remarks>
 276           <para>
 277             The <c>Run</c> property is executed by the the
 278             <see cref="M:Mono.Options.Command.Invoke" /> method when
 279             <see cref="M:Mono.Options.CommandSet.Run" /> dispatches to a
 280             <c>Command</c> instance.
 281           </para>
 282         </remarks>
 283       </Docs>
 284     </Member>
 285   </Members>
 286 </Type>