From 5a39e7fd2e1ea4b053dc7ff844c5842ae5d1ac0a Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 14:44:27 +0900 Subject: [PATCH 1/7] Add CLI documentation for BEAR.Sunday Added detailed CLI guide for BEAR.Sunday in both English and Japanese. The guide covers installation, basic usage, command generation, distribution via Homebrew, and customization. This enhances the usability and distribution ease of the CLI tool for BEAR.Sunday users. --- manuals/1.0/en/325.cli.md | 322 ++++++++++++++++++++++++++++++++++++++ manuals/1.0/ja/325.cli.md | 319 +++++++++++++++++++++++++++++++++++++ 2 files changed, 641 insertions(+) create mode 100644 manuals/1.0/en/325.cli.md create mode 100644 manuals/1.0/ja/325.cli.md diff --git a/manuals/1.0/en/325.cli.md b/manuals/1.0/en/325.cli.md new file mode 100644 index 00000000..5c0157aa --- /dev/null +++ b/manuals/1.0/en/325.cli.md @@ -0,0 +1,322 @@ +--- +layout: docs-en +title: Command Line Interface (CLI) +category: Manual +permalink: /manuals/1.0/en/cli.html +--- +# Command Line Interface (CLI) + +BEAR.Sunday's Resource-Oriented Architecture (ROA) represents every functionality of the application as a URI-addressable resource. This approach allows access to resources in various ways, not limited to the web. + +```bash +$ php page.php '/greeting?name=World&lang=ja' +{ + "greeting": "Hello, World", + "lang": "ja" +} +``` + +BEAR.Cli is a tool that converts such resources into native CLI commands, making them distributable via Homebrew: + +```bash +$ greet -n "World" -l ja +Hello, World +``` + +Without writing additional code, you can reuse existing application resources as standard CLI tools. Distribution through Homebrew allows users to use them just like any general command-line tool, without knowing that they are running on PHP or BEAR.Sunday. + +## Installation + +Install via Composer. + +```bash +composer require bear/cli +``` + +## Basic Usage + +### Adding CLI Attributes to Resources + +Add CLI attributes to the resource class to define the command-line interface. + +```php +use BEAR\Cli\Attribute\Cli; +use BEAR\Cli\Attribute\Option; + +class Greeting extends ResourceObject +{ + #[Cli( + name: 'greet', + description: 'Say hello in multiple languages', + output: 'greeting' + )] + public function onGet( + #[Option(shortName: 'n', description: 'Name to greet')] + string $name, + #[Option(shortName: 'l', description: 'Language (en, ja, fr, es)')] + string $lang = 'en' + ): static { + $this->body = [ + 'greeting' => "Hello, {$name}", + 'lang' => $lang + ]; + + return $this; + } +} +``` + +### Generating CLI Commands and Formula + +```bash +$ vendor/bin/bear-cli-gen MyVendor.MyProject +# Generated files: +# bin/cli/greet # CLI command +# var/homebrew/greet.rb # Homebrew formula +``` + +## Using the Command + +The generated command provides standard CLI features as follows: + +### Displaying Help + +```bash +$ greet --help +Say hello in multiple languages + +Usage: greet [options] + +Options: + --name, -n Name to greet (required) + --lang, -l Language (en, ja, fr, es) (default: en) + --help, -h Show this help message + --version, -v Show version information + --format Output format (text|json) (default: text) +``` + +### Displaying Version Information + +```bash +$ greet --version +greet version 0.1.0 +``` + +### Basic Usage Examples + +```bash +# Basic greeting +$ greet -n "World" +Hello, World + +# Specify language +$ greet -n "World" -l ja +こんにちは, World + +# Short options +$ greet -n "World" -l fr +Bonjour, World + +# Long options +$ greet --name "World" --lang es +¡Hola, World +``` + +### JSON Output + +```bash +$ greet -n "World" -l ja --format json +{ + "greeting": "こんにちは, World", + "lang": "ja" +} +``` + +## Distribution Methods + +Commands created with BEAR.Cli can be distributed via Homebrew in the following two ways: + +### 1. Distribution via Local Formula + +When testing a development version: + +```bash +$ brew install --formula ./var/homebrew/greet.rb +``` + +This method is suitable in the following cases: +- Private projects +- Testing during development +- Distribution of internal tools + +### 2. Distribution via Homebrew Tap + +A method to widely distribute using a public repository: + +```bash +$ brew tap your-vendor/greet +$ brew install your-vendor/greet +``` + +This method is suitable in the following cases: +- Open-source projects +- Distribution of public tools +- Providing continuous updates + +#### Testing Development Version + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +``` + +#### Stable Release + +1. Create a tag: + +```bash +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 +``` + +2. Update the formula: + +```diff + class Greet < Formula ++ desc "Your CLI tool description" ++ homepage "https://github.com/your-vendor/your-project" ++ url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" ++ sha256 "..." # Write the hash value obtained from the command below ++ version "0.1.0" +- head "https://github.com/your-vendor/your-project.git", branch: "main" + + depends_on "php@8.1" + depends_on "composer" + end +``` + +You can add dependencies like databases to the formula as needed. However, it's recommended to handle environment setup like database initialization with a `bin/setup` script. + +3. Obtain SHA256 hash: + +```bash +# Download tarball from GitHub and compute hash +$ curl -sL https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256 +``` + +4. Create a Homebrew Tap: + +Setup for GitHub CLI is required: +- [Install GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) +- [Authenticate GitHub CLI](https://cli.github.com/manual/gh_auth_login) + +```bash +# Authenticate with GitHub CLI +$ gh auth login + +# The public repository name must start with homebrew- +$ gh repo create your-vendor/homebrew-greet --public --clone +$ cd homebrew-greet +``` + +5. Place and Publish the Formula: + +```bash +$ cp /path/to/project/var/homebrew/greet.rb . +$ git add greet.rb +$ git commit -m "Add formula for greet command" +$ git push +``` + +6. Installation and Distribution: + +End users can start using the tool with just the following commands. Since PHP environments and dependency packages are installed automatically, users don't need to worry about environment setup: + +```bash +$ brew tap your-vendor/greet # The homebrew- prefix is omitted +$ brew install your-vendor/greet + +# Ready to use immediately +$ greet --version +greet version 0.1.0 +``` + +## Customizing the Formula + +If necessary, you can edit the formula using the `brew edit` command: + +```bash +$ brew edit your-vendor/greet +``` + +```ruby +class Greet < Formula + desc "Your CLI tool description" + homepage "https://github.com/your-vendor/your-project" + url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" + sha256 "..." # SHA256 of the tgz + version "0.1.0" + + depends_on "php@8.1" # Specify PHP version + depends_on "composer" + + # Add if your application requires + # depends_on "mysql" + # depends_on "redis" +end +``` + +## Version Management + +To pin to a specific version: + +```bash +# Pin version +$ brew pin your-vendor/greet + +# Unpin +$ brew unpin your-vendor/greet +``` + +## Deployment + +For continuous deployment, the following steps are recommended: + +1. Verification in Development Environment + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +$ greet --version # Check version +$ greet --help # Check help +``` + +2. Release and Deployment + +```bash +# Create version tag +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 + +# Update Homebrew tap +$ cp var/homebrew/greet.rb /path/to/homebrew-tap/Formula/ +$ cd /path/to/homebrew-tap +$ git add Formula/greet.rb +$ git commit -m "Release greet v0.1.0" +$ git push origin main +``` + +3. Verify Installation + +```bash +$ brew update +$ brew install your-vendor/greet +$ greet --version # Confirm the new version +``` + +## Clean Architecture + +BEAR.Cli demonstrates the strengths of Resource-Oriented Architecture (ROA) and Clean Architecture. In line with the Clean Architecture principle that "UI is a detail," you can add a new adapter, CLI, to the same resource in addition to the web interface. + +Furthermore, BEAR.Cli not only supports the creation of commands but also supports distribution and updates via Homebrew. This allows end-users to start using the tool with just one command, utilizing it like a native UNIX command without being aware of the existence of PHP or BEAR.Sunday. + +Also, the CLI tool can be version-managed and updated independently from the application repository. This enables you to maintain stability and continuous updates as a command-line tool without being affected by the evolution of the API. This is a new form of API provision realized through the combination of Resource-Oriented Architecture and Clean Architecture. + diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md new file mode 100644 index 00000000..d5823867 --- /dev/null +++ b/manuals/1.0/ja/325.cli.md @@ -0,0 +1,319 @@ +--- +layout: docs-ja +title: コマンドラインインターフェイス (CLI) +category: Manual +permalink: /manuals/1.0/ja/cli.html +--- +# コマンドラインインターフェイス (CLI) + +BEAR.Sundayのリソース指向アーキテクチャ（ROA）は、アプリケーションのあらゆる機能をURIでアドレス可能なリソースとして表現します。このアプローチにより、Webに限らず様々な方法でリソースにアクセスできます。 + +```bash +$ php page.php '/greeting?name=World&lang=ja' +{ + "greeting": "Hello, World", + "lang": "ja" +} +``` + +BEAR.Cliは、このようなリソースをネイティブなCLIコマンドに変換し、Homebrewで配布可能にするツールです： + + +```bash +$ greet -n "World" -l ja +Hello, World +``` + +追加のコードを書くことなく、既存のアプリケーションリソースを標準的なCLIツールとして再利用できます。Homebrewを通じた配布により、PHPやBEAR.Sundayで動作していることを知ることなく、一般的なコマンドラインツールと同じように利用できます。 + +## インストール + +Composerでインストールします。 + +```bash +composer require bear/cli +``` + +## 基本的な使い方 + +### リソースへのCLI属性の追加 + +リソースクラスにCLI属性を追加して、コマンドラインインターフェースを定義します。 + +```php +use BEAR\Cli\Attribute\Cli; +use BEAR\Cli\Attribute\Option; + +class Greeting extends ResourceObject +{ + #[Cli( + name: 'greet', + description: 'Say hello in multiple languages', + output: 'greeting' + )] + public function onGet( + #[Option(shortName: 'n', description: 'Name to greet')] + string $name, + #[Option(shortName: 'l', description: 'Language (en, ja, fr, es)')] + string $lang = 'en' + ): static { + $this->body = [ + 'greeting' => "Hello, {$name}", + 'lang' => $lang + ]; + + return $this; + } +} +``` + +### CLIコマンドとフォーミュラの生成 + +```bash +$ vendor/bin/bear-cli-gen MyVendor.MyProject +# 生成されたファイル: +# bin/cli/greet 　 # CLIコマンド +# var/homebrew/greet.rb # Homebrewフォーミュラ + + +## コマンドの使用方法 + +生成されたコマンドは以下のような標準的なCLI機能を提供します： + +### ヘルプの表示 + +```bash +$ greet --help +Say hello in multiple languages + +Usage: greet [options] + +Options: + --name, -n Name to greet (required) + --lang, -l Language (en, ja, fr, es) (default: en) + --help, -h Show this help message + --version, -v Show version information + --format Output format (text|json) (default: text) +``` + +### バージョン情報の表示 + +```bash +$ greet --version +greet version 0.1.0 +``` + +### 基本的な使用例 + +```bash +# 基本的な挨拶 +$ greet -n "World" +Hello, World + +# 言語を指定 +$ greet -n "World" -l ja +こんにちは, World + +# 短いオプション +$ greet -n "World" -l fr +Bonjour, World + +# 長いオプション +$ greet --name "World" --lang es +¡Hola, World +``` + +### JSON出力 + +```bash +$ greet -n "World" -l ja --format json +{ + "greeting": "こんにちは, World", + "lang": "ja" +} +``` + +## 配布方法 + +BEAR.Cliで作成したコマンドは、以下の2つの方法でHomebrewを通じて配布できます： + +### 1. ローカルフォーミュラによる配布 + +開発版をテストする場合： + +```bash +$ brew install --formula ./var/homebrew/greet.rb +``` + +この方法は以下の場合に適しています： +- プライベートプロジェクト +- 開発中のテスト +- 社内ツールの配布 + +### 2. Homebrewタップによる配布 + +公開リポジトリを使用して広く配布する方法です： + +```bash +$ brew tap your-vendor/greet +$ brew install your-vendor/greet +``` + +この方法は以下の場合に適しています： +- オープンソースプロジェクト +- 公開ツールの配布 +- 継続的なアップデートの提供 + +#### 開発版のテスト + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +``` + +#### 安定版のリリース + +1. タグを作成： +```bash +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 +``` + +2. フォーミュラを更新： +```diff + class Greet < Formula ++ desc "Your CLI tool description" ++ homepage "https://github.com/your-vendor/your-project" ++ url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" ++ sha256 "..." # 以下のコマンドで取得したハッシュ値を記述 ++ version "0.1.0" +- head "https://github.com/your-vendor/your-project.git", branch: "main" + + depends_on "php@8.1" + depends_on "composer" + end +``` + +フォーミュラには必要に応じてデータベースなどの依存関係を追加できます。ただし、データベースのセットアップなどの環境構築は `bin/setup` スクリプトで行うことを推奨します。 + +3. SHA256ハッシュの取得： +```bash +# GitHubからtarballをダウンロードしてハッシュを計算 +$ curl -sL https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256 +``` + +4. Homebrewタップの作成: + +GitHub CLIのセットアップが必要です： +- [GitHub CLI のインストール](https://docs.github.com/ja/github-cli/github-cli/about-github-cli) +- [GitHub CLI の認証](https://cli.github.com/manual/gh_auth_login) + +```bash +# GitHub CLIで認証 +$ gh auth login + +# 公開リポジトリ名はhomebrew-で始める必要があります +$ gh repo create your-vendor/homebrew-greet --public --clone +$ cd homebrew-greet +``` + +5. フォーミュラの配置と公開： +```bash +$ cp /path/to/project/var/homebrew/greet.rb . +$ git add greet.rb +$ git commit -m "Add formula for greet command" +$ git push +``` + +6. インストールと配布: + +エンドユーザーは以下のコマンドだけでツールを使い始めることができます。PHP環境や依存パッケージのインストールは自動的に行われるため、ユーザーが環境構築について心配する必要はありません： + +```bash +$ brew tap your-vendor/greet # homebrew-プレフィックスは省略 +$ brew install your-vendor/greet + +# すぐに使用可能 +$ greet --version +greet version 0.1.0 +``` + +## フォーミュラのカスタマイズ + +必要に応じて、`brew edit` コマンドでフォーミュラを編集できます： + +```bash +$ brew edit your-vendor/greet +``` + +```ruby +class Greet < Formula + desc "Your CLI tool description" + homepage "https://github.com/your-vendor/your-project" + url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz" + sha256 "..." # tgzのSHA256 + version "0.1.0" + + depends_on "php@8.1" # PHPバージョンの指定 + depends_on "composer" + + # アプリケーションが必要とする場合は追加 + # depends_on "mysql" + # depends_on "redis" +end +``` + +## バージョン管理 + +特定のバージョンに固定する場合： + +```bash + +# バージョンの固定 +$ brew pin your-vendor/greet + +# 固定解除 +$ brew unpin your-vendor/greet +``` + +## デプロイ + +継続的デプロイメントのために、以下のような手順が推奨されます： + +1. 開発環境での確認 + +```bash +$ brew install --HEAD ./var/homebrew/greet.rb +$ greet --version # バージョン確認 +$ greet --help # ヘルプの確認 +``` + +2. リリースとデプロイ + +```bash +# バージョンタグの作成 +$ git tag -a v0.1.0 -m "Initial stable release" +$ git push origin v0.1.0 + +# Homebrewタップの更新 +$ cp var/homebrew/greet.rb /path/to/homebrew-tap/Formula/ +$ cd /path/to/homebrew-tap +$ git add Formula/greet.rb +$ git commit -m "Release greet v0.1.0" +$ git push origin main +``` + +3. インストールの確認 + +```bash +$ brew update +$ brew install your-vendor/greet +$ greet --version # 新しいバージョンの確認 +``` + +## クリーンアーキテクチャ + +BEAR.Cliは、リソース指向アーキテクチャ（ROA）とクリーンアーキテクチャの強みを実証しています。クリーンアーキテクチャが目指す「UIは詳細である」という原則に従い、同じリソースに対してWebインターフェースだけでなく、CLIという新しいアダプターを追加できます。 + +さらに、BEAR.Cliはコマンドの作成だけでなく、Homebrewによる配布や更新もサポートしています。これにより、エンドユーザーはコマンド一つでツールを使い始めることができ、PHPやBEAR.Sundayの存在を意識することなく、ネイティブなUNIXコマンドのように利用できます。 + +また、CLIツールはアプリケーションリポジトリから独立してバージョン管理と更新が可能です。これにより、APIの進化に影響されることなく、コマンドラインツールとしての安定性と継続的なアップデートを保つことができます。これは、リソース指向アーキテクチャとクリーンアーキテクチャの組み合わせにより実現した、APIの新しい提供形態です。 From 19602819d8a435a1c6819866ccbf93020e745479 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 15:10:06 +0900 Subject: [PATCH 2/7] Add multilingual greeting support for CLI Implemented a language-specific greeting based on user input, supporting English, Japanese, French, and Spanish. This change updates both the Japanese and English manuals to reflect the new functionality. --- manuals/1.0/en/325.cli.md | 10 ++++++++-- manuals/1.0/ja/325.cli.md | 10 ++++++++-- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/manuals/1.0/en/325.cli.md b/manuals/1.0/en/325.cli.md index 5c0157aa..b7cc0e3d 100644 --- a/manuals/1.0/en/325.cli.md +++ b/manuals/1.0/en/325.cli.md @@ -56,11 +56,17 @@ class Greeting extends ResourceObject #[Option(shortName: 'l', description: 'Language (en, ja, fr, es)')] string $lang = 'en' ): static { + $greeting = match ($lang) { + 'ja' => 'こんにちは', + 'fr' => 'Bonjour', + 'es' => '¡Hola', + default => 'Hello', + }; $this->body = [ - 'greeting' => "Hello, {$name}", + 'greeting' => "{$greeting}, {$name}", 'lang' => $lang ]; - + return $this; } } diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md index d5823867..8e4a8e22 100644 --- a/manuals/1.0/ja/325.cli.md +++ b/manuals/1.0/ja/325.cli.md @@ -57,11 +57,17 @@ class Greeting extends ResourceObject #[Option(shortName: 'l', description: 'Language (en, ja, fr, es)')] string $lang = 'en' ): static { + $greeting = match ($lang) { + 'ja' => 'こんにちは', + 'fr' => 'Bonjour', + 'es' => '¡Hola', + default => 'Hello', + }; $this->body = [ - 'greeting' => "Hello, {$name}", + 'greeting' => "{$greeting}, {$name}", 'lang' => $lang ]; - + return $this; } } From a2553ac9d34eb37aad541d4df2c4e44e90217a26 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 15:31:59 +0900 Subject: [PATCH 3/7] Update Japanese CLI manual for improved clarity Refined sentences for better readability and consistency. Ensured that the descriptions are concise and more easily understood, without altering the original intent and meaning. --- manuals/1.0/ja/325.cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md index 8e4a8e22..5cacd79e 100644 --- a/manuals/1.0/ja/325.cli.md +++ b/manuals/1.0/ja/325.cli.md @@ -320,6 +320,6 @@ $ greet --version # 新しいバージョンの確認 BEAR.Cliは、リソース指向アーキテクチャ（ROA）とクリーンアーキテクチャの強みを実証しています。クリーンアーキテクチャが目指す「UIは詳細である」という原則に従い、同じリソースに対してWebインターフェースだけでなく、CLIという新しいアダプターを追加できます。 -さらに、BEAR.Cliはコマンドの作成だけでなく、Homebrewによる配布や更新もサポートしています。これにより、エンドユーザーはコマンド一つでツールを使い始めることができ、PHPやBEAR.Sundayの存在を意識することなく、ネイティブなUNIXコマンドのように利用できます。 +さらに、BEAR.Cliはコマンドの作成だけでなく、Homebrewによる配布や更新もサポートしています。これにより、エンドユーザーはコマンド一つでツールを使い始めることができ、PHPやBEAR.Sundayの存在を意識せず、ネイティブなUNIXコマンドのように扱えます。 -また、CLIツールはアプリケーションリポジトリから独立してバージョン管理と更新が可能です。これにより、APIの進化に影響されることなく、コマンドラインツールとしての安定性と継続的なアップデートを保つことができます。これは、リソース指向アーキテクチャとクリーンアーキテクチャの組み合わせにより実現した、APIの新しい提供形態です。 +また、CLIツールはアプリケーションリポジトリから独立してバージョン管理および更新が可能です。そのため、APIの進化に影響されず、コマンドラインツールとしての安定性と継続的なアップデートを保つことができます。これは、リソース指向アーキテクチャとクリーンアーキテクチャの組み合わせにより実現した、APIの新しい提供形態です。 From 50ca2a991a65db61af5e9c27cc4f6675ca08af69 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 15:38:04 +0900 Subject: [PATCH 4/7] Update manuals/1.0/ja/325.cli.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- manuals/1.0/ja/325.cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md index 5cacd79e..2528087a 100644 --- a/manuals/1.0/ja/325.cli.md +++ b/manuals/1.0/ja/325.cli.md @@ -11,7 +11,7 @@ BEAR.Sundayのリソース指向アーキテクチャ（ROA）は、アプリケ ```bash $ php page.php '/greeting?name=World&lang=ja' { - "greeting": "Hello, World", + "greeting": "こんにちは, World", "lang": "ja" } ``` From 1009a7d2139b09551c672c2738669ddd6d86d8a1 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 15:45:25 +0900 Subject: [PATCH 5/7] Update manuals/1.0/ja/325.cli.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- manuals/1.0/ja/325.cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md index 2528087a..e69dfe33 100644 --- a/manuals/1.0/ja/325.cli.md +++ b/manuals/1.0/ja/325.cli.md @@ -21,7 +21,7 @@ BEAR.Cliは、このようなリソースをネイティブなCLIコマンドに ```bash $ greet -n "World" -l ja -Hello, World +こんにちは, World ``` 追加のコードを書くことなく、既存のアプリケーションリソースを標準的なCLIツールとして再利用できます。Homebrewを通じた配布により、PHPやBEAR.Sundayで動作していることを知ることなく、一般的なコマンドラインツールと同じように利用できます。 From 490a56fee21066111b8dba3d7270686500323d76 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 15:45:03 +0900 Subject: [PATCH 6/7] Add CLI output behavior section to manual Updated the CLI manual to include detailed output behavior specifications, covering default output, JSON format option, error message handling, and HTTP status code mapping to exit codes. This addition ensures clearer understanding of how CLI command results are presented and how errors are communicated. --- manuals/1.0/en/325.cli.md | 9 +++++++++ manuals/1.0/ja/325.cli.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/manuals/1.0/en/325.cli.md b/manuals/1.0/en/325.cli.md index b7cc0e3d..e20c7fe5 100644 --- a/manuals/1.0/en/325.cli.md +++ b/manuals/1.0/en/325.cli.md @@ -138,6 +138,15 @@ $ greet -n "World" -l ja --format json } ``` +### Output Behavior + +The CLI command output follows these specifications: + +- **Default Output**: Displays only the specified field's value +- **`--format=json` option**: Shows the full JSON response like the API endpoint +- **Error Messages**: Displayed in standard error (stderr) +- **HTTP Status Code Mapping**: Maps to exit codes (0: success, 1: client error, 2: server error) + ## Distribution Methods Commands created with BEAR.Cli can be distributed via Homebrew in the following two ways: diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md index e69dfe33..fbb33dcc 100644 --- a/manuals/1.0/ja/325.cli.md +++ b/manuals/1.0/ja/325.cli.md @@ -139,6 +139,15 @@ $ greet -n "World" -l ja --format json } ``` +### 出力の挙動 + +CLIコマンドの出力は以下の仕様に基づきます： + +- **デフォルト出力**: 指定されたフィールドの値のみを表示 +- **`--format=json` オプション**: APIエンドポイントと同様に、フルJSONレスポンスを表示 +- **エラーメッセージ**: 標準エラー出力（stderr）に表示 +- **HTTPステータスコードのマッピング**: 終了コードにHTTPステータスコードをマップ（0: 成功、1: クライアントエラー、2: サーバーエラー） + ## 配布方法 BEAR.Cliで作成したコマンドは、以下の2つの方法でHomebrewを通じて配布できます： From fae277b87e9d6c6453c250c6bd135e68b9eac085 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Thu, 14 Nov 2024 16:04:38 +0900 Subject: [PATCH 7/7] Update manuals/1.0/en/325.cli.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- manuals/1.0/en/325.cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manuals/1.0/en/325.cli.md b/manuals/1.0/en/325.cli.md index e20c7fe5..863f3f57 100644 --- a/manuals/1.0/en/325.cli.md +++ b/manuals/1.0/en/325.cli.md @@ -11,7 +11,7 @@ BEAR.Sunday's Resource-Oriented Architecture (ROA) represents every functionalit ```bash $ php page.php '/greeting?name=World&lang=ja' { - "greeting": "Hello, World", + "greeting": "こんにちは, World", "lang": "ja" } ```