args

중요한

이 저장소는 https://github.com/dart-lang/core/tree/main/pkgs/args로 이동되었습니다.

원시 명령줄 인수를 옵션 및 값 집합으로 구문 분석합니다.

이 라이브러리는 GNU 및 POSIX 스타일 옵션을 지원하며 서버 측 앱과 클라이언트 측 앱 모두에서 작동합니다.

옵션 정의

먼저 ArgParser를 만듭니다.

 var parser = ArgParser();

그런 다음 addOption() 및 addFlag()를 사용하여 해당 파서에 대한 옵션 세트를 정의합니다. "name"이라는 옵션을 생성하는 최소한의 방법은 다음과 같습니다.

 parser.addOption('name');

옵션을 설정하거나 설정 해제만 할 수 있는 경우(문자열 값을 사용하는 것과 반대) 플래그를 사용하세요.

parser. addFlag ( 'name' );

플래그 옵션은 기본적으로 옵션을 무효화하기 위해 'no-' 접두사를 허용합니다. negatable 매개변수를 사용하여 'no-' 접두사를 비활성화할 수 있습니다.

parser. addFlag ( 'name' , negatable : false );

참고: 여기서부터 "옵션"은 일반 옵션과 플래그를 모두 의미합니다. 구별이 중요한 경우에는 "플래그가 아닌 옵션"을 사용합니다.

옵션에는 abbr 매개변수로 지정된 선택적 단일 문자 약어가 있을 수 있습니다.

parser. addOption ( 'mode' , abbr : 'm' );
parser. addFlag ( 'verbose' , abbr : 'v' );

옵션에는 defaultsTo 매개변수로 지정된 기본값이 있을 수도 있습니다. 인수가 옵션을 지정하지 않을 때 기본값이 사용됩니다.

parser. addOption ( 'mode' , defaultsTo : 'debug' );
parser. addFlag ( 'verbose' , defaultsTo : false );

플래그가 아닌 옵션의 기본값은 임의의 문자열일 수 있습니다. 플래그의 경우 bool 이어야 합니다.

플래그가 아닌 옵션의 유효성을 검사하려면 allowed 매개변수를 사용하여 허용된 값 집합을 제공하면 됩니다. 그렇게 하면 옵션 값이 허용된 세트에 없으면 파서는 ArgParserException 을 발생시킵니다. 다음은 허용되는 값을 지정하는 예입니다.

parser. addOption ( 'mode' , allowed : [ 'debug' , 'release' ]);

callback 매개변수를 사용하여 함수를 옵션과 연결할 수 있습니다. 나중에 구문 분석이 발생하면 콜백 함수가 옵션 값으로 호출됩니다.

parser. addOption ( 'mode' , callback : (mode) => print ( 'Got mode $ mode ' ));
parser. addFlag ( 'verbose' , callback : (verbose) {
  if (verbose) print ( 'Verbose' );
});

모든 옵션에 대한 콜백은 인수 집합이 구문 분석될 때마다 호출됩니다. 인수에 옵션이 제공되지 않으면 해당 콜백에 기본값이 전달되고 기본값이 설정되지 않은 경우 null .

옵션이 mandatory 이지만 제공되지 않은 경우 결과 객체는 검색 시 [ ArgumentError ][ArgumentError]를 발생시킵니다.

parser. addOption ( 'mode' , mandatory : true );

인수 구문 분석

몇 가지 옵션과 플래그를 사용하여 ArgParser를 설정한 후에는 일련의 인수와 함께 ArgParser.parse()를 호출하여 이를 사용합니다.

 var results = parser. parse ([ 'some' , 'command' , 'line' , 'args' ]);

이러한 인수는 일반적으로 main() 에 대한 인수에서 나옵니다. 예를 들어:

 main(List<String> args) {
  // ...
  var results = parser.parse(args);
}

그러나 모든 문자열 목록을 전달할 수 있습니다. 구문 parse() 메서드는 구문 분석된 옵션의 값을 포함하는 맵과 유사한 객체인 ArgResults의 인스턴스를 반환합니다.

 var parser = ArgParser ();
parser. addOption ( 'mode' );
parser. addFlag ( 'verbose' , defaultsTo : true );
var results = parser. parse ([ '--mode' , 'debug' , 'something' , 'else' ]);

print (results. option ( 'mode' )); // debug
print (results. flag ( 'verbose' )); // true

기본적으로, parse() 메소드는 -- 모든 추가 매개변수가 위치 매개변수라는 것을 나타내기 위해 사용되지 않는 한 위치 매개변수 뒤에 추가 플래그와 옵션이 전달되는 것을 허용합니다. 위치 인수는 ArgResults.rest로 이동됩니다.

 print (results.rest); // ['something', 'else']

위치 인수가 발견되는 즉시 옵션 구문 분석을 중지하려면 ArgParser를 생성할 때 allowTrailingOptions: false 사용하세요.

옵션 지정

실제로 명령줄에서 옵션과 플래그를 전달하려면 GNU 또는 POSIX 스타일을 사용하세요. 다음 옵션을 고려하십시오.

