[Rust 공식문서 한국어 정리] ㊼. Rust CLI 파싱 가이드 — Clap

[Rust 공식문서 한국어 정리] ㊼. Rust CLI 파싱 가이드 — Clap



원문 제목: clap — Command Line Argument Parser

작성자: clap Contributors



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 1. 서론 — 이 문서가 다루는 내용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이 문서는 Rust의 대표적인 명령줄 인자 파싱 라이브러리인 clap의 사용법을 설명합니다.

derive 매크로 기반 선언적 API와 빌더 패턴 기반의 명령적 API 두 가지 스타일을 다룹니다.

서브커맨드, 인자 유효성 검증, 자동 생성 도움말, 셸 보완 기능까지 체계적으로 안내합니다.

사용자 친화적인 CLI 도구를 빠르게 개발하면서도, 타입 안전성과 유지보수성을 확보하는 방법을 중심으로 설명합니다.

CLI 도구를 개발하는 모든 Rust 개발자에게 가장 많이 사용되는 라이브러리입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔑 2. 핵심 개념 4가지

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



① Derive API: #[derive(Parser)]로 구조체를 CLI 인자로 매핑하여 보일러플레이트를 제거합니다.

② Builder API: Command::new()로 프로그래매틱하게 인자를 정의하고 파싱합니다.

③ Subcommands: #[derive(Subcommand)]로 git처럼 다중 서브커맨드를 구성합니다.

④ Validation: value_parser, arg_enum 등으로 인자 타입과 범위를 컴파일 타임에 검증합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 3. 주요 내용 상세

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



clap의 derive API는 복잡한 CLI도 간결하게 정의할 수 있게 합니다.

#[derive(Parser)] struct Args { #[arg(short, long)] name: String, count: u8 } 형태로, 필드가 곧 CLI 인자가 됩니다.

타입이 bool이면 플래그, String이면 옵션, Vec면 다중 값으로 자동 해석됩니다.



빌더 API는 런타임에 동적으로 인자를 구성해야 할 때 유용합니다.

Command::new("myapp").arg(arg!(-c --config "Config file"))처럼 체이닝으로 정의합니다.

플러그인 시스템처럼 런타임에 명령어를 추가해야 하는 경우 derive 대신 builder를 사용합니다.



서브커맨드는 대형 CLI 도구의 필수 구조입니다.

#[derive(Subcommand)] enum Commands { Add { name: String }, Remove { name: String } } 형태로 정의합니다.

서브커맨드별로 독립적인 인자 집합을 가지며, 각각의 핸들러 함수로 분리할 수 있습니다.



자동 도움말과 에러 메시지는 clap의 큰 장점입니다.

--help와 --version 플래그가 자동으로 생성되며, 잘못된 인자 입력 시 색상이 입혀진 에러 메시지를 출력합니다.

cargo run -- --help로 미리 확인하고, 출력 형식을 Term styling으로 커스터마이징할 수 있습니다.



셸 자동 완성은 clap_complete로 생성합니다.

clap_complete::shells::Bash, Zsh, Fish, PowerShell 등의 생성기를 제공하여, 배포 시 셸 설정 파일을 함께 제공할 수 있습니다.

사용자 경험을 크게 향상시키며, modern CLI의 기대 수준을 충족합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛠 4. 실전 활용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



CLI 도구의 메인 진입점에서 #[derive(Parser)] 구조체로 인자를 파싱하고 match로 서브커맨드를 분기합니다.

env_logger와 clap_verbosity_flag를 조합하여 -v, -vv 등의 verbosity 플래그를 표준화합니다.

clap_complete으로 셸 자동 완성 스크립트를 생성하여 설치 패키지에 포함합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 5. 정리

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



clap은 Rust CLI 개발의 사실상 표준으로, derive API로 빠르게 구현할 수 있습니다.

자동 도움말, 타입 검증, 서브커맨드, 셸 완성까지 갖춘 종합 CLI 프레임워크입니다.

복잡도에 따라 derive와 builder API를 적절히 선택하여 사용하세요.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 출처 링크

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



원문: https://docs.rs/clap/latest/clap/

clap Book: https://docs.rs/clap/latest/clap/_derive/_tutorial/index.html



#Rust #Clap #CLI #Parser #Subcommand #ShellCompletion #번역