Back to Details

zsh-script-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zsh Script Writer

Zsh脚本编写指南

Write Zsh scripts and ShellSpec tests following project standards.
遵循项目标准编写Zsh脚本与ShellSpec测试。

Script Structure

脚本结构

zsh
#!/bin/zsh
zsh
#!/bin/zsh

Copyright (C) 2026 Jim Chen Jim@ChenJ.im, licensed under GPL-3.0-or-later

Copyright (C) 2026 Jim Chen Jim@ChenJ.im, licensed under GPL-3.0-or-later

This program is free software: you can redistribute it and/or modify

This program is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

it under the terms of the GNU General Public License as published by

the Free Software Foundation, either version 3 of the License, or

the Free Software Foundation, either version 3 of the License, or

(at your option) any later version.

(at your option) any later version.

This program is distributed in the hope that it will be useful,

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

You should have received a copy of the GNU General Public License

along with this program. If not, see https://www.gnu.org/licenses/.

along with this program. If not, see https://www.gnu.org/licenses/.

==================================================================

==================================================================

[Script description and usage information]

[脚本描述与使用说明]

undefined
undefined

Coding Standards

编码规范

Error Handling & Output

错误处理与输出

zsh
undefined
zsh
undefined

Color codes for user feedback

Color codes for user feedback

RED='\033[0;31m'; YELLOW='\033[1;33m'; GRAY='\033[0;90m'; RESET='\033[0m'
RED='\033[0;31m'; YELLOW='\033[1;33m'; GRAY='\033[0;90m'; RESET='\033[0m'

Dependency check (fail fast)

Dependency check (fail fast)

if ! command -v tool_name >/dev/null 2>&1; then echo "${RED}ERROR: tool_name is required but not installed${RESET}" >&2 exit 1 fi

- Use color codes: RED (errors), YELLOW (warnings), GRAY (info), RESET
- Exit with non-zero codes on failure
- Write errors to stderr (`>&2`)
- Fail fast: validate inputs and dependencies before processing
if ! command -v tool_name >/dev/null 2>&1; then echo "${RED}ERROR: tool_name is required but not installed${RESET}" >&2 exit 1 fi

- 使用颜色代码：RED（错误）、YELLOW（警告）、GRAY（信息）、RESET
- 失败时返回非零退出码
- 将错误信息写入标准错误流（`>&2`）
- 快速失败：在处理前验证输入与依赖

Function Organization

函数组织

Organize scripts into logical sections:
  1. Utility functions (colors, logging, helpers)
  2. Content processing functions (core logic)
  3. Main execution function
  4. Parameter handling (getopts or positional args)
将脚本划分为逻辑模块：
  1. 工具函数（颜色、日志、辅助工具）
  2. 内容处理函数（核心逻辑）
  3. 主执行函数
  4. 参数处理（使用getopts或位置参数）

Working Directory Convention

工作目录约定

Scripts process files in 
$(pwd)
, NOT the script location. Use relative file patterns for cross-directory operation via PATH execution.
脚本在
$(pwd)
目录下处理文件，而非脚本所在位置。使用相对文件路径，以便通过PATH执行时支持跨目录操作。

API Integration

API集成

  • Rate limiting for API calls
  • Authentication via environment variables only (never hardcode)
  • Safe HTTP operations (GET only unless explicitly specified)
  • Temporary file handling with cleanup traps:
zsh
TMPFILE=$(mktemp)
trap "rm -f $TMPFILE" EXIT INT TERM
  • API调用需做速率限制
  • 仅通过环境变量进行身份验证（绝对禁止硬编码）
  • 安全的HTTP操作（除非明确指定，否则仅使用GET）
  • 使用清理陷阱处理临时文件：
zsh
TMPFILE=$(mktemp)
trap "rm -f $TMPFILE" EXIT INT TERM

Safety

安全性

  • Atomic operations where possible
  • Validate input parameters before processing
  • Clear error messages with suggested solutions
  • Prefer fail-fast behavior
  • 尽可能使用原子操作
  • 处理前验证输入参数
  • 提供清晰的错误信息及建议解决方案
  • 优先采用快速失败机制

Testing

测试

Use ShellSpec for BDD testing. Target 85%+ coverage.
For complete testing patterns, mocking strategies, and ShellSpec syntax: See references/testing-shellspec.md
使用ShellSpec进行BDD测试，目标测试覆盖率**≥85%**。
如需完整的测试模式、模拟策略及ShellSpec语法，请参阅：references/testing-shellspec.md

Quick Reference

快速参考

bash
undefined
bash
undefined

Run all tests

Run all tests

shellspec
shellspec

Run specific test

Run specific test

shellspec spec/script_name_spec.sh
shellspec spec/script_name_spec.sh

Run with coverage

Run with coverage

shellspec --kcov
shellspec --kcov

Verbose output

Verbose output

shellspec --format documentation
undefined
shellspec --format documentation
undefined

Critical Rule

重要规则

Always use 
When run script
for coverage measurement:
bash
undefined
为了统计测试覆盖率，请始终使用
When run script
：
bash
undefined

✅ Correct — coverage is measured

✅ 正确 — 会统计覆盖率

When run script "$SHELLSPEC_PROJECT_ROOT/script_name.zsh"
When run script "$SHELLSPEC_PROJECT_ROOT/script_name.zsh"

❌ Wrong — coverage NOT measured

❌ 错误 — 不会统计覆盖率

When run zsh "$SHELLSPEC_PROJECT_ROOT/script_name.zsh"
undefined
When run zsh "$SHELLSPEC_PROJECT_ROOT/script_name.zsh"
undefined