parser. addOption ( 'name' , abbr : 'n' );

다음 중 하나를 사용하여 명령줄에서 해당 값을 지정할 수 있습니다.

 --name=somevalue
--name somevalue
-nsomevalue
-n somevalue

다음 플래그를 고려하세요.

parser. addFlag ( 'name' , abbr : 'n' );

다음 중 하나를 사용하여 이를 true로 설정할 수 있습니다.

 --name
-n

다음을 사용하여 false로 설정할 수 있습니다.

 --no-name

여러 플래그 약어를 단일 인수로 축소할 수 있습니다. 다음 플래그를 정의한다고 가정해 보겠습니다.

parser
  .. addFlag ( 'verbose' , abbr : 'v' )
  .. addFlag ( 'french' , abbr : 'f' )
  .. addFlag ( 'iambic-pentameter' , abbr : 'i' );

세 가지 플래그를 모두 한 번에 설정할 수 있습니다.

 -vfi

기본적으로 옵션에는 단일 값만 있으며 이후 옵션 값이 이전 값보다 우선합니다. 예를 들어:

 var parser = ArgParser ();
parser. addOption ( 'mode' );
var results = parser. parse ([ '--mode' , 'on' , '--mode' , 'off' ]);
print (results. option ( 'mode' )); // prints 'off'

addMultiOption() 사용하면 여러 값을 구문 분석할 수 있습니다. 이 메서드를 사용하면 옵션이 여러 번 발생할 수 있으며, parse() 메서드는 값 목록을 반환합니다.

 var parser = ArgParser ();
parser. addMultiOption ( 'mode' );
var results = parser. parse ([ '--mode' , 'on' , '--mode' , 'off' ]);
print (results. multiOption ( 'mode' )); // prints '[on, off]'

기본적으로 다중 값 옵션의 값은 쉼표로 구분될 수도 있습니다.

 var parser = ArgParser ();
parser. addMultiOption ( 'mode' );
var results = parser. parse ([ '--mode' , 'on,off' ]);
print (results. multiOption ( 'mode' )); // prints '[on, off]'

이는 splitCommas: false 전달하여 비활성화할 수 있습니다.

명령 정의

옵션 외에도 명령을 정의할 수도 있습니다. 명령은 고유한 옵션 세트가 있는 명명된 인수입니다. 예를 들어 다음 셸 명령을 고려해 보세요.

 $ git commit -a

실행 파일은 git 이고 명령은 commit 이며 -a 옵션은 명령에 전달되는 옵션입니다. addCommand 메소드를 사용하여 명령을 추가할 수 있습니다:

 var parser = ArgParser ();
var command = parser. addCommand ( 'commit' );

그러면 해당 명령과 관련된 옵션을 정의하는 데 사용할 수 있는 또 다른 ArgParser가 반환됩니다. 명령 옵션에 대한 ArgParser가 이미 있는 경우 이를 전달할 수 있습니다.

 var parser = ArgParser ();
var command = ArgParser ();
parser. addCommand ( 'commit' , command);

그러면 명령에 대한 ArgParser가 옵션이나 플래그를 정의할 수 있습니다.

command. addFlag ( 'all' , abbr : 'a' );

사용자가 가능한 명령 범위에서 하나를 선택할 수 있도록 동일한 파서에 여러 명령을 추가할 수 있습니다. 인수 목록을 구문 분석할 때 어떤 명령이 입력되었는지, 어떤 옵션이 제공되었는지 확인할 수 있습니다.

 var results = parser. parse ([ 'commit' , '-a' ]);
print (results.command.name);   // "commit"
print (results.command[ 'all' ]); // true

명령에 대한 옵션은 인수 목록에서 명령 뒤에 나타나야 합니다. 예를 들어, 위의 구문 분석기에서 "git -a commit" 유효 하지 않습니다 . 파서는 옵션을 허용하는 가장 오른쪽 명령을 찾으려고 시도합니다. 예를 들어:

 var parser = ArgParser ();
parser. addFlag ( 'all' , abbr : 'a' );
var command = parser. addCommand ( 'commit' );
command. addFlag ( 'all' , abbr : 'a' );

var results = parser. parse ([ 'commit' , '-a' ]);
print (results.command[ 'all' ]); // true

여기서 최상위 파서와 "commit" 명령은 모두 "-a" 를 허용할 수 있습니다(이는 아마도 잘못된 명령줄 인터페이스일 것입니다). 이 경우 " "commit" 뒤에 "-a" 가 나타나면 해당 명령에 적용됩니다. "commit" 왼쪽에 나타나면 최상위 파서에 전달됩니다.

명령 전달

명령 기반 애플리케이션을 작성하는 경우 CommandRunner 및 Command 클래스를 사용하여 애플리케이션을 구성할 수 있습니다. CommandRunner에는 명령줄 인수를 기반으로 명령을 디스패치하고 --help 플래그 및 유효하지 않은 인수를 처리하는 기능이 내장되어 있습니다.

