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

   1 <Type Name="ArgumentSource" FullName="Mono.Options.ArgumentSource">
   2   <TypeSignature Language="C#" Value="public abstract class ArgumentSource" />
   3   <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract beforefieldinit ArgumentSource extends System.Object" />
   4   <AssemblyInfo>
   5     <AssemblyName>Mono.Options</AssemblyName>
   6     <AssemblyVersion>0.2.2.0</AssemblyVersion>
   7   </AssemblyInfo>
   8   <Base>
   9     <BaseTypeName>System.Object</BaseTypeName>
  10   </Base>
  11   <Interfaces />
  12   <Docs>
  13     <summary>
  14       Support for inserting additional arguments during
  15       <see cref="M:Mono.Options.OptionSet.Parse(System.Collections.Generic.IEnumerable{System.String})" />
  16       processing.
  17     </summary>
  18     <remarks>
  19       <para>
  20         The <see cref="T:Mono.Options.ArgumentSource" /> type is an
  21         abstraction to allow "insertion" of additional values for option
  22         processing while processing arguments.
  23       </para>
  24       <para>
  25         The principal use case is for <i>response files</i>, as used by
  26         <c>CSC.EXE</c>, <c>CL.EXE</c>, and numerous other
  27         compilers.  A response file contains additional options for the tool,
  28         and the contents of the response file should be "inserted" as if
  29         entered on the command line.  Response files are useful for bypassing
  30         command-line length limitations, among other things.
  31       </para>
  32       <para>
  33         Applications must opt-in to response file support by calling
  34         <see cref="M:Mono.Options.OptionSet.Add(Mono.Options.ArgumentSource)" />
  35         before calling
  36         <see cref="M:Mono.Options.OptionSet.Parse(System.Collections.Generic.IEnumerable{System.String})" />.
  37       </para>
  38       <block subset="none" type="overrides">
  39         Inheriting classes must override the following abstract methods:
  40         <list type="bullet"><item><term><see cref="M:Mono.Options.ArgumentSource.GetNames" /></term></item><item><term><see cref="P:Mono.Options.ArgumentSource.Description" /></term></item><item><term><see cref="M:Mono.Options.ArgumentSource.GetArguments(System.Int32, System.Collections.Generic.IEnumerable{System.String}@)" /></term></item></list></block>
  41     </remarks>
  42     <altmember cref="T:Mono.Options.ResponseFileSource" />
  43   </Docs>
  44   <Members>
  45     <Member MemberName=".ctor">
  46       <MemberSignature Language="C#" Value="protected ArgumentSource ();" />
  47       <MemberSignature Language="ILAsm" Value=".method familyhidebysig specialname rtspecialname instance void .ctor() cil managed" />
  48       <MemberType>Constructor</MemberType>
  49       <AssemblyInfo>
  50         <AssemblyVersion>0.2.2.0</AssemblyVersion>
  51       </AssemblyInfo>
  52       <Parameters />
  53       <Docs>
  54         <summary>
  55           Construct and initialize a
  56           <see cref="T:Mono.Options.ArgumentSource" /> instance.
  57         </summary>
  58         <remarks>
  59         </remarks>
  60       </Docs>
  61     </Member>
  62     <Member MemberName="Description">
  63       <MemberSignature Language="C#" Value="public abstract string Description { get; }" />
  64       <MemberSignature Language="ILAsm" Value=".property instance string Description" />
  65       <MemberType>Property</MemberType>
  66       <AssemblyInfo>
  67         <AssemblyVersion>0.2.2.0</AssemblyVersion>
  68       </AssemblyInfo>
  69       <ReturnValue>
  70         <ReturnType>System.String</ReturnType>
  71       </ReturnValue>
  72       <Docs>
  73         <summary>
  74           The description to provide for the argument source within
  75           <see cref="M:Mono.Options.OptionSet.WriteOptionDescriptions(System.IO.TextWriter)" />.
  76         </summary>
  77         <value>
  78           A <see cref="T:System.String" /> containing
  79           the description to provide for the argument source within
  80           <see cref="M:Mono.Options.OptionSet.WriteOptionDescriptions(System.IO.TextWriter)" />.
  81         </value>
  82         <remarks>
  83         </remarks>
  84       </Docs>
  85     </Member>
  86     <Member MemberName="GetArguments">
  87       <MemberSignature Language="C#" Value="public static System.Collections.Generic.IEnumerable&lt;string&gt; GetArguments (System.IO.TextReader reader);" />
  88       <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Collections.Generic.IEnumerable`1&lt;string&gt; GetArguments(class System.IO.TextReader reader) cil managed" />
  89       <MemberType>Method</MemberType>
  90       <AssemblyInfo>
  91         <AssemblyVersion>0.2.2.0</AssemblyVersion>
  92       </AssemblyInfo>
  93       <ReturnValue>
  94         <ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
  95       </ReturnValue>
  96       <Parameters>
  97         <Parameter Name="reader" Type="System.IO.TextReader" />
  98       </Parameters>
  99       <Docs>
 100         <param name="reader">
 101           A <see cref="T:System.IO.TextReader" /> to extract arguments from.
 102         </param>
 103         <summary>
 104           Extract arguments from a <see cref="T:System.IO.TextReader" />.
 105         </summary>
 106         <returns>
 107           A <see cref="T:System.Collections.Generic.IEnumerable{System.String}" />
 108           which will provide arguments extracted from <paramref name="reader" />.
 109         </returns>
 110         <remarks>
 111           <para>
 112             Arguments are extracted from <paramref name="reader" /> by
 113             splitting on newlines and spaces but maintaining the contents of
 114             single-quoted and double-quoted strings.  Thus, <c>A B</c> will be
 115             split as the separate strings <c>"A", "B"</c>, while
 116             <c>"A B"</c> will be returned as-is.
 117           </para>
 118           <block subset="none" type="note">
 119             <paramref name="reader" /> is not
 120             <see cref="M:System.IO&gt;TextReader.Close" />d.
 121           </block>
 122         </remarks>
 123       </Docs>
 124     </Member>
 125     <Member MemberName="GetArguments">
 126       <MemberSignature Language="C#" Value="public abstract bool GetArguments (string value, out System.Collections.Generic.IEnumerable&lt;string&gt; replacement);" />
 127       <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance bool GetArguments(string value, class System.Collections.Generic.IEnumerable`1&lt;string&gt; replacement) cil managed" />
 128       <MemberType>Method</MemberType>
 129       <AssemblyInfo>
 130         <AssemblyVersion>0.2.2.0</AssemblyVersion>
 131       </AssemblyInfo>
 132       <ReturnValue>
 133         <ReturnType>System.Boolean</ReturnType>
 134       </ReturnValue>
 135       <Parameters>
 136         <Parameter Name="value" Type="System.String" />
 137         <Parameter Name="replacement" Type="System.Collections.Generic.IEnumerable&lt;System.String&gt;&amp;" RefType="out" />
 138       </Parameters>
 139       <Docs>
 140         <param name="value">
 141           A <see cref="T:System.String" /> containing the argument to replace
 142           with additional arguments.
 143         </param>
 144         <param name="replacement">
 145           A <see cref="T:System.Collections.Generic.IEnumerable{System.String}" />
 146           which will refer to teh replacement arguments if this method returns
 147           <see langword="true" />; otherwise, this value should be ignored by
 148           callers.
 149         </param>
 150         <summary>
 151           Replace the argument <paramref name="value" /> with a set of
 152           replacement arguments.
 153         </summary>
 154         <returns>
 155           <see langword="true" /> if this
 156           <see cref="T:Mono.Options.ArgumentSource" /> will replace
 157           <paramref name="value" /> with a set of replacement strings and
 158           <paramref name="replacement" /> contains the replacement strings;
 159           otherwise, <see langword="false" />.
 160         </returns>
 161         <remarks>
 162           <para>
 163             Before
 164             <see cref="M:Mono.Options.OptionSet.Parse(System.Collections.Generic.IEnumerable{System.String})" />
 165             attempts to parse an argument as an option (or option value), all
 166             registered <see cref="T:Mono.Options.OptionSet.ArgumentSources" />
 167             are consulted in registration order to see if
 168             <see cref="T:Mono.Options.ArgumentSource" /> "supports" the
 169             argument via
 170             <see cref="M:Mono.Options.ArgumentSource.GetArguments(System.Int32, System.Collections.Generic.IEnumerable{System.String}@)" />.
 171             The first <c>ArgumentSource</c> to return <see langword="true" />
 172             from <c>GetArguments()</c> may provide the replacement tokens, and
 173             no later <c>ArgumentSource</c>es are consulted.
 174           </para>
 175         </remarks>
 176         <altmember cref="M:Mono.Options.OptionSet.Parse(System.Collections.Generic.IEnumerable{System.String})" />
 177       </Docs>
 178     </Member>
 179     <Member MemberName="GetArgumentsFromFile">
 180       <MemberSignature Language="C#" Value="public static System.Collections.Generic.IEnumerable&lt;string&gt; GetArgumentsFromFile (string file);" />
 181       <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Collections.Generic.IEnumerable`1&lt;string&gt; GetArgumentsFromFile(string file) cil managed" />
 182       <MemberType>Method</MemberType>
 183       <AssemblyInfo>
 184         <AssemblyVersion>0.2.2.0</AssemblyVersion>
 185       </AssemblyInfo>
 186       <ReturnValue>
 187         <ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
 188       </ReturnValue>
 189       <Parameters>
 190         <Parameter Name="file" Type="System.String" />
 191       </Parameters>
 192       <Docs>
 193         <param name="file">
 194           A <see cref="T:System.String" /> containing the file to extract
 195           arguments from.
 196         </param>
 197         <summary>
 198           Extract arguments from the specified filename.
 199         </summary>
 200         <returns>
 201           A <see cref="T:System.Collections.Generic.IEnumerable{System.String}" />
 202           which will provide arguments extracted from <paramref name="file" />.
 203         </returns>
 204         <remarks>
 205         </remarks>
 206         <exception cref="T:System.IO.IOException">
 207           <paramref name="file" /> could not be read.
 208         </exception>
 209         <altmember cref="M:Mono.Options.ArgumentSource.GetArguments(System.IO.TextReader)" />
 210       </Docs>
 211     </Member>
 212     <Member MemberName="GetNames">
 213       <MemberSignature Language="C#" Value="public abstract string[] GetNames ();" />
 214       <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance string[] GetNames() cil managed" />
 215       <MemberType>Method</MemberType>
 216       <AssemblyInfo>
 217         <AssemblyVersion>0.2.2.0</AssemblyVersion>
 218       </AssemblyInfo>
 219       <ReturnValue>
 220         <ReturnType>System.String[]</ReturnType>
 221       </ReturnValue>
 222       <Parameters />
 223       <Docs>
 224         <summary>
 225           The names to provide for the argument source within
 226           <see cref="M:Mono.Options.OptionSet.WriteOptionDescriptions(System.IO.TextWriter)" />.
 227         </summary>
 228         <returns>
 229           A <see cref="T:System.String" /> array containing
 230           the names to provide for the argument source within
 231           <see cref="M:Mono.Options.OptionSet.WriteOptionDescriptions(System.IO.TextWriter)" />.
 232         </returns>
 233         <remarks>
 234         </remarks>
 235       </Docs>
 236     </Member>
 237   </Members>
 238 </Type>