argparse-c¶

argparse-c は、Python の argparse に近い書き心地で C99 の CLI を構築できるライブラリです。

Python argparse の使い勝手を C99 に持ち込み、completion・manpage 生成・subcommand・known-args parsing まで対応できます。

このリポジトリは、フル AI コーディング体制（設計・実装・ドキュメント更新まで一貫して AI を活用）でメンテナンスしています。

ここから始める¶

README / English: README.md
README / 日本語: README.ja.md
GitHub Pages / English: https://yoshihideshirai.github.io/argparse-c/en/
GitHub Pages / 日本語: https://yoshihideshirai.github.io/argparse-c/ja/
GitHub Pages / 简体中文: https://yoshihideshirai.github.io/argparse-c/zh-CN/（Partial support）
GitHub Pages / Español: https://yoshihideshirai.github.io/argparse-c/es/（Partial support）
GitHub Pages / Português (Brasil): https://yoshihideshirai.github.io/argparse-c/pt-BR/（Partial support）
Getting Started / English: https://yoshihideshirai.github.io/argparse-c/en/getting-started/
Getting Started / 日本語: docs/ja/getting-started.md

凡例:

Full support: English / 日本語（README と GitHub Pages を並行して保守）。
Partial support: 简体中文 / Español / Português (Brasil)（GitHub Pages を段階公開中）。

インストール手順、completion の設定、パッケージング、API の詳細は GitHub Pages または docs/ja/ 配下にまとめています。この README では ライブラリの概要、主な利点、最初に読むサンプル、日本語ドキュメントへの導線 に絞って説明します。

概要¶

argparse-c は、低レベルな引数走査や検証処理を手書きせずに、C99 で実用的なコマンドラインインターフェースを定義したい場面を想定したライブラリです。parser を作成し、option や positional を追加し、argv を parse して、namespace から値を取り出します。

主な機能は英語 README と粒度を揃えて管理しています。

Python argparse に着想を得た parser 定義
option、positional、default、required、choices
nargs、append/count/store-const action、mutually exclusive group
ネストした subcommand
同じ parser 定義から bash / fish / zsh の shell completion と manpage を生成
ap_parse_known_args(...) による未知引数の転送
parse 失敗時も exit() を強制せず、アプリ側でエラー処理を制御

主な利点¶

1. 慣れたスタイルで CLI を書ける¶

Python の argparse を使ったことがあれば、parser を作る、引数を追加する、parse する、値を読む、という流れをほぼ同じ感覚で扱えます。

2. 1 つの定義で実用機能までカバーできる¶

1 つの parser 定義から、次の機能を一貫して扱えます。

ヘルプ表示
shell completion の入口
manpage 生成
subcommand ツリー
wrapper CLI 向けの known / unknown 引数分離

3. エラー処理をアプリ側で決められる¶

argparse-c は parse 失敗時に一律で exit() しません。構造化されたエラーを受け取り、表示文言や終了コード、回復処理をアプリ側で制御できます。

体験をひと目で見る¶

argparse-c の 1 つの parser 定義から help、shell completion 候補、入力ミス時のわかりやすいエラーまで流れる様子を示すターミナル GIF。

この GIF は実際に動く sample/example_completion.c から生成しています。1 つの parser 定義を入れると、利用者にどう見えるかを伝える内容にしています。

--help
shell completion 用の hidden __complete transport
入力ミス時のわかりやすい validation error

リポジトリ内の実行可能サンプル¶

sample/example1.c: option / positional / 検証エラーの最小構成
sample/example_completion.c: completion と manpage 生成の入口
sample/example_subcommands.c: ネストした subcommand と subcommand_path
sample/example_test_runner.c: 引数パースを単体テスト風に検証する最小サンプル

最小サンプル¶

#include <stdio.h>
#include <stdlib.h>

#include "argparse-c.h"

int main(int argc, char **argv) {
  ap_error err = {0};
  ap_namespace *ns = NULL;
  ap_parser *parser = ap_parser_new("demo", "demo parser");

  ap_arg_options text = ap_arg_options_default();
  text.required = true;
  text.help = "input text";
  ap_add_argument(parser, "-t, --text", text, &err);

  if (ap_parse_args(parser, argc, argv, &ns, &err) != 0) {
    char *message = ap_format_error(parser, &err);
    fprintf(stderr, "%s", message ? message : err.message);
    free(message);
    ap_parser_free(parser);
    return 1;
  }

  {
    const char *value = NULL;
    if (ap_ns_get_string(ns, "text", &value)) {
      printf("text=%s\n", value);
    }
  }

  ap_namespace_free(ns);
  ap_parser_free(parser);
  return 0;
}

セットアップ、ビルド手順、次に覚える API は以下を参照してください。

日本語ドキュメント: docs/ja/index.md
Getting Started / 日本語: docs/ja/getting-started.md
GitHub Pages / 日本語トップ: https://yoshihideshirai.github.io/argparse-c/ja/

日本語ドキュメントへのリンク¶

日本語ドキュメント入口
Getting Started
ガイド一覧
API 仕様
機械可読API仕様 (JSON) ← AI/ツール連携時はこのJSONを参照してください。
AI agent guide (日本語) ← AI利用時の最初の読む順。
AI agent guide (English)

GitHub Pages 日本語トップへのリンク¶

https://yoshihideshirai.github.io/argparse-c/ja/

更新方針¶

