Skip to content

Commit b8cfd52

Browse files
yhk1038yhk1038
committed
docs: sync keyword args **{ } syntax to English and Japanese
- Updated Keyword Arguments section with inline/interface subsections - Added Required Keyword Arguments with **{ } syntax - Updated complex_function example in mixing section - Updated HTTP builder request method - Updated builder pattern and factory function examples - Updated summary table with all syntax variants Matches Korean documentation structure for Issue #19
1 parent 9337bf3 commit b8cfd52

File tree

2 files changed

+172
-46
lines changed

2 files changed

+172
-46
lines changed

‎docs/learn/functions/optional-rest-parameters.md‎

Lines changed: 86 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -130,15 +130,28 @@ team3 = create_team("Gamma", "Charlie", true, "Dave", "Eve", "Frank")
130130

131131
## Keyword Arguments
132132

133-
Ruby's keyword arguments can also be typed. These provide more clarity than positional arguments:
133+
In T-Ruby, keyword arguments are defined using the `**{ }` syntax. Unlike positional arguments, they are passed by name when calling.
134134

135-
```trb title="keyword.trb"
136-
def create_post(
135+
:::info Positional vs Keyword Arguments
136+
137+
| Definition | Call Style |
138+
|------------|------------|
139+
| `(x: String, y: Integer)` | `foo("hi", 10)` - positional |
140+
| `(**{ x: String, y: Integer })` | `foo(x: "hi", y: 10)` - keyword |
141+
142+
:::
143+
144+
### Inline Type Style
145+
146+
Define types directly inside `**{ }`. Default values use `= value` syntax:
147+
148+
```trb title="keyword_inline.trb"
149+
def create_post(**{
137150
title: String,
138151
content: String,
139152
published: Boolean = false,
140153
tags: Array<String> = []
141-
): Post
154+
}): Post
142155
Post.new(
143156
title: title,
144157
content: content,
@@ -161,6 +174,43 @@ post2 = create_post(
161174
)
162175
```
163176

177+
### Interface Reference Style
178+
179+
Define a separate interface and reference it. Default values use Ruby-style `: value` (no equals sign):
180+
181+
```trb title="keyword_interface.trb"
182+
interface PostOptions
183+
title: String
184+
content: String
185+
published?: Boolean # ? marks optional
186+
tags?: Array<String>
187+
end
188+
189+
def create_post(**{ title:, content:, published: false, tags: [] }: PostOptions): Post
190+
Post.new(
191+
title: title,
192+
content: content,
193+
published: published,
194+
tags: tags
195+
)
196+
end
197+
198+
# Call style is the same
199+
post = create_post(title: "Hello", content: "World")
200+
```
201+
202+
:::tip Choosing Between Inline and Interface
203+
204+
| Aspect | Inline Type | Interface Reference |
205+
|--------|-------------|---------------------|
206+
| Type definition | Inside `**{ }` | Separate interface |
207+
| Default value syntax | `= value` | `: value` (no equals) |
208+
| Optional marking | Implied by default value | `?` suffix |
209+
| Reusability | Single method | Shared across methods |
210+
211+
**Recommendation**: Use inline for single-method use, interface for reuse across multiple methods
212+
:::
213+
164214
## Keyword Rest Parameters
165215

166216
Use double splat `**` to collect keyword arguments into a hash:
@@ -194,15 +244,15 @@ The type annotation `**conditions: Hash<Symbol, String | Integer>` means "zero o
194244

195245
## Required Keyword Arguments
196246

197-
In Ruby, you can make keyword arguments required by omitting the default value:
247+
Keyword arguments without default values are required:
198248

199249
```trb title="required_kwargs.trb"
200-
def register_user(
250+
def register_user(**{
201251
email: String,
202252
password: String,
203253
name: String = "Anonymous",
204254
age: Integer
205-
): User
255+
}): User
206256
# email, password, and age are required
207257
# name is optional with default
208258
User.new(email: email, password: password, name: name, age: age)
@@ -230,17 +280,18 @@ You can combine all parameter types, but they must follow this order:
230280
1. Required positional parameters
231281
2. Optional positional parameters
232282
3. Rest parameter (`*args`)
233-
4. Required keyword arguments
234-
5. Optional keyword arguments
235-
6. Keyword rest parameter (`**kwargs`)
283+
4. Keyword arguments (`**{ ... }`)
284+
5. Keyword rest parameter (`**kwargs`)
236285

237286
```trb title="all_types.trb"
238287
def complex_function(
239288
required_pos: String, # 1. Required positional
240289
optional_pos: Integer = 0, # 2. Optional positional
241290
*rest_args: Array<String>, # 3. Rest parameter
242-
required_kw: Boolean, # 4. Required keyword
243-
optional_kw: String = "default", # 5. Optional keyword
291+
**{
292+
required_kw: Boolean, # 4. Required keyword
293+
optional_kw: String = "default" # 5. Optional keyword
294+
},
244295
**rest_kwargs: Hash<Symbol, String | Integer> # 6. Keyword rest
245296
): Hash<String, String | Integer | Boolean>
246297
{
@@ -287,14 +338,14 @@ class HTTPRequestBuilder
287338
urls.map { |url| make_request("DELETE", url, nil, {}) }
288339
end
289340
290-
# Keyword arguments with defaults
291-
def request(
341+
# Keyword arguments (inline type)
342+
def request(**{
292343
method: String,
293344
url: String,
294345
body: String? = nil,
295346
timeout: Integer = 30,
296347
retry_count: Integer = 3
297-
): Response
348+
}): Response
298349
make_request(method, url, body, {}, timeout, retry_count)
299350
end
300351
@@ -436,25 +487,28 @@ logger.debug(
436487

437488
## Common Patterns
438489

439-
### Builder Methods with Defaults
490+
### Builder Methods with Defaults (Keyword Arguments)
440491

441492
```trb title="builder_pattern.trb"
442-
def build_email(
493+
def build_email(**{
443494
to: String,
444495
subject: String,
445496
from: String = "[email protected]",
446497
reply_to: String? = nil,
447498
cc: Array<String> = [],
448499
bcc: Array<String> = []
449-
): Email
500+
}): Email
450501
Email.new(to, subject, from, reply_to, cc, bcc)
451502
end
503+
504+
# Call with keyword arguments
505+
email = build_email(to: "[email protected]", subject: "Hello")
452506
```
453507

454-
### Variadic Factory Functions
508+
### Variadic Factory Functions (Rest + Keyword Arguments)
455509

456510
```trb title="factory.trb"
457-
def create_users(*names: Array<String>, role: String = "user"): Array<User>
511+
def create_users(*names: Array<String>, **{ role: String = "user" }): Array<User>
458512
names.map { |name| User.new(name: name, role: role) }
459513
end
460514
@@ -479,9 +533,18 @@ config = merge_config(
479533

480534
Optional and rest parameters give your functions flexibility while maintaining type safety:
481535

482-
- **Optional parameters** (`param: Type = default`) have default values
483-
- **Rest parameters** (`*args: Array<Type>`) collect multiple arguments into an array
484-
- **Keyword rest** (`**kwargs: Hash<Symbol, Type>`) collects keyword arguments into a hash
536+
| Syntax | Description | Call Example |
537+
|--------|-------------|--------------|
538+
| `(x: Type)` | Positional argument | `foo("hi")` |
539+
| `(x: Type = default)` | Optional positional | `foo()` or `foo("hi")` |
540+
| `(*args: Array<Type>)` | Rest parameter | `foo("a", "b", "c")` |
541+
| `(**{ x: Type })` | Keyword argument | `foo(x: "hi")` |
542+
| `(**kwargs: Hash<Symbol, Type>)` | Keyword rest | `foo(a: 1, b: 2)` |
543+
544+
**Key Points:**
545+
- **Positional arguments** `(x: Type)`: passed by order
546+
- **Keyword arguments** `(**{ x: Type })`: passed by name
547+
- **Keyword rest** `(**kwargs: Hash<Symbol, Type>)`: collects arbitrary keyword arguments into a hash
485548
- T-Ruby ensures type safety for all parameter variations
486549

487550
Master these patterns to write flexible, type-safe APIs that are pleasant to use.

‎i18n/ja/docusaurus-plugin-content-docs/current/learn/functions/optional-rest-parameters.md‎

Lines changed: 86 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -130,15 +130,28 @@ team3 = create_team("Gamma", "Charlie", true, "Dave", "Eve", "Frank")
130130

131131
## キーワード引数
132132

133-
Rubyのキーワード引数も型を指定できます。位置引数よりも明確性を提供します：
133+
T-Rubyでは、キーワード引数は `**{ }` 構文を使用して定義します。位置引数とは異なり、呼び出し時に名前で引数を渡します。
134134

135-
```trb title="keyword.trb"
136-
def create_post(
135+
:::info 位置引数 vs キーワード引数
136+
137+
| 定義 | 呼び出し方法 |
138+
|------|-------------|
139+
| `(x: String, y: Integer)` | `foo("hi", 10)` - 位置引数 |
140+
| `(**{ x: String, y: Integer })` | `foo(x: "hi", y: 10)` - キーワード引数 |
141+
142+
:::
143+
144+
### インライン型方式
145+
146+
型を `**{ }` 内に直接定義します。デフォルト値は `= value` 形式で指定します：
147+
148+
```trb title="keyword_inline.trb"
149+
def create_post(**{
137150
title: String,
138151
content: String,
139152
published: Boolean = false,
140153
tags: Array<String> = []
141-
): Post
154+
}): Post
142155
Post.new(
143156
title: title,
144157
content: content,
@@ -161,6 +174,43 @@ post2 = create_post(
161174
)
162175
```
163176

177+
### Interface参照方式
178+
179+
別途interfaceを定義して参照します。デフォルト値はRubyスタイル `: value`（等号なし）で指定します：
180+
181+
```trb title="keyword_interface.trb"
182+
interface PostOptions
183+
title: String
184+
content: String
185+
published?: Boolean # ? でoptionalを表示
186+
tags?: Array<String>
187+
end
188+
189+
def create_post(**{ title:, content:, published: false, tags: [] }: PostOptions): Post
190+
Post.new(
191+
title: title,
192+
content: content,
193+
published: published,
194+
tags: tags
195+
)
196+
end
197+
198+
# 呼び出し方法は同じ
199+
post = create_post(title: "Hello", content: "World")
200+
```
201+
202+
:::tip インライン vs Interface の選択基準
203+
204+
| 項目 | インライン型 | interface参照 |
205+
|------|------------|---------------|
206+
| 型定義の場所 | `**{ }` 内に直接 | 別途interface |
207+
| デフォルト値構文 | `= value` | `: value`（等号なし） |
208+
| Optional表示 | デフォルト値で暗示 | `?` 接尾辞 |
209+
| 再利用性 | 単一メソッド | 複数メソッドで共有 |
210+
211+
**推奨**: 単一メソッドでのみ使用するならインライン、複数箇所で再利用するならinterface
212+
:::
213+
164214
## キーワード残余パラメータ
165215

166216
ダブルスプラット `**` を使用してキーワード引数をハッシュに収集します：
@@ -194,15 +244,15 @@ config = create_config(
194244

195245
## 必須キーワード引数
196246

197-
Rubyでは、デフォルト値を省略することでキーワード引数を必須にできます：
247+
デフォルト値のないキーワード引数は必須です：
198248

199249
```trb title="required_kwargs.trb"
200-
def register_user(
250+
def register_user(**{
201251
email: String,
202252
password: String,
203253
name: String = "Anonymous",
204254
age: Integer
205-
): User
255+
}): User
206256
# email、password、ageは必須
207257
# nameはデフォルト値付きのオプショナル
208258
User.new(email: email, password: password, name: name, age: age)
@@ -230,17 +280,18 @@ user2 = register_user(
230280
1. 必須位置パラメータ
231281
2. オプショナル位置パラメータ
232282
3. 残余パラメータ (`*args`)
233-
4. 必須キーワード引数
234-
5. オプショナルキーワード引数
235-
6. キーワード残余パラメータ (`**kwargs`)
283+
4. キーワード引数 (`**{ ... }`)
284+
5. キーワード残余パラメータ (`**kwargs`)
236285

237286
```trb title="all_types.trb"
238287
def complex_function(
239288
required_pos: String, # 1. 必須位置
240289
optional_pos: Integer = 0, # 2. オプショナル位置
241290
*rest_args: Array<String>, # 3. 残余パラメータ
242-
required_kw: Boolean, # 4. 必須キーワード
243-
optional_kw: String = "default", # 5. オプショナルキーワード
291+
**{
292+
required_kw: Boolean, # 4. 必須キーワード
293+
optional_kw: String = "default" # 5. オプショナルキーワード
294+
},
244295
**rest_kwargs: Hash<Symbol, String | Integer> # 6. キーワード残余
245296
): Hash<String, String | Integer | Boolean>
246297
{
@@ -287,14 +338,14 @@ class HTTPRequestBuilder
287338
urls.map { |url| make_request("DELETE", url, nil, {}) }
288339
end
289340
290-
# デフォルト値付きキーワード引数
291-
def request(
341+
# キーワード引数（インライン型）
342+
def request(**{
292343
method: String,
293344
url: String,
294345
body: String? = nil,
295346
timeout: Integer = 30,
296347
retry_count: Integer = 3
297-
): Response
348+
}): Response
298349
make_request(method, url, body, {}, timeout, retry_count)
299350
end
300351
@@ -436,25 +487,28 @@ logger.debug(
436487

437488
## 一般的なパターン
438489

439-
### デフォルト付きビルダーメソッド
490+
### デフォルト付きビルダーメソッド（キーワード引数）
440491

441492
```trb title="builder_pattern.trb"
442-
def build_email(
493+
def build_email(**{
443494
to: String,
444495
subject: String,
445496
from: String = "[email protected]",
446497
reply_to: String? = nil,
447498
cc: Array<String> = [],
448499
bcc: Array<String> = []
449-
): Email
500+
}): Email
450501
Email.new(to, subject, from, reply_to, cc, bcc)
451502
end
503+
504+
# キーワード引数で呼び出し
505+
email = build_email(to: "[email protected]", subject: "Hello")
452506
```
453507

454-
### 可変ファクトリ関数
508+
### 可変ファクトリ関数（残余 + キーワード引数）
455509

456510
```trb title="factory.trb"
457-
def create_users(*names: Array<String>, role: String = "user"): Array<User>
511+
def create_users(*names: Array<String>, **{ role: String = "user" }): Array<User>
458512
names.map { |name| User.new(name: name, role: role) }
459513
end
460514
@@ -479,9 +533,18 @@ config = merge_config(
479533

480534
オプショナルパラメータと残余パラメータは、型安全性を維持しながら関数に柔軟性を提供します：
481535

482-
- **オプショナルパラメータ** (`param: Type = default`) はデフォルト値を持ちます
483-
- **残余パラメータ** (`*args: Array<Type>`) は複数の引数を配列に収集します
484-
- **キーワード残余** (`**kwargs: Hash<Symbol, Type>`) はキーワード引数をハッシュに収集します
536+
| 文法 | 説明 | 呼び出し例 |
537+
|------|------|----------|
538+
| `(x: Type)` | 位置引数 | `foo("hi")` |
539+
| `(x: Type = default)` | オプショナル位置引数 | `foo()` または `foo("hi")` |
540+
| `(*args: Array<Type>)` | 残余パラメータ | `foo("a", "b", "c")` |
541+
| `(**{ x: Type })` | キーワード引数 | `foo(x: "hi")` |
542+
| `(**kwargs: Hash<Symbol, Type>)` | キーワード残余 | `foo(a: 1, b: 2)` |
543+
544+
**重要なポイント：**
545+
- **位置引数** `(x: Type)`: 順序で渡す
546+
- **キーワード引数** `(**{ x: Type })`: 名前で渡す
547+
- **キーワード残余** `(**kwargs: Hash<Symbol, Type>)`: 任意のキーワード引数をハッシュに収集
485548
- T-Rubyはすべてのパラメータのバリエーションに対して型安全性を保証します
486549

487550
これらのパターンをマスターして、使いやすい柔軟で型安全なAPIを作成しましょう。

0 commit comments

Comments
 (0)