CommandRunner를 사용하면 ArgParser가 대체됩니다.

다음 예에서는 commit 및 stash 명령을 사용하는 dgit 이라는 dart 애플리케이션을 구축합니다.

CommandRunner는 도움말 메시지를 생성하는 데 사용되는 executableName 사용합니다.

예: dgit commit -a

파일 dgit.dart

 void main ( List < String > args) {
  var runner = CommandRunner ( "dgit" , "A dart implementation of distributed version control." )
    .. addCommand ( CommitCommand ())
    .. addCommand ( StashCommand ())
    .. run (args);
}

위의 run(args) 줄이 실행되면 명령줄 args를 구문 분석하여 명령( commit 또는 stash ) 중 하나를 찾습니다.

CommandRunner가 일치하는 명령을 찾으면 CommandRunner는 일치하는 명령(예: CommitCommand().run)에 대해 재정의된 run() 메서드를 호출합니다.

명령은 Command 클래스를 확장하여 정의됩니다. 예를 들어:

 class CommitCommand extends Command {
  // The [name] and [description] properties must be defined by every
  // subclass.
  final name = "commit" ;
  final description = "Record changes to the repository." ;

  CommitCommand () {
    // we can add command specific arguments here.
    // [argParser] is automatically created by the parent class.
    argParser. addFlag ( 'all' , abbr : 'a' );
  }

  // [run] may also return a Future.
  void run () {
    // [argResults] is set before [run()] is called and contains the flags/options
    // passed to this command.
    print (argResults. flag ( 'all' ));
  }
}

CommandRunner 인수

CommandRunner를 사용하면 전역 인수와 명령 특정 인수(및 하위 명령 특정 인수)를 모두 지정할 수 있습니다.

글로벌 인수

전역 인수를 지정하려면 CommandRunner에 직접 인수를 추가하세요.

전역 인수 추가

 var runner = CommandRunner ( 'dgit' ,  "A dart implementation of distributed version control." );
// add global flag
runner.argParser. addFlag ( 'verbose' , abbr : 'v' , help : 'increase logging' );

명령별 인수

명령별 인수를 지정하려면 각 명령에 인수를 추가하세요.

  CommitCommand () {
    // we can add command specific arguments here.
    // [argParser] is automatically created by the parent class.
    argParser. addFlag ( 'all' , abbr : 'a' );
  }

하위 명령

명령에는 addSubcommand를 사용하여 추가되는 하위 명령이 있을 수도 있습니다. 하위 명령이 포함된 명령은 자체 코드를 실행할 수 없으므로 run을 구현할 필요가 없습니다. 예를 들어:

 class StashCommand extends Command {
  final String name = "stash" ;
  final String description = "Stash changes in the working directory." ;

  StashCommand () {
    addSubcommand ( StashSaveCommand ());
    addSubcommand ( StashListCommand ());
  }
}

기본 도움말 명령

CommandRunner는 명령에 대한 사용법 정보를 표시하는 help 명령을 자동으로 추가하고 모든 명령에 대한 --help 플래그를 지원합니다. 인수를 구문 분석하거나 명령을 처리하는 중에 오류가 발생하면 UsageException이 발생합니다. 귀하의 main() 메소드는 이를 포착하여 적절하게 인쇄해야 합니다. 예를 들어:

runner. run (arguments). catchError ((error) {
  if (error is ! UsageException ) throw error;
  print (error);
  exit ( 64 ); // Exit code 64 indicates a usage error.
});

사용량 표시

--help 의 출력으로 사용하기에 적합한 멋진 도움말 텍스트를 자동으로 생성할 수 있습니다. 좋은 사용법 정보를 표시하려면 옵션을 생성할 때 도움말 텍스트를 제공해야 합니다.

전체 옵션에 대한 도움말 텍스트를 정의하려면 help: 매개변수를 사용하세요.

parser. addOption ( 'mode' , help : 'The compiler configuration' ,
    allowed : [ 'debug' , 'release' ]);
parser. addFlag ( 'verbose' , help : 'Show additional diagnostic info' );

플래그가 아닌 옵션의 경우 매개변수에 대한 도움말 문자열을 제공할 수도 있습니다.

parser. addOption ( 'out' , help : 'The output path' , valueHelp : 'path' ,
    allowed : [ 'debug' , 'release' ]);

플래그가 아닌 옵션의 경우 allowedHelp: 매개변수를 사용하여 각 예상 값에 대한 자세한 도움말을 제공할 수도 있습니다.

parser. addOption ( 'arch' , help : 'The architecture to compile for' ,
    allowedHelp : {
      'ia32' : 'Intel x86' ,
      'arm' : 'ARM Holding 32-bit chip'
    });

도움말을 표시하려면 사용법 getter를 사용하십시오.

 print (parser.usage);

결과 문자열은 다음과 같습니다.

 --mode            The compiler configuration
                  [debug, release]

--out=<path>      The output path
--[no-]verbose    Show additional diagnostic info
--arch            The architecture to compile for
      [arm]       ARM Holding 32-bit chip
      [ia32]      Intel x86