README.md と README.ja.md では、概要・主な利点・機能一覧の粒度を大きくずらさずに保ちます。
README は訴求と導線を担い、詳細な使い方は docs/ja/getting-started.md や各 guide に寄せます。
詳細説明を追加したくなった場合は、まず docs 側へ追記し、README からはそのページへ案内します。

セキュリティ検証の現状と適用範囲¶

sanitizer と境界ケースを含むテストを CI で継続実行し、coverage を公開しています。
CI（tests + sanitizers + coverage）: https://github.com/yoshihideshirai/argparse-c/actions/workflows/ci.yml
Pages（coverage 公開ジョブ）: https://github.com/yoshihideshirai/argparse-c/actions/workflows/pages.yml
セキュリティテスト手順: https://yoshihideshirai.github.io/argparse-c/ja/security-testing/
公開時点の既知状態: この README の公開時点で、未修正の重大な脆弱性は把握していません。

非保証範囲¶

実際に本ライブラリを利用するアプリケーション側の入出力検証は、利用側アプリケーションの責務です。
OS・ツールチェーン・依存ライブラリなど、実行環境の差異による挙動差やリスクは、本ライブラリ単体では完全には保証できません。

更新ルール¶

リリースごとに本節の表現を見直し、最新の CI 実行結果とセキュリティテスト手順に合わせて更新します。

開発（クイックチェック）¶

AI・人間の共通の推奨入口:

./scripts/dev_quick_check.sh

このクイックチェックは、最低限の静的検証フローを順に実行します（docs同期検証 → format-check → 主要テスト最小構成）。

手動で実行する場合:

python scripts/verify_docs_repository_links.py
cmake -S . -B build
cmake --build build --target format-check
cmake --build build --target argparse_test example_completion example_manpage
ctest --test-dir build --output-on-failure -R '^argparse_test$'

コード変更の仕上げでは、フォーマッタも実行してください。

cmake --build build --target format

Warning policy¶

対象コンパイラと最低バージョン方針¶

warning policy の対象コンパイラは GCC と Clang です。
最低バージョン方針（ローカル再現・CI同等性の基準）:
GCC 11 以上
Clang 14 以上
補足:
CI の warning gate は GCC / Clang の両方で実行されます。
ローカルがこれより古いコンパイラの場合は、新しいツールチェーンで再現してから判定してください。

ローカル再現コマンド（English / 日本語）¶

English (configure/build/check)

# Configure (GCC)
cmake -S . -B build-warning-gcc -G Ninja \
  -DCMAKE_C_COMPILER=gcc \
  -DCMAKE_CXX_COMPILER=g++ \
  -DCMAKE_C_FLAGS='-Werror' \
  -DCMAKE_CXX_FLAGS='-Werror'

# Build (warning gate targets)
for target in argparse-c sample argparse_test; do
  cmake --build build-warning-gcc --target "${target}" --parallel
done

# Check (tests)
ctest --test-dir build-warning-gcc --output-on-failure

# Configure (Clang)
cmake -S . -B build-warning-clang -G Ninja \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_C_FLAGS='-Werror' \
  -DCMAKE_CXX_FLAGS='-Werror'

# Build (warning gate targets)
for target in argparse-c sample argparse_test; do
  cmake --build build-warning-clang --target "${target}" --parallel
done

# Check (tests)
ctest --test-dir build-warning-clang --output-on-failure

日本語（configure/build/check の再現）

# 設定（GCC）
cmake -S . -B build-warning-gcc -G Ninja \
  -DCMAKE_C_COMPILER=gcc \
  -DCMAKE_CXX_COMPILER=g++ \
  -DCMAKE_C_FLAGS='-Werror' \
  -DCMAKE_CXX_FLAGS='-Werror'

# ビルド（warning gate 対象）
for target in argparse-c sample argparse_test; do
  cmake --build build-warning-gcc --target "${target}" --parallel
done

# 確認（テスト）
ctest --test-dir build-warning-gcc --output-on-failure

# 設定（Clang）
cmake -S . -B build-warning-clang -G Ninja \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_C_FLAGS='-Werror' \
  -DCMAKE_CXX_FLAGS='-Werror'

# ビルド（warning gate 対象）
for target in argparse-c sample argparse_test; do
  cmake --build build-warning-clang --target "${target}" --parallel
done

# 確認（テスト）
ctest --test-dir build-warning-clang --output-on-failure

新規コード投入時の基準¶

GCC/Clang の warning-gate 構成で warning を増やさない こと。
警告抑制が不可避な場合は、局所抑制（行/ブロック/対象ターゲットの最小スコープ）を使ってください。
抑制には必ず短い理由コメントを添えてください（なぜ不可避か、なぜ局所抑制で安全か）。
まず全体フラグで広く抑制する方法は採らないでください。

CIジョブ名との対応と失敗時の確認導線¶

warning policy に関連する CI ジョブ（.github/workflows/ci.yml）:
warning-gate → Warning gate (gcc) / Warning gate (clang)（-Werror 設定・必須ターゲットのビルドログ）
build-and-test → Build & Test (gcc) / Build & Test (clang)（通常ビルドとテスト）
clang-tools → Clang format / tidy（warning 関連変更で併走しやすい静的チェック）
失敗時の確認手順:
失敗した workflow run を開き、該当 matrix job（gcc または clang）を選ぶ。
warning-gate 失敗時は warning-gate-logs-<compiler> artifact を取得して確認する。
本節の configure/build/check コマンドでローカル再現する。
修正後は以下を実行してから再 push:
- cmake --build build --target format
- ./scripts/dev_quick_check.sh