From 0dfbe69410ec9e8a3cef518e670bd7df008ac253 Mon Sep 17 00:00:00 2001 From: digital-teams Date: Mon, 4 Dec 2023 13:32:19 +0000 Subject: [PATCH] New Crowdin translations by GitHub Action (#523) --- i18n/ja/code.json | 492 ++++++++ .../options.json | 14 + .../current.json | 22 + .../current/02_zsh_plugin_standard.mdx | 532 +++++++++ .../03_zsh_native_scripting_handbook.mdx | 330 ++++++ .../current/99_contributors.mdx | 267 +++++ .../current/_category_.json | 7 + .../current/index.mdx | 30 + .../current.json | 18 + .../current/_category_.json | 7 + .../current/annexes/0_overview.mdx | 169 +++ .../current/annexes/19_eval.mdx | 125 ++ .../current/annexes/1_bin_gem_node.mdx | 568 +++++++++ .../current/annexes/20_test.mdx | 52 + .../current/annexes/2_meta_plugins.mdx | 243 ++++ .../current/annexes/3_default_ice.mdx | 76 ++ .../current/annexes/4_patch-dl.mdx | 72 ++ .../current/annexes/5_readurl.mdx | 131 +++ .../current/annexes/6_submods.mdx | 54 + .../current/annexes/7_unscope.mdx | 161 +++ .../current/annexes/8_linkbin.mdx | 102 ++ .../current/annexes/9_rust.mdx | 164 +++ .../current/annexes/_category_.json | 7 + .../current/index.mdx | 26 + .../current/packages/01_synopsis.mdx | 143 +++ .../current/packages/02_usage.mdx | 1022 +++++++++++++++++ .../current/packages/_category_.json | 7 + .../current.json | 18 + .../getting_started/01_installation.mdx | 281 +++++ .../current/getting_started/02_overview.mdx | 509 ++++++++ .../current/getting_started/03_migration.mdx | 476 ++++++++ .../current/getting_started/_category_.json | 7 + .../current/guides/01_commands.mdx | 262 +++++ .../current/guides/02_customization.mdx | 331 ++++++ .../current/guides/03_benchmark.mdx | 137 +++ .../current/guides/_category_.json | 7 + .../current/guides/syntax/01_standard.mdx | 801 +++++++++++++ .../current/guides/syntax/02_for.mdx | 266 +++++ .../guides/syntax/03_ice_modifiers.mdx | 227 ++++ .../current/guides/syntax/10_bindkey.mdx | 143 +++ .../current/guides/syntax/_category_.json | 7 + .../current/index.mdx | 127 ++ .../current/zi_code.mdx | 85 ++ i18n/ja/docusaurus-theme-classic/footer.json | 66 ++ i18n/ja/docusaurus-theme-classic/navbar.json | 22 + i18n/zh-Hans/code.json | 492 ++++++++ .../options.json | 14 + .../current.json | 22 + .../current/02_zsh_plugin_standard.mdx | 532 +++++++++ .../03_zsh_native_scripting_handbook.mdx | 330 ++++++ .../current/99_contributors.mdx | 267 +++++ .../current/_category_.json | 7 + .../current/index.mdx | 30 + .../current.json | 18 + .../current/_category_.json | 7 + .../current/annexes/0_overview.mdx | 169 +++ .../current/annexes/19_eval.mdx | 125 ++ .../current/annexes/1_bin_gem_node.mdx | 568 +++++++++ .../current/annexes/20_test.mdx | 52 + .../current/annexes/2_meta_plugins.mdx | 243 ++++ .../current/annexes/3_default_ice.mdx | 76 ++ .../current/annexes/4_patch-dl.mdx | 72 ++ .../current/annexes/5_readurl.mdx | 131 +++ .../current/annexes/6_submods.mdx | 54 + .../current/annexes/7_unscope.mdx | 161 +++ .../current/annexes/8_linkbin.mdx | 102 ++ .../current/annexes/9_rust.mdx | 164 +++ .../current/annexes/_category_.json | 7 + .../current/index.mdx | 26 + .../current/packages/01_synopsis.mdx | 143 +++ .../current/packages/02_usage.mdx | 1022 +++++++++++++++++ .../current/packages/_category_.json | 7 + .../current.json | 18 + .../getting_started/01_installation.mdx | 281 +++++ .../current/getting_started/02_overview.mdx | 510 ++++++++ .../current/getting_started/03_migration.mdx | 476 ++++++++ .../current/getting_started/_category_.json | 7 + .../current/guides/01_commands.mdx | 262 +++++ .../current/guides/02_customization.mdx | 331 ++++++ .../current/guides/03_benchmark.mdx | 137 +++ .../current/guides/_category_.json | 7 + .../current/guides/syntax/01_standard.mdx | 801 +++++++++++++ .../current/guides/syntax/02_for.mdx | 266 +++++ .../guides/syntax/03_ice_modifiers.mdx | 227 ++++ .../current/guides/syntax/10_bindkey.mdx | 143 +++ .../current/guides/syntax/_category_.json | 7 + .../current/index.mdx | 127 ++ .../current/zi_code.mdx | 85 ++ .../docusaurus-theme-classic/footer.json | 66 ++ .../docusaurus-theme-classic/navbar.json | 22 + 90 files changed, 17227 insertions(+) create mode 100644 i18n/ja/code.json create mode 100644 i18n/ja/docusaurus-plugin-content-blog/options.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs-community/current.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-community/current/99_contributors.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-community/current/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs-community/current/index.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/index.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/getting_started/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/01_commands.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/02_customization.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/index.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/zi_code.mdx create mode 100644 i18n/ja/docusaurus-theme-classic/footer.json create mode 100644 i18n/ja/docusaurus-theme-classic/navbar.json create mode 100644 i18n/zh-Hans/code.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-blog/options.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-community/current.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/99_contributors.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/index.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/index.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/01_commands.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/02_customization.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/zi_code.mdx create mode 100644 i18n/zh-Hans/docusaurus-theme-classic/footer.json create mode 100644 i18n/zh-Hans/docusaurus-theme-classic/navbar.json diff --git a/i18n/ja/code.json b/i18n/ja/code.json new file mode 100644 index 00000000..7ccd1e1b --- /dev/null +++ b/i18n/ja/code.json @@ -0,0 +1,492 @@ +{ + "homepage.feature1.title": { + "message": "Zshの起動を50-80%高速化", + "description": "Title of feature 1 (left) on the home page" + }, + "home.feature1": { + "message": ".zshrcの読み込みが終わってプロンプトが出るまでプラグインのロードを延期する", + "description": "Description of first featured banner in homepage" + }, + "homepage.feature2.title": { + "message": "大事なことに集中する", + "description": "Title of feature 2 (middle) on the home page" + }, + "home.feature2": { + "message": "プラグインが設定した関数、バインドキー、補完、その他の要素などプラグインに関する統計情報について説明します。", + "description": "Description of second featured banner in homepage" + }, + "homepage.feature3.title": { + "message": "幅広い特徴", + "description": "Title of feature 3 (right) on the home page" + }, + "home.feature3": { + "message": "Oh-My-ZshとPreztoをサポートします。フレームワーク固有ではありません。プラグイン、ライブラリ、テーマを簡単に作成できます。", + "description": "Description of third featured banner in homepage" + }, + "homepage.hero.title": { + "message": "A Swiss Army Knife for Zsh Unix Shell", + "description": "Home page hero title, can contain simple html tags" + }, + "homepage.banner.button.1": { + "message": "はじめに", + "description": "The homepage get started button" + }, + "homepage.banner.button.2": { + "message": "コミュニティ", + "description": "The homepage community button" + }, + "homepage.video.heading.1": { + "message": "高速かつ豊富な機能", + "description": "The homepage video container heading 1" + }, + "theme.ErrorPageContent.title": { + "message": "ページがクラッシュしました。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "ページトップへ戻る", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "アーカイブ", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "アーカイブ", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "ブログ記事一覧のナビゲーション", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "新しい記事", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "過去の記事", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "ブログ記事のナビゲーション", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "新しい記事", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "過去の記事", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "{count}件", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "「{tagName}」タグの記事が{nPosts}あります", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "全てのタグを見る", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel": { + "message": "ダークモードとライトモードの切り替え(現在は {mode})", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "ダークモード", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "ライトモード", + "description": "The name for the light color mode" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "パンくずリストのナビゲーション", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription": { + "message": "{count} 件", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "Docs pages", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "前へ", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "次へ", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "このタグのドキュメント1件 | このタグのドキュメント {count} 件", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "「{tagName}」が{nDocsTagged} あります", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "バージョン: {versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "これはリリース前の{siteTitle} {versionLabel}のドキュメントです。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "これは{siteTitle} {versionLabel}のドキュメントで現在はアクティブにメンテナンスされていません。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新のドキュメントは{latestVersionLink} ({versionLabel}) を見てください。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新バージョン", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "このページを編集", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "Direct link to {heading}", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "{date}に", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "{user}が", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "{atDate}{byUser}最終更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "バージョン", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "ページが見つかりません", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "タグ:", + "description": "The label alongside a tag list" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "危険", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "info", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "备注", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "tip", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "warning", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "閉じる", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近のブログ記事", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.CodeBlock.copied": { + "message": "コピーしました", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "クリップボードにコードをコピー", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "コピー", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "折り返し", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "Expand sidebar category '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "Collapse sidebar category '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "Main", + "description": "The ARIA label for the main navigation" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "言語", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.NotFound.p1": { + "message": "お探しのページが見つかりませんでした。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "このページにリンクしているサイトの所有者に連絡をしてリンクが壊れていることを伝えてください。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "目次", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "もっと見る", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "{title} について詳しく見る", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "約{readingTime}分", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.breadcrumbs.home": { + "message": "ホームページ", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "サイドバーを隠す", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "サイドバーを隠す", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "Docs sidebar", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "ナビゲーションバーを閉じる", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← メインメニューに戻る", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "ナビゲーションバーの切り替え", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "サイドバーを開く", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "サイドバーを開く", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.SearchBar.seeAll": { + "message": "{count} 件の結果を見る" + }, + "theme.SearchPage.documentsFound.plurals": { + "message": "{count}件のドキュメントが見つかりました", + "description": "Pluralized label for \"{count} documents found\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.SearchPage.existingResultsTitle": { + "message": "『{query}』の検索結果", + "description": "The search page title for non-empty query" + }, + "theme.SearchPage.emptyResultsTitle": { + "message": "ドキュメントを検索", + "description": "The search page title for empty query" + }, + "theme.SearchPage.inputPlaceholder": { + "message": "ここに検索するキーワードを入力してください", + "description": "The placeholder for search page input" + }, + "theme.SearchPage.inputLabel": { + "message": "検索", + "description": "The ARIA label for search page input" + }, + "theme.SearchPage.algoliaLabel": { + "message": "Algoliaで検索", + "description": "The ARIA label for Algolia mention" + }, + "theme.SearchPage.noResultsText": { + "message": "検索結果が見つかりませんでした", + "description": "The paragraph for empty search result" + }, + "theme.SearchPage.fetchingNewResults": { + "message": "新しい検索結果を取得しています...", + "description": "The paragraph for fetching new search results" + }, + "theme.SearchBar.label": { + "message": "検索", + "description": "The ARIA label and placeholder for search button" + }, + "theme.SearchModal.searchBox.resetButtonTitle": { + "message": "クリア", + "description": "The label and ARIA label for search box reset button" + }, + "theme.SearchModal.searchBox.cancelButtonText": { + "message": "キャンセル", + "description": "The label and ARIA label for search box cancel button" + }, + "theme.SearchModal.startScreen.recentSearchesTitle": { + "message": "最近の検索", + "description": "The title for recent searches" + }, + "theme.SearchModal.startScreen.noRecentSearchesText": { + "message": "最近の検索履歴はありません", + "description": "The text when no recent searches" + }, + "theme.SearchModal.startScreen.saveRecentSearchButtonTitle": { + "message": "この検索をお気に入りに追加", + "description": "The label for save recent search button" + }, + "theme.SearchModal.startScreen.removeRecentSearchButtonTitle": { + "message": "この検索を履歴から削除", + "description": "The label for remove recent search button" + }, + "theme.SearchModal.startScreen.favoriteSearchesTitle": { + "message": "お気に入り", + "description": "The title for favorite searches" + }, + "theme.SearchModal.startScreen.removeFavoriteSearchButtonTitle": { + "message": "この検索をお気に入りから削除", + "description": "The label for remove favorite search button" + }, + "theme.SearchModal.errorScreen.titleText": { + "message": "検索結果の取得に失敗しました", + "description": "The title for error screen of search modal" + }, + "theme.SearchModal.errorScreen.helpText": { + "message": "ネットワーク接続を確認してください", + "description": "The help text for error screen of search modal" + }, + "theme.SearchModal.footer.selectText": { + "message": "選ぶ", + "description": "The explanatory text of the action for the enter key" + }, + "theme.SearchModal.footer.selectKeyAriaLabel": { + "message": "エンターキー", + "description": "The ARIA label for the Enter key button that makes the selection" + }, + "theme.SearchModal.footer.navigateText": { + "message": "移動", + "description": "The explanatory text of the action for the Arrow up and Arrow down key" + }, + "theme.SearchModal.footer.navigateUpKeyAriaLabel": { + "message": "上矢印キー", + "description": "The ARIA label for the Arrow up key button that makes the navigation" + }, + "theme.SearchModal.footer.navigateDownKeyAriaLabel": { + "message": "下矢印キー", + "description": "The ARIA label for the Arrow down key button that makes the navigation" + }, + "theme.SearchModal.footer.closeText": { + "message": "閉じる", + "description": "The explanatory text of the action for Escape key" + }, + "theme.SearchModal.footer.closeKeyAriaLabel": { + "message": "エスケープキー", + "description": "The ARIA label for the Escape key button that close the modal" + }, + "theme.SearchModal.footer.searchByText": { + "message": "検索", + "description": "The text explain that the search is making by Algolia" + }, + "theme.SearchModal.noResultsScreen.noResultsText": { + "message": "見つかりませんでした", + "description": "The text explains that there are no results for the following search" + }, + "theme.SearchModal.noResultsScreen.suggestedQueryText": { + "message": "次の検索を試す:", + "description": "The text for the suggested query when no results are found for the following search" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsText": { + "message": "よりよい検索結果がありますか?", + "description": "The text for the question where the user thinks there are missing results" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsLinkText": { + "message": "報告する", + "description": "The text for the link to report missing results" + }, + "theme.SearchModal.placeholder": { + "message": "ドキュメントを検索", + "description": "The placeholder of the input of the DocSearch pop-up modal" + }, + "theme.IdealImageMessage.loading": { + "message": "読み込み中…", + "description": "When the full-scale image is loading" + }, + "theme.IdealImageMessage.load": { + "message": "クリックして{sizeMessage} を読み込む", + "description": "To prompt users to load the full image. sizeMessage is a parenthesized size figure." + }, + "theme.IdealImageMessage.offline": { + "message": "お使いのブラウザはオフラインです。画像が読み込まれません", + "description": "When the user is viewing an offline document" + }, + "theme.IdealImageMessage.404error": { + "message": "404. 画像が見つかりません", + "description": "When the image is not found" + }, + "theme.IdealImageMessage.error": { + "message": "エラー クリックで再読み込み", + "description": "When the image fails to load for unknown error" + }, + "theme.PwaReloadPopup.info": { + "message": "新しいバージョンが取得可能", + "description": "The text for PWA reload popup" + }, + "theme.PwaReloadPopup.refreshButtonText": { + "message": "更新", + "description": "The text for PWA reload button" + }, + "theme.PwaReloadPopup.closeButtonAriaLabel": { + "message": "閉じる", + "description": "The ARIA label for close button of PWA reload popup" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "やり直す", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "メインコンテンツまでスキップ", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "タグ", + "description": "The title of the tag list page" + }, + "theme.unlistedContent.title": { + "message": "Unlisted page", + "description": "The unlisted content banner title" + }, + "theme.unlistedContent.message": { + "message": "This page is unlisted. Search engines will not index it, and only users having a direct link can access it.", + "description": "The unlisted content banner message" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-blog/options.json b/i18n/ja/docusaurus-plugin-content-blog/options.json new file mode 100644 index 00000000..7abfbdd6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-blog/options.json @@ -0,0 +1,14 @@ +{ + "title": { + "message": "ブログ", + "description": "The title for the blog used in SEO" + }, + "description": { + "message": "ブログ", + "description": "The description for the blog used in SEO" + }, + "sidebar.title": { + "message": "最近の投稿", + "description": "The label for the left sidebar" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs-community/current.json b/i18n/ja/docusaurus-plugin-content-docs-community/current.json new file mode 100644 index 00000000..ddc3b3e1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-community/current.json @@ -0,0 +1,22 @@ +{ + "version.label": { + "message": "次へ", + "description": "The label for version current" + }, + "sidebar.SideBar.category.📖 Zsh User's Guide": { + "message": "📖 Zsh ユーザーガイド", + "description": "The label for category 📖 Zsh User's Guide in sidebar SideBar" + }, + "sidebar.SideBar.category.🎯 Roadmap": { + "message": "🎯ロードマップ", + "description": "The label for category 🎯 Roadmap in sidebar SideBar" + }, + "sidebar.SideBar.category.✨ Gallery of Invocations": { + "message": "✨ 呼び出しの一覧", + "description": "The label for category ✨ Gallery of Invocations in sidebar SideBar" + }, + "sidebar.SideBar.category.✨ Collection": { + "message": "✨ コレクション", + "description": "The label for category ✨ Collection in sidebar SideBar" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx b/i18n/ja/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx new file mode 100644 index 00000000..1844805d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx @@ -0,0 +1,532 @@ +--- +id: zsh_plugin_standard +title: ℹ️ Zsh プラグイン標準 +sidebar_position: 2 +image: /img/png/theme/z/320x320.png +toc_max_heading_level: 2 +keywords: + - zsh + - create + - plugin + - zsh-plugin + - ベストプラクティス + - create-zsh-plugin + - zsh-plugin-standard +--- + + + +## Zshプラグインとは何か + +歴史的に、ZshプラグインはOh My Zshによって最初に定義されました。 They provide a way to package together files that extend or configure the shell’s functionality in a particular way. + +簡単なレベルでは、プラグインは: + +1. Has directory added to `$fpath` ([Zsh documentation: #Autoloading-Functions][autoloading-functions]). This is being done either by a plugin manager or by the plugin itself (see [5th section](#run-on-unload-call) for more information). + +2. Has first `*.plugin.zsh` file sourced (or `*.zsh`, `init.zsh`, `*.sh`, these are non-standard). + + 2.1 The first point allows plugins to provide completions and functions that are loaded via Zsh’s `autoload` mechanism (a single function per file). + +3. より広い観点からは見ると、プラグインは次のもので構成されています: + + 3.1. a directory containing various files (the main script, autoload functions, completions, Makefiles, backend programs, documentation). + + 3.2. a source-able script that obtains the path to its directory via `$0` (see the [next section](#zero-handling) for a related enhancement proposal). + + 3.3. GitHub (or another site) repository identified by two components **username**/**plugin-name**. + + 3.4. software package containing any type of command line artifacts – when used with advanced plugin managers that have hooks, can run Makefiles, and add directories to `$PATH`. + +Below follow the proposed enhancements and codifications of the definition of a "Zsh the plugin" and the actions of plugin managers – the proposed standardization. + +Zshプラグインの書き方に関する情報を網羅しています。 + +## 1. Standardized `$0` handling {#zero-handling} + +> [ zero-handling ] + +プラグインのロケーションを取得するには、プラグインで以下を実行します: + +```shell showLineNumbers +0="${ZERO:-${${0:#$ZSH_ARGZERO}:-${(%):-%N}}}" +0="${${(M)0:#/*}:-$PWD/$0}" +``` + +Then `${0:h}` to get the plugin’s directory. + +上記のワンラインコードは次のとおりです: + +1. Be backward-compatible with normal `$0` setting and usage. + +2. Use `ZERO` if it’s not empty, + + 2.1. the plugin manager will be easily able to alter effective `$0` before loading a plugin, + + 2.2. this allows e.g. `eval "$( [ functions-directory ] + +Despite that, the current-standard plugins have their main directory added to `$fpath`, a more clean approach is being proposed: that the plugins use a subdirectory called `functions` to store their completions and autoload functions. This will allow a much cleaner design of plugins. The plugin manager should add such a directory to `$fpath`. The lack of support of the current plugin managers can be easily resolved via the [indicator](#indicator): + +```shell showLineNumbers +if [[ ${zsh_loaded_plugins[-1]} != */kalc && -z ${fpath[(r)${0:h}/functions]} ]]; then + fpath+=( "${0:h}/functions" ) +fi +``` + +or, via use of the `PMSPEC` [parameter](#pmspec): + +```shell showLineNumbers +if [[ $PMSPEC != *f* ]]; then + fpath+=( "${0:h}/functions" ) +fi +``` + +The above snippet added to the `plugin.zsh` file will add the directory to the `$fpath` with the compatibility with any new plugin managers preserved. The existence of the `functions` subdirectory cancels the normal adding of the main plugin directory to `$fpath`. + +### **STATUS:** [ functions-directory ] + +- GitHub Search: [zsh_loaded_plugins](https://github.com/search?q=%22$zsh_loaded_plugins%22&type=code) +- GitHub Search: [PMSPEC \*f\*](https://github.com/search?q=[[%20%22$PMSPEC%22%20!=%20*f*%20]]&type=code) + +## 3. Binaries directory {#binaries-directory} + +> [ binaries-directory ] + +Plugins sometimes provide a runnable script or program, either for their internal use or for the end-user. It is proposed that for the latter, the plugin shall use a `bin/` subdirectory inside its main dir (it is recommended, that for internal use, the runnable be called via the `$0` value obtained as described above). + +The runnable should be put into the directory with a `+x` access right assigned. The task of the plugin manager should be: + +1. Before sourcing the plugin’s script it should test, if the `bin/` directory exists within the plugin directory. + +2. If it does, it should add the directory to `$PATH`. + +3. The plugin manager can also, instead of extending the `$PATH`, create a **shim** (i.e.: a forwarder script) or a symbolic link inside a common directory that’s already added to `$PATH` (to limit extending it). + +4. The plugin manager is permitted to do optional things like ensuring `+x` access rights on the directory contents. The `$PMSPEC` code letter for the feature is `b`, and it allows for the plugin to handle the `$PATH` extending itself, via, e.g.: + +```shell showLineNumbers +if [[ $PMSPEC != *b* ]]; then + path+=( "${0:h}/bin" ) +fi +``` + +### **STATUS:** [ binaries-directory ] + +- GitHub Search: [PMSPEC \*b\*](https://github.com/search?q=[[%20%22$PMSPEC%22%20!=%20*b*%20]]&type=code) + +## 4. Unload function {#unload-function} + +> [ unload-function ] + +If a plugin is named e.g. `kalc` (and is available via `any-user/kalc` plugin-ID), then it can provide a function, `kalc_plugin_unload`, that can be called by a plugin manager to undo the effects of loading that plugin. + +A plugin manager can implement its tracking of changes made by a plugin so this is in general optional. However, to properly unload e.g. a prompt, dedicated tracking (easy to do for the plugin creator) can provide better, predictable results. Any special, uncommon effects of loading a plugin are possible to undo only by a dedicated function. + +However, an interesting compromise approach is available – to withdraw only the special effects of loading a plugin via the dedicated, plugin-provided function and leave the rest to the plugin manager. The value of such an approach is that maintaining such function (if it is to withdraw **all** plugin side-effects) can be a daunting task requiring constant monitoring of it during the plugin development process. + +Note that the unload function should contain `unfunction $0` (or better `unfunction kalc_plugin_unload` etc., for compatibility with the `*_argzero` options), to also delete the function itself. + +### **STATUS:** [ unload-function ] {#unload-function} + +- [Zi][] implements plugin unloading and calls the function. + +- [romkatv/powerlevel10k is using][] the function to execute a specific task: shutdown of the binary, background [gitstatus][] daemon, with very good results, + +- [agkozak/agkozak-zsh-prompt is using][] the function to completely unload the prompt, + +- [agkozak/zsh-z is using][] the function to completely unload the plugin, + +- [agkozak/zhooks is using][] the function to completely unload the plugin. + +## 5. `@zsh-plugin-run-on-unload` call {#run-on-unload-call} + +> [ run-on-unload-call ] + +The plugin manager can provide a function `@zsh-plugin-run-on-unload` which has the following call syntax: + +```shell +@zsh-plugin-run-on-unload "{code-snippet-1}" "{code-snippet-2}" … +``` + +The function registers pieces of code to be run by the plugin manager **on the unloading of the plugin**. The execution of the code should be done by the `eval` built-in in the same order as they are passed to the call. The code should be executed in the plugin’s directory, in the current shell. The mechanism thus provides another way, side to the [unload function](#unload-function), for the plugin to participate in the process of unloading it. + +### **STATUS:** [ run-on-unload-call ] + +- GitHub Search: [zsh-plugin-run-on-unload](https://github.com/search?q=@zsh-plugin-run-on-unload&type=code) + +## 6. `@zsh-plugin-run-on-update` call {#run-on-update-call} + +> [ run-on-update-call ] + +The plugin manager can provide a function `@zsh-plugin-run-on-update` which has the following call syntax: + +```shell +@zsh-plugin-run-on-update "{code-snippet-1}" "{code-snippet-2}" … +``` + +The function registers pieces of code to be run by the plugin manager on an update of the plugin. The execution of the code should be done by the `eval` built-in in the same order as they are passed to the call. The code should be executed in the plugin’s directory, possibly in a subshell **After downloading any new commits** to the repository. + +### **STATUS:** [ run-on-update-call ] + +- GitHub Search: [zsh-plugin-run-on-update](https://github.com/search?q=@zsh-plugin-run-on-update&type=code) + +## 7. Plugin manager activity indicator {#activity-indicator} + +> [ activity-indicator ] + +Plugin managers should set the `$zsh_loaded_plugins` array to contain all previously loaded plugins and the plugin currently being loaded (as the last element). + +This will allow any plugin to: + +1. Check which plugins are already loaded. + +2. Check if it is being loaded by a plugin manager (i.e. not just sourced). + +The first item allows a plugin to e.g. issue a notice about missing dependencies. Instead of issuing a notice, it may be able to satisfy the dependencies on resources it provides. For example, the `pure` prompt provides a `zsh-async` dependency library within its source tree, which is normally a separate project. Consequently, the prompt can decide to source its private copy of `zsh-async`, having also reliable `$0` defined by the previous section (note: `pure` doesn’t normally do this). + +The second item allows a plugin to e.g. set up `$fpath`, knowing that the plugin manager will not handle this: + +```shell showLineNumbers +if [[ ${zsh_loaded_plugins[-1]} != */kalc && -z ${fpath[(r)${0:h}]} ]]; then + fpath+=( "${0:h}" ) +fi +``` + +This will allow the user to reliably source the plugin without using a plugin manager. The code uses the wrapping braces around variables (i.e.: e.g.: `${fpath…}`) to make it compatible with the `KSH_ARRAYS` option and the quoting around `${0:h}` to make it compatible with the `SH_WORD_SPLIT` option. + +### **STATUS:** [ activity-indicator ] + +- GitHub Search: [zsh_loaded_plugins](https://github.com/search?q=%22${zsh_loaded_plugins[-1]}%22&type=code) + +## 8. Global parameter with PREFIX for make, configure, etc {#global-parameter-with-prefix} + +> [ global-parameter-with-prefix ] + +Plugin managers may export the parameter `$ZPFX` which should contain a path to a directory dedicated to user-land software, i.e. for directories `$ZPFX/bin`, `$ZPFX/lib`, `$ZPFX/share`, etc. The suggested name of the directory is `polaris` (e.g.: Zi uses this name and places this directory at `~/.zi/polaris` by default). + +Users can then configure hooks to invoke e.g. `make PREFIX=$ZPFX install` at clone & update the plugin to install software like e.g. [tj/git-extras][]. This is the developing role of Zsh plugin managers as package managers, where `.zshrc` has a similar role to Chef or Puppet configuration and allows to **declare** system state, and have the same state on different accounts/machines. + +No-narration facts-list related to `$ZPFX`: + +1. `export ZPFX="$HOME/polaris"` (or e.g. `$HOME/.zi/polaris`) + +2. `make PREFIX=$ZPFX install` + +3. `./configure --prefix=$ZPFX` + +4. `cmake -DCMAKE_INSTALL_PREFIX=$ZPFX .` + +5. `zi ice make"PREFIX=$ZPFX install"` + +6. `zi … hook-build:"make PREFIX=$PFX install"` + +### **STATUS:** [ global-parameter-with-prefix ] + +- GitHub Search: [ZPFX](https://github.com/search?q=%22$ZPFX%22&type=code) + +## 9. Global parameter holding the plugin manager’s capabilities {#global-parameter-with-capabilities} + +> [ global-parameter-with-capabilities ] + +The above paragraphs of the standard spec each constitute a capability, a feature of the plugin manager. It would make sense that the capabilities are somehow discoverable. To address this, a global parameter called `PMSPEC` (from _plugin-manager specification_) is proposed. It can hold the following Latin letters each informing the plugin, that the plugin manager has support for a given feature: + +- `0` – the plugin manager provides the `ZERO` parameter, + +- `f` - … supports the `functions/` subdirectory, + +- `b` - … supports the `bin/` subdirectory, + +- `u` - … the unload function, + +- `U` - … the `@zsh-plugin-run-on-unload` call, + +- `p` – … the `@zsh-plugin-run-on-update` call, + +- `i` – … the `zsh_loaded_plugins` activity indicator, + +- `b` – … the `ZPFX` global parameter, + +- `s` – … the `PMSPEC` global parameter itself (i.e.: should be always present). + +The contents of the parameter describing a fully-compliant plugin manager should be: `0fuUpiPs`. + +The plugin can then verify the support by: + +```shell showLineNumbers +if [[ $PMSPEC != *P* ]]; then + path+=( "${0:h}/bin" ) +fi +``` + +### **STATUS:** [ global-parameter-with-capabilities ] + +- GitHub Search: [PMSPEC](https://github.com/search?q=%22export+PMSPEC=%22&type=code) + +## Zsh plugin-programming best practices + +The document is to define a **Zsh-plugin** but also to serve as an information source for plugin creators. Therefore, it covers also best practices information in this section. + +## Use of `add-zsh-hook` to install hooks + +Zsh ships with the function `add-zsh-hook`. It has the following invocation syntax: + +```shell +add-zsh-hook [ -L | -dD ] [ -Uzk ] hook function +``` + +The command installs a `function` as one of the supported zsh `hook` entries. which are one of: `chpwd`, `periodic`, `precmd`, `preexec`, `zshaddhistory`, `zshexit`, `zsh_directory_name`. For their meaning refer to the [Zsh documentation: #Hook-Functions][hook-functions]. + +## Use of `add-zle-hook-widget` to install Zle Hooks + +The zle editor is the part of the Zsh that is responsible for receiving the text from the user. It can be said that it’s based on widgets, which are nothing more than Zsh functions that are allowed to be run in Zle context, i.e. from the Zle editor (plus a few minor differences, like e.g.: the `$WIDGET` parameter that’s automatically set by the Zle editor). + +The syntax of the call is: + +```shell +add-zle-hook-widget [ -L | -dD ] [ -Uzk ] hook widgetname +``` + +The call resembles the syntax of the `add-zsh-hook` function. The only difference is that it takes a `widgetname`, not a function name and that the `hook` is one of: `isearch-exit`, `isearch-update`, `line-pre-redraw`, `line-init`, `line-finish`, `history-line-set`, or `keymap-select`. Their meaning is explained in the [Zsh documentation: #Special-Widgets][special-widgets]. + +The use of this function is recommended because it allows the installation **multiple** hooks per each `hook` entry. Before introducing the `add-zle-hook-widget` function the "normal" way to install a hook was to define a widget with the name of one of the special widgets. Now, after the function has been introduced in Zsh `5.3` it should be used instead. + +## 一般的なパラメーターの命名 + +There’s a convention already present in the Zsh world – to name array variables lowercase and scalars uppercase. It’s being followed by e.g.: the Zsh manual and the Z shell itself (e.g.: `REPLY` scalar and `reply` array, etc.). + +The requirement for the scalars to be uppercase should be, in my opinion, kept only for the global parameters. e.g.: it’s fine to name local parameters inside a function lowercase even when they are scalars, not only arrays. + +An extension to the convention is being proposed: to name associative arrays (i.e.: hashes) capitalized, i.e.: with only the first letter uppercase and the remaining letters lowercase. + +See [the next section](#standard-plugins-hash) for an example of such hash. In the case of the name consisting of multiple words each of them should be capitalized, e.g.: `typeset -A MyHash`. + +This convention will increase code readability and bring order to it. + +## Standard `Plugins` hash + +The plugin often has to declare global parameters that should live throughout a Zsh session. Following the [namespace pollution prevention](#preventing-function-pollution) the plugin could use a hash to store the different values. Additionally, the plugins could use a single hash parameter – called `Plugins` – to prevent pollution. + +An example value needed by the plugin: + +```shell showLineNumbers +typeset -gA Plugins +Plugins[MY_PLUGIN_REPO_DIR]="${0:h}" +``` + +This way all the data of all plugins will be kept in a single parameter, available for easy examination and overview (via e.g.: `varied Plugins`), and also not polluting the namespace. + +## Standard recommended [options][] + +The following code snippet is recommended to be included at the beginning of each of the main functions provided by the plugin: + +```shell showLineNumbers +builtin emulate -L zsh ${=${options[xtrace]:#off}:+-o xtrace} +builtin setopt extended_glob warn_create_global typeset_silent no_short_loops rc_quotes no_auto_pushd +``` + +It resets all the options to their default state according to the `zsh` emulation mode, with the use of the `local_options` option – so the options will be restored to their previous state when leaving the function. It then alters the emulation by `7` different options: + +- `${=${options[xtrace]:#off}:+-o xtrace}` – `xtrace` prints commands and their arguments as they are executed, this specific variable calls `xtrace` when needed, e.g.: when already active at the entry to the function. + +- `extended_glob` – enables one of the main Zshell features – the advanced, built-in regex-like globing mechanism, + +- `warn_create_global` – enables warnings to be printed each time a (global) variable is defined without being explicitly defined by a `typeset`, `local`, `declare`, etc. call; it allows to catch typos and missing localizations of the variables and thus prevent from writing a bad code, + +- `typeset_silent` – it allows to call `typeset`, `local`, etc. multiple times on the same variable; without it, the second call causes the variable contents to be printed first; using this option allows declaring variables inside loops, near the place of their use, which sometimes helps to write a more readable code, + +- `no_short_loops` – disables the short-loops syntax; this is done because when the syntax is enabled it limits the parser’s ability to detect errors (see this [zsh-workers post][] for the details), + +- `rc_quotes` – adds useful ability to insert apostrophes into an apostrophe-quoted string, by use of `''` inside it, e.g.: `'a string’s example'` will yield the string `a string’s example`, + +- `no_auto_pushd` - disables the automatic push of the directory passed to `cd` builtin onto the directory stack; this is useful because otherwise, the internal directory changes done by the plugin will pollute the global directory stack. + +## Standard recommended variables + +It’s good to localize the following variables at the entry of the main function of a plugin: + +```shell showLineNumbers +local MATCH REPLY; integer MBEGIN MEND +local -a match mbegin mend reply +``` + +The variables starting with `m` and `M` are being used by the substitutions utilizing `(#b)` and `(#m)` flags, respectively. They should not leak to the global scope. Also, their automatic creation would trigger the warning from the `warn_create_global` option. + +The `reply` and `REPLY` parameters are normally used to return an array or a scalar from a function, respectively – it’s the standard way of passing values from functions. + +Their use is naturally limited to the functions called from the main function of a plugin – they should not be used to pass data around e.g.: in between prompts, thus it’s natural to localize them in the main function. + +## Standard function name-space prefixes + +The recommendation is the purely subjective opinion of the author. + +It can evolve – if you have any remarks, don’t hesitate to [fill them](https://github.com/z-shell/zw/issues/new). + +## The problems solved by the proposition + +However, when adopted, the proposition will solve the following issues: + +1. Using the underscore `_` to namespace functions – this isn’t the right thing to do because the prefix is being already used by the completion functions, so the namespace is already filled up greatly and the plugin functions get lost in it. + +2. Not using a prefix at all – this is also an unwanted practice as it pollutes the command namespace of such an issue appearing. + +3. It would allow quickly discriminate between function types – e.g.: seeing the `:` prefix informs the user that it’s a hook-type function while seeing the `@` prefix informs the user that it’s an API-like function, etc. + +4. It also provides an improvement during programming, by allowing to quickly limit the number of completions offered by the editor, e.g.: for Vim’s Ctrl-P completing, when entering +Ctrl-P, then only a subset of the functions are being completed (see below for the type of the functions). **Note:** the editor has to be configured so that it accepts such special characters as part of keywords, for Vim it’s: `:set isk+=@-@,.,+,/,:` for all of the proposed prefixes. + +## The Proposed function-name prefixes + +The proposition of the standard prefixes is as follows: + +1. `.`: for regular private functions. Example function: `.prompt_zinc_get_value`. + +2. `→`: for hook-like functions, so it should be used e.g.: for the [Zsh hooks](#use-of-add-zsh-hook-to-install-hooks) and the [Zle hooks](#use-of-add-zle-hook-widget-to-install-zle-hooks), but also any other, custom hook-like mechanism in the plugin. Example function name: `→prompt_zinc_precmd`. + + 2.1. the previous version of the document recommended colon (`:`) for the prefix, however, it was problematic, because Windows doesn’t allow colons in file names, so it wasn’t possible to name an autoload function this way, + + 2.2. the arrow has a rationale behind it - it denotes the execution **coming back** to the function at a later time after it has been registered as a callback or a handler, + + 2.3. the arrow is easy to type on most keyboard layouts – it is Right-Alt+I; in case of problems with typing the character can be always copied – handler functions do occur in the code rarely, + + 2.4. Zsh supports any string as a function name because absolutely any string can be a **file** name – if there would be an exception in the name of the call-ables, then how would it be possible to run a script called "→abcd"? There are **no** exceptions, the function can be called even as a sequence of null bytes: + + ```shell showLineNumbers + ❯ $'\0'() { print hello } + ❯ $'\0' + hello + ``` + +3. `+`: for output functions, i.e.: for functions that print to the standard output and error or a log, etc. Example function name: `+prompt_zinc_output_segment`. + +4. `/`: for debugging functions, i.e: for functions that output debugs messages to the screen or a log or e.g.: gather some debug data. **Note:** the slash makes it impossible for such functions to be auto-loaded via the `autoload` mechanism. It is somewhat risky to assume, that this will never be needed for the functions, however, the limited number of available ASCII characters justifies such allocation. Example function name: `/prompt_zinc_dmsg`. + +5. `@`: for API-like functions, i.e: for functions that are on a boundary to a subsystem and expose their functionality through a well-defined, generally fixed interface. For example, this plugin standard [defines](#update-register-call) the function `@zsh-plugin-run-on-update`, which is exposing a plugin manager’s functionality in a well-defined way. + +## Example code utilizing the prefixes + +```shell showLineNumbers +.zinc_register_hooks() { + add-zsh-hook precmd :zinc_precmd + /zinc_dmsg "Installed precmd hook with the result: $?" + @zsh-plugin-run-on-unload "add-zsh-hook -d precmd :zinc_precmd" + +zinc_print "Zinc initialization complete" +} +``` + +## Preventing function pollution + +When writing a larger autoload function, it very often is the case that the function contains definitions of other functions. + +When the main function finishes executing, the functions are left defined. This might be undesired, e.g.: because of the command namespace pollution. + +The following snippet of code, when added at the beginning of the main function will automatically unset the sub-functions when leaving the main function to don't leak any functions into the global namespace: + +```shell showLineNumbers +typeset -g prjef +prjef=( ${(k)functions} ) +trap "unset -f -- \"\${(k)functions[@]:|prjef}\" &>/dev/null; unset prjef" EXIT +trap "unset -f -- \"\${(k)functions[@]:|prjef}\" &>/dev/null; unset prjef; return 1" INT +``` + +Replace the `prj*` prefix with your project name, e.g.: `rustef` for a `rust`-related plugin. The `*ef` stands for "entry functions". The snippet works as follows: + +1. The line `prjef=( ${(k)functions} )` remembers all the functions that are currently defined – which means that the list excludes the functions that are to be yet defined by the body of the main function. + +2. The code `unset -f — "${(k)functions[@]:|prjef}"` first does a subtraction of array contents – the `:|` substitution operator – of the functions that are defined at the moment of leaving of the function (the `trap`-s invoke the code at this moment) with the list of functions from the start of the main function – the ones stored in the variables `$prjef`. + +3. It then unsets the resulting list of the functions – being only the newly defined functions in the main function – by passing it to `unset -f …`. This way the functions defined by the body of the main (most often an autoload) function will be only set during the execution of the function. + +## Preventing parameter pollution + +When writing a plugin one often needs to keep a state during the Zsh session. To do this it is natural to use global parameters. However, when the number of the parameters grows one might want to limit it. + +With the following method, only a single global parameter per plugin can be sufficient: + +```shell showLineNumbers +typeset -A PlgMap +typeset -A SomeMap +typeset -a some_array + +PlgMap[state]=1 +SomeMap[state]=1 +some_array[1]=state +``` + +can be converted into: + +```shell showLineNumbers +typeset -A PlgMap + +PlgMap[state]=1 +PlgMap[SomeMap__state]=1 +PlgMap[some_array__1]=state +``` + +The use of this method is very unproblematic. The author reduced the number of global parameters in one of the projects by 21 by using an automatic conversion with Vim substitution patterns with back references without any problems. + +Following the [Standard Plugins Hash](#standard-plugins-hash) section, the plugin could even use a common hash name – `Plugins` – to lower the pollution even more. + + + + + + + +[zi]: https://github.com/z-shell/zi + +[comparison]: https://www.zsh.org/mla/workers/2017/msg01827.html + +[romkatv/powerlevel10k is using]: https://github.com/romkatv/powerlevel10k/blob/f17081ca/internal/p10k.zsh#L5390 + +[gitstatus]: https://github.com/romkatv/gitstatus + +[agkozak/agkozak-zsh-prompt is using]: https://github.com/agkozak/agkozak-zsh-prompt/blob/ed228952d68fea6d5cad3beee869167f76c59606/agkozak-zsh-prompt.plugin.zsh#L992-L1039 + +[agkozak/zsh-z is using]: https://github.com/agkozak/zsh-z/blob/16fba5e9d5c4b650358d65e07609dda4947f97e8/zsh-z.plugin.zsh#L680-L698 + +[agkozak/zhooks is using]: https://github.com/agkozak/zhooks/blob/628e1e3b8373bf31c26cb154f71c16ebe9d13b51/zhooks.plugin.zsh#L75-L82 + +[tj/git-extras]: https://github.com/tj/git-extras + +[zsh-workers post]: https://www.zsh.org/mla/workers/2011/msg01050.html + +[autoloading-functions]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Autoloading-Functions + +[special-widgets]: https://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Special-Widgets + +[hook-functions]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Hook-Functions + +[options]: https://zsh.sourceforge.io/Doc/Release/Options.html diff --git a/i18n/ja/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx b/i18n/ja/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx new file mode 100644 index 00000000..018132a5 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx @@ -0,0 +1,330 @@ +--- +id: zsh_handbook +title: 🔤 Zsh Native Scripting Handbook +sidebar_position: 3 +image: /img/png/theme/z/320x320.png +keywords: + - zsh-handbook +--- + + + +import ReadINIExample from "@site/src/components/Markdown/_read_ini_example.mdx"; + +## Information + +### @ is about keeping array form + +How do access all array elements in a shell? The standard answer: `use @ subscript`, i.e. `${array[@]}`. However, this is the Bash & Ksh way (and with the option `KSH_ARRAYS`, Zsh also works this way, i.e. needs `@` to access the whole array). Z shell **is different**: it is a `$array` that refers to all elements anyway. There is no need for the `@` subscript. + +So what use has `@` in the Zsh-world? It is: "`keep array form`" or "`do not join`". When is it activated? When the user quotes the array, i.e. invokes `"$array"`, he induces _joining_ of all array elements (into a single string). `@` is to have elements still quoted (so empty elements are preserved), but not joined. + +Two forms are available, `"$array[@]"` and `"${(@)array}"`. The first form has an additional effect – when an option `KSH_ARRAYS` is set, it indeed induces referencing to the whole array instead of a first element only. It should then use braces, i.e. `${array[@]}`, `"${array[@]}"` (`KSH_ARRAYS` requirement). + +In practice, if you'll use `@` as a subscript – `[@]`, not as a flag – `${(@)...}`, then you'll make the code `KSH_ARRAYS`-compatible. + +### extended_glob + +Glob-flags `#b` and `#m` require `setopt extended_glob`. Patterns utilizing `~` and `^` also require it. Extended-glob is one of the main features of Zsh. + +## Constructs + +### Reading a file + +```shell showLineNumbers +typeset -a lines +lines=( "${(@f)"$( 0 ? b : c ))`. The flexibility of Zsh allows such expressions also in a normal context. Above is an example. `:+` is "if not empty, substitute …" `:-` is "if empty, substitute …". You can save a great number of lines of code with those substitutions, it's normally at least 4-lines `if` condition or lengthy `&&`/`||` use. + +### Ternary expressions with `:#` substitution + +```shell showLineNumbers +var=abc; print ${${${(M)var:#abc}:+is abc}:-not abc} → is abc +var=abcd; print ${${${(M)var:#abc}:+is abc}:-not abc} → not abc +``` + +A one-line "if var = x, then …, else …". Again, can spare a great amount of boring code that makes a 10-line function a 20-line one. + +### Using built-in regular expressions engine + +```shell +[[ "aabbb" = (#b)(a##)*(b(#c2,2)) ]] && print ${match[1]}-${match[2]} → aa-bb +``` + +`\##` is: "1 or more". `(#c2,2)` is: "exactly 2". A few other constructs: `#` is "0 or more", `?` is "any character", `(a|b|)` is "a or b or empty match". `#b` enables the `$match` parameters. There's also `#m` but it has one parameter `$MATCH` for whole matched text, not for any parenthesis. + +Zsh patterns are a custom regular expressions engine. They are slightly faster than the `zsh/regex` module (used for the `=~` operator) and don't have that dependency (regex module can be not present, e.g. in the default static build of Zsh). Also, they can be used in substitutions, for example in the `//` substitution. + +### Skipping uniq + +```shell showLineNumbers +typeset -aU array; array=( a a b ); print $array → a b +typeset -a array; array=( a a b ); print ${(u)array} → a b +``` + +Enable the `-U` flag for the array so that it guards elements to be unique, or use the `u`-flag to make unique elements of an array. + +### Skipping awk + +```shell showLineNumbers +typeset -a list; list=( "a,b,c,1,e" "p,q,r,2,t" ); +print "${list[@]/(#b)([^,]##,)(#c3,3)([^,]##)*/${match[2]}}" → 1 2 +``` + +The pattern specifies 3 blocks of `[^,]##,` so 3 "not-comma multiple times, then comma", then the single block of "not-comma multiple times" in second parentheses -- and then replaces this with second parentheses. The result is the 4th column extracted from multiple lines of text, something `awk` is often used for. Another method is the use of the `s`-flag. For a single line of text: + +```shell +text="a,b,c,1,e"; print ${${(s:,:)text}[4]} → 1 +``` + +Thanks to in-substitution code-execution capabilities it's possible to use the `s`-flag to apply it to multiple lines: + +```shell showLineNumbers +typeset -a list; list=( "a,b,c,1,e" "p,q,r,2,t" ); +print "${list[@]/(#m)*/${${(s:,:)MATCH}[4]}}" → 1 2 +``` + +There is a problem with the `(s::)` flag that can be solved if Zsh is version `5.4` or higher: if there will be single input column, e.g. `list=( "column1" "a,b")` instead of two or more columns (i.e. `list=( "column1,column2" "a,b" )`), then `(s::)` will return **string** instead of 1-element **array**. So the index `[4]` in the above snippet will index a string, and show its 4th letter. Starting with Zsh 5.4, thanks to a patch by Bart Schaefer (`40640: the (A) parameter flag forces array result even if...`), it is possible to force **array**-kind of result even for a single column, by adding `(A)` flag, i.e.: + +```shell showLineNumbers +typeset -a list; list=( "a,b,c,1,e" "p,q,r,2,t" "column1" ); +print "${list[@]/(#m)*/${${(As:,:)MATCH}[4]}}" → 1 2 +print "${list[@]/(#m)*/${${(s:,:)MATCH}[4]}}" → 1 2 u +``` + +Side-note: `(A)` flag is often used together with the `::=` assignment-substitution and `(P)` flag, to assign arrays and hashes by name. + +### Searching arrays + +```shell showLineNumbers +typeset -a array; array=( a b " c1" d ); print ${array[(r)[[:space:]][[:alpha:]]*]} → c1 +``` + +`\[[:space:]]` contains unicode spaces. This is often used in conditional expression like `[[ -z ${array[(r)...]} ]]`. + +Note that [Skipping grep](#skipping-grep) that uses `:#` substitution can also be used to search arrays. + +### Code execution in `//` substitution + +```shell showLineNumbers +append() { gathered+=( $array[$1] ); } +functions -M append 1 1 append +typeset -a array; array=( "Value 1" "Other data" "Value 2" ) +typeset -a gathered; integer idx=0 +: ${array[@]/(#b)(Value ([[:digit:]]##)|*)/$(( ${#match[2]} > 0 ? append(++idx) : ++idx ))} +print $gathered → Value 1 Value 2 +``` + +Use of the `#b` glob flag enables math-code execution (and not only) in `/` and `//` substitutions. Implementation is very fast. + +### Serializing data + +```shell showLineNumbers +typeset -A hsh deserialized; hsh=( key value ) +serialized="${(j: :)${(qkv@)hsh}}" +deserialized=( "${(Q@)${(z@)serialized}}" ) +print ${(kv)deserialized} → key value +``` + +`j`-flag means join -- by spaces, in this case. Flags `kv` mean keys and values, interleaving. Important `q`-flag means: quote. So what is obtained is each key and value quoted, and put into a string separated by spaces. + +`z`-flag means: split as if Zsh parser would split. So quoting (with backslashes, double quoting, and others) is recognized. Obtained is array `( "key" "value")` which is then de-quoted with `Q`-flag. This yields original data, assigned to the hash `deserialized`. Use this to e.g. implement an array of hashes. + +Note: to be compatible with `setopt ksharrays`, use `[@]` instead of `(@)`, e.g.: `...( "${(Q)${(z)serialized[@]}[@]}" )` + +#### Tip: serializing with Bash + +```shell showLineNumbers +array=( key1 key2 ) +printf -v serialized "%q " "${array[@]}" +eval "deserialized=($serialized)" +``` + +This method works also with Zsh. The drawback is the use of `eval`, however, no problem may occur unless someone compromises the variable's value, but as always, `eval` should be avoided if possible. + +## Real-world examples + +### Testing for Git subcommand + +Following code checks, if there is a `git` subcommand `$mysub`: + +```shell +if git help -a | grep "^ [a-z]" | tr ' ' '\n' | grep -x $mysub > /dev/null > /dev/null; then +``` + +Those are `4` forks. The code can be replaced according to this guide: + +```shell showLineNumbers +local -a lines_list +lines_list=( ${(f)"$(git help -a)"} ) +lines_list=( ${(M)${(s: :)${(M)lines_list:# [a-z]*}}:#$mysub} ) +if (( ${#lines_list} > 0 )); then + … +fi +``` + +The result is just `1` fork. + +### Counting unquoted-only apostrophes + +A project was needing this to do some Zle line-continuation tricks (when you put a backslash-\\ at the end of the line and press enters – it is the line continuation that occurs at that moment). + +The required functionality is: in the given string, count the number of apostrophes, but _only the unquoted ones_. This means that only apostrophes with null or an even number of preceding backslashes should be accepted into the count: + +```shell showLineNumbers +buf="word'continue\'after\\\'afterSecnd\\''afterPair" +integer count=0 +: ${buf//(#b)((#s)|[^\\])([\\][\\])#(\'\'#)/$(( count += ${#match[3]} ))} +echo $count → 3 +``` + +The answer (i.e. the output) to the above presentation and example is: `3` (there are `3` unquoted apostrophes in total in the string kept in the variable `$buf`). + +Below follows a variation of the above snippet that doesn't use math-code execution: + +```shell showLineNumbers +buf="word'continue\'after\\\'afterSecnd\\''afterPair" +buf="${(S)buf//(#b)*((#s)|[^\\])([\\][\\])#(\'\'#)*/${match[3]}}"; buf=${buf%%[^\']##} +integer count=${#buf} +echo $count → 3 +``` + +This is possible thanks to `(S)` flag – non-greedy matching, `([\\][\\])#` trick – it matches only unquoted following `(\'\'##)` characters (which are the apostrophes) and a general strategy to replace `anything-apostrope(s)` (unquoted ones) with `the-apostrope(s)` (and then count them with `${#buf}`). + +## Tips and Tricks + +### Parsing INI file + +With Zshell `extended_glob` parsing an `ini` file is an easy task. It will not result in a nested-arrays data structure (Zsh doesn't support nested hashes), but the hash keys are intuitive such as `$DB_CONF[db1__host]`. + +The code should be placed in a file named `read-ini-file`, in `$fpath`, and `autoload read-ini-file` should be invoked. + + diff --git a/i18n/ja/docusaurus-plugin-content-docs-community/current/99_contributors.mdx b/i18n/ja/docusaurus-plugin-content-docs-community/current/99_contributors.mdx new file mode 100644 index 00000000..4e34bc71 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-community/current/99_contributors.mdx @@ -0,0 +1,267 @@ +--- +id: contributors +title: '🏆 貢献者' +sidebar_position: 4 +image: /img/png/theme/z/320x320.png +hide_title: false +hide_table_of_contents: false +description: プロジェクトの貢献者 +keywords: + - contributors +draft: false +slug: contributors +--- + +import Link from "@docusaurus/Link"; +import Image from "@theme/IdealImage"; +import useBaseUrl from "@docusaurus/useBaseUrl"; +import ThemedImage from "@theme/ThemedImage"; + +```mdx-code-block + +``` + +貢献により、オープンソースコミュニティは学び、刺激を与え、創造するための素晴らしい場所になります。 あなたの貢献は、他のすべての人や愛するプロジェクトのためになり、非常に感謝されます。 . + +> プロジェクトに参加/サポートするには、 参加 、 翻訳、および共有 を検討してください。 + +## 全般 + +```mdx-code-block + + + + + + + + + + + +
+ + +
+ Salvydas Lukosius + + 		+ + +
+ onokatio + + 		+ + +
+ Omelet + + 		+ + +
+ Sai + + 		+ + +
+ William Cooper + + 		+ + +
+ Farzat07 + +
+``` + +## コンテンツ + +```mdx-code-block + + + + + + + + + +
+ + +
+ Sebastian + + 		+ + +
+ Callista Chang + + 		+ + +
+ signed-log + + 		+ + +
+ 0xMRTT + +
+``` + +## 翻訳 + +```mdx-code-block + + + + + + + + + + + +
+ + +
+ Colerar + + 		+ + +
+ Dongsen + + 		+ + +
+ nakayama900 + + 		+ + +
+ awarewen + + 		+ + +
+ Kazuma Miebori + + 		+ + +
+ syrinka + +
+``` + +## 参加 + +```mdx-code-block + + + + + + + + +
+ + +
+ Benoit de Chezelles + + 		+ + +
+ Caleb Cushing + + 		+ + +
+ Kritiqual + +
+``` + + diff --git a/i18n/ja/docusaurus-plugin-content-docs-community/current/_category_.json b/i18n/ja/docusaurus-plugin-content-docs-community/current/_category_.json new file mode 100644 index 00000000..5e5cc6f1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-community/current/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "👥 コミュニティ ドキュメント", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs-community/current/index.mdx b/i18n/ja/docusaurus-plugin-content-docs-community/current/index.mdx new file mode 100644 index 00000000..6fb70cb2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-community/current/index.mdx @@ -0,0 +1,30 @@ +--- +id: コミュニティ +slug: / +title: 👥 コミュニティ ドキュメント +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +keywords: + - documentation + - zsh-lovers + - コミュニティ + - gallery +--- + + + +```mdx-code-block +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +
+ +
+``` diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current.json b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current.json new file mode 100644 index 00000000..9a505b9a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current.json @@ -0,0 +1,18 @@ +{ + "version.label": { + "message": "次へ", + "description": "The label for version current" + }, + "sidebar.SideBar.category.🌀 Annexes": { + "message": "🌀 別館", + "description": "The label for category 🌀 Annexes in sidebar SideBar" + }, + "sidebar.SideBar.category.📦 Packages": { + "message": "📦 パッケージ", + "description": "The label for category 📦 Packages in sidebar SideBar" + }, + "sidebar.SideBar.category.⚙️ Plugins": { + "message": "⚙️ Plugins", + "description": "The label for category ⚙️ Plugins in sidebar SideBar" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/_category_.json b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/_category_.json new file mode 100644 index 00000000..dc7deef7 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "🌐 エコシステム", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx new file mode 100644 index 00000000..530b327e --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx @@ -0,0 +1,169 @@ +--- +id: overview +title: 🌀 別館でできることは？ +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: 別館の紹介 +keywords: + - annex + - overview +--- + + + +1. Add a new Zi subcommand (i.e. the [command][command] that’s placed after the function `zi …` when calling Zi). + +2. Add new [ice-modifiers][ice-modifiers]. + +3. 4種類のフックを登録します: + + 3.1. `atclone` hook – run after cloning any plugin or downloading any snippet. + + 3.2. `atpull` hook – run after pulling new commits (i.e. updating) for any plugin/snippet. + + 3.3. `atinit` hook – run before loading any plugin/snippet, after it has been set up (i.e. downloaded). + + 3.4. `atload` hook – run after loading any plugin/snippet. + +4. Register hooks for generating help text, shown by the `zi icemods` subcommand. + +## 推奨する別館 + +### 共通 + +1. [z-a-bin-gem-node][bin-gem-node] +2. [z-a-readurl][readurl] +3. [z-a-patch-dl][patch-dl] +4. [z-a-rust][rust] + +### その他 + +1. [z-a-submods][submods] +2. [z-a-unscope][unscope] +3. [z-a-test][test] + +:::tip + +Use [meta-plugins](/ecosystem/annexes/meta-plugins) to install common annexes as a group: + +```shell +zi light-mode for z-shell/z-a-meta-plugins @annexes +``` + +共通およびその他の別館をインストールする場合: + +```shell +zi light-mode for z-shell/z-a-meta-plugins @annexes+rec +``` + +::: + +## どのように使うのですか？ + +Below is an example body of an `atclone` hook taken from [submods][submods] annex. + +It shows how to: + +1. Obtain the arguments passed to the hook. +2. Use an [ice-modifier][ice-modifiers]. +3. It also shows a useful snippet that will trim the whitespace in array elements (see `# (4) …` in the code). +4. Utilize the last hook argument – the plugin’s/snippet’s containing directory. + +```shell showLineNumbers +emulate -L zsh -o extended_glob -o warn_create_global -o typeset_silent + +[[ -z "${ZI_ICE[submods]}" ]] && return 0 + +# (1) – get arguments +[[ "$1" = plugin ]] && \ +local type="$1" user="$2" plugin="$3" id_as="$4" dir="$5" hook="$6" || \ +local type="$1" url="$2" id_as="$3" dir="$4" hook="$6" # type: snippet + +# (2) – we're interested only in plugins/snippets +# which have the submods'' ice in their load command +[[ -z ${ZI_ICE[submods]} ]] && return 0 + +local -a mods parts +local mod from + +# (3) – process the submods'' ice +mods=( ${(@s.;.)ZI_ICE[submods]} ) +for mod in "${mods[@]}"; do + parts=( "${(@s:->:)mod}" ) + # (4) Remove only leading and trailing whitespace + parts=( "${parts[@]//((#s)[[:space:]]##|[[:space:]]##(#e))/}" ) + + print "\nCloning submodule: ${parts[1]} to dir: ${parts[2]}" + from="https://github.com" + parts[1]="${from}/${parts[1]}" + # (5) – the use of the input argument: `$dir' + command git -C "$dir" clone --progress "${parts[1]}" "${parts[2]}" +done +``` + +The recommended method of creating a hook is to place its body into a file that starts with a right arrow `→` ([more information][the-proposed-function-name-prefixes], and also a `za-` prefix, e.g. `→za-myproject-atclone-hook` and then to mark it for autoloading via `autoload -Uz →za-myproject-atclone-hook`. Then register the hook, presumably in the `myproject.plugin.zsh` file, with the API call: + +`@zi-register-annex`: + +```shell showLineNumbers +@zi-register-annex myproject hook:atclone \ + →za-myproject-atclone-handler \ + →za-myproject-atclone-help-handler \ + "submods''" # register a new ice-modifier: submods'' +``` + +The general syntax of the API call is: + +```shell showLineNumbers +@zi-register-annex {project-name} \ + {hook: \ + {name-of-the-handler-function} \ + {name-of-the-HELP-handler-function} \ + "{ice-mod1}|{ice-mod2}|…" < hook-type >| subcommand: < new-subcommand-name > } +``` + +The last argument, i.e. the `|`-separated ice list, is optional. That’s all! After this loading the plugin `myproject` will set up the new [ice-modifier][ice-modifiers] `submods` that will have syntax `submods'{user}/{plugin} –> {output-dir}; …'` and will clone submodules when installing the original plugin or snippet! + +Example of the [submods][submods] ice-modifier to load the `zsh-autosuggestions` plugin via the Prezto module: `autosuggestions`: + +```shell showLineNumbers +zi ice svn submods'zsh-users/zsh-autosuggestions -> external' +zi snippet PZT::modules/autosuggestions +``` + +Check out the project which fully implements this idea, [z-a-submods][submods]. It e.g. also implements the `atpull` hook, i.e. supports the automatic update of the submodules. The `z-a-*` prefix is recommended for projects which indicate annexes. + +## 概要 + +There are 2 or 3 subtypes for each of the hooks: + +1. `atinit` or `!atinit` – the `!` version is run before the `atinit` ice-modifier (i.e. before `zi ice atinit'echo this!'; …`), while the normal version runs after it. +2. `atload` or `!atload` – analogous to the `atinit` case: the `!` version runs before the `atload` ice-modifier (while the normal version runs after it). +3. `atclone` or `!atclone` – analogous to the `atinit` and `atload` cases. +4. `atpull`, `!atpull`, or `%atpull` – the first two are being run **only when there are new commits to be downloaded** during the update. The `%` version is being **always** run, regardless of whether the update will pull any actual commits or not, and it is being run **after** the `atpull` ice-modifier. + + + + + +[command]: /docs/guides/commands + +[ice-modifiers]: /docs/guides/syntax/ice-modifiers + +[the-proposed-function-name-prefixes]: /community/zsh_plugin_standard#the-proposed-function-name-prefixes + + + +[bin-gem-node]: https://github.com/z-shell/z-a-bin-gem-node + +[patch-dl]: https://github.com/z-shell/z-a-patch-dl + +[readurl]: https://github.com/z-shell/z-a-readurl + +[rust]: https://github.com/z-shell/z-a-rust + +[submods]: https://github.com/z-shell/z-a-submods + +[test]: https://github.com/z-shell/z-a-test + +[unscope]: https://github.com/z-shell/z-a-unscope diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx new file mode 100644 index 00000000..654a1f65 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx @@ -0,0 +1,125 @@ +--- +id: eval +title: 🌀 Eval +image: /img/png/theme/z/320x320.png +description: Annex - Eval documentation. +keywords: + - annex + - eval +draft: false +--- + + + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +The output of a slow initialization command is redirected to a file located within the plugin or snippets directory and sourced while loading. The next time the plugin or snippet is loaded, this file will be sourced skipping the need to run the initialization command. + +The ice-modifier `eval'…'` provided and handled by this annex creates a `cache` in the plugin or snippets directory which stores the output of the command and the cache is regenerated when: + +1. The plugin or snippet is updated. +2. The cache file is removed. +3. When running `zi recache`. + +:::note + +The optional preceding `!` flag means to store command output regardless of exit code. Otherwise `eval'…'` will avoid caching the output of code which returns a non-zero exit code. + +::: + +## Example invocations + + + + +```shell showLineNumbers +zi ice as"command" from"gh-r" \ + atclone"./zoxide init --cmd x zsh > init.zsh" \ + atpull"%atclone" src"init.zsh" nocompile'!' +zi light ajeetdsouza/zoxide +``` + +```shell showLineNumbers +zi ice atclone"dircolors -b LS_COLORS > init.zsh" \ + atpull"%atclone" pick"init.zsh" nocompile'!' \ + atload'zstyle ":completion:*" list-colors ${(s.:.)LS_COLORS}' +zi light trapd00r/LS_COLORS +``` + + + + +```shell {2} showLineNumbers +zi ice as"command" from"gh-r" \ + eval"./zoxide init --cmd x zsh" +zi light ajeetdsouza/zoxide +``` + +```shell {1} showLineNumbers +zi ice eval"dircolors -b LS_COLORS" \ + atload'zstyle ":completion:*" list-colors ${(s.:.)LS_COLORS}' +zi light trapd00r/LS_COLORS +``` + + + + + + +```shell showLineNumbers +if [[ "${+commands[kubectl]}" == 1 ]]; then + eval $(kubectl completion zsh) +fi +``` + + + + +```shell {2} showLineNumbers +zi ice id-as"kubectl_completion" has"kubectl" \ + eval"kubectl completion zsh" run-atpull +zi light z-shell/null +``` + + + + +## Install eval {#install-eval} + +:::info Source + +- + z-shell/z-a-eval + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-eval +``` + + + + +Add the following snippet in the `.zshrc` file: + +> Set value `Z_A_USECOMP=1` to enable TAB completion for subcommand `recache`. + +```shell showLineNumbers +zi ice atinit'Z_A_USECOMP=1' +zi light z-shell/z-a-eval +``` + + + + +This will register subcommand `recache` and `eval'…'` ice-modifier. diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx new file mode 100644 index 00000000..11dbb2b8 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx @@ -0,0 +1,568 @@ +--- +id: bin-gem-node +title: 🌀 Bin Gem Node +image: /img/png/theme/z/320x320.png +description: Annex - Bin Gem Node documentation. +keywords: + - annex, + - bin-gem-node +--- + + + +import Tabs from "@theme/Tabs"; +import Link from "@docusaurus/Link"; +import TabItem from "@theme/TabItem"; +import Player from "@site/src/components/Player"; +import APITable from "@site/src/components/APITable"; +import Shortcuts from "@site/src/components/Markdown/_player_shortcuts.mdx"; + +An annex provides the following functionality: + +1. Run programs and scripts without adding anything to `$PATH`, +2. Install: [Ruby Gems][rubygems], [Node][node], and [Python][python] modules, with automatically set: + - [$GEM_HOME][gem-home] + - [$NODE_PATH][node-path] + - [$VIRTUALENV][virtualenv] +3. Run programs, scripts, and functions with automatic `cd` into the plugin or snippet directory, plus also with automatic standard output & standard error redirecting. +4. Source scripts through an automatically created function with the above `$GEM_HOME`, `$NODE_PATH`, `$VIRTUALENV`, and `cd` features available, +5. Create the so-called `shims` known from [rbenv][rbenv/rbenv] – the same feature as the first item of this enumeration – of running a program without adding anything to `$PATH` with all of the above features, however through an automatic **script** created in `$ZPFX/bin`, not a **function** (the first item uses a function-based mechanism), +6. Automatic updates of Ruby gems and Node modules during regular plugin and snippet updates with `zi update …`. + +The [sbin](#sbin-1) ice-modifier that creates forwarder-scripts instead of forwarder-functions created by the [fbin](#fbin-1) ice-modifier turned out to be the proper, best method for exposing binary programs and scripts. This way there is no need to add anything to `$PATH` – `z-a-bin-gem-node` will automatically create a function that will wrap the binary and provide it on the command line as if it was being placed in the `$PATH`. + +As previously mentioned, the function can automatically export `$GEM_HOME`, `$NODE_PATH`, `$VIRTUALENV` shell variables and also automatically cd into the plugin or snippet directory right before executing the binary and then cd back to the original directory after the execution is finished. As previously mentioned, instead of the function an automatically created script – the so-called `shim` – can be used for the same purpose and with the same functionality, so that the command is accessible practically fully normally – not only in the live Zsh session, only within which the functions created by [fbin](#fbin-1) exist, but also from any Zsh script. + +Suppose that we want to install the `junegunn/fzf` plugin from GitHub Releases, which contains only a single file – the `fzf` binary for the selected architecture. It is possible to do it in the standard way – by adding the plugin's directory to the `$PATH`. + +```shell +zi ice as'program' from'gh-r' +zi load junegunn/fzf +``` + +After this command, the `$PATH` variable will contain e.g.: + +```shell title="print $PATH" showLineNumbers +/home/sall/.zi/plugins/junegunn---fzf:/bin:/usr/bin:/usr/sbin:/sbin +``` + +For many such programs loaded as plugins, the PATH can become quite cluttered. I've had 26 entries before switching to `z-a-bin-gem-node`. To solve this, load with the use of [sbin](#sbin-1) ice-modifier provided and handled by `z-a-bin-gem-node`: + +```shell showLineNumbers +zi ice as'program' from'gh-r' sbin'fzf' +zi load junegunn/fzf +``` + +The `$PATH` will remain unchanged and a forwarder-script of `fzf` shim will be created in `$ZPFX/bin` (`~/.zi/polaris/bin` by default), which is being already added to the `$PATH` by Zi when it is being sourced: + +```shell title="cat $ZPFX/bin/fzf" showLineNumbers +#!/usr/bin/env zsh + +function fzf { + local bindir="/home/sall/.zi/plugins/junegunn---fzf" + "$bindir"/"fzf" "$@" +} + +fzf "$@" +``` + +Running the script will forward the call to the program accessed through an embedded path to it. Thus, no `$PATH` changes are needed. + +```mdx-code-block + +``` + +| Ice modifier | 説明 | +| :-------------- | :--------------------------------------------------------------------------------------------------------- | +| [sbin](#sbin-1) | Creates `shims` for binaries and scripts. | +| [fbin](#fbin-2) | Creates functions for binaries and scripts. | +| [gem](#gem-3) | Installs and updates gems + creates functions for gems binaries. | +| [node](#node-4) | Installs and updates node_modules + creates functions for binaries of the modules. | +| [pip](#pip-5) | Installs and updates python packages into a `virtualenv` + creates functions for binaries of the packages. | +| [fmod](#fmod-6) | Creates wrapping functions for other functions. | +| [fsrc](#fsrc-7) | Creates functions that source given scripts. | +| [ferc](#ferc-8) | The same as [fsrc](#fscr-7), but using an alternate script-loading method. | + +```mdx-code-block + +``` + +Function wrappers for binaries, scripts, gems, node_modules, python packages, etc: + +```mdx-code-block + +``` + +| Flag | 説明 | +| :--- | :-------------------------------------------------------------------------------------------------------------------- | +| `g` | Set `$GEM_HOME` variable to `{plugin-dir}`. | +| `n` | Set `$NODE_PATH` variable to `{plugin-dir}/node_modules`. | +| `p` | Set `$VIRTUALENV` variable to `{plugin-dir}/venv`. | +| `c` | `cd` to the plugin's directory before running the program and then cd back after it has been run. | +| `N` | Append `&>/dev/null` to the call of the binary, i.e. redirect both standard output and standard error to `/dev/null`. | +| `E` | Append `2>/dev/null` to the call of the binary, i.e. redirect standard error to `/dev/null`. | +| `O` | Append `>/dev/null` to the call of the binary, i.e. redirect standard output to `/dev/null`. | + +```mdx-code-block + +``` + +View all currently registered: + +- ice-modifiers: `zi icemods` +- subcommand: `zi subcmds` + +## `SBIN'…'` {#sbin-1} + +```shell +sbin'[{g|n|c|N|E|O}:]{path-to-binary}[ -> {name-of-the-script}]; …' +``` + +Creates the so-called `shim` known from `rbenv` – a wrapper script that forwards the call to the actual binary. The script is created always under the same, standard, and single `$PATH` entry: `$ZPFX/bin` (which is `~/.zi/polaris/bin` by default). The flags have the same meaning as with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice as'program' from'gh-r' sbin'fzf' +zi load junegunn/fzf +``` + +```shell title="cat $ZPFX/bin/fzf" showLineNumbers +#!/usr/bin/env zsh + +function fzf { + local bindir="/home/sall/.zi/plugins/junegunn---fzf" + local -xU PATH="$bindir":"$PATH" + "$bindir"/"fzf" "$@" +} + +fzf "$@" +``` + +:::note + +- as'program' (an alias: as'command') - used for the plugin to be added to $PATH when a plugin is not a file for sourcing. + +The [sbin](#sbin-1) ice-modifier can be empty, it will then try to create the shim for the trailing component of the [id-as][] ice, e.g.: + +- `id_as'exts/git-my'` → it'll check if a file `git-my` exists and if yes, will create the function `git-my`. +- `paulirish/git-open` → it'll check if a file `git-open` exists and if yes, will create the function `git-open`. + +The same trailing component would be set for the snippet URL, for any alphabetically first and executable file. + +::: + +## `FBIN'…'` {#fbin-2} + +```shell +fbin'[{g|n|c|N|E|O}:]{path-to-binary}[ -> {name-of-the-function}]; …' +``` + +Creates a wrapper function of the name the same as the last segment of the path or as `{name-of-the-function}`. + + + + + + + + + + +```shell showLineNumbers +zi ice from"gh-r" fbin"g:fzf -> myfzf" nocompile +zi load junegunn/fzf +``` + +```shell title="which myfzf" showLineNumbers +myfzf () { + local bindir="/home/sall/.zi/plugins/junegunn---fzf" + local -x GEM_HOME="/home/sall/.zi/plugins/junegunn---fzf" + local -xU PATH="/home/sall/.zi/plugins/junegunn---fzf"/bin:"$bindir":"$PATH" + "$bindir"/"fzf" "$@" +} +``` + +:::note + +- `nocompile` ice-modifier is used to skip file compilation when it is not required. + +::: + +## `GEM'…'` {#gem-3} + +```shell showLineNumbers +gem'{gem-name}; …' +gem'[{path-to-binary} <-] !{gem-name} [-> {name-of-the-function}]; …' +``` + +Installs the gem of name `{gem-name}` with `$GEM_HOME` set to the plugin's or snippet's directory. In other words, the gem and its dependencies will be installed locally in that directory. In the second form, it also creates a wrapper function identical to the one created with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice gem'!asciidoctor' id-as'asciidoctor' nocompile +zi load z-shell/0 +``` + +```shell title="which asciidoctor" showLineNumbers +asciidoctor () { + local bindir="/home/sall/.zi/plugins/asciidoctor/bin" + local -x GEM_HOME="/home/sall/.zi/plugins/asciidoctor" + local -xU PATH="/home/sall/.zi/plugins/asciidoctor"/bin:"$bindir":"$PATH" + "$bindir"/"asciidoctor" "$@" +} +``` + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `asciidoctor` gem. +- `id-as'asciidoctor'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `NODE'…'` {#node-4} + +```shell showLineNumbers +node'{node-module}; …' +node'[{path-to-binary} <-] !{node-module} [-> {name-of-the-function}]; …' +``` + +Installs the node module of name `{node-module}` inside the plugin's or snippet's directory. In the second form, it also creates a wrapper function identical to the one created with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice node'remark <- !remark-cli -> remark; remark-man' id-as'remark' nocompile +zi load z-shell/0 +``` + +```shell title="which remark" showLineNumbers +remark () { + local bindir="/home/sall/.zi/plugins/remark/node_modules/.bin" + local -x NODE_PATH="/home/sall/.zi/plugins/remark"/node_modules + local -xU PATH="/home/sall/.zi/plugins/remark"/node_modules/.bin:"$bindir":"$PATH" + "$bindir"/"remark" "$@" +} +``` + +In this case, the name of the binary program provided by the node module is different from its name, hence the second form with the `b <- a -> c` syntax has been used. + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `remark` Node module. +- `id-as'remark'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `PIP'…'` {#pip-5} + +```shell showLineNumbers +pip'{pip-package}; …' +pip'[{path-to-binary} <-] !{pip-package} [-> {name-of-the-function}]; …' +``` + +Installs the node module of name `{pip-package}` inside the plugin's or snippet's directory. In the second form, it also creates a wrapper function identical to the one created with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice pip'youtube-dl <- !youtube-dl -> youtube-dl' id-as'youtube-dl' nocompile +zi load z-shell/0 +``` + +```shell title="which youtube-dl" showLineNumbers +youtube-dl () { + local bindir="/home/sall/.zi/plugins/youtube-dl/venv/bin" + local -x VIRTUALENV="/home/sall/.zi/plugins/youtube-dl"/venv + local -xU PATH="/home/sall/.zi/plugins/youtube-dl"/venv/bin:"$bindir":"$PATH" + "$bindir"/"youtube-dl" "$@" +} +``` + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `youtube-dl` pip package. +- `id-as'youtube-dl'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `FMOD'…'` {#fmod-6} + +```shell showLineNumbers +fmod'[{g|n|c|N|E|O}:]{function-name}; …' +fmod'[{g|n|c|N|E|O}:]{function-name} -> {wrapping-function-name}; …' +``` + +It wraps the given function with the ability to set `$GEM_HOME`, etc. – the meaning of the `g`, `n`, and `c` flags is the same as in the `fbin'…'` ice. + +Example: + + + + + + + + + + +```shell showLineNumbers +myfunc() { pwd; ls -1 }; zi ice fmod'cgn:myfunc' id-as'myfunc' nocompile +zi load z-shell/0 +``` + +```shell title="which myfunc" showLineNumbers +myfunc () { + local -x GEM_HOME="/home/sall/.zi/plugins/myfunc" + local -x NODE_PATH="/home/sall/.zi/plugins/myfunc"/node_modules + local oldpwd="/home/sall" + () { + setopt local_options no_auto_pushd + builtin cd -q "/home/sall/.zi/plugins/myfunc" + } + "myfunc--za-bgn-orig" "$@" + () { + builtin setopt local_options no_auto_pushd + builtin cd -q "$oldpwd" + } +} +``` + +```shell title="myfun" showLineNumbers +/home/sall/.zi/plugins/z-shell---0 +docs/ +LICENSE +README.md +``` + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `myfunc` function files. +- `id-as'myfunc'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `FSCR'…'` {#fscr-7} + +```shell +fsrc'[{g|n|c|N|E|O}:]{path-to-script}[ -> {name-of-the-function}]; …' +``` + +## `FERC'…'` {#ferc-8} + +```shell +ferc'[{g|n|c|N|E|O}:]{path-to-script}[ -> {name-of-the-function}]; …' +``` + +Creates a wrapper function that at each invocation sources the given file. The second ice, `FERC'…'` works the same with the single difference that it uses `eval "$(<{path-to-script})"` instead of `source "{path-to-script}"` to load the script. + + + + + + + + + + +```shell showLineNumbers +zi ice fsrc"myscript -> myfunc" ferc"myscript" nocompile +zi load z-shell/0 +``` + +```shell title="which myfunc" showLineNumbers +myfunc () { + local bindir="/home/sall/.zi/plugins/z-shell---0" + local -xU PATH="$bindir":"$PATH" + () { + source "$bindir"/"myscript" + } "$@" +} +``` + +```shell title="which myscript" showLineNumbers +myscript () { + local bindir="/home/sall/.zi/plugins/z-shell---0" + local -xU PATH="$bindir":"$PATH" + () { + eval "$(<"$bindir"/"myscript")" + } "$@" +} +``` + +:::note + +- `nocompile` ice-modifier is used to skip file compilation when it is not required. + +The ices can be empty as the trailing component will be assigned with [id-as][] ice-modifier the same way as described in the [sbin](#sbin-1). + +::: + +## `shim-list` {#shim-list} + +An annex provides a subcommand – `shim-list` for shims currently stored in `$ZPFX/bin` management: + +Available flags are: + +```shell +zi shim-list [ -t | -i | -o | -s | -h ] +``` + +| Flag | 説明 | +| :----------------- | :--------------------------------------------------------------------------------------- | +| `-t` `--this-dir` | Instructs Zi to look for shims in the current directory instead of `$ZPFX/bin`. | +| `-i` `--from-ices` | Normally the code looks for the shim files by examining their contents (more info [^1]). | +| `-o` `--one-line` | Display the list of shim files without line breaks, in a single line, after spaces. | +| `-s` `--short` | Don't show the plugin/snippet that the shim belongs to. | +| `-h` `--help` | Shows usage information. | + +## Cygwin support {#cygwin-support} + +The [sbin](#sbin-1) ice-modifier has an explicit Cygwin support – it creates additional, **extra shim files** – Windows batch scripts that allow running the shielded applications from e.g.: Windows run dialog – if the `~/.zi/polaris/bin` directory is being added to the Windows `PATH` environment variable, for example (it is a good idea to do so, IMHO). The Windows shims have the same name as the standard ones (which are also being created, normally) plus the `.cmd` extension. You can test the feature by e.g.: installing Firefox from the Zi package via: + +```shell +zi pack=bgn for firefox +``` + +## Install bin-gem-node {#install-bin-gem-node} + +:::info Source + +- + z-shell/z-a-bin-gem-node + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-bin-gem-node +``` + + + + +Add the following snippet in the `.zshrc` file to install using the [unscope][] annex: + +```shell +zi light z-shell/z-a-unscope bgn +``` + + + + +This will register the [shim-list](#shim-list) subcommand and following ice-modifiers: + + + + + +[^1]: shims created by the `bin-gem-node` annex have a fixed structure, this option instructs Zi to show the list of shims that results from the [sbin](#sbin-1) ice-modifier of the loaded plugins. If a plugin for example has `sbin'git-open'`, means that such shim has already been created. + + + +[id-as]: /docs/guides/syntax/standard#id-as + +[unscope]: /ecosystem/annexes/unscope + + + +[gem-home]: https://guides.rubygems.org/command-reference/#gem-environment + +[node-path]: https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders + +[node]: https://github.com/npm/cli + +[python]: https://python.org + +[rbenv/rbenv]: https://github.com/rbenv/rbenv + +[rubygems]: https://github.com/rubygems/rubygems + +[virtualenv]: https://docs.python.org/3/tutorial/venv.html diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx new file mode 100644 index 00000000..9af42699 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx @@ -0,0 +1,52 @@ +--- +id: test +title: 🌀 テスト +hide_title: false +hide_table_of_contents: false +image: /img/png/theme/z/320x320.png +description: 別館 - テスト用ドキュメント +keywords: + - annex + - test +draft: true +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import ImgShow from "@site/src/components/ImgShow"; + +An annex runs `zunit` and `make` tests if they are configured in the repository. + + + +他のプラグインと同様に読み込むだけで、アクティブになります。 + +```shell +zi light z-shell/z-a-test +``` + +
+ 📖 Configuration + +テストを冗長モードで実行するには、次のようにします。 + +```shell +zstyle :zi:annex:test quiet 0 +``` + +To skip tests for a single plugin before installing or updating add the `notest` ice-modifier: + +```shell showLineNumbers +zi ice notest +zi load … +``` + +
diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx new file mode 100644 index 00000000..d25ff36e --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx @@ -0,0 +1,243 @@ +--- +id: meta-plugins +title: 🌀 Meta Plugins +image: /img/png/theme/z/320x320.png +description: Annex meta-plugins documentation +keywords: + - annex + - meta-plugins +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import APITable from "@site/src/components/APITable"; + +An annex has the curated, optimal [ice-modifiers][] lists automatically applied. For more details refer to [z-a-meta-plugins.plugin.zsh][] file. + +:::tip + +- To create your group of plugins as meta-plugins propose them in a new [issue][issues/new] +- Prefix `@` used to avoid syntax conflicts, e.g: `zi light @` +- Before installing any plugin visit the original repository where available to verify that system is supported and meets other requirements + +::: + +## Usage of meta-plugins + +The following snippets are examples of how to install meta-plugins: + +```shell +zi light @annexes +``` + +```shell +zi light-mode for @annexes @zsh-users @console-tools +``` + +```shell showLineNumbers +zi light-mode for z-a-meta-plugins \ + @annexes @ext-git @zsh-users +``` + +```shell showLineNumbers +zi light-mode for @annexes \ + skip'zsh-completions' @zsh-users \ + skip'vivid exa tig' @console-tools +``` + +## Available meta-plugins + +```mdx-code-block + +``` + +| Meta-plugin name | Consisting plugins | +| ---------------- | --------------------------------------------------------------------------------------------------------------------- | +| @annexes | [bin-gem-node][], [readurl][], [patch-dl][], [rust][], [default-ice][], [unscope][] | +| @annexes+ | @annexes + [submods][], [test][] | +| @console-tools | [dircolors-material][] (package), [fd][], [bat][], [hexyl][], [hyperfine][], [vivid][], [exa][], [ripgrep][], [tig][] | +| @developer-tools | [color][], [revolver][], [zunit][], [gitignore.plugin.zsh][], [tig][] | +| @ext-git | [git-open][], [git-recent][], [git-my][], [git-quick-stats][], [git-now][], [git-extras][], [forgit][] | +| @fuzzy | [fzf][] (package), [fzy][] (package), [skim][], [peco][] | +| @fuzzy-src | fzf-go, [fzy][], skim-cargo, peco-go | +| @prezto | PZTM::archive, PZTM::directory, PZTM::utility | +| @py-utils | [pyenv][] (package) | +| @romkatv | [powerlevel10k][] | +| @rust-utils | rust-toolchain, cargo-extensions | +| @sharkdp | [fd][], [bat][], [hexyl][], [hyperfine][], [vivid][] | +| @z-shell | [F-Sy-H][], [H-S-MW][], [zsh-diff-so-fancy][] | +| @z-shell+ | [zsh-select][], [zconvey][], [zui][], [zflai][] | +| @zsh-users | [zsh-syntax-highlighting][], [zsh-autosuggestions][], [zsh-completions][] | +| @zsh-users+fast | [F-Sy-H][], [zsh-autosuggestions][], [zsh-completions][], [z-shell/zsh-fancy-completions][] | +| @zunit | [color][], [revolver][], [zunit][] | + +```mdx-code-block + +``` + +### Summary of the meta-plugins + +It consumes time to: + +- Constantly, over and over collect some new interesting plugins to install/load. +- Over and over reconstruct the new findings on the new machines. +- Constantly extend and tweak the ice list of each plugin, so that it's hard on the eyes, especially for an outsider. + +```mdx-code-block + +``` + +| Problem | Solution | +| :---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| (1) _finding new plugins_ | The annex contains a curated, broad list of plugins, e.g.: all the console tools like `fd`, `fzf`, `exa`, `ripgrep`, etc., | +| (2) _reconstructing the findings in new environments_ | It's easy to say and memorize e.g.: `zi for console-tools` – one label pulls a group of plugins and also the curated, optimal, default ice lists for each of them, | +| (3) _constant increase of complexity of the commands_ | The provided, hopefully, best/optimal ices for each plugin are handled transparently and automatically; care is given to each ice list so that the plugin loads without any glitches (e.g.: without the "No files for compilation found." message and other, even such slight issues). | + +```mdx-code-block + +``` + +Other unique benefits of the meta-plugins annex: + +```mdx-code-block + +``` + +| Benefit | 説明 | +| :---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Plugin dependencies | The meta-plugins implement a dependency mechanism: selecting a from-source built [ogham/exa][exa] will automatically pull in also the Rust compiler (available under the meta-plugin name: `rust-toolchain`). | +| Flexible disabling of chosen sub-plugins in any meta-plugin | A meta-plugin can contain many sub-plugins and it's possible to skip installing some of them by the **skip'plugin-1 plugin-2…'** ice, e.g.: `zi skip'ripgrep fd' for console-tools`. This way despite that some of the meta plugins are broad the user still has control over what's and how much is being installed. | +| Common from-source meta plugins | For the plugins that provide the binary programs it is often the case that a meta-plugin exists that'll build the program from the source (e.g.: **fuzzy** meta-plugin and its **fuzzy-src** counterpart). This might be handy e.g.: if there's no binary for our machine. | + +```mdx-code-block + +``` + +## Install meta-plugins {#install-meta-plugins} + +:::info Source + +- + z-shell/z-a-meta-plugins + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-meta-plugins +``` + + + + +This will register the `skip'…'` ice-modifier. + + + + + +[ice-modifiers]: /docs/guides/syntax/ice-modifiers + + + +[bat]: https://github.com/sharkdp/bat + +[bin-gem-node]: https://github.com/z-shell/z-a-bin-gem-node + +[color]: https://github.com/zdharma/color + +[default-ice]: https://github.com/z-shell/z-a-default-ice + +[dircolors-material]: https://github.com/z-shell/dircolors-material + +[exa]: https://github.com/ogham/exa + +[f-sy-h]: https://github.com/z-shell/F-Sy-H + +[fd]: https://github.com/sharkdp/fd + +[forgit]: https://github.com/wfxr/forgit + +[fzf]: https://github.com/z-shell/fzf + +[fzy]: https://github.com/z-shell/fzy + +[git-extras]: https://github.com/tj/git-extras + +[git-my]: https://github.com/davidosomething/git-my + +[git-now]: https://github.com/iwata/git-now + +[git-open]: https://github.com/paulirish/git-open + +[git-quick-stats]: https://github.com/arzzen/git-quick-stats + +[git-recent]: https://github.com/paulirish/git-recent + +[gitignore.plugin.zsh]: https://github.com/voronkovich/gitignore.plugin.zsh + +[h-s-mw]: https://github.com/z-shell/H-S-MW + +[hexyl]: https://github.com/sharkdp/hexyl + +[hyperfine]: https://github.com/sharkdp/hyperfine + +[issues/new]: https://github.com/z-shell/z-a-meta-plugins/issues/new + +[patch-dl]: https://github.com/z-shell/z-a-patch-dl + +[peco]: https://github.com/peco/peco + +[powerlevel10k]: https://github.com/romkatv/powerlevel10k + +[pyenv]: https://github.com/z-shell/pyenv + +[readurl]: https://github.com/z-shell/z-a-readurl + +[revolver]: https://github.com/zdharma/revolver + +[ripgrep]: https://github.com/BurntSushi/ripgrep + +[rust]: https://github.com/z-shell/z-a-rust + +[skim]: https://github.com/lotabout/skim + +[submods]: https://github.com/z-shell/z-a-submods + +[test]: https://github.com/z-shell/z-a-test + +[tig]: https://github.com/jonas/tig + +[unscope]: https://github.com/z-shell/z-a-unscope + +[vivid]: https://github.com/sharkdp/vivid + +[z-a-meta-plugins.plugin.zsh]: https://github.com/z-shell/z-a-meta-plugins/blob/main/z-a-meta-plugins.plugin.zsh + +[zconvey]: https://github.com/z-shell/zconvey + +[zflai]: https://github.com/z-shell/zflai + +[zsh-autosuggestions]: https://github.com/zsh-users/zsh-autosuggestions + +[zsh-completions]: https://github.com/zsh-users/zsh-completions + +[zsh-diff-so-fancy]: https://github.com/z-shell/zsh-diff-so-fancy + +[zsh-select]: https://github.com/z-shell/zsh-select + +[zsh-syntax-highlighting]: https://github.com/zsh-users/zsh-syntax-highlighting + +[zui]: https://github.com/z-shell/zui + +[zunit]: https://github.com/zdharma/zunit + +[z-shell/zsh-fancy-completions]: https://github.com/z-shell/zsh-fancy-completions diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx new file mode 100644 index 00000000..1b48dff2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx @@ -0,0 +1,76 @@ +--- +id: default-ice +title: 🌀 Default Ice +image: /img/png/theme/z/320x320.png +description: 別館 - デフォルト Iceのドキュメント +keywords: + - annex + - default-ice +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex delivers the capability to set **default ices** for the next `zi` command, e.g: + +デフォルトのiceの設定: + +```shell +zi default-ice lucid from"gh-r" +``` + +これは GitHub リリース (gh-r) からダウンロードされ、デフォルトでは lucid ice も使用します。 + +```shell showLineNumbers +zi wait for \ + sbin junegunn/fzf-bin \ + sbin"**/pk" peco/peco +``` + +:::caution + +The `wait` ice cannot be made default by using this subcommand. + +::: + +## `default-ice` {#default-ice} + +An annex provides a subcommand – `default-ice` which has the following synopsis: + +```shell showLineNumbers +— default-ice [ -s | -c | -g | -t | -q | -h ] + + [ -s ] - 現在設定されているデフォルトのiceを表示 + [ -c ] - デフォルトのiceをリセット + [ -g ] - REPLAYハッシュに現在のiceを返す + [ -t ] - 統計情報を表示 + [ -q ] - すべてのメッセージを隠す + [ -h ] - このメッセージを表示 +``` + +## Install default-ice {#install-default-ice} + +:::info Source + +- + z-shell/z-a-default-ice + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-default-ice +``` + + + + +This will register the [default-ice](#default-ice) subcommand. diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx new file mode 100644 index 00000000..2449661d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx @@ -0,0 +1,72 @@ +--- +id: patch-dl +title: 🌀 Patch DL +image: /img/png/theme/z/320x320.png +description: 別館 - Patch DLのドキュメント +keywords: + - annex + - patch-dl +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import ImgShow from "@site/src/components/ImgShow"; + +この別館では、ファイルのダウンロードとパッチの適用をする、2つのice修飾子の追加を行います。 + +1番目 + +```shell +zi ice dl'{URL} [-> {optional-output-file-name}]; …' … +``` + +2番目 + +```shell +zi ice patch'{file-name-with-the-patch-to-apply}; …' … +``` + +The annex will download the given `{URL}` under the path `{optional-output-file-name}` (if no file name given, then it is taken from last segment of the URL) in case of the `dl'…'` ice-modifier, and apply a patch given by the `{file-name-with-the-patch-to-apply}` in case of the `patch'…'` ice-modifier. この機能を利用して、パッチのダウンロードや適用を行うことができます。 + +For example, to install `fbterm`, two patches are being needed, one to fix the operation, the other one to fix the build: + +```shell showLineNumbers +zi ice as"command" pick"$ZPFX/bin/fbterm" \ + dl"https://bugs.archlinux.org/task/46860?getfile=13513 -> ins.patch" \ + dl"https://aur.archlinux.org/cgit/aur.git/plain/0001-Fix-build-with-gcc-6.patch?h=fbterm-git" \ + patch"ins.patch; 0001-Fix-build-with-gcc-6.patch" \ + atclone"./configure --prefix=$ZPFX" \ + atpull"%atclone" make"install" reset +zi load izmntuk/fbterm +``` + +このコマンドを実行すると、次のようになります。 + + + +## Install patch-dl {#install-patch-dl} + +:::info Source + +- + z-shell/z-a-patch-dl + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-patch-dl +``` + + + + +This will register the `dl'…'` and `patch'…'` ice-modifiers. diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx new file mode 100644 index 00000000..7b5637da --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx @@ -0,0 +1,131 @@ +--- +id: readurl +title: 🌀 Read URL +image: /img/png/theme/z/320x320.png +description: Annex - Read URL documentation. +keywords: + - annex + - readurl +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex allows automatically downloading the newest version of a file to which the URL is hosted on a webpage. It works as follows: + +Invoke `snippet` (or simply pass the `https://…` address using the `for` syntax) on the web page that hosts the URL to the file to download, provide `dlink'…'` ice with the expected file-download URL replacing the version with the `%VERSION%` keyword, also provide `as'…'` ice with one of the following values: + +1. `readurl`, +2. `readurl|command`, +3. `readurl|completion`, +4. `readurl|null`. + +:::note + +The part after the `|` has the same meaning as in the normal `as'…'` ice. + +::: + +## Examples + +```shell showLineNumbers +zi id-as=fzf as='readurl|command' for \ + dlink='/junegunn/fzf/releases/download/%VERSION%/fzf-%VERSION%-linux_amd64.tar.gz' \ + https://github.com/junegunn/fzf/releases/ +``` + +The snippet is just an example. The same effect is obtained by loading as the `junegunn/fzf` plugin with `from'gh-r'` ice. + +As it can be seen, the `dlink'…'` can be a relative or an absolute path and also a full URL (i.e.: beginning with the `https://…` prefix). + +### Intermediate download page + +Sometimes, like it is in the case of the [terraform][terraform-link] command, the final download link isn't on the download page, but on a page, that's listed on it. In such a case use the `dlink0'…'` ice to provide the pattern for the additional, intermediate download page, e.g.: + +```shell showLineNumbers +zi id-as=terraform as='readurl|command' extract for \ + dlink0='/terraform/%VERSION%/' \ + dlink='/terraform/%VERSION%/terraform_%VERSION%_linux_386.zip' \ + https://releases.hashicorp.com/terraform/ +``` + +### Skipping `dlink'…'` ice + +Sometimes the URL of the download page differs from the URL of the archive in just a few `/`-sections. In such a case, it is possible to skip the `dlink'…'` ice by appending a `++`-separated fragment of the archive URL, like so: + +```shell showLineNumbers +zi as'readurl|command' extract for \ + http://domain.com/download-page++/archive.zip +``` + +If the archive URL has some different `/`-sections, then it's possible to strip the conflicting ones from the download URL by using `+++`, `++++`, etc. – the number of the `/`-section that'll be stripped equals to the number of the `+` minus 2. So, for example: + +```shell showLineNumbers +zi as'readurl|command' extract for \ + http://domain.com/download-page/removed-section+++/archive.zip +``` + +### Sorting the matched URLs / package versions + +Sometimes the download page doesn't list the package versions from newest to oldest, but in some other order. In such case, it's possible to sort the URLs / package versions by prepending the chosen `dlink` ice (`dlink0'…'` or `dlink'…'`) with the exclamation mark (`dlink'!…'`, etc.). See the next section for an example: + +### Filtering the matched URLs + +Sometimes some unwanted URLs match the `dlink'…'`/`dlink0'…'` regex/pattern. In such a case it's possible to filter them out by appending a filtering regex to the `dlink'…'` ice as: `dlink='the-main-regex~%the-unwanted-URLs-regex%'` (or the same for `dlink0'…'`). An example package that can benefit from this is the [Open Shift][open-shift-link] client, which doesn't sort the URLs from latest to the oldest – hence the exclamation mark (`!`) prepend – and it has special URLs like `stable-4.4` or `candidate-4.5` together with the regular version URLs (like `4.5.0-rc.1`): + +```shell showLineNumbers +zi id-as"ocp" as"readurl|command" for \ + dlink0'!%VERSION%~%(stable|latest|fast|candidate).*%' \ + dlink"openshift-client-windows-%VERSION%.zip" \ + https://mirror.openshift.com/pub/openshift-v4/clients/ocp/ +``` + +The above snippet of Zsh code / Zi invocation will sort the URLs (`dlink0'!…'`) and then filter out the special ones from the results (via `…~%(stable|latest|fast|candidate).*%`), this way selecting the latest version of the Open Shift client. + +### Other examples + +[Pulumi][pulumi-link], a tool to create, deploy and manage modern cloud software. + +```shell showLineNumbers +zi id-as'pulumi' as'readurl|null' for \ + dlink='https://get.pulumi.com/releases/sdk/pulumi-%VERSION%-linux-x64.tar.gz' \ + sbin'pulumi*' \ + https://www.pulumi.com/docs/get-started/install/versions/ +``` + +## Install readurl {#install-readurl} + +:::info Source + +- + z-shell/z-a-readurl + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-readurl +``` + + + + +This will register the `dlink'…'` and `dlink0'…'` ice-modifiers and also the special `as'readurl|…'` value of the `as'…'`. + + + + + + + +[open-shift-link]: https://www.openshift.com/ + +[pulumi-link]: https://www.pulumi.com/ + +[terraform-link]: https://releases.hashicorp.com/terraform diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx new file mode 100644 index 00000000..7e45aa4d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx @@ -0,0 +1,54 @@ +--- +id: submods +title: 🌀 Submods +image: /img/png/theme/z/320x320.png +description: 別館 - Submodsのドキュメント +keywords: + - annex + - submods +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +この別館は、プラグインやスニペットをインストールする際に、追加のサブモジュールをクローンする機能を提供します。 The submodules are then automatically updated on the `zi update …` command. + +概要: + +```shell +submods'{user}/{plugin} -> {output directory}; …` +``` + +An example command utilizing the annex and its ice-modifier to load `zsh-autosuggestions` plugin via [Prezto module](/docs/getting_started/migration#pzt-modules) `autosuggestions`. + +```shell title='~/.zshrc' showLineNumbers +zi ice svn submods'zsh-users/zsh-autosuggestions -> external' +zi snippet PZT::modules/autosuggestions +``` + +## Install submods {#install-submods} + +:::info Source + +- + z-shell/z-a-submods + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-submods +``` + + + + +This will register the `submods'…'` ice-modifier. diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx new file mode 100644 index 00000000..a98e6078 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx @@ -0,0 +1,161 @@ +--- +id: unscope +title: 🌀 Unscope +image: /img/png/theme/z/320x320.png +description: 別館 - アンスコープ IDのドキュメント +keywords: + - annex + - unscope +--- + + + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import Highlight from "@site/src/components/Highlight"; +import APITable from "@site/src/components/APITable"; + +この別館では、以下のようにGitHubのユーザー名を指定せずにプラグインをインストールすることができます。 + +1. On the installation of a plugin without any slashes (/) in its name the annex will query the GitHub API searching for `*/{the-name}`, sorting on stars. + +2. まず候補にはフォークが10回以上必要で、なければ次に2回、そして0回となります。 + +3. After finding the best result it sets it as the **full** remote-id of the plugin, storing the ID on disk for later automatic use. + +4. For security, for such GH-API request to be made a newly added (by this annex) ice: `ghapi` is required to be given. + +5. そうでない場合は、プラグインのニックネームとフルスコープIDの静的マッピングデータベースのみが検索されます。 It contains many mappings, like, e.g.: `vi-reg → zsh-vi-more/evil-registers`, and some of the popular plugins, like, e.g.: `zsh-syntax-highlighting → zsh-users/zsh-syntax-highlighting` and more. + +## 静的マッピング + +:::info + +Fill [request](https://github.com/z-shell/z-a-unscope/issues/new/choose) to add new repositories with scoped IDs. + +::: + +Besides the GitHub-API querying, there's also a fixed, curated list of mappings of short names to the full GitHub IDs: + +```mdx-code-block + +``` + +| 略称(ニックネーム) | GitHub ID / scoped ID | +| :-----------------------------------------------------------------------------: | :-------------------------------- | +| null | z-shell/null | +| z-a-readurl | z-shell/z-a-readurl | +| readurl | z-shell/z-a-readurl | +| rdurl | z-shell/z-a-readurl | +| z-a-patch-dl | z-shell/z-a-patch-dl | +| patch-dl | z-shell/z-a-patch-dl | +| z-a-submods | z-shell/z-a-submods | +| submods | z-shell/z-a-submods | +| z-a-rust | z-shell/z-a-rust | +| rust | z-shell/z-a-rust | +| z-a-bin-gem-node | z-shell/z-a-bin-gem-node | +| bin-gem-node | z-shell/z-a-bin-gem-node | +| bgn | z-shell/z-a-bin-gem-node | +| meta | z-shell/z-a-meta-plugins | +| metaplg | z-shell/z-a-meta-plugins | +| meta-plugins | z-shell/z-a-meta-plugins | +| archive | PZTM::archive | +| arch | PZTM::archive | +| directory | PZTM::directory | +| dir | PZTM::directory | +| environment | PZTM::environment | +| env | PZTM::environment | +| utility | PZTM::utility | +| util | PZTM::utility | +| fast-syntax-highlighting | z-shell/fast-syntax-highlighting | +| f-sy-h | z-shell/fast-syntax-highlighting | +| fsh | z-shell/fast-syntax-highlighting | +| history-search-multi-word | z-shell/history-search-multi-word | +| hsmw | z-shell/history-search-multi-word | +| zui | z-shell/zui | +| ZUI | z-shell/zui | +| zconvey | z-shell/zconvey | +| zconv | z-shell/zconvey | +| zbrowse | z-shell/zbrowse | +| zzcomplete | z-shell/zzcomplete | +| zzcomp | z-shell/zzcomplete | +| zzcom | z-shell/zzcomplete | +| zsh-autosuggestions | zsh-users/zsh-autosuggestions | +| autosuggestions | zsh-users/zsh-autosuggestions | +| autosug | zsh-users/zsh-autosuggestions | +| asug | zsh-users/zsh-autosuggestions | +| z-asug | zsh-users/zsh-autosuggestions | +| zsh-syntax-highlighting | zsh-users/zsh-syntax-highlighting | +| z-sy-h | zsh-users/zsh-syntax-highlighting | +| zsh-autocomplete | marlonrichert/zsh-autocomplete | +| autocomplete | marlonrichert/zsh-autocomplete | +| autocomp | marlonrichert/zsh-autocomplete | +| aucom | marlonrichert/zsh-autocomplete | +| acom | marlonrichert/zsh-autocomplete | +| z-aucom | marlonrichert/zsh-autocomplete | +| z-acom | marlonrichert/zsh-autocomplete | +| zsh-autopair | hlissner/zsh-autopair | +| autopair | hlissner/zsh-autopair | +| aupair | hlissner/zsh-autopair | +| aupa | hlissner/zsh-autopair | +| z-aupa | hlissner/zsh-autopair | +| evil-registers | zsh-vi-more/evil-registers | +| evil-reg | zsh-vi-more/evil-registers | +| vi-reg | zsh-vi-more/evil-registers | +| vireg | zsh-vi-more/evil-registers | +| vi-motions | zsh-vi-more/vi-motions | +| evil-mot | zsh-vi-more/vi-motions | +| vi-mot | zsh-vi-more/vi-motions | +| vimot | zsh-vi-more/vi-motions | +| vi-increment | zsh-vi-more/vi-increment | +| evil-inc | zsh-vi-more/vi-increment | +| vi-inc | zsh-vi-more/vi-increment | +| viinc | zsh-vi-more/vi-increment | +| vi-quote | zsh-vi-more/vi-quote | +| evil-qte | zsh-vi-more/vi-quote | +| vi-qte | zsh-vi-more/vi-quote | +| viqte | zsh-vi-more/vi-quote | +| directory-marks | zsh-vi-more/directory-marks | +| evil-dir-marks | zsh-vi-more/directory-marks | +| vi-dir-marks | zsh-vi-more/directory-marks | +| vi-dirma | zsh-vi-more/directory-marks | +| vidirma | zsh-vi-more/directory-marks | +| fd | sharkdp/fd | +| shark-fd | sharkdp/fd | +| bat | sharkdp/bat | +| shark-bat | sharkdp/bat | +| exa | ogham/exa | +| zsh-completions | zsh-users/zsh-completions | +| completions | zsh-users/zsh-completions | +| comps | zsh-users/zsh-completions | + +```mdx-code-block + +``` + +## Install unscope {#install-unscope} + +:::info Source + +- + z-shell/z-a-unscope + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-unscope +``` + + + + +これにより、スコープ ID の検索と解決が可能になります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx new file mode 100644 index 00000000..e699dade --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx @@ -0,0 +1,102 @@ +--- +id: linkbin +title: 🌀 Link Bin +image: /img/png/theme/z/320x320.png +description: Annex - Link Bin documentation. +keywords: + - annex + - linkbin +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex exposes a binary program without modifying `$PATH` – `z-a-linkbin` and automatically creates a hard or soft link to the binary at `$ZPFX/bin` exposing the program to the command line as if it were being placed in `$PATH`. + +The command can then be accessed normally – not only in the live Zsh session but also from any Zsh script. The ice-modifier `lbin''` provided by the annex creates `links` for binaries and scripts. + +It creates the `link` that calls the actual binary. The link is created always under the same, standard and single `$PATH` entry: `$ZPFX/bin` + +## Soft link + +:::note + +The optional preceding `!` flag means creating a soft link instead of a hard link. + +::: + +Example: + +```shell {2} showLineNumbers +zi ice from'gh-r' as'program' \ + lbin'!fzf' +zi load junegunn/fzf +``` + +Check the output: + +```shell showLineNumbers +ls -l $ZPFX/bin/ | awk '{print $(NF-2),$(NF-1),$NF}' +fzf --version +``` + +## Hard link + +:::note + +The ice-modifier can contain globs as it will expand these when searching for the binary. + +::: + +Example: + +```shell {2} showLineNumbers +zi ice from'gh-r' as'program' \ + lbin'**fzf -> myfzf' +zi load junegunn/fzf +``` + +Check the output: + +```shell +ls -l $ZPFX/bin/ | awk '{print $(NF-2),$(NF-1),$NF}' +myfzf --version +``` + +## Auto nickname link + +If ice-modifier [id-as](/docs/guides/syntax/standard#id-as) is empty, then will try to create the link with a nickname as follows: + +1. Trailing component of the `id-as` ice-modifier, e.g.: `id-as'exts/git-my'` → it will check if a file `git-my` exists and if yes, create the link `git-my`. +2. The plugin name, e.g.: for `paulirish/git-open` it'll check if a file `git-open` exists and if yes, create the link `git-open`. +3. Trailing component of the snippet URL. +4. For any alphabetically first executable file. + +The above also applies if just `!` were passed. + +## Install linkbin {#install-linkbin} + +:::info Source + +- + z-shell/z-a-linkbin + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-linkbin +``` + + + + +This will register the `lbin'…'` ice-modifier. diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx new file mode 100644 index 00000000..5a14cbce --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx @@ -0,0 +1,164 @@ +--- +id: rust +title: 🌀 Rust +image: /img/png/theme/z/320x320.png +description: An annex installs rust and cargo packages. +keywords: + - annex + - rust +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import Player from "@site/src/components/Player"; +import Shortcuts from "@site/src/components/Markdown/_player_shortcuts.mdx"; + +An annex installs rust and cargo packages locally inside the plugin or snippet directories. + + + + + + + + + + +## Usage of the annex + +The Zi annex provides ice-modifiers `rustup` and `cargo'…'`. + +The first one installs rust inside the plugin's folder using the official `rustup` installer and the second one has the following syntax: + +```shell +cargo'[{name-of-the-binary-or-path} <-] [[!][c|n|e|o]:]{crate-name} [-> {shim-script-name}]'` +``` + +| Flag | 説明 | +| ---- | ------------------------------------------------------------------------------------------------ | +| `N` | redirect both standard output and error to `/dev/null` | +| `E` | redirect standard error to `/dev/null` | +| `O` | redirect standard output to `/dev/null` | +| `c` | change the current directory to the plugin's or snippet's directory before executing the command | + +As the examples showed, the name of the binary to run and the shim name are by default equal to the name of the crate. Specifying `{binary-name} <- …` and/or `… -> {shim-name}` allows to override them. + +The crate can create so-called _shims_ – scripts that are exposed to the standard `$PATH`. The shim script is a wrapper around the binary that is installed by the crate. The shim script is created in the plugin's or snippet's directory and is named after the crate. The shim script is a shell script that sets up the environment variables and then runs the binary. + +Example of the _shim_ script: + +```shell showLineNumbers +#!/usr/bin/env zsh + +function lsd { + local bindir="/root/.zi/plugins/z-shell---null/bin" + local -x PATH="/root/.zi/plugins/z-shell---null"/bin:"$PATH" # -x means export + local -x RUSTUP_HOME="/root/.zi/plugins/z-shell---null"/rustup CARGO_HOME="/root/.zi/plugins/z-shell---null" + + "$bindir"/"lsd" "$@" +} + +lsd "$@" +``` + +As it can be seen shim ultimately provides the binary to the command line. + +
+ Use case examples + +Set up rust and the `lsd` crate with a shim `lsd` exposing the binary: + +```shell showLineNumbers +zi ice rustup cargo'!lsd' +zi load z-shell/0 +``` + +Set up rust and the `exa` crate with a shim `ls` exposing the `exa` binary: + +```shell showLineNumbers +zi ice rustup cargo'!exa -> ls' +zi load z-shell/0 +``` + +Set up rust and the `exa` and `lsd` crates: + +```shell showLineNumbers +zi ice rustup cargo'exa;lsd' +zi load z-shell/0 +``` + +Set up rust, then the `exa` and `lsd` crates, with their binaries exposed by altering `$PATH`: + +```shell showLineNumbers +zi ice rustup cargo'exa;lsd' as"command" pick"bin/(exa|lsd)" +zi load z-shell/0 +``` + +Set up rust and then the `exa` crate with shim standard error redirected to `/dev/null`: + +```shell showLineNumbers +zi ice rustup cargo'!E:exa' +zi load z-shell/0 +``` + +Just install rust and make it available globally in the system: + +```shell showLineNumbers +zi ice id-as"rust" wait"0" lucid rustup as"command" pick"bin/rustc" atload="export \ + CARGO_HOME=\$PWD RUSTUP_HOME=\$PWD/rustup" +zi load z-shell/0 +``` + +A little more complex rustup configuration that uses [bin-gem-node][annex-bin-gem-node] annex and installs the cargo completion provided with rustup, using the [for][for-syntax] syntax: + +```shell showLineNumbers +zi id-as=rust wait=1 as=null sbin="bin/*" lucid rustup \ + atload="[[ ! -f ${ZI[COMPLETIONS_DIR]}/_cargo ]] && zi creinstall rust; \ + export CARGO_HOME=\$PWD RUSTUP_HOME=\$PWD/rustup" for \ +z-shell/0 +``` + +
+ +## Install rust {#install-rust} + +:::info Source + +- + z-shell/z-a-rust + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-rust +``` + + + + +This will register the `rustup` and `cargo'…'` ice-modifiers. + + + + + +[annex-bin-gem-node]: /ecosystem/annexes/bin-gem-node + +[for-syntax]: /docs/guides/syntax/for diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json new file mode 100644 index 00000000..14b2f212 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "🌀 別館", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/index.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/index.mdx new file mode 100644 index 00000000..db67ca15 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/index.mdx @@ -0,0 +1,26 @@ +--- +id: ecosystem +slug: / +title: 🌐 エコシステム +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: エコシステムの紹介 +--- + + + +```mdx-code-block +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +
+ +
+``` diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx new file mode 100644 index 00000000..be5df187 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx @@ -0,0 +1,143 @@ +--- +id: synopsis +title: 📦 概要 +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: パッケージの紹介 +keywords: + - package + - zpackage + - zsh-package + - packages-overview +--- + + + +パッケージ機能を追加する動機 + +1. Ziは柔軟で機能豊富なプラグインマネージャーですが、ユーザーはその設定に圧倒されることが多いようです。 + +2. パッケージマネージャーに似た次のような機能が複数あります。 + + - プラグインのGitリポジトリまたはパッケージのリリースURLを指定できます。 + - get the list of the recommended [ice-modifiers][] for the plugin, + - there can be multiple lists of [ice-modifiers][], + - ice修飾子リストはプロファイルに保存されます。デフォルトでは少なくとも 1 つのプロファイルがあります。 + - the [ice-modifiers][] can be selectively overridden. + - バイナリに対していわゆるシム（転送スクリプト）を自動的に提供します。 + - extend `$PATH` to expose the binaries, + - it can run `Makefile` and more. + +3. 一般に、Ziには驚くようなことを可能にするフックがたくさんありますが、その内容は徐々に良いものに進化していくことが多く、現在のバージョンをすべて把握することは困難です。 + +:::info + +The [bin-gem-node][] annex is recommended, otherwise, some packages will fail to install due to missing functionality. + +::: + +## The [any-gem][] and [any-node][] packages + +これらは、新しく作成されたプラグインディレクトリに、任意のGem（複数可）やNodeモジュール（複数可）をローカルインストールすることを可能にします。 例: + +```shell showLineNumbers +zi pack param='GEM -> rails' for any-gem +zi pack param='MOD -> doctoc' for any-node +``` + +If the installation is used in the `.zshrc` file then use `id-as'…'`, then Zi knows that the package is already installed. + +:::note + +Zi の構文では、以下の例のように Unicode 矢印を使用することができます。 + +::: + +```shell +zi id-as=jekyll pack param='GEM → jekyll' for any-gem +``` + +バイナリは shims 経由で PATH を変更することなく公開されます。 Shims are correctly removed when deleting a plugin with `zi delete …` The so-called packages are GitHub repositories holding a `package.json` file with the meta-data in them. This way you don't have to (but still can) specify ice-modifiers, which might be handy when the [ice-modifiers][] list is long and complex. + +## 導入例 + +This way, instead of the following command used to install `fzf`: + +```shell showLineNumbers +zi lucid as=program pick="$ZPFX/bin/(fzf|fzf-tmux)" \ + atclone="cp shell/completion.zsh _fzf_completion; \ + cp bin/(fzf|fzf-tmux) $ZPFX/bin" \ + make="PREFIX=$ZPFX install" for \ + junegunn/fzf +``` + +必要なもの: + +```shell +zi pack for fzf +``` + +to get the complete setup of the fuzzy finder, including: + +- the completion +- the additional executable script `fzf-tmux` + +The installation is like with package-manager because you don't need to invoke Zi anymore once installed to use `fzf` (that's because `fzf` is just a binary program and not e.g.: a shell function). You can also update the package with `zi update fzf` – it'll cause the project to refresh and rebuild, like with a "normal" package manager such as `apt-get`. However, it'll be more like to `emerge` from Gentoo, because the installation will be from the source… unless… the user will pick up a binary installation by profile argument specified in the `pack'…'` ice. + +## 通常のソフトウェアインストールにZiパッケージを使用する場合の長所 + +通常のパッケージマネージャでインストールできるソフトウェアをZiでインストールすることには、いくつかの利点があります。 + +1. **Pro:** The Zi packages typically use the URLs to the official and _latest_ distributions of the software (e.g.: the [ecs-cli][] package, which uses the URL: `https://amazon-ecs-cli.s3.amazonaws.com/ecs-cli-linux-amd64-latest` when installing on Linux). + +2. **Pro:** You can influence the installation easily by specifying Zi ice-modifiers, e.g.: + + ```shell + zi pack=bgn atclone="cp fzy.1 $ZI[MAN_DIR]/man1" for fzy + ``` + + to install also the man page for the `fzy` fuzzy finder (this omission in the package will be fixed soon). + +3. **Pro:** The installation is much more flexible than a normal package manager. 使用可能な自由度の例: + + - to install from Git or release-tarball, or a binary-release file, + - to install via shims or via extending `$PATH`, or by copying to `$ZPFX/bin`, + - to download files and apply patches to the source by using the `patch-dl` annex features. + +4. **Pro:** The installations are located in the user home directory, which doesn't require root access. Also, for Gems and Node modules, they are installed in their plugin directory, which can have advantages (e.g.: isolation allowing e.g: easy removal by `rm -rf …`). + +5. **Con:** You're somewhat "on your own", with no support from any package maintainer. + +Thus, summing up 1. with 4., it might be nice/convenient too, for example, have the latest ECS CLI binary installed in the home directory, without using root access and always the latest, and – summing up with 2. and 3. – to, for example, have always the latest `README` downloaded by additional ice: `dl'https://raw.githubusercontent.com/aws/amazon-ecs-cli/master/README.md'` (and then to have the `README` converted into a man page by the `remark` Markdown processor or other via an `atclone''` ice, as the tool doesn't have any official man page). + +## パッケージの追加 + +1. Contact the author to have the repository at the [Z-Shell][z-shell] organization or set the [ZI\[PKG_OWNER\]][modify-settings]. + +2. Populate the `package.json` – I suggest grabbing the one for `fzf` or `doctoc` and doing a few substitutions like [doctoc][] → `your-project` and then simply filling the `default` profile in the `zi-ices` object – it is same as passing ice-modifiers to `zi ice …` but in JSON. + +3. The project name in the `package.json` should start with `zsh-`. Zi で指定する場合、このプレフィックスはスキップされます。 + +4. コミットしてプッシュする。 + + + + + +[bin-gem-node]: /ecosystem/annexes/bin-gem-node + +[ice-modifiers]: /docs/guides/syntax/ice-modifiers + +[modify-settings]: /docs/guides/customization#modify-settings + + + +[any-gem]: https://github.com/z-shell/any-gem + +[any-node]: https://github.com/z-shell/any-node + +[ecs-cli]: https://github.com/z-shell/ecs-cli + +[z-shell]: https://github.com/z-shell + +[doctoc]: https://github.com/z-shell/doctoc diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx new file mode 100644 index 00000000..382b4bfb --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx @@ -0,0 +1,1022 @@ +--- +id: usage +title: 📦 使用方法 +image: /img/png/theme/z/320x320.png +description: Ziパッケージの使用方法。 +keywords: + - zpackage + - packages + - zsh-packages +--- + + + +import Emoji from "@site/src/components/Emoji"; +import APITable from "@site/src/components/APITable"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +## パッケージ集 + +For all the available packages use [GitHub search][github-search]. + +```mdx-code-block + +``` + +| パッケージ名 | 説明 | +| :--------------------: | :-------------------------------------------------------------------------------------------------- | +| [any-node][] | 新しく作成されたプラグインディレクトリに、任意のNodeモジュール（複数可）を配置します。 | +| [any-gem][] | 新しく作成されたプラグインディレクトリに、任意のGem（複数可）を配置します。 | +| [apr][] | Apache Portable Runtime (APR) ライブラリです。 | +| [fzf][] | コマンドラインファジーファインダーのfzf。 | +| [fzy][] | コマンドラインファジーファインダーのfzy。 | +| [pyenv][] | Pythonの仮想環境マネージャー pyenv。 | +| [remark][] | The remark Markdown processor. | +| [doctoc][] | The doctoc Markdown processor. | +| [ls_colors][] | The LS_COLORS and setup a zsh-completion system color scheme. | +| [dircolors-material][] | The dircolors-material and set up a zsh-completion system color scheme. | +| [asciidoctor][] | The asciidoctor Markdown processor. | +| [system-completions][] | Moves the stock Zsh completions under the control of Zi. | +| [brew-completions][] | The Homebrew Shell Completion under the control of Zsh & Zi. | +| [ecs-cli][] | AWS ECS のCLI。 | +| [subversion][] | Subversionのクライアント。 | +| [github-issues][] | GitHub Issuesのクライアントです。 | +| [github-issues-srv][] | GitHub Issues サーバーです。 | +| [firefox-dev][] | Firefox Developer Edition。 | +| [zsh][] | The Zsh mirror of zsh-users. | +| [nb][] | Bookmarking, and archiving with linking, tagging, search, Git syncing, Pandoc conversion, and more. | +| [zsh-bin][] | Package of statically-linked, hermetic, relocatable - romkatv/zsh-bin. | + +```mdx-code-block + +``` + +## パッケージの概要 + +### Apache Portable Runtime (APR) ライブラリ + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ +Download, build and install the latest Apache Portable Runtime. + +```shell +zi pack for apr +``` + +### `asciidoctor` Markdown processor + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + + + + + (default) +
+ +Download the Gem of asciidoctor locally with the [bin-gem-node][] annex. + +> Using the `@` prefix because of collision with the as'' ice. + +```shell +zi pack for @asciidoctor +``` + +### AWS ECS CLI + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + (default) + + + + + + +
+ + + + +Download the binary of the Amazon-ECS-CLI command. + +```shell +zi pack for ecs-cli +``` + + + + +Download the ECS-CLI binary with the use of the bin-gem-node annex. + +```shell +zi pack"bgn" for ecs-cli +``` + + + + +### `dircolors-material` color scheme + + + + + + + + + + + + + + + + + + + + +
+ Package source + TarballBinaryGitNodeGem
+ Status: + + + + + + (default) + + + + +
+ + + + +Download the default profile. + +```shell +zi pack for dircolors-material +``` + + + + +Download the "no-zsh-completion" profile. + +```shell +zi pack"no-zsh-completion" for dircolors-material +``` + + + + +Download the "no-color-swaps" profile. + +```shell +zi pack"no-color-swaps" for dircolors-material +``` + + + + +Download the minimal profile without altering the original theme. + +```shell +zi pack"minimal" for dircolors-material +``` + + + + +### `doctoc` Markdown processor + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + + + (default) + + +
+ +A download default profile with the Node package of doctoc. + +```shell +zi pack for doctoc +``` + +### Firefox Developer Edition + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + (default) + + + + + + +
+ + + + +Download the firefox-dev latest binary. + +```shell +zi pack for firefox-dev +``` + + + + +Download the firefox-dev latest binary with use of the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for firefox-dev +``` + + + + +### `fzf` command-line fuzzy finder + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ + + + +Download the package with the default profile. + +```shell +zi pack for fzf +``` + + + + +Download the package with the default profile + key bindings. + +```shell +zi pack"default+keys" for fzf +``` + + + + +Download the package with the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for fzf +``` + + + + +Download the package with the [bin-gem-node][] annex and with the key bindings. + +> The "+keys" variants are available for each profile. + +```shell +zi pack"bgn+keys" for fzf +``` + + + + +Download with the [bin-gem-node][] annex from GitHub repository. + +```shell +zi pack"bgn" git for fzf +``` + + + + +Download the binary from the GitHub releases. + +```shell +zi pack"binary" for fzf +``` + + + + +Download the binary from the GitHub releases and install using [bin-gem-node][] + shims. + +```shell +zi pack"bgn-binary" for fzf +``` + + + + +### `fzy` command-line fuzzy finder + + + + + + + + + + + + + + + + + + + + +
+ Package source: + TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ + + + +Download the package with the default profile. + +```shell +zi pack for fzy +``` + + + + +Download the package with the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for fzy +``` + + + + +Download with the [bin-gem-node][] annex from GitHub repository. + +```shell +zi pack"bgn" git for fzy +``` + + + + +Download normal ice list and override atclone'' ice to skip the contrib scripts + +```shell +zi pack"bgn" atclone'' for fzy +``` + + + + +### `LS_COLORS` color scheme + + + + + + + + + + + + + + + + + + +
+ Package source: + TarballGitNodeGem
+ Status: + + + + (default) + + + + +
+ + + + +Download the default profile. + +```shell +zi pack for ls_colors +``` + + + + +Download the "no-zsh-completion" profile. + +```shell +zi pack"no-zsh-completion" for ls_colors +``` + + + + +Download the "no-dir-color-swap" profile. + +```shell +zi pack"no-dir-color-swap" for ls_colors +``` + + + + +### Feature-rich note‑taking (`nb`) {#nb-pkg-profile} + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballGitNodeGem
+ Status: + + (default) + + + + + + +
+ +Default profile are using [bin-gem-node][] to set shims. + +```shell +zi pack for nb +``` + +### Python virtual environment manager - `pyenv` {#pyenv-pkg-profile} + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ + + + +Download the tarball with the default ice list. + +```shell +zi pack for pyenv +``` + + + + +Download the binary from the GitHub releases with the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for pyenv +``` + + + + +Download with the [bin-gem-node][] annex from GitHub repository. + +```shell +zi pack"bgn" git for pyenv +``` + + + + +### `remark` Markdown processor + + + + + + + + + + + + + + + + + + +
+ Package source: + TarballGitNodeGem
+ Status: + + + + + + (default) + + +
+ + + + +Download the Node package of remark-CLI, remark-man and remark-HTML + +```shell +zi pack for remark +``` + + + + +Download the Node package of remark-CLI and remark-man + +```shell +zi pack"man-only" for remark +``` + + + + +Download the Node package of remark-CLI and remark-HTML + +```shell +zi pack"html-only" for remark +``` + + + + +### Subversion + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ +Download, build and install the latest Subversion. + +> Dependency of Subversion: [APR][] + +```shell +zi pack for subversion +``` + +### Zsh mirror of zsh-users + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + (default) + + + + +
+ + + + +Install the newest Zsh. + +```shell +zi pack for zsh +``` + + + + +Install preferred Zsh version. + +```shell +zi pack"5.9" for zsh +zi pack"5.8.1" for zsh +zi pack"5.8" for zsh +zi pack"5.7.1" for zsh +zi pack"5.6.2" for zsh +zi pack"5.5.1" for zsh +zi pack"5.4.2" for zsh +zi pack"5.3.1" for zsh +zi pack"5.2.4" for zsh +zi pack"5.1.1" for zsh +``` + + + + +### Statically-linked, hermetic, relocatable Zsh + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + (default) + + + + +
+ + + + +Requires **root** access to install Zsh at `/usr/local` and will attempt to register it as a login shell. + +```shell +zi pack for zsh-bin +``` + + + + +Does not require **root** access, when install using [bin-gem-node][] to set shims. + +```shell +zi pack"bgn" for zsh-bin +``` + + + + +Does not require **root** access, will install to `~/.local`. + +```shell +zi pack"rootless" for zsh-bin +``` + + + + + + + + +[bin-gem-node]: /ecosystem/annexes/bin-gem-node + + + +[any-node]: https://github.com/z-shell/any-node + +[any-gem]: https://github.com/z-shell/any-gem + +[apr]: https://github.com/z-shell/apr + +[fzf]: https://github.com/z-shell/fzf + +[fzy]: https://github.com/z-shell/fzy + +[pyenv]: https://github.com/z-shell/pyenv + +[remark]: https://github.com/z-shell/remark + +[doctoc]: https://github.com/z-shell/doctoc + +[ls_colors]: https://github.com/z-shell/ls_colors + +[dircolors-material]: https://github.com/z-shell/dircolors-material + +[asciidoctor]: https://github.com/z-shell/asciidoctor + +[system-completions]: https://github.com/z-shell/system-completions + +[ecs-cli]: https://github.com/z-shell/ecs-cli + +[subversion]: https://github.com/z-shell/subversion + +[github-issues]: https://github.com/z-shell/github-issues + +[github-issues-srv]: https://github.com/z-shell/github-issues-srv + +[firefox-dev]: https://github.com/z-shell/firefox-dev + +[zsh]: https://github.com/z-shell/zsh + +[nb]: https://github.com/z-shell/nb + +[zsh-bin]: https://github.com/z-shell/zsh-bin + +[brew-completions]: https://github.com/z-shell/brew-completions + +[github-search]: https://github.com/search?q=topic%3Azpackage+org%3Az-shell&type=Repositories diff --git a/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json new file mode 100644 index 00000000..d7c4f2cd --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "📦 パッケージ", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current.json b/i18n/ja/docusaurus-plugin-content-docs/current.json new file mode 100644 index 00000000..67aabb4f --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,18 @@ +{ + "version.label": { + "message": "次へ", + "description": "The label for version current" + }, + "sidebar.SideBar.category.🚀 Getting Started": { + "message": "🚀 はじめに", + "description": "The label for category 🚀 Getting Started in sidebar SideBar" + }, + "sidebar.SideBar.category.💡 Guides": { + "message": "💡 ガイド", + "description": "The label for category 💡 Guides in sidebar SideBar" + }, + "sidebar.SideBar.category.✍️ Syntax": { + "message": "✍️ 構文", + "description": "The label for category ✍️ Syntax in sidebar SideBar" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx new file mode 100644 index 00000000..3cf4de9b --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx @@ -0,0 +1,281 @@ +--- +id: installation +title: ⚡️ 導入 +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: インストールガイド +keywords: + - install +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +## Quick setup {#quick-setup} + +Place the following snippet to the .zshrc file: + + + + +```shell title="~/.zshrc" +source <(curl -sL init.zshell.dev); zzinit +``` + + + + +:::caution + +This setup method requires manually verifying the sha256 [checksum][checksum-txt] for a file lib/zsh/init.zsh every time the content is changed in the repository. + +::: + +```shell showLineNumbers title="~/.zshrc" +local cs_ok='7fab1ecb8d2ffbdb4aa98dd1e51cebaeaa4d8137e1de11938f3e0df24af262bb' +local cs_get=$(sha256sum <(curl -sL init.zshell.dev) | awk '{print $1}') +[[ $cs_ok == $cs_get ]] && { source <(curl -sL init.zshell.dev); zzinit; } || { + print -P "%F{160}▓▒░ Houston, we have a problem, the %F{226}$cs_get%F{160} do not match\!%f%b"; return 1 +} +unset cs_ok cs_get +``` + + + + +Reload the shell with exec zsh -il and run zi -h for usage information. + +## Automated setup {#automated-setup} + +:::tip + +- Verify the sha256 [checksum][checksum-txt] for file: lib/sh/install.sh +- If required append -b \ or -b \ e.g: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -i skip -b main +``` + +::: + + + + +Install and include minimal configuration to the .zshrc: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- +``` + + + + +Install and include minimal configuration with [loader](#loader): + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a loader +``` + +The installer will download the loader and add the snippet below to the .zshrc file. + +```shell showLineNumbers +if [[ -r "${XDG_CONFIG_HOME:-${HOME}/.config}/zi/init.zsh" ]]; then + source "${XDG_CONFIG_HOME:-${HOME}/.config}/zi/init.zsh" && zzinit +fi +``` + +:::tip + +The loader can be manually fetched from available [links](#loader) to any location on the system, and sourced from .zshrc or as shown in the [quick-setup](#quick-setup). + +::: + +Then reload the shell with: `exec zsh`. すべて完了です！ + + + + +Clone repository using default or if set custom values: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -i skip +``` + + + + +Install and include minimal configuration with recommended annexes: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a annex +``` + + + + +Install and include minimal configuration with recommended annexes and setup zdharma/zunit: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a zunit +``` + + + + +## Manual Setup {#manual-setup} + +:::tip Related + +- [🏗 Configuration management](/docs/guides/customization#customizing-paths) + +::: + +インストール先を設定し、ディレクトリを作成します。 + +```shell showLineNumbers +typeset -Ag ZI +typeset -gx ZI[HOME_DIR]="${HOME}/.zi" ZI[BIN_DIR]="${ZI[HOME_DIR]}/bin" +command mkdir -p "$ZI[BIN_DIR]" +``` + +For security reasons run function compaudit to check if the [completion system][completion-system] would use files owned by root or by the current user, or files in directories that are world or group-writable. + +失敗した場合は、現在のユーザーをディレクトリのオーナーに設定し、グループ/その他の書き込み権限を削除して、リポジトリを複製します。 + +```shell showLineNumbers +compaudit | xargs chown -R "$(whoami)" "$ZI[HOME_DIR]" +compaudit | xargs chmod -R go-w "$ZI[HOME_DIR]" +command git clone https://github.com/z-shell/zi.git "$ZI[BIN_DIR]" +``` + +To enable Zi, source the zi.zsh from the previously set up directory placing the following snippet in the .zshrc file: + +```shell title="~/.zshrc" showLineNumbers +typeset -A ZI +ZI[BIN_DIR]="${HOME}/.zi/bin" +source "${ZI[BIN_DIR]}/zi.zsh" +``` + +:::caution + +以下の2行は、上の行の後、つまりZiを有効にした後に配置する必要があります。 + +::: + +以下でZi補完を有効にします: + +```shell title="~/.zshrc" showLineNumbers +autoload -Uz _zi +(( ${+_comps} )) && _comps[zi]=_zi +``` + +## Post-install {#post-install} + +After a fresh install, it is recommended to reload the shell and recompile Zi with: + +- exec zsh -il +- zi self-update + +Run zi -h for available commands or [explore][collection-page] wiki to [extend][ecosystem-page], [customize][customization-page] and [create][zsh-plugin-standard] . + +If you have any issue or need help , lets [discuss][discuss] it or open an [issue][issue] on GitHub. + +It helps us to improve and make Zi better. Don't forget to help the project: share, contribute, or [translate][help-translate] . + +Let's glue a toolchain that works for us . + +## Have ideas? + +###  Suggest or request at playground + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a ??? +``` + +##  Need warm-up? + +###  Docker Alpine + +```shell +docker run --rm -it ghcr.io/z-shell/zd:latest +``` + +### Turbo Zi in Docker + +If you create a Docker image that uses Zi, install Turbo-loaded plugins before the shell starts interactively, with the @zi-scheduler function in such a way, that it: + +- Install plugins without waiting for the prompt (i.e. it's script friendly). +- Install all plugins instantly, without respecting the wait argument. + +To accomplish this, use burst argument and call the @zi-scheduler function: + +```docker +RUN zsh -i -c -- '@zi-scheduler burst || true' +``` + +> - An example: [Dockerfile][dockerfile] +> - In action: [Playground][playground] + +## Zi Module: zpmod {#zi-module} + +The module transparently and automatically compiles sourced scripts and lists of all sourced files with the time the sourcing took in milliseconds on the left. + +- [⚙️ Wiki: zpmod][zpmod-page] +- [📦 Source: zpmod][z-shell/zpmod] + +## Available links {#available-links} + +[Status page][status] + +### Installer {#installer} + +| サービス | URL | +| :--------- | ----------------------------------------------------------------------- | +| リダイレクト | https://get.zshell.dev | +| Cloudflare | https://src.zshell.dev/sh/install.sh | +| Git.io | https://git.io/get-zi | +| GitHub RAW | https://raw.githubusercontent.com/z-shell/zi-src/main/lib/sh/install.sh | + +### Loader {#loader} + +| サービス | URL | +| :--------- | ---------------------------------------------------------------------- | +| リダイレクト | https://init.zshell.dev | +| Cloudflare | https://src.zshell.dev/zsh/init.zsh | +| Git.io | https://git.io/zi-loader | +| GitHub RAW | https://raw.githubusercontent.com/z-shell/zi-src/main/lib/zsh/init.zsh | + + + + + +[zpmod-page]: /ecosystem/plugins/zsh-modules#-z-shellzpmod + +[customization-page]: /docs/guides/customization + +[ecosystem-page]: /ecosystem + +[collection-page]: /community/category/-collection + +[zsh-plugin-standard]: /community/zsh_plugin_standard + + + +[checksum-txt]: https://raw.githubusercontent.com/z-shell/zi-src/main/lib/checksum.txt + +[completion-system]: https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Use-of-compinit + +[discuss]: https://github.com/orgs/z-shell/discussions/new + +[dockerfile]: https://github.com/robobenklein/configs/blob/master/Dockerfile + +[issue]: https://github.com/z-shell/zi/issues/new/choose + +[playground]: https://github.com/z-shell/playground + +[status]: https://status.zshell.dev + +[help-translate]: https://digitalclouds.crowdin.com/z-shell + +[z-shell/zpmod]: https://github.com/z-shell/zpmod diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx new file mode 100644 index 00000000..51b11dba --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx @@ -0,0 +1,509 @@ +--- +id: overview +title: ☑️ 概要 +image: /img/png/theme/z/320x320.png +description: Zi の使用方法の概要 +--- + +import ImgShow from "@site/src/components/ImgShow"; +import Link from "@docusaurus/Link"; + +この概要では、以下の基礎を説明します。 + +1. [Oh-My-Zsh & Prezto](/search?q=Oh+My+Zsh+%26+Prezto) +2. [Completions](/search?q=completions) +3. [Turbo mode](/search?q=turbo+mode) +4. [Ice modifiers](/search?q=ice+modifiers) + +## プラグインとスニペットの読み込み + +```shell showLineNumbers +zi load z-shell/H-S-MW +zi light zsh-users/zsh-syntax-highlighting +``` + +上記のコマンドは2通りの基本的なプラグインの読み込み方法です。 If you want to source local or remote files (using a direct URL), you can do so with a `snippet`. + +```shell +zi snippet +``` + +Such lines should be added to `.zshrc`. Snippets are cached locally, use the `-f` option to download a fresh version of a snippet, or `zi update {URL}`. Use `zi update --all` to update all snippets and plugins. + +Using `load` causes reporting to be enabled – you can track what the plugin does, view the information with `zi report {plugin-name}`, and then also unload the plugin with `zi unload {plugin-name}`. + +Using `light` is a faster loading without tracking and reporting about the plugin but also withdrawing the ability to unload it. + +Using `load` or `light`: + +```shell showLineNumbers +zi load # Load with reporting/investigating. +zi light # Load without reporting/investigating. +``` + +プラグイン history-search-multi-word が調査しながら読み込み: + +```shell +zi load z-shell/H-S-MW +``` + +2つの通常のプラグインを調査せずに読み込み: + +```shell showLineNumbers +zi light zsh-users/zsh-autosuggestions +zi light z-shell/F-Sy-H +``` + +スニペット: + +```shell +zi snippet https://gist.githubusercontent.com/hightemp/5071909/raw/ +``` + +:::note + +In turbo mode loading, the slowdown by plugin tracking is done in the background and does not affect the user experience, i.e., loading with `zi light` and `zi load` has the same effect. + +::: + +## Oh-My-Zsh, Prezto + +To load Oh-My-Zsh and Prezto plugins, use the `snippet` feature. Snippets are **single files** downloaded by `curl`, `wget`, etc., automatic detection of the download tool is being performed, directly from the URL: + +```shell showLineNumbers +zi snippet 'https://github.com/robbyrussell/oh-my-zsh/raw/master/plugins/git/git.plugin.zsh' +zi snippet 'https://github.com/sorin-ionescu/prezto/blob/master/modules/helper/init.zsh' +``` + +Also, for Oh-My-Zsh and Prezto, you can use `OMZ::` and `PZT::` shorthands: + +```shell showLineNumbers +zi snippet OMZ::plugins/git/git.plugin.zsh +zi snippet PZT::modules/helper/init.zsh +``` + +さらに、GitHubはスニペットのためにSubversionプロトコルをサポートしています。 This allows loading snippets that are multi-file (for example, a Prezto module can consist of two or more files, e.g. `init.zsh` and `alias.zsh`). + +Default files that will be sourced are: `*.plugin.zsh`, `init.zsh`, `*.zsh-theme`: + +URLはディレクトリを指します: + +```shell {2} showLineNumbers +zi ice svn +zi snippet PZT::modules/docker +``` + +## スニペットとパフォーマンス + +Using `curl`, `wget`, etc. along with Subversion allows us to almost completely avoid code dedicated to Oh-My-Zsh and Prezto, and also to other frameworks. メモリへの負荷が少なく、ロード時間も短いため、より高いパフォーマンスを実現します。 + +## Ice 修飾子 + +The command `zi ice` provides [ice modifiers][1] for the single Zi command, i.e., `zi ice ; zi load some/plugin`, after loading some/plugin the ice-modifier has to be set again. + +この考え方は、"氷"が飲み物やコーヒーに入れられるようなもので、これをZIに置き換えると、iceは次のZIコマンドへ変更を与えることを意味しています。 また、溶けること(つまり長く続かない)は、Ziの中ではその変更は次のZIコマンドにのみ有効ということです。 + +Using one other ice modifier "**pick**" users can explicitly **select the file to source**: + +```shell {1} showLineNumbers +zi ice svn pick"init.zsh" +zi snippet PZT::modules/git +``` + +The content of the ice-modifier is simply put into `"…"`, `'…'`, `$'…'`. No need for `":"` after the ice-modifier name (although it's allowed: as the equal sign `=`, e.g. `pick="init.zsh"` or `pick=init.zsh`). + +This way editors like `vim` and `emacs` and also `zsh-users/zsh-syntax-highlighting` and `z-shell/F-Sy-H` will highlight the contents of ice-modifiers. + +## as"program" について + +A plugin might not be a file for sourcing, but a command to be added to `$PATH`. To obtain this effect, use ice-modifier `as` with value `program` (or an alias value `command`). + +```shell {1} showLineNumbers +zi ice as"program" cp"httpstat.sh -> httpstat" pick"httpstat" +zi light b4b4r07/httpstat +``` + +The above command will add plugin directory to `$PATH`, copy file `httpstat.sh` into `httpstat` and add execution rights (`+x`) to the file selected with `pick`, i.e. to `httpstat`. Another ice-mod exists, `mv`, which works like `cp` but **moves** a file instead of **copying** it. `mv` is run before `cp`. + +:::tip + +The `cp` and `mv` ices (and also some other ones, like `atclone`) are being run when the plugin or snippet is being _installed_. To test them again first delete the plugin or snippet (example: `zi delete PZT::modules/osx`). + +::: + +## Ice 修飾子: atpull'…' + +Copying file is safe for doing later updates – original files of the repository are unmodified and `Git` will report no conflicts. However, `mv` also can be used, if a proper `atpull`, an ice-modifier ran at **update** of the plugin: + +```shell showLineNumbers +zi ice as"program" mv"httpstat.sh -> httpstat" \ + pick"httpstat" atpull'!git reset --hard' +zi light b4b4r07/httpstat +``` + +If `atpull` starts with an exclamation mark, then it will be run before `git pull`, and before `mv`. Nevertheless, `atpull`, `mv`, and `cp` are run **only if new commits are to be fetched**. + +So in summary, when the user runs `zi update b4b4r07/httpstat` to update this plugin, and there are new commits, what happens first is that `git reset --hard` is run – and it **restores** original `httpstat.sh`, **then** `git pull` is ran and it downloads new commits (doing fast-forward), **then** `mv` is running again so that the command is `httpstat` not `httpstat.sh`. + +This way the `mv` ice can be used to induce permanent changes into the plugin's contents without blocking the ability to update it with `git` or with `subversion` in the case of snippets. + +:::info + +For exclamation marks to not be expanded by Zsh an interactive session, use `'…'` not `"…"` to enclose contents of `atpull` [ice-modifier](/search?q=ice-modifier). + +::: + +## Ice 修飾子: subscribe'…' + +このice修飾子は、与えられたファイル(複数可) の更新時間をチェックしながらプラグインの読み込みを延期し、変更されるとプラグインまたはスニペットの読み込みを実行します。 + +Copy and paste the example below to the terminal or add it to the `.zshrc` file and reload the shell with `exec zsh`. + +```shell {1} showLineNumbers +zi ice subscribe'{~/files-*,/tmp/files-*}' id-as'z-sub' lucid \ + atload'+zi-message "{profile}I have been loaded{nl}\ + {auto}\`Zi Rocks ♥\`"' notify"Yes that is cool ♥ " +zi load z-shell/0 +``` + +上記で説明したようにファイルを更新して、 ice 修飾子をテストします。 + +```shell +touch ~/files-1 +``` + +プラグインやスニペットは、ファイルが更新されるたびに何度でもsourceされます。 + +## スニペットで as'…' program + +Commands can also be added to `$PATH` using **snippets**: + +```shell {2} showLineNumbers +zi ice mv"httpstat.sh -> httpstat" \ + pick"httpstat" as"program" +zi snippet https://github.com/b4b4r07/httpstat/blob/master/httpstat.sh +``` + +:::tip + +Snippets also support `atpull`, e.g. `atpull'!svn revert'`. There’s also an `atinit` ice-modifier, executed before each loading of plugin or snippet. + +::: + +## スニペットで as'…' completion + +By using the `as'…'` ice modifier with the value `completion` you can point the `snippet` subcommand directly to a completion file: + +```shell {1} showLineNumbers +zi ice as"completion" +zi snippet https://github.com/docker/cli/blob/master/contrib/completion/zsh/_docker +``` + +## 補完管理 + +Ziは、各プラグインの各補完機能を無効化、有効化することができます。 補完を提供する人気のプラグインをインストールしてみましょう: + +```shell {1} showLineNumbers +zi ice blockf +zi light zsh-users/zsh-completions +``` + +The first command, the `blockf` ice, will block the traditional method of adding completions. Zi uses this method, based on symlinks instead of adding several directories to `$fpath`. Zi will automatically **install** completions of a newly downloaded plugin. + +補完のアンインストールとインストール: + +アンインストール: + +```shell +zi cuninstall zsh-users/zsh-completions +``` + +インストール: + +```shell +zi creinstall zsh-users/zsh-completions +``` + +### 使用可能な補完のリスト + +To see what completions **all** plugins provide, in tabular formatting and with the name of each plugin: + +```shell +zi clist +``` + +This command is adapted for plugins like `zsh-users/zsh-completions`, which provide many completions – listing will have `3` completions per line, and a smaller number of terminal pages can be occupied like this: + + + +To show more completions per line by providing an **argument** to `clist`, e.g.: `zi clist 6`, will show: + + + +### 補完の有効化／無効化 + +補完を無効にし、Zshの組み込み関数など他の補完を使用することも可能です。 The commands are very basic, they only need completion **name**: + +Disable `cmake` completion: + +```shell +zi cdisable cmake +``` + +Enable `cmake` completion: + +```shell +zi cenable cmake +``` + +Command `zi csearch` will **search** all plugin directories for available completions: + + + +## Subversionを使ってサブディレクトリ指定 + +In general, to use **subdirectories** of Github projects as snippets add `/trunk/{path-to-dir}` to the URL: + +```shell showLineNumbers +zi ice svn +zi snippet https://github.com/zsh-users/zsh-completions/trunk/src +``` + +:::tip + +For Oh-My-Zsh and Prezto, the OMZ:: and PZT:: prefixes work without the need to add the `/trunk/` infix, however, the path should point to a directory, not to a file. + +::: + +```shell showLineNumbers +zi ice svn +zi snippet PZT::modules/docker +``` + +## Turbo Mode (Zsh >= 5.3) {#turbo-mode-zsh--53} + +The ice-modifier `wait` allows the user to postpone the loading of a plugin to the moment when the processing of `.zshrc` is finished and the first prompt is shown. + +Windowsと同じで、起動時に、バックグラウンドでデータを読み込んでいるにもかかわらず、デスクトップを表示するのです。 欠点もありますが、10分も真っ白な画面が続くよりは確実にマシです。 しかし、Ziでは、この方法の欠点はありません 。ラグやフリーズなどはありません。プラグインがロードされている間、コマンドラインは完全に使用可能で、プラグインの数に関係なく使用できます。 + +:::info + +Turbo will speed up Zsh startup by **50%–80%**. たとえば、200ミリ秒ではなく、40ミリ秒になります。 + +::: + +:::note + +Zsh 5.3以降が必要です。 + +::: + +To use turbo mode add `wait` ice to the target plugin in one of the following ways: + +```shell {2} showLineNumbers +PS1="READY > " +zi ice wait'!0' +zi load halfo/lambda-mod-zsh-theme +``` + +This sets plugin `halfo/lambda-mod-zsh-theme` to be loaded `0` seconds after `.zshrc`. これは、 1 ms of showing the basic prompt `READY >`. + +このような方法でプロンプトを読み込むことはないでしょうが、ターボモードが観察できる良い例です。 感嘆符を使うと、Zi はプラグインのロード後にプロンプトをリセットします。これはテーマに大抵必要です。 Prezto プロンプトの場合も同様です。遅延時間がより長い場合: + +```shell showLineNumbers +zi ice svn silent wait'!1' atload'prompt smiley' +zi snippet PZT::modules/prompt +``` + +Using `zsh-users/zsh-autosuggestions` without any drawbacks: + +```shell showLineNumbers +zi ice wait lucid atload'!_zsh_autosuggest_start' +zi light zsh-users/zsh-autosuggestions +``` + +### ターボモードが性能の決め手です。 + +非同期で読み込むことができるので、プラグインの量が増えたときに大きな差が出ます。 Usually used as `zi ice wait''`. + +:::note + +The `wait` is equivalent to `wait'0'`. + +::: + +```shell showLineNumbers +zi ice wait +zi load z-shell/H-S-MW +``` + +2秒後に読み込みむ: + +```shell showLineNumbers +zi ice wait'2' +zi load z-shell/H-S-MW +``` + +Also can be used in `light` and `snippet`: + +```shell showLineNumbers +zi ice wait +zi snippet https://gist.githubusercontent.com/hightemp/5071909/raw/ +``` + +### Turbo mode & lucid + +Turbo and lucid are the most used options because turbo mode is verbose and may require an option for quiet and this can be achieved with the `lucid`. + +```shell showLineNumbers +zi ice wait lucid +zi load z-shell/H-S-MW +``` + +## 高度なプロンプトを使用したターボ・モード + +For some, mostly advanced themes the initialization of the prompt is being done in a `precmd`-hook, i.e.; in a function that gets called before each prompt. The hook is installed by the [add-zsh-hook][12] Zsh function by adding its name to the `$precmd_functions` array. + +To make the prompt fully initialized after turbo mode loading in the middle of the prompt the same situation as with the `zsh-autosuggestions` plugin, the hook should be called from `atload'…'` ice. + +First, find the name of the hook function by examining the `$precmd_functions` array. For example, for the `robobenklein/zinc` theme, they'll be two functions: `prompt_zinc_setup` and `prompt_zinc_precmd`: + +```shell title="print $precmd_functions" +_zsh_autosuggest_start prompt_zinc_setup prompt_zinc_precmd +``` + +Then, add them to the ice list in the `atload'…'` ice: + +```shell {2} showLineNumbers +zi ice wait'!' lucid nocd \ + atload'!prompt_zinc_setup; prompt_zinc_precmd' +zi load robobenklein/zinc +``` + +The exclamation mark in `atload'!…'` is to track the functions allowing the plugin to be unloaded, as described [here](/docs/guides/syntax/standard#atclone-atpull-atinit-atload). 次に説明するマルチプロンプトの設定に便利かもしれません。 + +### ターボモードのまとめ + +Autosuggestions use the `precmd` hook, which is being called right after processing `.zshrc` – `precmd` hooks are being called **right before displaying each prompt**. + +Turbo mode with the empty `wait` ice will postpone the loading `1` ms after that, so `precmd` will not be called at that first prompt. これにより、最初のプロンプトでautosuggestionは無効となります。 + +**However** the given `atload'…'` ice-modifier fixes this, it calls the same function that `precmd` would, right after loading autosuggestions, resulting in the same behavior of the plugin. + +The ice called `lucid` causes the under-prompt message saying `Loaded zsh-users/zsh-autosuggestions` that normally appears for every Turbo-loaded plugin to not show. + +## Automatic condition based - load & unload + +Ices `load` and `unload` allow defining when you want plugins active or inactive: + +Load when in `~/tmp`: + +```shell {1} showLineNumbers +zi ice load'![[ $PWD = */tmp* ]]' unload'![[ $PWD != */tmp* ]]' \ + atload'!promptinit; prompt sprint3' +zi load z-shell/zprompts +``` + + + +Load when NOT in `~/tmp`: + +```shell {1} showLineNumbers +zi ice load'![[ $PWD != */tmp* ]]' unload'![[ $PWD = */tmp* ]]' +zi load russjohnson/angry-fly-zsh +``` + + + +2つのプロンプトは、それぞれ異なるディレクトリでアクティブになります。 This technique can be used to have plugin-sets, e.g. by defining parameter `$PLUGINS` with possible values like `cpp`, `web`, `admin` and by setting `load` / `unload` conditions to activate different plugins on `cpp`, on `web`, etc. + +:::note + +- The difference with `wait` is that `load` / `unload` are constantly active, not only till the first activation. Note that for the unloading of a plugin to work the plugin needs to be loaded with tracking, so `zi load …` and not `zi light …`. + +トラッキングにより若干の速度低下が発生しますが、ターボモード使用時のZsh起動時間には影響ありません。 + +::: + +### プロンプトの概要 + +:::tip + +参照： 複数のプロンプト または詳細。 マルチプロンプト・セットアップの実際の例をさらに示します。これは、著者がセットアップで使用するものに近いものです。 + +::: + +This is [powerlevel10k](https://github.com/romkatv/powerlevel10k), [pure](https://github.com/sindresorhus/pure), [starship](https://github.com/starship/starship) sample: + +powerlevel10kのテーマを読み込む: + +```shell title="~/.zshrc" showLineNumbers +zi ice depth"1" +zi light romkatv/powerlevel10k +``` + +pure のテーマを読み込む: + +> will pick the `async.zsh` library and will source it. + +```shell {1} title="~/.zshrc" showLineNumbers +zi ice pick"async.zsh" src"pure.zsh" +zi light sindresorhus/pure +``` + +starship テーマをロード読み込む: + +> - pick `starship` binary as a command, from the GitHub release. +> - setup `starship` using `atclone` and create `init.zsh` and `completion`. +> - the `atpull'…'` behavior same as `atclone'…'` and but is used when running `zi update`. +> - `src` will source `init.zsh`. + +```shell {2} {3} title="~/.zshrc" showLineNumbers +zi ice as"command" from"gh-r" \ + atclone"./starship init zsh > init.zsh; ./starship completions zsh > _starship" \ + atpull"%atclone" src"init.zsh" +zi light starship/starship +``` + +### Common use cases {#common-use-cases} + +Load the pure theme, with the **zsh-async** library that's bundled with it. + +```shell title="~/.zshrc" showLineNumbers +zi ice pick"async.zsh" src"pure.zsh" +zi light sindresorhus/pure +``` + +GitHub のバイナリのリリースを使う場合。 自動で展開後、プログラム "fzf "を提供します。 + +```shell title="~/.zshrc" showLineNumbers +zi ice from"gh-r" as"program" +zi light junegunn/fzf +``` + +One other binary release needs renaming from `docker-compose-Linux-x86_64`. This can be done by [ice modifier][1]: `mv'{from} -> {to}'`. + +There are multiple packages per single version for OS X, Linux, and Windows – the ice-modifier `bpick` is utilized to select the Linux package – in this case - not required, Zi will grep operating system name and architecture automatically when there's no `bpick`. + +```shell title="~/.zshrc" showLineNumbers +zi ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*" +zi load docker/compose +``` + +Handle completions without loading any plugin, see the `clist` command. こちらは、インタラクティブセッションで一度だけ実行することになっています。 + +```shell title="~/.zshrc" +zi creinstall %HOME/my_completions +``` + +If you are interested to try out more then check out the [playground repository](https://github.com/z-shell/playground) where users have uploaded the `~/.zshrc` and other Zi configurations. Feel free to [submit](https://github.com/z-shell/playground/issues/new?template=request-to-add-zshrc-to-the-zi-configs-repo.md) your `~/.zshrc` configuration. + +Additional examples: [collection](/community/gallery/collection). + + + + + +[1]: /search?q=ice+modifiers + +[12]: /community/zsh_plugin_standard#use-of-add-zsh-hook-to-install-hooks diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx new file mode 100644 index 00000000..8a0c3737 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx @@ -0,0 +1,476 @@ +--- +id: migration +title: ♻️ 移行 +image: /img/png/theme/z/320x320.png +description: 移行ガイド +keywords: + - prezto + - oh-my-zsh +--- + +import Link from "@docusaurus/Link"; + +## Oh-My-Zsh + +### OMZ のショートハンドシンタックス + +```shell title="~/.zshrc" showLineNumbers +zi snippet # Raw syntax with URL +zi snippet OMZ:: # Shorthand OMZ:: (http://github.com/ohmyzsh/ohmyzsh/raw/master/) +zi snippet OMZL:: # Shorthand OMZ::lib (http://github.com/ohmyzsh/ohmyzsh/raw/master/lib) +zi snippet OMZT:: # Shorthand OMZ::themes (http://github.com/ohmyzsh/ohmyzsh/raw/master/themes) +zi snippet OMZP:: # Shorthand OMZ::plugins (http://github.com/ohmyzsh/ohmyzsh/raw/master/plugins) +``` + +### OMZライブラリ + +Importing the [clipboard][omz/clipboard] and [termsupport][omz/termsupport] from the OMZ library example: + +生の構文: + +```shell title="~/.zshrc" showLineNumbers +zi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh +zi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh +``` + +OMZの省略記号構文: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZ::lib/clipboard.zsh +zi snippet OMZ::lib/termsupport.zsh +``` + +OMZLの省略記号構文: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZL::clipboard.zsh +zi snippet OMZL::termsupport.zsh +``` + +より高度な、Subversionを使ったライブラリの読み込みの例: + +```shell title="~/.zshrc" showLineNumbers +if (( $+commands[svn] )) { + sni=({git,theme-and-appearance,prompt_info_functions,history,completion,vcs_info}.zsh) + zi is-snippet has'svn' for svn \ + multisrc'${sni[*]}' pick'/dev/null' \ + atinit'typeset -gx COMPLETION_WAITING_DOTS=true \ + HISTSIZE=290000 SAVEHIST=290000 HISTFILE=${ZSH_CACHE_DIR}/.history;' \ + OMZ::lib + unset sni +} else { + +zi-message "{auto}Subversion not installed!" +} +``` + +### OMZ プラグイン + +```diff title="~/.zshrc" showLineNumbers +- plugins=( +- git +- dotenv +- rake +- rbenv +- ruby +-) + ++ zi snippet OMZP::git ++ zi snippet OMZP::dotenv ++ zi snippet OMZP::rake ++ zi snippet OMZP::rbenv ++ zi snippet OMZP::ruby +``` + +より高度な、条件付きターボローディングの例: + +```shell title="~/.zshrc" showLineNumbers +zi is-snippet wait lucid for \ + atload"unalias grv g" \ + OMZP::{git,sudo,encode64,extract} \ + if'[[ -d /opt/google-cloud-sdk ]]' \ + OMZP::gcloud \ + if'[[ -f /etc/os-release ]] && source /etc/os-release && [[ "$ID" = arch ]]' \ + OMZP::archlinux \ + if'[[ -d ~/.nvm ]]' \ + OMZP::nvm \ + if'[[ -d ~/.ssh ]]' \ + OMZP::ssh-agent \ + if'[[ -d ~/.gnupg ]]' \ + OMZP::gpg-agent \ + if'[[ "$OSTYPE" = *-gnu ]]' \ + OMZP::gnu-utils \ + has'pip' \ + OMZP::pip \ + has'python' \ + OMZP::python +``` + +:::tip + +上の例を1つのファイルに束ねる: + +`zi snippet テーマによっては、追加の設定が必要な場合があります。それは、テーマ設定ファイルから判断できます。 + +- Load `git` library +- Load the `git` plugin +- ライブラリの依存関係を読み込む +- Enable `setopt prompt_subst` + +上記のうち1つでも欠けていたり、順番が違っていたりすると、以下のようにテーマが壊れます。 + +```shell +… $(build_prompt) … +``` + +If the `Git` library is not loaded or loaded in the wrong order, then it may appear similar to the following: + +```shell showLineNumbers +........:1: command not found: git_prompt_status +........:1: command not found: git_prompt_short_sha +``` + +テーマで問題が発生した場合、OMZサポートライブラリを読み込む必要があります。 + +- If your theme isn't colored when it should, you will want to load `theme-and-appearance.zsh` + +- 次のようなエラーメッセージが表示された場合: + +```shell showLineNumbers +zsh: command not found: ruby_prompt_info +``` + +You need to load `prompt_info_functions.zsh` + +まとめると、次のようになります: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZL::git.zsh +zi snippet OMZP::git +zi snippet OMZL::theme-and-appearance.zsh +zi snippet OMZL::prompt_info_functions.zsh +``` + +その後、プロンプトを読み込みます: + +```shell showLineNumbers +setopt prompt_subst +zi snippet OMZT::robbyrussell +``` + +### External theme sample: [NicoSantangelo/Alpharized][] + +OMZを読み込む: + +```shell title="~/.zshrc" +ZSH_THEME="alpharized" +``` + +Load `git` library from OMZ: + +```shell title="~/.zshrc" +zi snippet OMZL::git.zsh +``` + +Load `git` plugin from OMZ: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZP::git +zi cdclear -q +``` + +その後、プロンプトを読み込みます: + +```shell title="~/.zshrc" showLineNumbers +setopt prompt_subst +zi light NicoSantangelo/Alpharized +``` + +## Prezto + +### PZT 省略記号構文 + +```shell title="~/.zshrc" showLineNumbers +zi snippet # Raw syntax with URL +zi snippet PZT:: # Shorthand PZT:: (https://github.com/sorin-ionescu/prezto/tree/master/) +zi snippet PZTM:: # Shorthand PZT::modules/ (https://github.com/sorin-ionescu/prezto/tree/master/modules/) +``` + +### PZT modules {#pzt-modules} + +Importing the [environment](https://github.com/sorin-ionescu/prezto/tree/master/modules/environment/README.md) and [terminal](https://github.com/sorin-ionescu/prezto/tree/master/modules/terminal/README.md) Prezto modules example: + +生の構文 + +```shell title="~/.zshrc" showLineNumbers +zi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/environment/init.zsh +zi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/terminal/init.zsh +``` + +PZT 省略記号構文: + +```shell title="~/.zshrc" showLineNumbers +zi snippet PZT:: +zi snippet PZT::modules/environment +zi snippet PZT::modules/terminal +``` + +PZTMの省略記号構文: + +```shell title="~/.zshrc" showLineNumbers +zi snippet PZTM:: +zi snippet PZTM::environment +zi snippet PZTM::terminal +``` + +Preztoモジュール: + +```diff title="~/.zshrc" showLineNumbers +- zstyle ':prezto:load' pmodule 'git' +- zstyle ':prezto:load' pmodule 'environment' 'terminal' + ++ zi snippet PZTM::git ++ zi is-snippet for PZTM::environment PZTM::terminal +``` + +利用可能なPreztoモジュール: + +| モジュール名 | 説明 | +| -------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | +| [archive](https://github.com/sorin-ionescu/prezto/blob/master/modules/archive/README.md) | アーカイブの一覧表示や抽出を行う機能を提供します。 | +| [autosuggestions](https://github.com/sorin-ionescu/prezto/blob/master/modules/autosuggestions/README.md) | Integrates `zsh-autosuggestions` plugin into Prezto. | +| [command-not-found](https://github.com/sorin-ionescu/prezto/tree/master/modules/command-not-found/README.md) | Loads the `command-not-found` tool on macOS or Debian-based distributions. | +| [completion](https://github.com/sorin-ionescu/prezto/tree/master/modules/completion/README.md) | Sets TAB completion and provides additional completions from the `zsh-completions`. | +| [directory](https://github.com/sorin-ionescu/prezto/tree/master/modules/directory/README.md) | ディレクトリのオプションを設定し、ディレクトリ・エイリアスを定義します。 | +| [dnf](https://github.com/sorin-ionescu/prezto/tree/master/modules/dnf/README.md) | Defines `dnf` aliases. | +| [docker](https://github.com/sorin-ionescu/prezto/tree/master/modules/docker/README.md) | Defines `docker` aliases and functions. | +| [dpkg](https://github.com/sorin-ionescu/prezto/tree/master/modules/dpkg/README.md) | Defines `dpkg` aliases and functions. | +| [editor](https://github.com/sorin-ionescu/prezto/tree/master/modules/editor/README.md) | キーバインディングを設定します。 | +| [emacs](https://github.com/sorin-ionescu/prezto/tree/master/modules/emacs/README.md) | Emacsの依存関係管理を有効にします。 | +| [environment](https://github.com/sorin-ionescu/prezto/tree/master/modules/environment/README.md) | 一般的なシェルオプションを設定し、環境変数を定義します。 | +| [fasd](https://github.com/sorin-ionescu/prezto/tree/master/modules/fasd/README.md) | 頻繁に使用するファイルやディレクトリのリストを保持し、高速なアクセスを実現します。 | +| [git](https://github.com/sorin-ionescu/prezto/tree/master/modules/git/README.md) | 別名、関数、およびリポジトリー状況情報をプロンプトに表示することによって、 Git を拡張します。 | +| [gnu-utility](https://github.com/sorin-ionescu/prezto/tree/master/modules/gnu-utility/README.md) | GNU 以外のシステムでの GNU ユーティリティのインタラクティブな使用を可能にします。 | +| [gpg](https://github.com/sorin-ionescu/prezto/tree/master/modules/gpg/README.md) | Provides for an easier use of GPG by setting up `gpg-agent`. | +| [haskell](https://github.com/sorin-ionescu/prezto/tree/master/modules/haskell/README.md) | Haskell パッケージのローカルインストールを有効にします。 | +| [helper](https://github.com/sorin-ionescu/prezto/tree/master/modules/helper/README.md) | モジュール開発のためのヘルパー機能を提供します。 | +| [history-substring-search](https://github.com/sorin-ionescu/prezto/tree/master/modules/history-substring-search/README.md) | Zsh-history-substring-searchをPreztoに統合します。 | +| [history](https://github.com/sorin-ionescu/prezto/tree/master/modules/history/README.md) | ヒストリーのオプションを設定し、ヒストリーのエイリアスを定義します。 | +| [homebrew](https://github.com/sorin-ionescu/prezto/tree/master/modules/homebrew/README.md) | Homebrewのエイリアスを定義します。 | +| [macports](https://github.com/sorin-ionescu/prezto/tree/master/modules/macports/README.md) | MacPortsのエイリアスを定義し、MacPortsのディレクトリをpathに追加します。 | +| [node](https://github.com/sorin-ionescu/prezto/tree/master/modules/node/README.md) | Provides utility functions for Node.js and loads `npm` completion. | +| [ocaml](https://github.com/sorin-ionescu/prezto/tree/master/modules/ocaml/README.md) | OCaml パッケージ管理を初期化します。 | +| [osx](https://github.com/sorin-ionescu/prezto/tree/master/modules/osx/README.md) | MacOSのエイリアスや関数を定義しています。 | +| [pacman](https://github.com/sorin-ionescu/prezto/tree/master/modules/pacman/README.md) | Pacman パッケージマネージャとフロントエンドのためのエイリアスや関数を提供します。 | +| [perl](https://github.com/sorin-ionescu/prezto/tree/master/modules/perl/README.md) | MacOSでのPerlモジュールのローカルインストールを可能にし、エイリアスを定義します。 | +| [prompt](https://github.com/sorin-ionescu/prezto/tree/master/modules/prompt/README.md) | プロンプトのテーマを読み込みます。 | +| [python](https://github.com/sorin-ionescu/prezto/tree/master/modules/python/README.md) | ローカルPythonおよびローカルPythonパッケージのインストールを有効にします。 | +| [rails](https://github.com/sorin-ionescu/prezto/tree/master/modules/rails/README.md) | Ruby on Railsのエイリアスを定義します。 | +| [rsync](https://github.com/sorin-ionescu/prezto/tree/master/modules/rsync/README.md) | Defines `rsync` aliases. | +| [ruby](https://github.com/sorin-ionescu/prezto/tree/master/modules/ruby/README.md) | Rubyのローカルgemのインストール、バージョンマネージャのロード、エイリアスの定義などを設定します。 | +| [screen](https://github.com/sorin-ionescu/prezto/tree/master/modules/screen/README.md) | GNU Screen のエイリアスを定義し、起動時に自動起動する機能を提供します。 | +| [spectrum](https://github.com/sorin-ionescu/prezto/tree/master/modules/spectrum/README.md) | 256 colorやエフェクトをより使いやすくするための機能を提供します。 | +| [ssh](https://github.com/sorin-ionescu/prezto/tree/master/modules/ssh/README.md) | Provides for an easier use of SSH by setting up `ssh-agent`. | +| [syntax-highlighting](https://github.com/sorin-ionescu/prezto/tree/master/modules/syntax-highlighting/README.md) | Integrates `zsh-syntax-highlighting` into Prezto. | +| [terminal](https://github.com/sorin-ionescu/prezto/tree/master/modules/terminal/README.md) | ターミナルウィンドウとタブのタイトルを設定します。 | +| [tmux](https://github.com/sorin-ionescu/prezto/tree/master/modules/tmux/README.md) | Defines `tmux` aliases and provides for auto launching it at start-up. | +| [utility](https://github.com/sorin-ionescu/prezto/tree/master/modules/utility/README.md) | 一般的なエイリアスや関数を定義します。 | +| [wakeonlan](https://github.com/sorin-ionescu/prezto/tree/master/modules/wakeonlan/README.md) | このモジュールは、wakeonlanツールのラッパーを提供します。 | +| [yum](https://github.com/sorin-ionescu/prezto/blob/master/modules/autosuggestions/README.md) | yum のエイリアスを定義します。 | + +Use `zi ice svn` if multiple files require an entire subdirectory. + +- [docker](https://github.com/sorin-ionescu/prezto/tree/master/modules/docker/README.md) +- [git](https://github.com/sorin-ionescu/prezto/tree/master/modules/git/README.md) + +```shell title="~/.zshrc" showLineNumbers +zi ice svn +zi snippet PZTM::docker + +zi ice svn +zi snippet PZTM::git +``` + +Use `zi ice as"null"` no `*.plugin.zsh`, `init.zsh`, `*.zsh-theme*` files exist in module directory. + +- [archive](https://github.com/sorin-ionescu/prezto/tree/master/modules/archive/README.md): + +```shell title="~/.zshrc" showLineNumbers +zi ice svn as"null" +zi snippet PZTM::archive +``` + +Use `zi ice atclone"git clone "` if module have external module. + +- [completion](https://github.com/sorin-ionescu/prezto/tree/master/modules/completion/README.md): + +```shell title="~/.zshrc" showLineNumbers +zi ice svn blockf \ + atclone"git clone --recursive https://github.com/zsh-users/zsh-completions.git external" +zi snippet PZTM::completion +``` + +Use `blockf` to prevent any unnecessary additions to `fpath`, as Zi manages `fpath`. + +:::tip + +What is `zstyle`? + +- Official (zsh.sourceforge.net): [zsh/zutil](https://zsh.sourceforge.net/Doc/Release/Zsh-Modules.html#The-zsh_002fzutil-Module) +- StackExchange: [What does `zstyle` do?][about-zstyle] + +::: + +利用可能 + +## Zgen + +### OMZライブラリの読み込み + +```diff title="~/.zshrc" showLineNumbers +- zgen oh-my-zsh + ++ zi snippet OMZL:: +``` + +### OMZプラグインの読み込み + +```diff title="~/.zshrc" showLineNumbers +- zgen oh-my-zsh + ++ zi snippet OMZP:: +``` + +### Prezto モジュールのロード + +```diff title="~/.zshrc" showLineNumbers +- zgen prezto + ++ zi snippet PZTM:: +``` + +リポジトリを prezto プラグインとして読み込む: + +```diff title="~/.zshrc" showLineNumbers +- zgen pmodule + ++ zi ice ver"" ++ zi load +``` + +### Zgenの要約 + +:::info + +For the `location`: refer src, pick, multisrc ice-modifier. + +::: + +```diff title="~/.zshrc" showLineNumbers +- zgen load [location] [branch] + ++ zi ice ver"[branch]" ++ zi load +``` + +## Zplugの基本 + +```diff title="~/.zshrc" showLineNumbers +- zplug , tag1:, tag2: + ++ zi ice tag1"" tag2"" ++ zi load +``` + +### タグの比較 + +- `as` => `as` +- `use` => `pick`, `src`, `multisrc` +- `ignore` => None +- `from` => `from` +- `at` => `ver` +- `rename-to` => `mv`, `cp` +- `dir` => Selection(`pick`, …) with rename +- `if` => `if` +- `hook-build` => `atclone`, `atpull` +- `hook-load` => `atload` +- `frozen` => None +- `on` => None +- `defer` => `wait` +- `lazy` => `autoload` +- `depth` => `depth` + + + + + + + +[about-zstyle]: https://unix.stackexchange.com/questions/214657/what-does-zstyle-do + +[nicosantangelo/alpharized]: https://github.com/nicosantangelo/Alpharized + +[omz/ag]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/ag + +[omz/clipboard]: https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh + +[omz/docker]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker + +[omz/fd]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/fd + +[omz/gitfast]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/gitfast + +[omz/history-substring-search]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/history-substring-search + +[omz/osx]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/macos + +[omz/termsupport]: https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/_category_.json new file mode 100644 index 00000000..32a2af52 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting_started/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "🚀 はじめに", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/01_commands.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/01_commands.mdx new file mode 100644 index 00000000..40070c4d --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/01_commands.mdx @@ -0,0 +1,262 @@ +--- +id: commands +title: 🛠 Commands +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: Zi subcommands and functionality +slug: commands +--- + + + +import Link from "@docusaurus/Link"; +import APITable from "@site/src/components/APITable"; +import ZiTabCompletion from "@site/src/components/Markdown/_zi_tab_completion.mdx"; + +## Updates {#updates-upgrades} + +To update and recompile Zi run `zi self-update` in the command line. To update all plugins and snippets, issue `zi update`. To update all in parallel (up to 40 at the time) `zi update -p 40` If you wish to update only a single plugin/snippet instead issue `zi update `. A list of commits will be shown if any. + +Some plugins require acting each time they're updated. One way you can do this is by using the `atpull'…'` ice modifier. For example, writing `zi ice atpull'./configure'` before loading a plugin will execute `./configure` after a successful update. Refer to [ice-modifiers][1] for more information. + +The ice-modifiers for any plugin or snippet are stored in their directory in a `._zi` subdirectory, hence the plugin doesn't have to be loaded to be correctly updated. There's one other file created there, `.zi_lstupd` – it holds the log of the new commits pulled-in in the last update. + +Self-update & compile: + +```shell +zi self-update +``` + +プラグインとスニペットを更新: + +```shell showLineNumbers +zi update --all +zi update --reset +zi update --quiet +``` + +プラグインまたはスニペットを更新: + +```shell showLineNumbers +zi update --plugins +zi update --snippets +``` + +特定のプラグインを更新 Default is GitHub but can specify any with ice [from'…'](/search?q=from): + +```shell +zi update / +``` + +プラグインの並列アップデート + +```shell +zi update --parallel +``` + +同時実行するジョブの数を 40 に増やす + +```shell +zi update --parallel 40 +``` + +## Compinit + +:::note + +Calling `compinit` once is a huge performance gain, for example, shell startup time with double `compinit`: **0.980** sec, with `cdreplay` and single `compinit`: **0.156** sec. + +::: + +### Calling `compinit` without turbo mode + +With no turbo mode in use, compinit can be called normally, i.e.: as `autoload compinit; compinit`. This should be done after loading all plugins and before possibly calling `zi cdreplay`. The `cdreplay` subcommand is provided to re-play all caught `compdef` calls. The `compdef` calls are used to define a completion for a command. For example, `compdef _git git` defines that the `git` command should be completed by a `_git` function. The `compdef` function is provided by the `compinit` call. + +As it should be called later, after loading all of the plugins, Zi provides its own `compdef` function that catches (i.e.: records in an array) the arguments of the call, so that the loaded plugins can freely call `compdef`. Then, the `cdreplay` (compdef-replay) can be used, after `compinit` will be called (and the original `compdef` function will become available), to execute all detected `compdef` calls. + +```shell title="~/.zshrc" showLineNumbers +source ~/.zi/bin/zi.zsh + +zi load "some/plugin" + +(…) + +compdef _gnu_generic fd # this will be intercepted by ZI, because as the compinit + # isn't yet loaded, thus there's no such function `compdef'; yet + # ZI provides its own `compdef' function which saves the + # completion-definition for later possible re-run with `zi + # cdreplay' or `zicdreplay' (the second one can be used in hooks + # like atload'…', atinit'…', etc.) + +(…) + +zi load "other/plugin" + +autoload -Uz compinit +compinit + +zi cdreplay -q # -q is for quiet; actually, run all the `compdef's saved before + #`compinit` call (`compinit' declares the `compdef' function, so + # it cannot be used until `compinit' is run; ZI solves this + # via intercepting the `compdef'-calls and storing them for later + # use with `zi cdreplay') +``` + +### Calling `compinit` with turbo mode + +If you load completions using `wait'…'` [turbo mode][2] then you can add `atinit'zicompinit'` to the syntax-highlighting plugin (which should be the last one loaded, as their (2 projects, [zsh-syntax-highlighting][3] & [F-Sy-H][4]) documentation state), or `atload'zicompinit'` to last completion-related plugin. `zicompinit` is a function that just runs `autoload compinit; compinit`, created for convenience. + +Alternatively, the `zicompinit` can be replaced with `zicompinit_fast` which checks the cached `.zcompdump` and determines when to regenerate the file. This restricts checking it once a day, as compinit doesn't always need to modify the compdump and compiles mapped to share in the background in multiple shells. + +There's also `zicdreplay` which will replay any caught compdefs so you can also do: `atinit'zicompinit; zicdreplay'`, etc. + +It is recommended to run the `compinit` call in the `atinit` or `atload` hook of the last related plugin with the use of the helper functions `zicompinit`,`zicdreplay` & `zicdclear` as shown below: + +```shell {10} title="~/.zshrc" showLineNumbers +source ~/.zi/bin/zi.zsh + +# Load using the for-syntax +zi wait lucid for \ + "some/plugin" + +zi wait lucid for \ + "other/plugin" + +zi wait lucid atload"zicompinit; zicdreplay" blockf for \ + zsh-users/zsh-completions +``` + +### Ignoring compdefs + +If you want to ignore compdefs provided by some plugins or snippets, place their load commands before commands loading other plugins or snippets, and issue `zi cdclear` (or `zicdclear`, designed to be used in hooks like `atload'…'`): + +```shell showLineNumbers +source ~/.zi/bin/zi.zsh +zi snippet OMZP::git +zi cdclear -q # <- forget completions provided by Git plugin + +zi load "some/plugin" + +(…) + +zi load "other/plugin" + +autoload -Uz compinit +compinit +zi cdreplay -q # <- execute compdefs provided by rest of plugins +zi cdlist # look at gathered compdefs +``` + +The `cdreplay` is important if you use plugins like `OMZP::kubectl` or `asdf-vm/asdf` because these plugins call `compdef`. + +Following commands are passed to `zi …` to obtain described effects. + +## Loading and unloading + +| Command | 説明 | +| :------------------: | ------------------------------------------------------------------------------------------------- | +| `load` `'…'` | Load plugin, can also receive absolute local path. | +| `light` `-b` `'…'` | Light plugin load, without reporting/investigating. `-b` – investigate `bindkey`-calls only. [^1] | +| `unload` `-q` `'…'` | Unload plugin loaded with `zi load …`. `-q` – quiet. | +| `snippet` `-f` `URL` | Source local (full path) or remote file (URL). `-f` – don't use cache (force re-download). [^2] | + +## Completions management + +| Command | 説明 | +| :------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------- | +| `clist` `columns` or `completions` `columns` | List completions in use, with `columns` completions per line. `zi clist 5` will for example print 5 completions per line. Default is 3. | +| `cdisable` `'…'` | Disable completion. | +| `cenable` `'…'` | Enable completion. | +| `creinstall` `-q` `-Q` `'…'` | Install completions for the plugin, can also receive absolute local path. `-q` – quiet. `-Q` - quiet all. | +| `cuninstall '…'` | Uninstall completions for the plugin. | +| `csearch` | Search for available completions from any plugin. | +| `compinit` | Refresh installed completions. | +| `cclear` | Clear stray and improper completions. | +| `cdlist` | Show compdef replay list. | +| `cdreplay` `-q` | Replay compdefs (to be done after compinit). `-q` – quiet. | +| `cdclear` `-q` | Clear compdef replay list. `-q` – quiet. | + +## Tracking of the active session + +| Command | 説明 | +| :--------------: | ----------------------------------------------------- | +| `dtrace, dstart` | Start investigating what's going on in the session. | +| `dstop` | Stop investigating what's going on in the session. | +| `dunload` | Revert changes recorded between `dstart` and `dstop`. | +| `dreport` | Report what was going on in the session. | +| `dclear` | Clear report of what was going on in the session. | + +## Reports and statistics + +| Command | 説明 | +| :-----------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `times` `-s` `-m` `-a` | Statistics on plugin load times, sorted in order of loading. `-s` – use seconds instead of milliseconds. `-m` – show plugin loading moments and `-a` both. | +| `zstatus` | Overall ZI status. | +| `report` `'…'` `--all` | Show plugin report. `--all` – do it for all plugins. | +| `loaded` | Show loaded plugins | +| `list` `keyword` | Filter loaded plugins with only 'keyword' | +| `ls` | List snippets in a formatted and colorized manner. Requires **tree** program. | +| `status` `'…'` or `URL` `--all` | Git status for plugin or svn status for the snippet. `--all` – do it for all plugins and snippets. | +| `recently` `time-spec` | Show plugins that changed recently, the argument is e.g. 1 month 2 days. | +| `bindkeys` | Lists bindkeys set up by each plugin. | + +## Compiling + +| Command | 説明 | +| :-----------------------: | ----------------------------------------------------------------------- | +| `compile` `'…'` `--all` | Compile plugin. `--all` – compile all plugins. | +| `uncompile` `'…'` `--all` | Remove compiled version of the plugin. `--all` – do it for all plugins. | +| `compiled` | List plugins that are compiled. | + +## Other commands + +| Command | 説明 | +| :------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `self-update` | Updates and compiles Zi. | +| `update` `-q` `-r` `'…'` or `--all` | Update all plugins and snippets with `--all` – for quiet `-q` – execute `git reset --hard` or `svn revert` before pulling changes with `-r`. | +| `ice '…'` | Add ice to next command, argument e.g.: from"gitlab". | +| `delete` `'…'` or `--clean` `--all` | Remove plugin or snippet from disk (good to forget wrongly passed ice-modifiers) `--all` – delete plugins and snippets that are not loaded with `--clean`. | +| `cd '…'` | Jump into the plugin's directory. Also support snippets if fed with URL. | +| `edit '…'` | Edit plugin's file with set $EDITOR. | +| `glance '…'` | Look at plugin's source (pygmentize, source-highlight). | +| `stress '…'` | Test plugin for compatibility with a set of options. | +| `changes '…'` | View plugin's git log. | +| `create '…'` | Create plugin (also together with GitHub repository). | +| `srv` `service-id` `{command}` | Control a service, command can be: stop,start,restart,next,quit; `next` moves the service to another Z shell. | +| `recall '…'` `URL` | Fetch saved ice modifiers and construct `zi ice '…'` command. | +| `env-whitelist` `-v` `-h` `{env..}` | Allows to specify names or patterns of variables left unchanged during an unload – verbose `-v` – help `-h`. | +| `module` | Manage binary Zsh module shipped with ZI, see `zi module help`. | +| `add-fpath` `fpath` `-f` `--front` `'…'` `sub-directory` | Adds given plugin (not yet snippet) directory to `$fpath`. If the second argument is given, it is appended to the directory path. [^3] | +| `run` `-l` `plugin` `{command}` | Runs the given command in the given plugin's directory. [^4] | + +## Help & manual + +| Command | 説明 | +| :--------: | ---------------- | +| `-h, help` | 利用方法 | +| `man` | マニュアル | + +## Commands available using ^TAB completion + + + + + + + +[^1]: There's also `light-mode` ice which can be used to induce the no-investigating (i.e.: _light_) loading, regardless of the command used. +[^2]: The URL can use the following shorthands: `PZT::` (Prezto), `PZTM::` (Prezto module), `OMZ::` (Oh-My-Zsh), `OMZP::` (OMZ plugin), `OMZL::` (OMZ library), `OMZT::` (OMZ theme), e.g.: `PZTM::environment`, `OMZP::git`, etc. +[^3]: The `'…'` can be an absolute path, i.e.: it's possible to also add regular directories. If the option `-f` or `--front` is given, the directory path is prepended instead of appended to `$fpath`. +[^4]: If the option `-l` will be given then the plugin should be skipped – the option will cause the previous plugin to be reused. + + + +[1]: /search/?q=ice-modifiers + +[2]: /search?q=turbo+mode + + + +[3]: https://github.com/zsh-users/zsh-syntax-highlighting + +[4]: https://github.com/z-shell/F-Sy-H diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/02_customization.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/02_customization.mdx new file mode 100644 index 00000000..68e169e5 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/02_customization.mdx @@ -0,0 +1,331 @@ +--- +id: customization +title: 🏗 Configuration management +sidebar_position: 2 +image: /img/png/theme/z/320x320.png +description: User preferences, environment, and configuration. +keywords: + - config + - preferences +--- + + + +import APITable from "@site/src/components/APITable"; +import MultiplePromptsExample from "@site/src/components/Markdown/_multiple_prompts_example.mdx"; + +## Hash parameter + +:::info Related + +- [standard parameter naming][] + +::: + +Set the initial hash definition and custom values, before enabling Zi. + +Example: + +```shell showLineNumbers +typeset -A ZI +ZI[BIN_DIR]="some/custom/path/to/bin" +source "${ZI[BIN_DIR]}/zi.zsh" +``` + +### Customize paths {#customizing-paths} + +```mdx-code-block + +``` + +| Hash Field | デフォルト | 説明 | +| ------------------------------------ | ----------------------------- | ---------------------------------------------- | +| `ZI[HOME_DIR]` | `$HOME/.zi` | Where Zi should create all working directories | +| `ZI[BIN_DIR]` | `$HOME/.zi/bin` | Directory where Zi code resides | +| `ZI[COMPLETIONS_DIR]` | `$ZI[HOME_DIR]/completions` | Completion working directory | +| `ZI[CACHE_DIR]` | `$HOME/.cache/zi` | キャッシュディレクトリ | +| `ZI[CONFIG_DIR]` | `$HOME/.config/zi` | 設定ファイルのディレクトリ | +| `ZI[MAN_DIR]` | `$ZPFX/man` | Directory to store manpages | +| `ZI[LOG_DIR]` | `$ZI[CACHE_DIR]/log` | Directory to store log files | +| `ZI[PLUGINS_DIR]` | `$ZI[HOME_DIR]/plugins` | 作業中ディレクトリのプラグイン | +| `ZI[SNIPPETS_DIR]` | `$ZI[HOME_DIR]/snippets` | Snippets working directory | +| `ZI[ZCOMPDUMP_PATH]` | `${ZI[CACHE_DIR]}/.zcompdump` | Path to `.zcompdump` file | +| `ZI[ZMODULES_DIR]` | `$ZI[HOME_DIR]/zmodules` | Zsh modules working directory | +| [ZPFX][global-parameter-with-prefix] | `$ZI[HOME_DIR]/polaris` | Directory to store binary and related files | + +```mdx-code-block + +``` + +### Modify settings {#modify-settings} + +```mdx-code-block + +``` + +| Hash Field | デフォルト | 説明 | +| -------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ZI[OPTIMIZE_OUT_DISK_ACCESSES]` | `undefined` | If set to `1`, will skip checking if a turbo-loaded object exists on the disk. This option can give a performance gain of about 10 ms out of 150 ms (e.g: Zsh will start up in 140 ms instead of 150 ms). | +| `ZI[COMPINIT_OPTS]` | `undefined` | Options for `compinit` call (e.g: done by `zicompinit`), commonly used with `-C` to speed up loading | +| `ZI[MUTE_WARNINGS]` | `undefined` | If set to `1`, mutes some warnings, specifically the `plugin already registered` warning | +| `ZI[PKG_OWNER]` | `z-shell` | Owner of the [packages][] (`zi pack …`) | + +```mdx-code-block + +``` + +## Non-GitHub (Local) Plugins {#non-github-local-plugins} + +Use the `create` subcommand with user name `_local` (the default) to create the plugin's skeleton in `$ZI[PLUGINS_DIR]`. It will be not connected with the GitHub repository (because of the user name being `_local`). To enter the plugin's directory use the `cd` command with just the plugin's name (without `_local`, it's optional). + +If the username is not `_local`, then Zi will create a repository also on GitHub and set up the correct repository origin. + +## Extending Git {#extending-git} + +Several projects provide git extensions. Installing them with Zi has many benefits: + +- all files are under `$HOME` – no administrator rights are needed, +- declarative setup (like Chef or Puppet) – copying `.zshrc` to a different account brings also git-related setup, +- easy update by e.g: `zi update --all`. + +Below is a configuration that adds multiple git extensions, loaded in Turbo mode, 1 second after prompt, with the use of the [bin-gem-node][z-shell/z-a-bin-gem-node] annex: + +```shell title="~/.zshrc" showLineNumbers +zi as'null' wait'1' lucid for \ + sbin Fakerr/git-recall \ + sbin cloneopts paulirish/git-open \ + sbin paulirish/git-recent \ + sbin davidosomething/git-my \ + sbin iwata/git-now \ + sbin atload'export _MENU_THEME=legacy' \ + arzzen/git-quick-stats \ + sbin'bin/git-dsf;bin/diff-so-fancy' \ + z-shell/zsh-diff-so-fancy \ + make'PREFIX=$ZPFX install' \ + tj/git-extras +``` + +The target directory for installed files is `$ZPFX` - `~/.zi/polaris` by default. + +With [meta-plugins][z-shell/z-a-meta-plugins] consisting of: + +Annexes: + +1. [z-shell/z-a-readurl][], +2. [z-shell/z-a-patch-dl][], +3. [z-shell/z-a-rust][], +4. [z-shell/z-a-bin-gem-node][]. + +Git tools: + +1. [paulirish/git-open][], +2. [paulirish/git-recent][], +3. [davidosomething/git-my][], +4. [arzzen/git-quick-stats][], +5. [iwata/git-now][], +6. [tj/git-extras][], +7. [wfxr/forgit][]. + +just run: + +```shell +zi light-mode for z-shell/z-a-meta-plugins @annexes @ext-git +``` + +## [Zsh option][zsh-options]: `setopt` {#zsh-option-setopt} + +[Options][zsh-options] are primarily referred to by name. These names are case insensitive and underscores are ignored. For example, `allexport` is equivalent to `A__lleXP_ort`. + +The sense of an option name may be inverted by preceding it with `no`, so `setopt No_Beep` is equivalent to `unsetopt beep`. This inversion can only be done once, so `nonobeep` is not a synonym for `beep`. Similarly, `tify` is not a synonym for `nonotify` (the inversion of `notify`). + +### History optimization {#history-optimization} + + + +```shell title="~/.zshrc" showLineNumbers +setopt append_history # Allow multiple sessions to append to one Zsh command history. +setopt extended_history # Show timestamp in history. +setopt hist_expire_dups_first # Expire A duplicate event first when trimming history. +setopt hist_find_no_dups # Do not display a previously found event. +setopt hist_ignore_all_dups # Remove older duplicate entries from history. +setopt hist_ignore_dups # Do not record an event that was just recorded again. +setopt hist_ignore_space # Do not record an Event Starting With A Space. +setopt hist_reduce_blanks # Remove superfluous blanks from history items. +setopt hist_save_no_dups # Do not write a duplicate event to the history file. +setopt hist_verify # Do not execute immediately upon history expansion. +setopt inc_append_history # Write to the history file immediately, not when the shell exits. +setopt share_history # Share history between different instances of the shell. +``` + +### Other tweaks {#other-tweaks} + +```shell title="~/.zshrc" showLineNumbers +setopt auto_cd # Use cd by typing directory name if it's not a command. +setopt auto_list # Automatically list choices on ambiguous completion. +setopt auto_pushd # Make cd push the old directory onto the directory stack. +setopt bang_hist # Treat the '!' character, especially during Expansion. +setopt interactive_comments # Comments even in interactive shells. +setopt multios # Implicit tees or cats when multiple redirections are attempted. +setopt no_beep # Don't beep on error. +setopt prompt_subst # Substitution of parameters inside the prompt each time the prompt is drawn. +setopt pushd_ignore_dups # Don't push multiple copies directory onto the directory stack. +setopt pushd_minus # Swap the meaning of cd +1 and cd -1 to the opposite. +``` + +## Style the [completion system][completion-system-configuration] with: `zstyle` {#style-the-completion-system-with-zstyle} + +What does `zstyle` do? - [unix.stackexchange.com/what-does-zstyle-do][what-does-zstyle-do] + +The `zstyle` handles the obvious style control for the [completion system][completion-system-configuration], but it seems to cover more than just that. e.g., the vcs_info module relies on it for the display of git status in your prompt. You can start by looking at the few explanatory paragraphs in `man zshmodules` in the `zstyle` section. + +### Fuzzy matching of completions {#fuzzy-matching-of-completions} + + + +```shell title="~/.zshrc" showLineNumbers +zstyle ':completion:*' completer _complete _match _approximate +zstyle ':completion:*:match:*' original only +zstyle -e ':completion:*:approximate:*' max-errors 'reply=($((($#PREFIX+$#SUFFIX)/3>7?7:($#PREFIX+$#SUFFIX)/3))numeric)' +``` + +### Pretty completions {#pretty-completions} + +```shell title="~/.zshrc" showLineNumbers +zstyle ':completion:*:matches' group 'yes' +zstyle ':completion:*:options' description 'yes' +zstyle ':completion:*:options' auto-description '%d' +zstyle ':completion:*:corrections' format ' %F{green}-- %d (errors: %e) --%f' +zstyle ':completion:*:descriptions' format ' %F{yellow}-- %d --%f' +zstyle ':completion:*:messages' format ' %F{purple} -- %d --%f' +zstyle ':completion:*:warnings' format ' %F{red}-- no matches found --%f' +zstyle ':completion:*:default' list-prompt '%S%M matches%s' +zstyle ':completion:*' format ' %F{yellow}-- %d --%f' +zstyle ':completion:*' group-name '' +zstyle ':completion:*' verbose yes +zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=*' 'l:|=* r:|=*' +zstyle ':completion:*:functions' ignored-patterns '(_*|pre(cmd|exec))' +zstyle ':completion:*' use-cache true +zstyle ':completion:*' rehash true +``` + +### Do menu-driven completion {#do-menu-driven-completion} + +```shell +zstyle ':completion:*' menu select +``` + +### Color completion for [some things][color-completion-using-zsh-modules-on] {#color-completion-for-some-things} + +```shell +zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS} +``` + +## Disabling System-Wide `compinit` Call (Ubuntu) {#disabling-system-wide-compinit-call-ubuntu} + +On Ubuntu users might get surprised that e.g. their completions work while they didn't call `compinit` in their `.zshrc`. That's because the function is being called in `/etc/zshrc`. + +To disable this call – what is needed to avoid the slowdown and if the user loads any completion-equipped plugins, i.e. almost on 100% – add the following line to `~/.zshenv` to skip the not helping Ubuntu global compinit: + +```shell title="~/.zshenv" +skip_global_compinit=1 +``` + +## Multiple prompts {#multiple-prompts} + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ----------- | :---------------------------------------------------------------- | +| `load'…'` | Condition that when fulfilled will cause the plugin to be loaded. | +| `unload'…'` | Same as above, but will unload the plugin. | + +```mdx-code-block + +``` + +:::note + +`zi light …` loads the plugin without tracking it, while `zi load` tracks the plugin. To be able to unload the plugin, it has to be loaded with `zi load …` instead of `zi light …`. + +::: + +| 構文 | 説明 | +| ------------ | :---------------------------------------------------------------------------------------------------- | +| `atload'!…'` | Run the `precmd` hooks to make the prompts fully initialized when loaded in the middle of the prompt. | +| `precmd` | Hooks are normally run before each **new** prompt. | + +:::info + +Exclamation mark causes the effects of the functions to be tracked. + +::: + +To allow better unloading, conditions are checked every second, you can use conditions like: + +```mdx-code-block + +``` + +| 条件 | 説明 | +| ------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `![[ $PWD == *github* ]]` | Change prompt after changing directory to `*github*`. | +| `![[ $MYPROMPT = 1 ]]` | Change prompt when variable `MYPROMPT = 1` is true. | +| `![[ … ]]` | The exclamation mark causes the prompt to be reset after loading or unloading the plugin `pick'/dev/null'` – disable sourcing of the default-found file. | +| `multisrc'…'` | Source multiple files. | +| `lucid` | Don't show the under-prompt message that says e.g: `Loaded geometry-zsh/geometry`. | +| `nocd` | Don't cd into the plugin's directory when executing the `atload'…'`. | +| `atload'…'` | This ice can make the path that's displayed by the theme point to that directory. | + +```mdx-code-block + +``` + +### Loading and unloading themes (8 examples) {#loading-and-unloading-themes-8-examples} + + + + + + + +[global-parameter-with-prefix]: /community/zsh_plugin_standard#global-parameter-with-prefix + +[packages]: /ecosystem/packages/synopsis + +[standard parameter naming]: /community/zsh_plugin_standard#standard-parameter-naming + + + +[arzzen/git-quick-stats]: https://github.com/arzzen/git-quick-stats + +[color-completion-using-zsh-modules-on]: https://linuxshellaccount.blogspot.com/2008/12/color-completion-using-zsh-modules-on.html + +[completion-system-configuration]: https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Completion-System-Configuration + +[davidosomething/git-my]: https://github.com/davidosomething/git-my + +[iwata/git-now]: https://github.com/iwata/git-now + +[paulirish/git-open]: https://github.com/paulirish/git-open + +[paulirish/git-recent]: https://github.com/paulirish/git-recent + +[tj/git-extras]: https://github.com/tj/git-extras + +[wfxr/forgit]: https://github.com/wfxr/forgit + +[what-does-zstyle-do]: https://unix.stackexchange.com/questions/214657/what-does-zstyle-do/239980 + +[z-shell/z-a-bin-gem-node]: https://github.com/z-shell/z-a-bin-gem-node + +[z-shell/z-a-meta-plugins]: https://github.com/z-shell/z-a-meta-plugins + +[z-shell/z-a-patch-dl]: https://github.com/z-shell/z-a-patch-dl + +[z-shell/z-a-readurl]: https://github.com/z-shell/z-a-readurl + +[z-shell/z-a-rust]: https://github.com/z-shell/z-a-rust + +[zsh-options]: https://zsh.sourceforge.io/Doc/Release/Options.html diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx new file mode 100644 index 00000000..8a8c1e73 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx @@ -0,0 +1,137 @@ +--- +id: benchmark +title: ⏲ ベンチマーク +sidebar_position: 3 +image: /img/png/theme/z/320x320.png +description: Benchmarking, Profiling & Statistics +keywords: + - statistics + - benchmark + - profiling + - レポート +--- + + + +import APITable from "@site/src/components/APITable"; +import ReportZprofExample from "@site/src/components/Markdown/_report_zprof_example.mdx"; + +:::info + +Run `zi analytics` to see the available commands for statistics and reporting. + +::: + +## Profile plugins + +```shell title="~/.zshrc" showLineNumbers +zi ice atinit'zmodload zsh/zprof' \ + atload'zprof | head -n 20; zmodload -u zsh/zprof' +zi light z-shell/F-Sy-H +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ----------- | :----------------------------------------------------------------------------------------------------------------------- | +| `atinit'…'` | loads the `zsh/zprof` module, shipped with Zsh, before loading the plugin – this starts the profiling. | +| `atload'…'` | works after loading the plugin – shows profiling results `zprof / head`, unloads `zsh/zprof` - this stops the profiling. | + +```mdx-code-block + +``` + +While in effect, only a single plugin, in this case, `z-shell/F-Sy-H`, will be profiled. + +The rest plugins will go on completely normally, as when plugins are loaded with `light` - reporting is disabled. + +Less code is being run in the background, the automatic data gathering, during loading of a plugin, for the reports and the possibility to unload the plugin will be activated and the functions will not appear in the `zprof` report. + +Example `zprof` report: + + + +The first column is the time in milliseconds: + +- It denotes the amount of time spent in a function in total +- For example, `--zi-shadow-autoload` consumed 10.71 ms of the execution time + +The fourth column is also a time in milliseconds, but it denotes the amount of time spent on executing only of function's **own code**, it doesn't count the time spent in **descendant functions** that is called from the function: + +- For example, `--zi-shadow-autoload` spent 8.71 ms on executing only its code + +The table is sorted in the **self-time** column. + +## Profile `.zshrc` startup + +### 方法1 + +> `PROFILE_STARTUP=true` to enable profiling. + +Place the snippet below at the top of `.zshrc`. + +```shell title="~/.zshrc" showLineNumbers +PROFILE_STARTUP=false + +if [[ "$PROFILE_STARTUP" == true ]]; then + zmodload zsh/zprof + PS4=$'%D{%M%S%.} %N:%i> ' + exec 3>&2 2>$HOME/startlog.$$ + setopt xtrace prompt_subst +fi +``` + +:::info PS4 Prompt Expansion + +Zsh Sourceforge docs: [Prompt Expansion][prompt-expansion] + +::: + +Place at the bottom of `.zshrc` + +```shell title="~/.zshrc" showLineNumbers +if [[ "$PROFILE_STARTUP" == true ]]; then + unsetopt xtrace + exec 2>&3 3>&-; zprof > ~/zshprofile$(date +'%s') +fi +``` + +The next time your `.zshrc` is sourced it will generate 2 files in the `$HOME` directory. + +### 方法2 + +Store multiple values to a variable: + +```shell title="~/.zshrc" showLineNumbers +# Set variable +typeset -Ag ZLOGS +# Message to store +zmsg() { ZLOGS+=( "\n[$1]: ${(M)$(( SECONDS * 1000 ))#*.?} ms" ); } + +# Start profiling +typeset -F4 SECONDS=0 + +# + +zmsg "Loaded functions" + +# + +zmsg "Loaded something else" + +# + +zmsg "Done" +``` + +Then use the `$ZLOGS` variable to retrieve: + +```shell title="print $ZLOGS" showLineNumbers +[Loaded functions]: 0.0 ms +[Loaded something else]: 0.0 ms +[Done]: 0.1 ms +``` + +[prompt-expansion]: https://zsh.sourceforge.net/Doc/Release/Prompt-Expansion.html diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/guides/_category_.json new file mode 100644 index 00000000..625928e1 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "💡 ガイド", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx new file mode 100644 index 00000000..e34a4946 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx @@ -0,0 +1,801 @@ +--- +id: standard +title: 🔀 標準の構文 +sidebar_position: 1 +toc_max_heading_level: 3 +image: /img/png/theme/z/320x320.png +description: 基本的な構文のドキュメントです。 +keywords: + - syntax + - standard + - how-to-use + - fundamental +--- + + + +import ImgShow from "@site/src/components/ImgShow"; +import APITable from "@site/src/components/APITable"; + +## Introduction + +Ziは、構造化された文・式に対して2つの構文タイプを提供します。 + +- 標準構文 +- The ["For"][for-syntax] syntax + +どちらの構文を使うかはユーザー次第ですが、両方の構文に慣れることを強くお勧めします。 In this example, we will use an empty repository [z-shell/0](https://github.com/z-shell/0) to practice the basics of the standard syntax. + +- ターミナルで以下のコマンドを実行します。 + +```shell +zi load z-shell/0 +``` + +Successfully installed the Zsh plugin which usually contains all the setup instructions as described in the [Zsh plugin standard](https://wiki.zshell.dev/community/zsh_plugin_standard). + +スニペットは、再利用可能なソースコード、マシンコード、またはテキストの一部を含む単一のファイルで、ファイルへのフルパスまたはURLが必要です。 + +> - ターミナルで以下のコマンドを実行します。 + +```shell +zi snippet https://raw.githubusercontent.com/z-shell/zi-src/main/lib/zsh/snippets/welcome.zsh +``` + +成功しました！ しかし、必ずしもとても簡単でシンプルであるとは限りません。時には、特定の時間や条件であることを指定したいこともあります。 This can be achieved using [ice-modifiers][ice-mods]. + +上の行には ice 修飾子が含まれており、下の行でプラグインを読み込んでいます。 + +> - ターミナルで以下のコマンドを実行します。 + +```shell showLineNumbers +zi ice id-as'zsh/plugin' atinit'print "Hello World!"' +zi load z-shell/0 +``` + +This registered the plugin under the [plugin ID](#id-as) `zsh/plugin` instead of `z-shell/0`. This will work as expected e.g. `zi update zsh/plugin`, `zi remove zsh/plugin`, etc. プラグインをロードする前に「Hello World!」が表示されます。 + +Ice-modifierを増やしてもう一度インストールしましょう。 + +> - ターミナルで以下のコマンドを実行します。 + +```shell showLineNumbers +zi ice id-as'final/countdown' \ + atinit'+zi-message "{bapo}Cloned!"' \ + atclone'+zi-message "{quos}Boom!"' \ + atload'+zi-message "{apo}Loaded!"' countdown +zi load z-shell/0 +``` + +## Order of execution {#order-of-execution} + +関連する ice-modifier の実行順序は次のとおりです。 + +```shell showLineNumbers + atinit'' → + atpull'!' → + make'!!' → + mv'' → + cp'' → + make'!' → + atclone'' / atpull'' → + make'!' → + [ plugin script loading ] → + src'' → + multisrc'' → + atload'' +``` + +### A few remarks {#a-few-remarks} + +- The syntax automatically detects if the object is a snippet or a plugin, by checking if the object is an URL, i.e.: if it starts with `http*://` or `OMZ::`, etc. +- To load a local-file snippet (which will be treated as a local-directory plugin by default) use the `is-snippet` ice, +- To load a plugin in `light` mode use the `light-mode` ice. +- If the plugin name collides with an ice name, precede the plugin name with `@`, e.g.: `@sharkdp/fd` (collides with the `sh` ice, ZI will take the plugin name as `sh"arkdp/fd"`), see the next section for an example. + +### Syntax alternatives {#syntax-alternatives} + +Zi supports alternatives such as the equal (`=`) syntax: + +```shell showLineNumbers +zi ice id-as=equal atload="print Hello World" +zi load z-shell/0 +``` + +The colon (`:`) syntax: + +```shell showLineNumbers +zi ice id-as:colon atload:"print Hello World" +zi load z-shell/0 +``` + +そして、上記の全てと併せて、GNU 構文も同様に利用できます。 + +```shell showLineNumbers +zi ice id-as=GNU --atload="print Hello World" +zi load z-shell/0 +``` + +代わりの構文はVimのようなエディタのハイライトを利用し、文字列とiceの表現を別の色にすることができます。 However, with [zi-vim-syntax][] the syntax definition can be superseded with the highlighting specifically for Zi. syntax definition can be superseded with the highlighting specifically for Zi. + +### Utilizing "make" {#utilizing-make} + +Vim repository on GitHub – a typical source code that needs compilation, Zi can manage the run of `./configure` and other `make` stuff. Ice-modifier `pick` adds the binary program to `$PATH`. You could also install the package under the path $ZPFX. + +```shell title="~/.zshrc" showLineNumbers +zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \ + atpull"%atclone" make pick"src/vim" +zi light vim/vim +``` + +The `make'…'` ice could also be: `make"install PREFIX=$ZPFX"`, if "install" wouldn't be the only, default target. + +:::info + +[$ZPFX][zpfx] is provided by Zi, it is set to `~/.zi/polaris` by default. However, it can be changed by specifying the `$ZPFX=` target. + +::: + +```shell title="~/.zshrc" showLineNumbers +zi ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX" +zi light tj/git-extras +``` + +The `Makefile` of the project above has only 2 tasks: + +1. Install the target. +2. Build scripts that are required for installation. + +The `Makefile` with 2 tasks, can use: + +1. `make"all install PREFIX=…"`, +2. `pick'…'` will `chmod +x` all matching files and add `$ZPFX/bin/` to `$PATH`. + +### Compiling programs {#compiling-programs} + +```shell showLineNumbers +zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \ + atpull"%atclone" make pick"src/vim" +zi light vim/vim +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ------------------ | :---------------------------------------------------------------------------------------- | +| `as'program'` | Add file selected by `pick'…'` to `$PATH`, and do not source it. | +| `atclone'…'` | ダウンロード後、任意のコマンドを実行する。 | +| `atpull'%atclone'` | Execute the same code `atclone'…'` is given, but after successful update. | +| `make` | Run `make` after `atclone'…'` and `atpull'…'` (note: `make'!'` will execute before them). | +| `pick'src/vim'` | Set the executable flag on `src/vim`, hint that `src/` should be added to `$PATH`. | + +```mdx-code-block + +``` + +The same but with **installation** (`make install`) under [$ZPFX][zpfx] by default: + +```shell showLineNumbers +zi ice as'program' atclone'rm -f src/auto/config.cache; \ + ./configure --prefix=$ZPFX' atpull'%atclone' make'all install' pick'$ZPFX/bin/vim' +zi light vim/vim +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ------------------ | :------------------------------------------------------------------------------------------- | +| `as'program'` | As above. | +| `atclone'…'` | As above **plus** pass `--prefix=$ZPFX` to `./configure`, to set the installation directory. | +| `atpull'%atclone'` | As above. | +| `make` | As above, but also run the `install` target. | +| `pick'src/vim'` | as above, but for a different path `$ZPFX/bin/vim`. | + +```mdx-code-block + +``` + +### LS_COLORS {#ls_colors} + +A repository [trapd00r/LS_COLORS][trapd00r-ls_colors] provides a file with color definitions for GNU `ls` command, and also for [ogham/exa][ogham-exa]. Typically one does `eval $( dircolors -b $HOME/LS_COLORS)` to process this file and set the environment for `ls`. This means `dircolors` is run by every shell startup. It costs much time to create a fork and program, i.e., the `dircolors` binary needs to be loaded to obtain and process the color definitions. The following invocation solves this problem: + +```shell showLineNumbers +zi ice atclone'dircolors -b LS_COLORS > clrs.zsh' \ + atpull'%atclone' pick"clrs.zsh" nocompile'!' \ + atload'zstyle ":completion:*" list-colors ${(s.:.)LS_COLORS}' +zi light trapd00r/LS_COLORS +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ------------------ | :------------------------------------------------------------------------------------------ | +| `atclone'…'` | Generate shell script, passing it to `eval`. More: [^1] | +| `atpull'%atclone'` | Do the same at any update of the plugin. More: [^2] | +| `pick"clrs.zsh"` | Source the previously generated file `clrs.zsh`. | +| `nocompile'!'` | Invokes compilation **after** the `atclone'…'` and the [exclamation][] mark causes this. | +| `atload'…'` | Additionally sets up the Zsh completion to use the colors provided by the trapd00r package. | + +```mdx-code-block + +``` + +This way, except for the plugin installation and update, `dircolors` isn't run, just normal sourcing is done. The everyday sourced file, i.e. `clrs.zsh`, is being compiled to speed up the loading. + +### Direnv {#direnv} + +The project [direnv/direnv][direnv-direnv] registers itself in the Z shell to modify the environment on directory change. This registration is most often done by `eval "$(direnv hook zsh)"` added to `.zshrc`. + +```shell showLineNumbers +zi ice as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' \ + atpull'%atclone' src"zhook.zsh" +zi light direnv/direnv +``` + +- `make'!'` – execute `make` before `atclone'…'` and before `atpull'…'` (see `make` above), +- `src'zhook.zsh'` – source file `zhook.zsh`. + +In general, `direnv` works by hooking up to Zsh. The code that does this is provided by the program `direnv` (built by `make'…'`). + +Above `atclone'…'` puts this code into file `zhook.zsh`, `src''` sources it. This way `direnv hook zsh` is executed only on clone and update, and Zsh starts faster. + +#### Glance at the 'for' syntax {#glance-at-the-for-syntax} + +The drawback of this standard procedure is that the `direnv` binary is run on every shell startup and significantly slows it down. Zi allows to solve this in the following way: + +```shell showLineNumbers +zi as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' \ + atpull'%atclone' pick"direnv" src"zhook.zsh" for \ + direnv/direnv +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ------------------ | :----------------------------------------------------------------------------------------------------------------------------- | +| `make'!'` | Compile `direnv`, the exclamation mark means: run the `make` first, before `atclone'…'` and `atpull'…'` hooks. | +| `atclone'…'` | As soon as the plugin is installed generate the registration code and save it to `zhook.zsh`, instead of passing it to `eval`. | +| `atpull'%atclone'` | The `atclone'…'` runs on **installation** while `atpull'…'` runs on **update** of the plugin. | +| `src'zhook.zsh'` | Load generated registration code | +| `pick'direnv'` | Ensure `+x` permission on the binary | +| `as'program'` | The plugin is a program, there's no main file to the source. | + +```mdx-code-block + +``` + +In this method, the registered code is generated once on every installation or update, then sourced without running `direnv` itself. The project is also available as a binary [GitHub releases][gh-releases]. This distribution can be installed by: + +```shell showLineNumbers +zi from"gh-r" as"program" mv"direnv* -> direnv" \ + atclone'./direnv hook zsh > zhook.zsh' atpull'%atclone' \ + pick"direnv" src="zhook.zsh" for \ + direnv/direnv +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ------------------------- | :------------------------------------------------------------------------- | +| `from'gh-r'` | Install from `direnv` from GitHub Github releases. | +| `mv'direnv* -> direnv'` | After installation, rename `direnv.linux-386` or similar file to `direnv`. | +| `atclone'…'`, `atpull'…'` | Same above example. | +| `pick'direnv'` | Same above example. | +| `as'program'` | Same above example. | + +```mdx-code-block + +``` + +## `extract'…'` {#extract} + +A swiss-knife tool for unpacking all kinds of archives – the `extract'…'` ice. It works in two modes – automatic mode and fixed mode. + +Automatic mode: + +It is active if the ice is empty (or contains only flags). It works as follows: + +1. At first, a recursive search for files of known [file extensions](#supported-file-formats) located not deeper than in a sub-directory is being performed. All such found files are then extracted. + - The directory-level limit is to skip extraction of some helper archive files, which are typically located somewhere deeper in the directory tree. +2. **If** no such files will be found, then a recursive search for files of known archive **types** will be performed. This is done by running the `file` Unix command on each file in the plugin or snippet directory and then grepping the output for strings like `Zip`, `bzip2`, etc. All such discovered files are then extracted. + - The directory-level requirement is imposed during this stage. The files located deeper than in a sub-directory are omitted. +3. If no archive files will be discovered then no action is being performed and also no warning message is being printed. + +Fixed mode: + +It is active when a filename is being passed as the `extract`'s argument, e.g.: `zi extract=archive.zip for z-shell/null`. Multiple files can be specified – separated by spaces. In this mode all and only the specified files are being extracted. + +Filenames with spaces: + +The filenames with spaces are supported when correctly passing such filenames to an `extract` with the non-breaking spaces for the original in-filename. + +The non-breaking space is easy to type by pressing right ALT and the SPACE. + +Flags: + +The value of the ice can begin with two special characters: + +1. Exclamation mark (`!`), i.e.: `extract='!…'` – it'll cause the files to be moved one directory level up upon unpacking, +2. Two exclamation marks (`!!`), i.e.: `extract='!!…'` – it'll cause the files to be moved two directory-level up upon unpacking, +3. Dash (`-`), i.e.: `extract'-…'` – it'll prevent removal of the archive after unpacking. + - This flag allows comparing timestamps with the server in case of snippet-downloaded file – it will prevent unnecessary downloads during `zi update`, as the timestamp of the archive file on the disk will be first compared with the HTTP last-modification time header. + +The flags can be combined in any order: `extract'!-'`. + +## `ziextract` {#ziextract} + +Sometimes a more uncommon unpacking operation is needed. In such a case you can directly use the function that implements the ice – it is called `ziextract`. + +It recognizes the following options: + +1. `--auto` – runs the automatic extraction. +2. `--move` – performs the one-directory-level-up move of the files after unpacking. +3. `--move2` – performs the two-directory-level-up move of the files after unpacking. +4. `--norm` - prevents the archive file removal. +5. And also one option specific only to the function: `--nobkp`, which prevents clearing the plugin's directory before the extraction. – All files besides the archive are being moved into the `._backup` directory after extraction is done. - `extract` ice also skips creating the backup **if** more than one archive is found or given as the argument. + +### Supported file formats {#supported-file-formats} + +Zip, rar, tar.gz, tar.bz2, tar.xz, tar.7z, tar, tgz, tbz2, gz, bz2, txz, xz, 7z, exe, deb, OS X (dmg). + +## `from'…'` {#from} + +To install and load a plugin whose repository is private - e.g: requires providing credentials to log in – use the `from'…'` ice in the following way: + +```shell showLineNumbers +zi ice from"user@github.com" +zi load user/fsh-auto-themes +``` + +現在のプリセット： + +```mdx-code-block + +``` + +| Ice name | Domain name / URL | +| ---------- | :----------------------------------- | +| ge | gitee.com | +| gitee | gitee.com | +| github | github.com | +| gh | github.com | +| gitlab | gitlab.com | +| gl | gitlab.com | +| notabug | notabug.org | +| nb | notabug.org | +| bitbucket | bitbucket.org | +| bb | bitbucket.org | +| github-rel | github.com/$remote_url_path/releases | +| gh-r | github.com/$remote_url_path/releases | +| cygwin | cygwin | + +```mdx-code-block + +``` + +:::note + +If the `from'…'` ice isn't one of the above tables, then **it is treated as a domain name** and inserted into the domain position into the `git clone` URL: + +```shell +git clone https://{from-ice-contents}/user/plugin +``` + +In order to change the protocol, use the `proto'…'` ice. + +::: + +## `id-as'…'` {#id-as} + +Load a plugin or snippet with a nickname with the `id-as'…'` ice-modifier. For example, one could try to load [docker/compose][docker-compose] from GitHub binary releases: + +```shell showLineNumbers +zi ice as"program" from"gh-r" mv"docker-c* -> docker-compose" +zi light "docker/compose" +``` + +This registers the plugin under the ID `docker/compose`. Now suppose the user would want to also load a completion from the project's GitHub repository (not the binary release catalog) which is also available under the GitHub URL **…/docker/compose**. The two IDs, both being "docker/compose", will collide. + +The solution to this problem – the `id-as'…'` (to be read as _identify-as_) ice to which this document is devoted: by using the `id-as'…'` ice the user can resolve the conflict by loading the completion under a kind of a _nickname_, for example under "_dc-complete_", by issuing the following commands: + +```shell showLineNumbers +zi ice as"completion" id-as"dc-complete" +zi load docker/compose +``` + +The plugin (of the type `completion`) is now seen under ID `dc-complete`: + +```shell showLineNumbers +zi list | grep -i dc-complete +dc-complete +``` + +Issuing `zi report dc-complete` will work as with regular command: + +```shell showLineNumbers +zi report dc-complete + +Plugin report for dc-complete +------------------------------- + +Completions: +_docker-compose [enabled] +``` + +The same method applies to nickname snippets. For instance, use it to create handy IDs in place of long URLs: + +```shell showLineNumbers +zi ice as"program" id-as"git-unique" +zi snippet https://github.com/Osse/git-scripts/blob/master/git-unique +``` + +The commands `zi update git-unique`, and `zi delete git-unique` will work as expected and e.g. `zi times` will show the _nickname_-ID `git-unique` instead of the long URL. + +- `id-as'auto'`: + +There's a special value to the `id-as'…'` ice – `auto`. It causes the nickname to be automatically set to the last component of the plugin name or snippet URL. 例: + +```shell showLineNumbers +zi ice as"program" id-as"auto" +zi snippet https://github.com/Osse/git-scripts/blob/master/git-unique +``` + +will work the same as before, e.g: if the ice used was `id-as'git-unique'`. Will work as if id-as'zsh-autopair' was passed: + +```shell showLineNumbers +zi ice wait lucid id-as"auto" +zi load hlissner/zsh-autopair +``` + +- empty `id-as'…'`: + +An empty `id-as'…'` will work the same as `id-as'auto'` as if id-as'zsh-autopair' was passed, e.g: + +```shell showLineNumbers +zi ice wait lucid id-as +zi load hlissner/zsh-autopair +``` + +## `wait'…'` {#wait} + +:::note + +Turbo mode, i.e. the `wait'…'` is ice that implements it - needs Zsh >= 5.3. + +::: + +```shell showLineNumbers +zi ice wait'0' # もしくは単に zi ice wait +zi light wfxr/forgit +``` + +- waits for prompt, +- instantly ("0" seconds) after prompt loads given plugin. + +```shell showLineNumbers +zi ice wait'[[ -n ${ZLAST_COMMANDS[(r)cras*]} ]]' +zi light z-shell/zi-crasis +``` + +- screencast that presents the feature: + + + +- `$ZLAST_COMMANDS` is an array built by [F-Sy-H][z-shell-f-sy-h], it contains commands currently entered at prompt, +- `(r)` searches for an element that matches a given pattern (`cras*`) and returns it, +- `-n` means: not-empty, so it will be true when users enter "cras", +- after 1 second or less, Zi will detect that the `wait'…'` condition is true, and load the plugin, which provides command _crasis_, + +```shell showLineNumbers +zi ice wait'[[ $PWD = */github || $PWD = */github/* ]]' +zi load unixorn/git-extra-commands +``` + +it waits until the user enters a `github` directory. Turbo mode also supports a suffix – the letter a, `b`, or `c`. The meaning is illustrated by the following example: + +```shell showLineNumbers +zi ice wait"0b" as"command" pick"wd.sh" atinit"echo Firing 1" lucid +zi light mfaerevaag/wd +zi ice wait"0a" as"command" pick"wd.sh" atinit"echo Firing 2" lucid +zi light mfaerevaag/wd +``` + +will output: + +```shell showLineNumbers +Firing 2 +Firing 1 +``` + +As can be seen, the second plugin has been loaded first. That's because there are now three sub-slots (the `a`, `b`, and `c`) into which the plugin/snippet loadings can be put. Plugins from the same time slot with suffix `a` will be loaded before plugins with suffix `b`, etc. + +In other words, instead of `wait'1'`, you can enter `wait'1a'`, `wait'1b'`, and `wait'1c'` – this **imposes the loading order** of the **commands** regardless of actual execution time. + +## `src'…'` `pick'…'` `multisrc'…'` {#src-pick-multisrc} + +Normally `src'…'` can be used to specify the additional file to the source: + +```shell showLineNumbers +zi ice pick'powerless.zsh' src'utilities.zsh' +zi light martinrotter/powerless +``` + +| 構文 | 説明 | +| :-------: | :--------------------------------------------------------------------------------------------------------- | +| `pick'…'` | Provide the main file to the source - like `*.sh`, otherwise alphabetically first matched file is sourced. | +| `src'…'` | Provide a second file to the source - not a pattern - plain file name. | + +### The `svn` ice {#the-svn-ice} + +However, via `atload'…'` ice one can provide a simple loop to source more files: + +```shell showLineNumbers +zi ice svn pick'completion.zsh' \ + atload'local f; for f in git.zsh misc.zsh; do source $f done' +zi snippet OMZ::lib +``` + +| 構文 | 説明 | +| :---------: | :--------------------------------------------------------------------------------------------------------------------------------- | +| `svn` | Use Subversion to clone `OMZ::lib` (the whole Oh-My-Zsh `lib/` directory). More [^3]. | +| `atload'…'` | Code isn't tracked and cannot be unloaded. The `atload'…'` is executed after loading main files `pick'…'` and `src'…'`. More [^4]. | + +### The `multisrc'…'` ice {#the-multisrc-ice} + +Loads **multiple** files enumerated with spaces as the separator (e.g. `multisrc'misc.zsh grep.zsh'`) and also using brace-expansion syntax (e.g. `multisrc'{misc,grep}.zsh')`. Example: + +```shell showLineNumbers +zi ice svn pick'completion.zsh' \ + multisrc'git.zsh functions.zsh {history,grep}.zsh' +zi snippet OMZ::lib +``` + +All possible ways to use the `multisrc'…'` ice-modifier: + +```shell +zi ice depth'1' multisrc='lib/{functions,misc}.zsh' pick'/dev/null' +zi load robbyrussell/oh-my-zsh +``` + +Can use patterns: + +```shell showLineNumbers +zi ice svn multisrc'{funct*,misc}.zsh' pick'/dev/null' +zi snippet OMZ::lib +``` + +```shell showLineNumbers +zi ice svn multisrc'misc.zsh functions.zsh' pick'/dev/null' +zi snippet OMZ::lib +``` + +Will use the array's value at the moment of plugin load: + +> This can matter when using turbo mode. + +```shell showLineNumbers +array=({functions,misc}.zsh) +zi ice svn multisrc"\$array" pick'/dev/null' +zi snippet OMZ::lib +``` + +Compatible with KSH_ARRAYS option: + +```shell showLineNumbers +array=({functions,misc}.zsh) +zi ice svn multisrc"${array[*]}" pick'/dev/null' +zi snippet OMZ::lib +``` + +Hack with Zi: the ice's contents are simply `eval`-uated like follows: eval "reply=($multisrc)". + +So it might get handy on an occasion to pass code there, but first, you must close the paren and then don't forget to assign `reply`, and to provide a trailing opening paren. In the code be careful to not redefine any variable used internally by Zi – e.g.: `i` is safe: + +```shell showLineNumbers +array=({functions,misc}.zsh) +zi ice svn multisrc'); local i; for i in $array; do reply+=( ${i/.zsh/.sh} ); done; ((1)' pick'/dev/null' +zi snippet OMZ::lib +``` + +Extended with the [for][for-syntax] syntax which can in some situations replace a typical `multisrc'…'` loading. The idea of this syntax is to source multiple snippets with a single command. + +Instead of: + +```shell showLineNumbers +zi ice multisrc'(functions|misc|completion).zsh' +zi snippet OMZ::lib +``` + +書き込みが可能： + +```shell showLineNumbers +zi for \ + OMZL::functions.zsh \ + OMZL::misc.zsh \ + OMZL::completion.zsh +``` + +which is somewhat easier on the eyes. + +:::info Important Property + +The multiple snippets loaded with the `for` syntax are being loaded _separately_, which means that they will not cause a longer keyboard blockage, which could have been noticeable – when loading in turbo mode. + +::: + +The Zi scheduler will distribute the work over time and will allow activation of the keyboard in between the snippets. The `multisrc'…'` way doesn't work this way – sourcing many files may cause a noticeable keyboard freeze (in turbo mode). + +## `atclone'…'` `atpull'…'` `atinit'…'` `atload'…'` {#atclone-atpull-atinit-atload} + +There are four code-receiving ice-modifiers: `atclone'…'`, `atpull'…'`, `atinit'…'`, `atload'…'`. + +Their role is to **receive a portion of Zsh code and execute it in specific moments of the plugin life-cycle**. + +| 構文 | Execution moment | +| :----------: | :-------------------------------------------------------------- | +| `atclone'…'` | **after cloning** the associated plugin or snippet to the disk. | +| `atpull'…'` | **after updating** the associated plugin or snippet. | +| `atinit'…'` | **before loading** of the associated plugin or snippet. | +| `atload'…'` | **after loading** of the associated plugin or snippet. | + +For convenience, you can use each of the ices multiple times in a single `zi ice …` invocation – all commands will run in the given order. + +The `atpull'…'` ice recognizes a special value: `%atclone`, so the code looks: `atpull'%atclone'`. It causes the contents of the `atclone'…'` ice to be copied into the contents of the `atpull'…'` ice. + +This is handy when the same tasks have to be performed on clone **and** on the update of plugin or snippet, like e.g.: in the [direnv example](#direnv). + +### `atload'!…'` with exclamation mark preceded + +The [wrap'…'](#wrap) The ice-modifier allows the track and unload of plugins that defer their initialization to a function and run later after sourcing the plugin's script – When the function call, the plugin is then fully initialized. + +However, if the function is being called from the `atload'…'` ice, then the _exclamation mark_-preceded method can be used with `atload'…'` contents. The exclamation mark causes the effects of the execution of the code passed to `atload'…'` ice to be recorded. + +### Use case for `atload'…'` + +For example, in the following invocation: + +```shell showLineNumbers +zi ice id-as'test' atload'!PATH+=:~/share' +zi load z-shell/null +``` + +the `$PATH` is being changed within `atload'…'` ice. Zi's tracking registers `$PATH` changes and withdraws them on the plugin unload and shows loading information: + +```shell title="zi report test" showLineNumbers +Report for test plugin +---------------------- +Source (reporting enabled) + +PATH elements added: +/home/sg/share +``` + +As it can be seen, the `atload'…'` code is being correctly tracked and can be unloaded & viewed. Below is the result of using the `unload'…'` subcommand to unload the `test` plugin: + +```shell title="zi unload test" showLineNumbers +--- Unloading plugin: test --- +Removing PATH element /home/user/share +Unregistering plugin test +Plugin report saved to $LASTREPORT +``` + +The same example as in the [wrap'…'](#use-case-for-wrap) article, but using the _exclamation mark_-preceded `atload'…'` instead of `wrap'…'`: + +Load when - `MYPROMPT == 4` + +```shell showLineNumbers +zi ice load'![[ $MYPROMPT = 4 ]]' unload'![[ $MYPROMPT != 4 ]]' \ + atload'!source ~/.p10k.zsh; _p9k_precmd' +zi load romkatv/powerlevel10k +``` + +## `wrap'…'` {#wrap} + +The `wrap' …'` ice-modifier allows extending the tracking (e.g.: the gathering of the report and unloading data) of a plugin beyond the moment of sourcing its main file(s). It works by wrapping the given functions with a tracking-enabling and disabling snippet of code. This is useful especially with prompts, as they very often do their initialization in the first call to their `precmd` [hook][hook-functions] function. + +For example, [romkatv/powerlevel10k][romkatv-powerlevel10k] works this way. The ice takes a list of function names, with the elements separated by `;`: + +```shell +zi ice wrap"func1;func2;…" +``` + +### Use case for `wrap'…'` {#use-case-for-wrap} + +Therefore, to load and unload for the example powerlevel10k prompt in the fashion of [multiple prompts][multiple-prompts] article, the `precmd` function of the plugin – called `_p9k_precmd`, to get the name of the function do `echo $precmd_functions` after loading a theme, should be passed to `wrap'…'` ice. + +Load when `MYPROMPT == 4` + +```shell showLineNumbers +zi ice load'![[ $MYPROMPT = 4 ]]' unload'![[ $MYPROMPT != 4 ]]' \ + atload'source ~/.p10k.zsh; _p9k_precmd' wrap'_p9k_precmd' +zi load romkatv/powerlevel10k +``` + +This way the actions done during the first call to `_p9k_precmd()` will be normally recorded, which can be viewed in the report of the [romkatv/powerlevel10k][romkatv-powerlevel10k] theme: + +```shell title="zi report romkatv/powerlevel10k" showLineNumbers +Report for romkatv/powerlevel10k plugin +--------------------------------------- +Source powerlevel10k.zsh-theme (reporting enabled) +Autoload is-at-least with options -U -z + +(…) + +Note: === Starting to track function: _p9k_precmd === +Zle -N p9k-orig-zle-line-finish _zsh_highlight_widget_zle-line-finish +Note: a new widget created via zle -N: p9k-orig-zle-line-finish +Zle -N -- zle-line-finish _p9k_wrapper__p9k_zle_line_finish +Autoload vcs_info with options -U -z +Zstyle :vcs_info:* check-for-changes true + +(…) + +Zstyle :vcs_info:* get-revision false +Autoload add-zsh-hook with options -U -z +Zle -F 22_gitstatus_process_response_POWERLEVEL9K +Autoload_gitstatus_cleanup_15877_0_16212/docs/guides/syntax/wrap +Zle -N -- zle-line-pre-redraw _p9k_wrapper__p9k_zle_line_pre_redraw +Note: a new widget created via zle -N: zle-line-pre-redraw +Zle -N -- zle-keymap-select _p9k_wrapper__p9k_zle_keymap_select +Note: === Ended tracking function:_p9k_precmd === + +Functions created: ++vi-git-aheadbehind +vi-git-remotebranch + +(…) +``` + +Summary of `wrap'…'`: + +As it can be seen, the creation of four additional Zle-widgets has been recorded - `Zle -N …` lines. They will be properly deleted/restored on the plugin unload with `MYPROMPT=3` as an example and the shell state will be clean, ready to load a new prompt. + + + + + +[^1]: Save it to a file. The `atclone'…'` is being run on the **installation** while the `atpull'…'` hook is being run on an **update** of the [**trapd00r/LS_COLORS**][trapd00r-ls_colors] plugin. +[^2]: The `%atclone` is just a special string that denotes the `atclone'…'` hook and is copied onto the `atpull'…'` hook. +[^3]: Note that `atload'…'` uses apostrophes, not double quotes, to put `$f` into the string, `atload'…'`'s code is automatically being run **within the snippet's or plugin's directory**. +[^4]: Unless you load a plugin (not a snippet) with `zi load …` and prepend the value of the ice with an exclamation mark. Example: `atload'!local f; for …'`. + + + +[for-syntax]: /docs/guides/syntax/for + +[ice-mods]: /docs/guides/syntax/ice-modifiers + +[exclamation]: /search?q=exclamation+mark + +[zpfx]: /docs/guides/customization#$ZPFX + +[multiple-prompts]: /docs/guides/customization#multiple-prompts + + + +[trapd00r-ls_colors]: https://github.com/trapd00r/LS_COLORS + +[ogham-exa]: https://github.com/ogham/exa + +[direnv-direnv]: https://github.com/direnv/direnv + +[gh-releases]: https://github.com/direnv/direnv/releases/ + +[zi-vim-syntax]: https://github.com/z-shell/zi-vim-syntax + +[docker-compose]: https://github.com/docker/compose + +[z-shell-f-sy-h]: https://github.com/z-shell/F-Sy-H + +[hook-functions]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Hook-Functions + +[romkatv-powerlevel10k]: https://github.com/romkatv/powerlevel10k diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx new file mode 100644 index 00000000..a197d075 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx @@ -0,0 +1,266 @@ +--- +id: for +title: ✨ "For" 構文 +sidebar_position: 2 +image: /img/png/theme/z/320x320.png +description: '"For" 構文のドキュメント' +keywords: + - for + - syntax + - how-to-use + - the-for-syntax +--- + + + +import APITable from "@site/src/components/APITable"; + +The `for` syntax is the most popular, more concise, and more optimized. The single command will work the same as the [standard syntax][standard-syntax] invocation. + +It allows providing common/default ice-modifiers for a set of plugins or to source multiple files with the ices: [src, pick, multisrc][src-pick-multisrc]. + +:::tip + +To find more information about anything use [search][3] or just CTRL+K. + +::: + +```shell showLineNumbers +zi light-mode for \ + zsh-users/zsh-autosuggestions \ + z-shell/F-Sy-H \ + z-shell/H-S-MW \ + pick"async.zsh" src"pure.zsh" \ + sindresorhus/pure +``` + +実例を挙げて紹介するのが一番です。 + +```shell showLineNumbers +zi wait"3" lucid for as"null" \ + sbin Fakerr/git-recall \ + sbin paulirish/git-open \ + sbin paulirish/git-recent \ + sbin davidosomething/git-my \ + make"PREFIX=$ZPFX install" iwata/git-now \ + make"PREFIX=$ZPFX" tj/git-extras +``` + +The above single command installs 6 plugins ([git extension][2] packages), with the base ices `as"null" wait"3" lucid` that are common to all of the plugins and 6 plugin-specific add-on ice-modifiers. + +Load a few useful binary packages from the [GitHub releases][1], utils: + +```shell showLineNumbers +zi for as"null" wait"2" lucid from"gh-r" \ + mv"exa* -> exa" sbin ogham/exa \ + mv"fd* -> fd" sbin"fd/fd" @sharkdp/fd \ + sbin"fzf" junegunn/fzf +``` + +:::note + +- `sbin'…'` is an [ice][3] added by the [bin-gem-node][4] [annex][5], it provides the command to the command line without altering `$PATH`. +- If the name of the command is the same as the name of the plugin, the ice contents can be skipped. + +::: + +[Turbo][6] load some plugins, without any plugin-specific ices: + +```shell showLineNumbers +zi wait lucid for \ + hlissner/zsh-autopair \ + urbainvaes/fzf-marks +``` + +Load two [Oh-My-Zsh][7] files as [snippets][8], in turbo mode: + +```shell showLineNumbers +zi wait lucid for \ + OMZ::lib/git.zsh \ + atload"unalias grv" \ + OMZ::plugins/git/git.plugin.zsh +``` + +Popular plugin set with [turbo][6] and The "For": + +```shell {1} showLineNumbers +zi wait lucid light-mode for \ + atinit"zicompinit; zicdreplay" \ + z-shell/F-Sy-H \ + atload"_zsh_autosuggest_start" \ + zsh-users/zsh-autosuggestions \ + blockf atpull'zi creinstall -q .' \ + zsh-users/zsh-completions +``` + +```mdx-code-block + +``` + +| 構文 | 説明 | +| ------------ | :------------------------------------------------------------------------------------------- | +| `wait` | Load 0 seconds (about 5 ms exactly) after prompt ([turbo mode][6]). | +| `lucid` | Silence the under-prompt messages ("`Loaded {name of the plugin}`"). | +| `light-mode` | Load the plugin in `light` mode. [^1]. | +| `atpull'…'` | Execute after updating the plugin – the command in the ice will install any new completions. | +| `atinit'…'` | Execute code before loading plugin. | +| `atload'…'` | Execute code after loading the plugin. | +| `zicompinit` | Equals to `autoload compinit; compinit`. | +| `zicdreplay` | Execute `compdef …` calls by plugins. More below [^2]. | + +```mdx-code-block + +``` + +## Oh-My-Zsh, [turbo][6] Oh-My-Zsh and the The "For" syntax + +### Without [turbo mode][6] and The "For" + +```shell showLineNumbers +# A. +setopt prompt_subst + +# B. +zi snippet OMZL::git.zsh + +# C. +zi ice atload"unalias grv" +zi snippet OMZP::git + +# D. +zi for OMZL::prompt_info_functions.zsh OMZT::gnzh + +# E. +zi snippet OMZP::colored-man-pages + +# F. +zi ice as"completion" +zi snippet OMZP::docker/_docker + +# G. +zi ice atinit"zicompinit; zicdreplay" +zi light z-shell/F-Sy-H +``` + +### With [turbo mode][6] and The "For" + +```shell showLineNumbers +# A. +setopt prompt_subst + +# B, C. +zi wait lucid for \ + OMZL::git.zsh \ + atload"unalias grv" \ + OMZP::git + +# Provide a simple prompt till the theme loads to visualize the effect. +PS1="READY >" + +# D. +zi wait'!' lucid for \ + OMZL::prompt_info_functions.zsh \ + OMZT::gnzh + +# E, F, G. +zi wait lucid for \ + atinit"zicompinit; zicdreplay" \ + z-shell/fast-syntax-highlighting \ + OMZP::colored-man-pages \ + as"completion" \ + OMZP::docker/_docker +``` + +:::info + +**A** - Most themes use this option. + +**B, C** - OMZ themes use this library and some others use also the plugin. It provides many aliases – `atload'…'` showing how to disable some of them (e.g.: to use the program `rgburke/grv`). + +**D** - Set OMZ theme. Loaded separately because the theme needs the `!` passed to the `wait` ice to reset the prompt after loading the snippet in turbo mode. + +**E, F, G** - Some plugins: + +1. syntax-highlighting, loaded possibly early for a better user experience). +2. example functional plugin. +3. docker completion. + +::: + +The above setup loads everything after the prompt, because of the preceding `wait` ice. That is called **turbo mode**, which shortens Zsh startup time by 50%-80%, e.g. instead of 200 ms, it'll be getting your shell started up after **40 ms**. + +Try both setups on the daily basis to notice the difference. The features of Zi can do much more than this simple example. + +### `zi-turbo '…' for …` {#zi-turbo--for-} + +The `zi-turbo` is a function to simplify `wait`: + +```shell showLineNumbers +zi-turbo() { + zi depth'3' lucid ${1/#[0-9][a-c]/wait"${1}"} "${@:2}" +} +``` + +Then use the `for` syntax in the imposed loading order: + +```shell {1,6,10,15} showLineNumbers +zi-turbo '0a' for \ + OMZL::git.zsh \ + OMZL::compfix.zsh \ + OMZL::functions.zsh \ + +zi-turbo '0b' for \ + OMZL::prompt_info_functions.zsh OMZL::spectrum.zsh \ + OMZL::clipboard.zsh OMZL::termsupport.zsh OMZL::directories.zsh + +zi-turbo '0c' for \ + OMZP::sudo OMZP::encode64 \ + atload"unalias grv g" OMZP::git \ + OMZP::gcloud OMZP::nvm OMZP::gem OMZP::rust + +zi-turbo '1a' for \ + MichaelAquilina/zsh-you-should-use +``` + +## Summary + +In general, [turbo mode][6] can be optionally enabled only for a subset of plugins or for all plugins. + +Syntax-highlighting plugins, like [F-Sy-H][11] or [zsh-syntax-highlighting][12], theoretically expect to be loaded last, even after the completion initialization as `compinit` function. + +However, in practice, you just have to ensure that such plugin is loaded after plugins that are issuing `compdef` – which means completions that aren't using the underscore-starting function file; the completion initialization still has to be performed before the syntax-highlighting plugin, hence the `atinit'…'` ice, which will load `compinit` right before loading the plugin, the syntax-highlighting and suggestions plugins are loaded early for a better user experience. + + + + + +[^1]: Then the tracking of plugin, activity report gathering, accessible via the `zi report {plugin-name}` subcommand) is being disabled. Note that for turbo mode, the performance gains are almost `0`, so in this mode, you can load all plugins with the tracking and the `light-mode` ice can be removed from the command. +[^2]: They were recorded and `compinit` can be called later. `compinit` provides the `compdef` function, so it must be run before issuing the taken-over `compdef`s with `zicdreplay`. + + + +[1]: /search/?q=GH-R + +[2]: /search/?q=git+ext + +[3]: /search/?q=ice + +[4]: /search/?q=bin+gem+node + +[5]: /search/?q=annex + +[6]: /search/?q=turbo+mode + +[7]: /search/?q=oh+my+zsh + +[8]: /search/?q=snippets + +[standard-syntax]: /docs/guides/syntax/standard + +[src-pick-multisrc]: /docs/guides/syntax/standard#src-pick-multisrc + + + +[11]: https://github.com/z-shell/F-Sy-H + +[12]: https://github.com/zsh-users/zsh-syntax-highlighting diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx new file mode 100644 index 00000000..7932aeee --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx @@ -0,0 +1,227 @@ +--- +id: ice-modifiers +title: 🧊 Ice 修飾子 +sidebar_position: 4 +image: /img/png/theme/z/320x320.png +description: Ice 修飾子 ドキュメント +slug: ice-modifiers +--- + +import Image from "@theme/IdealImage"; +import ZIceImg from "/img/png/theme/ice_180x170.png"; +import APITable from "@site/src/components/APITable"; + +:::info FAQ: What is ice? + +What is ice + +The ice is something that melts in a drink, though in Zi syntax, it means adding an ice-modifier that's temporary because it disappears – which means that the ice-modifier will last only for the next Zi command. + +::: + +An ice-modifiers are [passed][alternate-syntax] to `zi ice …` to obtain described effects, additionally can be added with [annexes][12]. To see all available ice-modifiers run `zi icemods`. + +いくつかのice 修飾子はハイライト表示されており、クリックすると該当するWikiページに移動し、詳しい説明が表示されます。 特に明記されていない限り、与えられたiceはプラグインとスニペットの両方で機能すると考えていただいて結構です。 + +## Ice effects {#ice-effects} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :-------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `as` | Can be `as"program"` (alias: `as"command"`), and will cause to add script/program to `$PATH` instead of sourcing (see `pick`). Can also be `as"completion"` – use with plugins or snippets in whose only underscore-starting `_*` files you are interested in. [^8] | +| [id-as][6] | Nickname a plugin or snippet, e.g. create a short handler for the long-URL snippet. | +| `teleid` | Effective remote-ID (i.e.: URL, GitHub username/repo, package name, etc.). | +| `compile` | Pattern (possible `{…}` expansion, like `{a/*,b*}`) to select additional files to compile, e.g. `compile"(pure \| async).zsh"`for`sindresorhus/pure`. | +| `nocompile` | Don't try to compile `pick`-pointed files. If passed the exclamation mark (i.e. `nocompile'!'`), then do compile, but after `make'…'` and `atclone'…'` (useful if Makefile installs some scripts, to point `pick'…'` at the location of their installation). | +| `service` | Make the following plugin or snippet a _service_, which will run in the background, and only in a single Zshell instance. See [#zservice][7] topic. | +| `reset-prompt` | Reset the prompt after loading the plugin/snippet (by issuing `zle .reset-prompt`). Note: normally it's sufficient to precede the value of `wait'…'` ice with `!`. | +| [bindmap][8] | To hold `;`-separated strings like `Key(s)A -> Key(s)B`, e.g. `^R -> ^T; ^A -> ^B`. In general, `bindmap'…'` changes bindings (done with the `bindkey` builtin) the plugin does. The example would cause the plugin to map Ctrl-T instead of Ctrl-R, and Ctrl-B instead of Ctrl-A. **Does not work with snippets.** | +| [trackbinds][8] | Shadow but only `bindkey` calls even with `zi light …`, i.e. even with investigating disabled (fast loading), to allow `bindmap` to remap the key-binds. The same effect has the `zi light -b …`, i.e. additional `-b` option to the `light`-subcommand. **Does not work with snippets.** | +| [wrap][9] | Takes a `;`-separated list of function names to be investigated (meaning gathering report and unloading data) **once** during execution. It works by wrapping the functions with an investigating-enabling and disabling snippet of code. [^9] | +| `aliases` | Load the plugin with the aliases mechanism enabled. Use plugins that define **and use** aliases in their scripts. | +| `light-mode` | Load the plugin without investigating, i.e., the same as the `light` command. Useful with the "for" syntax, where there is no `load` nor `light` subcommand | +| [extract][10] | Performs archive extraction supporting multiple formats like `zip`, `tar.gz`, etc., and OS X `dmg` images. [^10] | +| `subst` | Substitute the given string into another string when sourcing the plugin script, e.g.: `zi subst'autoload → autoload -Uz' …`. | +| `autoload` | Autoload the given functions (from their files). Equivalent to calling `atinit'autoload the-function'`. Supports renaming of the function – pass `'… → new-name'` or `'… -> new-name'`, e.g.: `zi autoload'fun → my-fun; fun2 → my-fun2'`. | + +```mdx-code-block + +``` + +## Cloning options {#cloning-options} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :-------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `proto` | Change protocol to `git`,`ftp`,`ftps`,`ssh`, `rsync`, etc. The default is `https`. **Does not work with snippets.** | +| [from](standard#from) | Clone plugin from a given site. Supported are `from"github"` (default), `…"github-rel"`, `…"gitlab"`, `…"bitbucket"`, `…"notabug"` (short names: `gh`, `gh-r`, `gl`, `bb`, `nb`). Can also be a full domain name e.g: for GitHub enterprise. **Does not work with snippets.** | +| `ver` | Used with `from"gh-r"` (i.e. downloading a binary release, e.g. for use with `as"program"`) – selects which version to download. Default is latest, can also be explicit `ver"latest"`. Works also with regular plugins, and checkouts e.g. `ver"branch"`, i.e. a specific version. **Does not work with snippets.** | +| `bpick` | Used to select which release from GitHub Releases to download, e.g. `zi ice from"gh-r" as"program" bpick"*Darwin*"; zi load docker/compose`. **Does not work with snippets.** | +| `depth` | Pass `--depth` to `git`. I.e., limit how much history to download. **Does not work with snippets.** | +| `cloneopts` | Pass the contents of `cloneopts` to `git clone`. Defaults to `--recursive`. I.e., change cloning options. Pass empty ice to disable recursive cloning. **Does not work with snippets.** | +| `pullopts` | Pass the contents of `pullopts` to `git pull` used when updating plugins. **Does not work with snippets.** | +| `svn` | Use Subversion for downloading snippets. GitHub supports the `SVN` protocol, which allows cloning of subdirectories as snippets, e.g. `zi ice svn; zi snippet OMZP::git`. Other ice `pick` can be used to select a file to the source (default are: `*.plugin.zsh`, `init.zsh`, `*.zsh-theme`). **Does not work with plugins.** | + +```mdx-code-block + +``` + +## Selection of files (source '…') {#selection-of-files-source} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| [pick][1] | Select the file to source, or the file to set as a command, when using `snippet --command` or the ice `as"program"`. More below [^1]. | +| [src][1] | Specify an additional file to source after the main file or after setting up command via `as"program"`. It is not a pattern but a plain filename. | +| [multisrc][1] | Allows specifying multiple files for sourcing, enumerated with spaces as the separators. More below [^2]. | + +```mdx-code-block + +``` + +## Conditional loading {#conditional-loading} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :------------: | ------------------------------------------------------------------------------------------------------------------------ | +| [wait][2] | Postpone loading a plugin or snippet. For `wait'1'`, loading is done `1` second after the prompt. [^3]. | +| [load][3] | A condition to check which should cause the plugin to load. [^4]. | +| [unload][3] | A condition to check to cause the plugin to unload. More below [^5]. | +| `cloneonly` | Don't load the plugin/snippet, only download it. | +| `if` | Load plugin/snippet only when a given condition is true. Example: [^6]. | +| `has` | Load plugin or snippet only when given command is available (in $PATH), e.g. `zi ice has'git' …`. | +| `subscribe` | Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. `subscribe'{~/files-*,/tmp/files-*}'`. | +| `trigger-load` | Creates a function that loads the associated plugin/snippet, with an option. More below [^7]. | + +```mdx-code-block + +``` + +## Plugin output {#plugin-output} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :--------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `silent` | Mute plugin's or snippet's `stderr` & `stdout`. Also, skip the `loaded …` message under the prompt for `wait`, etc. loaded plugins, and completion-installation messages. | +| `lucid` | Skip `loaded …` message under prompt for `wait`, etc. loaded plugins (a subset of `silent`). | +| `notify` | Output given message under-prompt after successfully loading a plugin/snippet. In case of problems with the loading, output a warning message and the return code. If starts with `!` it will then always output the given message. Hint: if the message is empty, then it will just notify about problems. | + +```mdx-code-block + +``` + +## Completions {#completions} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :-------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockf` | Disallow plugin to modify `fpath`. Useful when a plugin wants to provide completions traditionally. Manage completions using Zi and block the plugins to expose them. | +| `nocompletions` | Skip plugin completions detection and installation. Completions can be installed anytime using: `zi creinstall {plugin-name}`. | + +```mdx-code-block + +``` + +## Command execution after cloning, updating or loading {#command-execution-after-cloning-updating-or-loading} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `mv` | Move file after cloning or update (only for new commits). Example: `mv "fzf-* -> fzf"`. It uses `->` as a separator for old and new file names. Also works with snippets. | +| `cp` | Copy file after cloning or update (only for new commits). Example: `cp "docker-c* -> dcompose"`. Ran after `mv`. | +| [atclone][4] | Run command after cloning, within plugin's directory, e.g. `zi ice atclone"echo cloned"`. Ran also after downloading the snippet. | +| [atpull][4] | Run command after updating (only for new commits), within the plugin's directory. If starts with "!" then the command will be run before `mv` & `cp` ices and before `git pull` or `svn update`. Otherwise is run after `mv` & `cp` ices. Use the `atpull'%atclone'` to repeat `atclone` ice-modifier. | +| [atinit][4] | Run command after directory setup (cloning, checking, etc.) of the plugin/snippet before loading it. | +| [atload][4] | Run the given command within the plugin's directory after loading. Can be used with snippets. Passed code can be preceded with `!`, to be investigated (when using `load`, not `light`). | +| `run-atpull` | Always run the atpull hook (when updating), not exclusively for new commits. | +| `nocd` | Don't switch the current directory to the plugin's directory when evaluating the above ice-modifiers `atinit'…'`, `atload'…'`, etc. | +| [make][5] | Run the `make` command after cloning or updating and executing the `mv`, `cp`, `atpull`, `atclone` ice-modifiers. Can obtain argument, e.g. `make"install PREFIX=/opt"`. If the value starts with `!` then `make` is run before `atclone` and `atpull` ice-modifiers, e.g. `make'!'`. | +| `countdown` | Causes an interruptive (Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing `atclone'…'`, `atpull'…'` and `make` ices-modifiers. | +| `reset` | Invokes `git reset --hard HEAD` for plugins or `svn revert` for SVN snippets before pulling any new changes. This way `git` or `svn` will not report conflicts if some changes were done by e.g.: `atclone'…'` ice-modifier. For file snippets and `gh-r` plugins, it invokes `rm -rf *`. | + +```mdx-code-block + +``` + +## Sticky-Emulation Of other shells {#sticky-emulation-of-other-shells} + +```mdx-code-block + +``` + +| Ice 修飾子 | 説明 | +| :-------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sh`, `!sh` | Source the plugin's (or snippet's) script with `sh` emulation so that also all functions declared within the file will get a **sticky** emulation assigned and invoked with the `sh` emulation set-up. The `!sh` version switches additional options that are rather not important from the portability perspective. | +| `bash`, `!bash` | The same as `sh`, but with the `SH_GLOB` option disabled, for "Bash" regular expressions to work. | +| `ksh`, `!ksh` | The same as `sh`, but emulating the `ksh` shell. | +| `csh`, `!csh` | The same as `sh`, but emulating the `csh` shell. | + +```mdx-code-block + +``` + + + + + +[^1]: This pattern will alphabetically match and choose the first file e.g: `zi ice pick"*.plugin.zsh"; zi load …`. +[^2]: Example: `multisrc'misc.zsh grep.zsh'` and also using brace-expansion syntax: `multisrc'{misc,grep}.zsh'` also supports patterns. +[^3]: For `wait'[[ … ]]'`, `wait'(( … ))'`, loading is done when given condition is meet. For `wait'!…'`, the prompt is reset after load. Zsh can start 80% (i.e.: 5x) faster thanks to postponed loading. **Fact:** when `wait` is used without a value, it works as `wait'0'`. +[^4]: It will load once, the condition can be still true, but will not trigger the second load, unless the plugin is unloaded earlier, see `unload`. E.g.: `load'[[ $PWD = */github* ]]'`. +[^5]: It will unload once, then only if loaded again e.g: `unload'[[ $PWD != */github* ]]'`. +[^6]: Example: `zi ice if'[[ -n "$commands[otool]" ]]'; zi load …` or `zi ice if'[[ $OSTYPE = darwin* ]]'; zi load …`. +[^7]: To use the option, precede the ice content with `!` to automatically forward the call afterward, to a command of the same name as the function. Can obtain multiple functions to create – separate with `;`. +[^8]: The third possible value is `as"null"` – a shorthand for `pick"/dev/null" nocompletions` – i.e.: it disables the default script-file sourcing and also the installation of completions. +[^9]: In summary, `wrap` allows to extend the investigating beyond the moment of loading of a plugin. An example use is to `wrap` a precmd function of a prompt (like `_p9k_precmd()` of powerlevel10k) or other plugins that _postpones its initialization till the first prompt_ (like e.g.: zsh-autosuggestions). **Does not work with snippets.** +[^10]: If it has no value, then it works in the _auto_ mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known **type** – the type is being read by the `file` Unix command. If not empty, then takes the names of the files to extract. Refer to the Wiki page for further information. + + + + + +[8]: /docs/guides/syntax/bindkey + +[9]: /docs/guides/syntax/standard#wrap + +[10]: /docs/guides/syntax/standard#extract + +[12]: /ecosystem/annexes/overview + +[alternate-syntax]: /docs/guides/syntax/standard#the-alternative-syntaxes + +[1]: /docs/guides/syntax/standard#src-pick-multisrc + +[2]: /docs/guides/syntax/standard#wait + +[3]: /docs/guides/customization#multiple-prompts + +[4]: /docs/guides/syntax/standard#atclone-atpull-atinit-atload + +[5]: /docs/guides/syntax/standard#the-make-syntax + +[6]: /docs/guides/syntax/standard#id-as + + + +[7]: https://github.com/search?q=topic%3Azservice+org%3Az-shell&type=Repositories diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx new file mode 100644 index 00000000..c6244105 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx @@ -0,0 +1,143 @@ +--- +id: bindkey +title: 🗒 Bindkeys マップ +sidebar_position: 5 +image: /img/png/theme/z/320x320.png +description: Usage bindmap & bindkey. +keywords: + - syntax + - bindkey + - bindmap + - how-to-use +--- + + + +## Bindkey + +The `bindkey` key mappings can be very confusing to decipher. It can use multiple different notations but it's smart to use the same key notation throughout your configuration. You can print all of your current key bindings in the current keymap with `bindkey`. To print the full `bindkey` command to add to your `.zshrc` file use `bindkey -L`. + +In general, you'll bind a widget so a key sequence or a key with a modifier. This can be declared in [caret notation][5] using `^`, using [escape sequences][6] using `\`, in octal (`\NNN`), hex (`\xNN`), or Unicode (`\uNNNN`). None of these are particularly great for people to read. This is also tricky because it depends on your keyboard, operating system, and shell. + +次に、いくつかの例を示します: + +- `\e`, `\E`, = Escape +- `^[` = Alt key (on some keyboards this is the same as escape) +- `^?` = Delete +- `^X`, `^` = Control + +The keys that come after the modifier can add more confusion. + +## Delete key binding + +To delete a key binding you can use `bindkey -d $KEYS`. Make sure you don't delete the characters you need for typing. + +## The `bindmap'…'` keybindings {#bindmap} + +Sometimes plugins call [bindkey][1] to assign keyboard shortcuts. This can cause problems because multiple plugins can bind the same keys. + +Also, the user might want a different binding(s), which will require complicated, additional `bindkey` commands in `.zshrc`. + +Zi provides a solution to this problem – the ability to remap the bindkeys with a short [ice-modifier][2] `bindmap'…'`. + +### Examples for `bindmap'…'` + +Map Ctrl-G instead of Ctrl-R for the history searcher. + +```shell +zi bindmap'^R -> ^G' for z-shell/history-search-multi-word +``` + +Map Ctrl-Shift-Left and Ctrl-Shift-Right used by URxvt instead of the Xterms' ones. Load with the bindkey-tracking ↔ with light-loading for anything else. + +Could also separate the bindmaps with a semicolon, i.e.: + +```shell +bindmap'"\\e[1\;6D" -> \\e[1\;5D ; "\\e[1\;6C" -> ^[[1\;5C' \ +``` + +```shell showLineNumbers +zi wait light-mode trackbinds bindmap'"\\e[1\;6D" -> \\e[1\;5D"' \ + bindmap'"\\e[1\;6C" -> ^[[1\;5C' pick'dircycle.zsh' for \ + michaelxmcbride/zsh-dircycle +``` + +Map space to regular space and Ctrl-Space to the `globalias` widget, which expands the alias entered on the left, provided by OMZ globalias plugin. + +```shell showLineNumbers +zi bindmap='!" " -> magic-space; !"^ " -> globalias' nocompletions \ + depth=1 pick=plugins/globalias/globalias.plugin.zsh for \ + ohmyzsh/ohmyzsh +``` + +### Explanation + +The `bindmap'…'` ice has two modes of operation: normal and exclamation-mark (`bindmap'!…'`). In the first mode, the remapping is being done from-key to-key, i.e.: `bindmap'fromkey -> to-key'`. + +The given key is changed to the second given key in the `bindkey` command while loading the plugin. In the second mode, the remapping is being done from-key to-widget, e.g: `bindmap'!from-key -> to-widget'`. + +In this mode, the given key is being mapped to the given widget instead of the widget specified in the `bindkey` command e.g.: + +Instead of: + +```shell showLineNumbers +bindkey "^ " magic-space +bindkey " " globalias +``` + +The actual call that'll be done will be: + +```shell showLineNumbers +bindkey "^ " globalias +bindkey " " magic-space +``` + +For the `bindmap='!" " -> magic-space; !"^ " -> globalias'` ice. + +### Using `bindmap'…'` in light mode {#trackbinds} + +When the investigation mode is on i.e.: + +- when the full loading mode is being used, default in the `for` syntax, and when `zi load …` is used, then the `bindmap'…'` ice works normally. + +In the non-investigation: + +- the [light mode](/search/?q=light+mode) – activated when `zi light …` or the `light-mode` ice is being used – the `bindmap'…'` is unavailable, unless the `trackbinds` ice is specified: + +With the use of the light-mode ice and the for-syntax: + +```shell showLineNumbers +zi light-mode for trackbinds bindmap'^R -> ^G' \ + z-shell/history-search-multi-word +``` + +With the use of the traditional syntax: + +```shell showLineNumbers +zi ice trackbinds bindmap'^R -> ^G' +zi light z-shell/history-search-multi-word +``` + +### Using the UPAR shorthands + +There are four special values that can be used on the left side of the bind-map: UPAR, DOWNAR, LEFTAR, RIGHTAR. They'll match up arrow, down arrow, etc. So that it's possible to do: + +```shell +zi bindmap='LEFTAR -> ^F; RIGHTAR -> ^G' … +``` + +The benefit of using the UPAR, … shorthands is that they cover multiple possible cursor-key codes for each of the cursor keys so that they'll work regardless of the terminal is used. + + + + + +[1]: /search/?q=bindkey + +[2]: /search/?q=ice+modifier + + + +[5]: https://en.wikipedia.org/wiki/Caret_notation + +[6]: https://en.wikipedia.org/wiki/Escape_sequence diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json new file mode 100644 index 00000000..fbad9de0 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "✍️ 構文", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/index.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/index.mdx new file mode 100644 index 00000000..bf33e1b4 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/index.mdx @@ -0,0 +1,127 @@ +--- +id: intro +slug: / +title: 🎉 はじめに +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: Zshのためのスイスアーミーナイフ（旧称：zplugin, zinit）の紹介。 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import Image from "@theme/IdealImage"; +import ImgShow from "@site/src/components/ImgShow"; +import ZGitImg from "@site/static/img/png/theme/branch_box.png"; + +Z-Shell + + + + +[RubyGems](https://rubygems.org) と [$GEM_HOME](https://guides.rubygems.org/command-reference/#gem-environment) は、 [bin-gem-node](/ecosystem/annexes/bin-gem-node) 別館によって自動的に管理されるか、 [any-gem](https://github.com/z-shell/any-gem) パッケージによってインストールされます。 + + + + +[Node](https://www.npmjs.com) モジュールと [$NODE_PATH](https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders) は [bin-gem-node](/ecosystem/annexes/bin-gem-node) 別館で自動的に管理されるか、 [any-node](https://github.com/z-shell/any-node) パッケージでインストールされます。 + + + + +[Python](https://python.org) モジュール、[$VIRTUALENV](https://docs.python.org/3/tutorial/venv.html) は [bin-gem-node](/ecosystem/annexes/bin-gem-node) 別館により自動的に管理されます。 + + + + +[Rust](https://crates.io) パッケージは [rust](/ecosystem/annexes/rust) 別館によって管理されています。 + + + + +[Annexes](/ecosystem/category/-annexes), [Packages](/ecosystem/category/-packages), [Gallery of Invocations](/community/gallery/collection): GitHubからほとんどすべてのものをインストールし、制御することができます。 + + + + +## Fast and feature-rich + +- [Meta plugins][meta-plugins] allow installing groups of plugins via a single, friendly label. +- [Packages](/ecosystem/category/-packages) offload the user from providing long and complex commands. +- [Annexes](ecosystem/category/-annexes) allow extending the plugin manager with new features. +- [Turbo][turbo-mode-zsh--53] mode yields **50-80%** faster Zsh startup. + +## Neat and flexible + +- [Customize paths][customizing-paths], use [multiple prompts][multiple-prompts] or create [your own][non-github-local-plugins] plugins. +- Supports [Oh My Zsh][oh-my-zsh-prezto] and [Prezto][oh-my-zsh-prezto] plugins and libraries. ([migration][help-migrate]). +- Does not use $FPATH, loading multiple plugins doesn't clutter $FPATH with the same number of entries, e.g: 10, 15, or more. +- Code is immune to KSH_ARRAYS and other options typically causing compatibility problems. +- Do not require root access, and provide many workarounds e.g: setting so-called **shims** locally. + +## Familiarize and control + +- [Visualize and manage][commands] elements of the plugin: + - **aliases**, **functions**, **bindkeys**, **zle widgets**, **completions**, **variables**. +- Quickly [familiarize][reports-and-statistics] yourself with rich and easy-to-digest information. +- [Load or unload][loading-and-unloading] plugins, use the ability to [manage][completions-management] completions. +- Docker [playground][configs-playground], test or propose configurations. + +## Summary + + + + + + + + + + + + +[commands]: /docs/guides/commands + +[completions-management]: /docs/guides/commands#completions-management + +[customizing-paths]: /docs/guides/customization#customizing-paths + +[loading-and-unloading]: /docs/guides/commands#loading-and-unloading + +[meta-plugins]: /search?q=meta+plugins + +[help-migrate]: /docs/getting_started/migration + +[multiple-prompts]: /docs/guides/customization#multiple-prompts + +[non-github-local-plugins]: /docs/guides/customization#non-github-local-plugins + +[oh-my-zsh-prezto]: /docs/getting_started/overview#oh-my-zsh-prezto + +[reports-and-statistics]: /docs/guides/commands#reports-and-statistics + +[turbo-mode-zsh--53]: /docs/getting_started/overview#turbo-mode-zsh--53 + + + +[configs-playground]: https://github.com/z-shell/playground diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/zi_code.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/zi_code.mdx new file mode 100644 index 00000000..c6d227aa --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/zi_code.mdx @@ -0,0 +1,85 @@ +--- +id: code +title: 🔖 コードドキュメント +image: /img/png/theme/z/320x320.png +description: 文書には、すべての機能、それらの間の相互作用、それらのコメント、および機能が示されています。 +keywords: + - code + - zi-code + - documentation + - code-explained +--- + + + +import APITable from "@site/src/components/APITable"; + +:::info + +Documentation is automatically updated every `Thursday` at `4:30 UTC` at [z-shell/docs][]. + +::: + +```mdx-code-block + +``` + +| ファイル | ドキュメントの様式 | 説明 | +| -------------------- | --------------------------------- | ------------------------------------------------------------- | +| [zi.zsh][2] | [adoc][3], [pdf][4], [html][5] | The main script which is always loaded, in `.zshrc` | +| [side.zsh][6] | [adoc][7], [pdf][8], [html][9] | Functions, loaded by `install.zsh` and `autoload.zsh` scripts | +| [install.zsh][10] | [adoc][11], [pdf][12], [html][13] | プラグインまたはスニペットをインストールする場合にのみ使用される関数 | +| [autoload.zsh][14] | [adoc][15], [pdf][16], [html][17] | Functions used only in interactive `Zi` invocations | +| [additional.zsh][18] | [adoc][19], [pdf][20], [html][21] | 関数に対する追加サポート | + +```mdx-code-block + +``` + + + + + + + +[z-shell/docs]: https://github.com/z-shell/docs + +[2]: https://github.com/z-shell/zi/blob/main/zi.zsh + +[3]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/zi.zsh.adoc + +[4]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/zi.zsh.pdf + +[5]: https://z-shell.github.io/docs/code/html/zi.zsh.html + +[6]: https://github.com/z-shell/zi/blob/main/lib/zsh/side.zsh + +[7]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/side.zsh.adoc + +[8]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/side.zsh.pdf + +[9]: https://z-shell.github.io/docs/code/html/side.zsh.html + +[10]: https://github.com/z-shell/zi/blob/main/lib/zsh/install.zsh + +[11]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/install.zsh.adoc + +[12]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/install.zsh.pdf + +[13]: https://z-shell.github.io/docs/code/html/install.zsh.html + +[14]: https://github.com/z-shell/zi/blob/main/lib/zsh/autoload.zsh + +[15]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/autoload.zsh.adoc + +[16]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/autoload.zsh.pdf + +[17]: https://z-shell.github.io/docs/code/html/autoload.zsh.html + +[18]: https://github.com/z-shell/zi/blob/main/lib/zsh/additional.zsh + +[19]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/additional.zsh.adoc + +[20]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/additional.zsh.pdf + +[21]: https://z-shell.github.io/docs/code/html/additional.zsh.html diff --git a/i18n/ja/docusaurus-theme-classic/footer.json b/i18n/ja/docusaurus-theme-classic/footer.json new file mode 100644 index 00000000..cfc6996f --- /dev/null +++ b/i18n/ja/docusaurus-theme-classic/footer.json @@ -0,0 +1,66 @@ +{ + "link.title.Knowledge Base": { + "message": "知識", + "description": "The title of the footer links column with title=Knowledge Base in the footer" + }, + "link.title.Community": { + "message": "コミュニティ", + "description": "The title of the footer links column with title=Community in the footer" + }, + "link.title.More": { + "message": "もっと見る", + "description": "The title of the footer links column with title=More in the footer" + }, + "link.title.Legal": { + "message": "法的事項", + "description": "The title of the footer links column with title=Legal in the footer" + }, + "link.item.label.Introduction": { + "message": "はじめに", + "description": "The label of footer link with label=Introduction linking to /docs" + }, + "link.item.label.Ecosystem": { + "message": "エコシステム", + "description": "The label of footer link with label=Ecosystem linking to /ecosystem" + }, + "link.item.label.Community": { + "message": "コミュニティ", + "description": "The label of footer link with label=Community linking to /community" + }, + "link.item.label.Discussions": { + "message": "議論", + "description": "The label of footer link with label=Discussions linking to https://discussions.zshell.dev" + }, + "link.item.label.GitHub": { + "message": "GitHub", + "description": "The label of footer link with label=GitHub linking to https://github.com/orgs/z-shell" + }, + "link.item.label.Matrix": { + "message": "Matrix", + "description": "The label of footer link with label=Matrix linking to https://matrix.to/#/#zshell:matrix.org" + }, + "link.item.label.Zsh Manual": { + "message": "Zsh マニュアル", + "description": "The label of footer link with label=Zsh Manual linking to https://zsh.sourceforge.io/Doc/Release/zsh_toc.html" + }, + "link.item.label.Localization": { + "message": "翻訳", + "description": "The label of footer link with label=Localization linking to https://translate.zshell.dev" + }, + "link.item.label.Uptime Status": { + "message": "稼働状況", + "description": "The label of footer link with label=Uptime Status linking to https://status.zshell.dev" + }, + "link.item.label.Privacy Policy": { + "message": "プライバシーポリシー", + "description": "The label of footer link with label=Privacy Policy linking to legal/PRIVACY" + }, + "link.item.label.Code of Conduct": { + "message": "行動規範", + "description": "The label of footer link with label=Code of Conduct linking to legal/CODE_OF_CONDUCT" + }, + "copyright": { + "message": "著作権 © 2023 Z-Shell コミュニティ", + "description": "The footer copyright" + } +} diff --git a/i18n/ja/docusaurus-theme-classic/navbar.json b/i18n/ja/docusaurus-theme-classic/navbar.json new file mode 100644 index 00000000..33c1bd10 --- /dev/null +++ b/i18n/ja/docusaurus-theme-classic/navbar.json @@ -0,0 +1,22 @@ +{ + "title": { + "message": "Z-Shell", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "A Swiss Army Knife for Zsh Unix shell", + "description": "The alt text of navbar logo" + }, + "item.label.Docs": { + "message": "ドキュメント", + "description": "Navbar item with label Docs" + }, + "item.label.Ecosystem": { + "message": "エコシステム", + "description": "Navbar item with label Ecosystem" + }, + "item.label.Community": { + "message": "コミュニティ", + "description": "Navbar item with label Community" + } +} diff --git a/i18n/zh-Hans/code.json b/i18n/zh-Hans/code.json new file mode 100644 index 00000000..b4d2ec01 --- /dev/null +++ b/i18n/zh-Hans/code.json @@ -0,0 +1,492 @@ +{ + "homepage.feature1.title": { + "message": "Zsh 启动速度快 50-80%", + "description": "Title of feature 1 (left) on the home page" + }, + "home.feature1": { + "message": "即时提示将插件加载推迟到 .zshrc 文件处理完成时。", + "description": "Description of first featured banner in homepage" + }, + "homepage.feature2.title": { + "message": "专注于重要的事情", + "description": "Title of feature 2 (middle) on the home page" + }, + "home.feature2": { + "message": "关于插件的统计信息，描述插件设置的功能、键位绑定、补全和其他东西。", + "description": "Description of second featured banner in homepage" + }, + "homepage.feature3.title": { + "message": "广泛的功能", + "description": "Title of feature 3 (right) on the home page" + }, + "home.feature3": { + "message": "支持 Oh-My-Zsh 和 Prezto - 不特定于框架的。轻松制作您的插件、库和主题。", + "description": "Description of third featured banner in homepage" + }, + "homepage.hero.title": { + "message": "Zsh Unix Shell 的 瑞士军刀 ", + "description": "Home page hero title, can contain simple html tags" + }, + "homepage.banner.button.1": { + "message": "开始使用", + "description": "The homepage get started button" + }, + "homepage.banner.button.2": { + "message": "社区", + "description": "The homepage community button" + }, + "homepage.video.heading.1": { + "message": "快速且功能丰富", + "description": "The homepage video container heading 1" + }, + "theme.ErrorPageContent.title": { + "message": "页面已崩溃。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "回到顶部", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "历史博文", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "历史博文", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "博文列表分页导航", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "较新的博文", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "较旧的博文", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "博文分页导航", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "较新一篇", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "较旧一篇", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "{count} 篇博文", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} 含有标签「{tagName}」", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "查看所有标签", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel": { + "message": "切换浅色/暗黑模式（当前为{mode}）", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "暗黑模式", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "浅色模式", + "description": "The name for the light color mode" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "页面路径", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription": { + "message": "{count} 个项目", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "Docs pages", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "上一页", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "下一页", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "{count} 篇文档带有标签", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged}「{tagName}」", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "版本：{versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版尚未发行的文档。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版的文档，现已不再积极维护。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新的文档请参阅 {latestVersionLink} ({versionLabel})。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新版本", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "编辑此页", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "Direct link to {heading}", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "于 {date} ", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "由 {user} ", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最后{byUser}{atDate}更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "选择版本", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "找不到页面", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "标签：", + "description": "The label alongside a tag list" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "危险", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "信息", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "备注", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "提示", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "warning", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "关闭", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近博文导航", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.CodeBlock.copied": { + "message": "复制成功", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "复制代码到剪贴板", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "复制", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "切换自动换行", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "Expand sidebar category '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "Collapse sidebar category '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "Main", + "description": "The ARIA label for the main navigation" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "选择语言", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.NotFound.p1": { + "message": "我们找不到您要找的页面。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "请联系原始链接来源网站的所有者，并告知他们链接已损坏。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "本页总览", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "阅读更多", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "阅读 {title} 的全文", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "阅读需 {readingTime} 分钟", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.breadcrumbs.home": { + "message": "主页面", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "Docs sidebar", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "关闭导航栏", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← 回到主菜单", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "切换导航栏", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.SearchBar.seeAll": { + "message": "查看全部 {count} 个结果" + }, + "theme.SearchPage.documentsFound.plurals": { + "message": "找到 {count} 份文件", + "description": "Pluralized label for \"{count} documents found\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.SearchPage.existingResultsTitle": { + "message": "「{query}」的搜索结果", + "description": "The search page title for non-empty query" + }, + "theme.SearchPage.emptyResultsTitle": { + "message": "在文档中搜索", + "description": "The search page title for empty query" + }, + "theme.SearchPage.inputPlaceholder": { + "message": "在此输入搜索字词", + "description": "The placeholder for search page input" + }, + "theme.SearchPage.inputLabel": { + "message": "搜索", + "description": "The ARIA label for search page input" + }, + "theme.SearchPage.algoliaLabel": { + "message": "通过 Algolia 搜索", + "description": "The ARIA label for Algolia mention" + }, + "theme.SearchPage.noResultsText": { + "message": "未找到任何结果", + "description": "The paragraph for empty search result" + }, + "theme.SearchPage.fetchingNewResults": { + "message": "正在获取新的搜索结果...", + "description": "The paragraph for fetching new search results" + }, + "theme.SearchBar.label": { + "message": "搜索", + "description": "The ARIA label and placeholder for search button" + }, + "theme.SearchModal.searchBox.resetButtonTitle": { + "message": "清除查询", + "description": "The label and ARIA label for search box reset button" + }, + "theme.SearchModal.searchBox.cancelButtonText": { + "message": "取消", + "description": "The label and ARIA label for search box cancel button" + }, + "theme.SearchModal.startScreen.recentSearchesTitle": { + "message": "最近搜索", + "description": "The title for recent searches" + }, + "theme.SearchModal.startScreen.noRecentSearchesText": { + "message": "没有最近搜索", + "description": "The text when no recent searches" + }, + "theme.SearchModal.startScreen.saveRecentSearchButtonTitle": { + "message": "保存这个搜索", + "description": "The label for save recent search button" + }, + "theme.SearchModal.startScreen.removeRecentSearchButtonTitle": { + "message": "从历史记录中删除这个搜索", + "description": "The label for remove recent search button" + }, + "theme.SearchModal.startScreen.favoriteSearchesTitle": { + "message": "收藏", + "description": "The title for favorite searches" + }, + "theme.SearchModal.startScreen.removeFavoriteSearchButtonTitle": { + "message": "从收藏列表中删除这个搜索", + "description": "The label for remove favorite search button" + }, + "theme.SearchModal.errorScreen.titleText": { + "message": "无法获取结果", + "description": "The title for error screen of search modal" + }, + "theme.SearchModal.errorScreen.helpText": { + "message": "你可能需要检查网络连接。", + "description": "The help text for error screen of search modal" + }, + "theme.SearchModal.footer.selectText": { + "message": "选中", + "description": "The explanatory text of the action for the enter key" + }, + "theme.SearchModal.footer.selectKeyAriaLabel": { + "message": "Enter 键", + "description": "The ARIA label for the Enter key button that makes the selection" + }, + "theme.SearchModal.footer.navigateText": { + "message": "导航", + "description": "The explanatory text of the action for the Arrow up and Arrow down key" + }, + "theme.SearchModal.footer.navigateUpKeyAriaLabel": { + "message": "向上键", + "description": "The ARIA label for the Arrow up key button that makes the navigation" + }, + "theme.SearchModal.footer.navigateDownKeyAriaLabel": { + "message": "向下键", + "description": "The ARIA label for the Arrow down key button that makes the navigation" + }, + "theme.SearchModal.footer.closeText": { + "message": "关闭", + "description": "The explanatory text of the action for Escape key" + }, + "theme.SearchModal.footer.closeKeyAriaLabel": { + "message": "Esc 键", + "description": "The ARIA label for the Escape key button that close the modal" + }, + "theme.SearchModal.footer.searchByText": { + "message": "搜索提供", + "description": "The text explain that the search is making by Algolia" + }, + "theme.SearchModal.noResultsScreen.noResultsText": { + "message": "没有结果：", + "description": "The text explains that there are no results for the following search" + }, + "theme.SearchModal.noResultsScreen.suggestedQueryText": { + "message": "试试搜索", + "description": "The text for the suggested query when no results are found for the following search" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsText": { + "message": "认为这个查询应该有结果？", + "description": "The text for the question where the user thinks there are missing results" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsLinkText": { + "message": "请告知我们。", + "description": "The text for the link to report missing results" + }, + "theme.SearchModal.placeholder": { + "message": "搜索文档", + "description": "The placeholder of the input of the DocSearch pop-up modal" + }, + "theme.IdealImageMessage.loading": { + "message": "加载中……", + "description": "When the full-scale image is loading" + }, + "theme.IdealImageMessage.load": { + "message": "点击加载图片{sizeMessage}", + "description": "To prompt users to load the full image. sizeMessage is a parenthesized size figure." + }, + "theme.IdealImageMessage.offline": { + "message": "你的浏览器处于离线状态。图片未加载", + "description": "When the user is viewing an offline document" + }, + "theme.IdealImageMessage.404error": { + "message": "未找到图片", + "description": "When the image is not found" + }, + "theme.IdealImageMessage.error": { + "message": "出现错误，点击重试", + "description": "When the image fails to load for unknown error" + }, + "theme.PwaReloadPopup.info": { + "message": "有可用的新版本", + "description": "The text for PWA reload popup" + }, + "theme.PwaReloadPopup.refreshButtonText": { + "message": "刷新", + "description": "The text for PWA reload button" + }, + "theme.PwaReloadPopup.closeButtonAriaLabel": { + "message": "关闭", + "description": "The ARIA label for close button of PWA reload popup" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "重试", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "跳到主要内容", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "标签", + "description": "The title of the tag list page" + }, + "theme.unlistedContent.title": { + "message": "Unlisted page", + "description": "The unlisted content banner title" + }, + "theme.unlistedContent.message": { + "message": "This page is unlisted. Search engines will not index it, and only users having a direct link can access it.", + "description": "The unlisted content banner message" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-blog/options.json b/i18n/zh-Hans/docusaurus-plugin-content-blog/options.json new file mode 100644 index 00000000..61298ed5 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-blog/options.json @@ -0,0 +1,14 @@ +{ + "title": { + "message": "博客", + "description": "The title for the blog used in SEO" + }, + "description": { + "message": "博客", + "description": "The description for the blog used in SEO" + }, + "sidebar.title": { + "message": "最新发布", + "description": "The label for the left sidebar" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current.json new file mode 100644 index 00000000..7e19d35f --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current.json @@ -0,0 +1,22 @@ +{ + "version.label": { + "message": "下一页", + "description": "The label for version current" + }, + "sidebar.SideBar.category.📖 Zsh User's Guide": { + "message": "📖 Zsh 用户指南", + "description": "The label for category 📖 Zsh User's Guide in sidebar SideBar" + }, + "sidebar.SideBar.category.🎯 Roadmap": { + "message": "🎯 Roadmap", + "description": "The label for category 🎯 Roadmap in sidebar SideBar" + }, + "sidebar.SideBar.category.✨ Gallery of Invocations": { + "message": "✨ 调用库", + "description": "The label for category ✨ Gallery of Invocations in sidebar SideBar" + }, + "sidebar.SideBar.category.✨ Collection": { + "message": "✨ 集合", + "description": "The label for category ✨ Collection in sidebar SideBar" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx new file mode 100644 index 00000000..924f5263 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/02_zsh_plugin_standard.mdx @@ -0,0 +1,532 @@ +--- +id: zsh_plugin_standard +title: ℹ️ Zsh Plugin Standard +sidebar_position: 2 +image: /img/png/theme/z/320x320.png +toc_max_heading_level: 2 +keywords: + - zsh + - create + - plugin + - zsh-plugin + - best-practices + - create-zsh-plugin + - zsh-plugin-standard +--- + + + +## What is a Zsh plugin? + +从历史上看，Zsh 插件最初是由 Oh My Zsh 定义的。 They provide a way to package together files that extend or configure the shell’s functionality in a particular way. + +简单来说，一个插件： + +1. Has directory added to `$fpath` ([Zsh documentation: #Autoloading-Functions][autoloading-functions]). This is being done either by a plugin manager or by the plugin itself (see [5th section](#run-on-unload-call) for more information). + +2. Has first `*.plugin.zsh` file sourced (or `*.zsh`, `init.zsh`, `*.sh`, these are non-standard). + + 2.1 The first point allows plugins to provide completions and functions that are loaded via Zsh’s `autoload` mechanism (a single function per file). + +3. 从更全面的角度来看，一个插件包含以下几点： + + 3.1. a directory containing various files (the main script, autoload functions, completions, Makefiles, backend programs, documentation). + + 3.2. a source-able script that obtains the path to its directory via `$0` (see the [next section](#zero-handling) for a related enhancement proposal). + + 3.3. GitHub (or another site) repository identified by two components **username**/**plugin-name**. + + 3.4. software package containing any type of command line artifacts – when used with advanced plugin managers that have hooks, can run Makefiles, and add directories to `$PATH`. + +Below follow the proposed enhancements and codifications of the definition of a "Zsh the plugin" and the actions of plugin managers – the proposed standardization. + +它们涵盖了如何编写Zsh插件的信息。 + +## 1. Standardized `$0` handling {#zero-handling} + +> [ zero-handling ] + +要获取插件的位置，插件应该这样做: + +```shell showLineNumbers +0="${ZERO:-${${0:#$ZSH_ARGZERO}:-${(%):-%N}}}" +0="${${(M)0:#/*}:-$PWD/$0}" +``` + +Then `${0:h}` to get the plugin’s directory. + +以上的单行代码将： + +1. Be backward-compatible with normal `$0` setting and usage. + +2. Use `ZERO` if it’s not empty, + + 2.1. the plugin manager will be easily able to alter effective `$0` before loading a plugin, + + 2.2. this allows e.g. `eval "$( [ functions-directory ] + +Despite that, the current-standard plugins have their main directory added to `$fpath`, a more clean approach is being proposed: that the plugins use a subdirectory called `functions` to store their completions and autoload functions. This will allow a much cleaner design of plugins. The plugin manager should add such a directory to `$fpath`. The lack of support of the current plugin managers can be easily resolved via the [indicator](#indicator): + +```shell showLineNumbers +if [[ ${zsh_loaded_plugins[-1]} != */kalc && -z ${fpath[(r)${0:h}/functions]} ]]; then + fpath+=( "${0:h}/functions" ) +fi +``` + +or, via use of the `PMSPEC` [parameter](#pmspec): + +```shell showLineNumbers +if [[ $PMSPEC != *f* ]]; then + fpath+=( "${0:h}/functions" ) +fi +``` + +The above snippet added to the `plugin.zsh` file will add the directory to the `$fpath` with the compatibility with any new plugin managers preserved. The existence of the `functions` subdirectory cancels the normal adding of the main plugin directory to `$fpath`. + +### **STATUS:** [ functions-directory ] + +- GitHub Search: [zsh_loaded_plugins](https://github.com/search?q=%22$zsh_loaded_plugins%22&type=code) +- GitHub Search: [PMSPEC \*f\*](https://github.com/search?q=[[%20%22$PMSPEC%22%20!=%20*f*%20]]&type=code) + +## 3. Binaries directory {#binaries-directory} + +> [ binaries-directory ] + +Plugins sometimes provide a runnable script or program, either for their internal use or for the end-user. It is proposed that for the latter, the plugin shall use a `bin/` subdirectory inside its main dir (it is recommended, that for internal use, the runnable be called via the `$0` value obtained as described above). + +The runnable should be put into the directory with a `+x` access right assigned. The task of the plugin manager should be: + +1. Before sourcing the plugin’s script it should test, if the `bin/` directory exists within the plugin directory. + +2. If it does, it should add the directory to `$PATH`. + +3. The plugin manager can also, instead of extending the `$PATH`, create a **shim** (i.e.: a forwarder script) or a symbolic link inside a common directory that’s already added to `$PATH` (to limit extending it). + +4. The plugin manager is permitted to do optional things like ensuring `+x` access rights on the directory contents. The `$PMSPEC` code letter for the feature is `b`, and it allows for the plugin to handle the `$PATH` extending itself, via, e.g.: + +```shell showLineNumbers +if [[ $PMSPEC != *b* ]]; then + path+=( "${0:h}/bin" ) +fi +``` + +### **STATUS:** [ binaries-directory ] + +- GitHub Search: [PMSPEC \*b\*](https://github.com/search?q=[[%20%22$PMSPEC%22%20!=%20*b*%20]]&type=code) + +## 4. Unload function {#unload-function} + +> [ unload-function ] + +If a plugin is named e.g. `kalc` (and is available via `any-user/kalc` plugin-ID), then it can provide a function, `kalc_plugin_unload`, that can be called by a plugin manager to undo the effects of loading that plugin. + +A plugin manager can implement its tracking of changes made by a plugin so this is in general optional. However, to properly unload e.g. a prompt, dedicated tracking (easy to do for the plugin creator) can provide better, predictable results. Any special, uncommon effects of loading a plugin are possible to undo only by a dedicated function. + +However, an interesting compromise approach is available – to withdraw only the special effects of loading a plugin via the dedicated, plugin-provided function and leave the rest to the plugin manager. The value of such an approach is that maintaining such function (if it is to withdraw **all** plugin side-effects) can be a daunting task requiring constant monitoring of it during the plugin development process. + +Note that the unload function should contain `unfunction $0` (or better `unfunction kalc_plugin_unload` etc., for compatibility with the `*_argzero` options), to also delete the function itself. + +### **STATUS:** [ unload-function ] {#unload-function} + +- [Zi][] implements plugin unloading and calls the function. + +- [romkatv/powerlevel10k is using][] the function to execute a specific task: shutdown of the binary, background [gitstatus][] daemon, with very good results, + +- [agkozak/agkozak-zsh-prompt is using][] the function to completely unload the prompt, + +- [agkozak/zsh-z is using][] the function to completely unload the plugin, + +- [agkozak/zhooks is using][] the function to completely unload the plugin. + +## 5. `@zsh-plugin-run-on-unload` call {#run-on-unload-call} + +> [ run-on-unload-call ] + +The plugin manager can provide a function `@zsh-plugin-run-on-unload` which has the following call syntax: + +```shell +@zsh-plugin-run-on-unload "{code-snippet-1}" "{code-snippet-2}" … +``` + +The function registers pieces of code to be run by the plugin manager **on the unloading of the plugin**. The execution of the code should be done by the `eval` built-in in the same order as they are passed to the call. The code should be executed in the plugin’s directory, in the current shell. The mechanism thus provides another way, side to the [unload function](#unload-function), for the plugin to participate in the process of unloading it. + +### **STATUS:** [ run-on-unload-call ] + +- GitHub Search: [zsh-plugin-run-on-unload](https://github.com/search?q=@zsh-plugin-run-on-unload&type=code) + +## 6. `@zsh-plugin-run-on-update` call {#run-on-update-call} + +> [ run-on-update-call ] + +The plugin manager can provide a function `@zsh-plugin-run-on-update` which has the following call syntax: + +```shell +@zsh-plugin-run-on-update "{code-snippet-1}" "{code-snippet-2}" … +``` + +The function registers pieces of code to be run by the plugin manager on an update of the plugin. The execution of the code should be done by the `eval` built-in in the same order as they are passed to the call. The code should be executed in the plugin’s directory, possibly in a subshell **After downloading any new commits** to the repository. + +### **STATUS:** [ run-on-update-call ] + +- GitHub Search: [zsh-plugin-run-on-update](https://github.com/search?q=@zsh-plugin-run-on-update&type=code) + +## 7. Plugin manager activity indicator {#activity-indicator} + +> [ activity-indicator ] + +Plugin managers should set the `$zsh_loaded_plugins` array to contain all previously loaded plugins and the plugin currently being loaded (as the last element). + +This will allow any plugin to: + +1. Check which plugins are already loaded. + +2. Check if it is being loaded by a plugin manager (i.e. not just sourced). + +The first item allows a plugin to e.g. issue a notice about missing dependencies. Instead of issuing a notice, it may be able to satisfy the dependencies on resources it provides. For example, the `pure` prompt provides a `zsh-async` dependency library within its source tree, which is normally a separate project. Consequently, the prompt can decide to source its private copy of `zsh-async`, having also reliable `$0` defined by the previous section (note: `pure` doesn’t normally do this). + +The second item allows a plugin to e.g. set up `$fpath`, knowing that the plugin manager will not handle this: + +```shell showLineNumbers +if [[ ${zsh_loaded_plugins[-1]} != */kalc && -z ${fpath[(r)${0:h}]} ]]; then + fpath+=( "${0:h}" ) +fi +``` + +This will allow the user to reliably source the plugin without using a plugin manager. The code uses the wrapping braces around variables (i.e.: e.g.: `${fpath…}`) to make it compatible with the `KSH_ARRAYS` option and the quoting around `${0:h}` to make it compatible with the `SH_WORD_SPLIT` option. + +### **STATUS:** [ activity-indicator ] + +- GitHub Search: [zsh_loaded_plugins](https://github.com/search?q=%22${zsh_loaded_plugins[-1]}%22&type=code) + +## 8. Global parameter with PREFIX for make, configure, etc {#global-parameter-with-prefix} + +> [ global-parameter-with-prefix ] + +Plugin managers may export the parameter `$ZPFX` which should contain a path to a directory dedicated to user-land software, i.e. for directories `$ZPFX/bin`, `$ZPFX/lib`, `$ZPFX/share`, etc. The suggested name of the directory is `polaris` (e.g.: Zi uses this name and places this directory at `~/.zi/polaris` by default). + +Users can then configure hooks to invoke e.g. `make PREFIX=$ZPFX install` at clone & update the plugin to install software like e.g. [tj/git-extras][]. This is the developing role of Zsh plugin managers as package managers, where `.zshrc` has a similar role to Chef or Puppet configuration and allows to **declare** system state, and have the same state on different accounts/machines. + +No-narration facts-list related to `$ZPFX`: + +1. `export ZPFX="$HOME/polaris"` (or e.g. `$HOME/.zi/polaris`) + +2. `make PREFIX=$ZPFX install` + +3. `./configure --prefix=$ZPFX` + +4. `cmake -DCMAKE_INSTALL_PREFIX=$ZPFX .` + +5. `zi ice make"PREFIX=$ZPFX install"` + +6. `zi … hook-build:"make PREFIX=$PFX install"` + +### **STATUS:** [ global-parameter-with-prefix ] + +- GitHub Search: [ZPFX](https://github.com/search?q=%22$ZPFX%22&type=code) + +## 9. Global parameter holding the plugin manager’s capabilities {#global-parameter-with-capabilities} + +> [ global-parameter-with-capabilities ] + +The above paragraphs of the standard spec each constitute a capability, a feature of the plugin manager. It would make sense that the capabilities are somehow discoverable. To address this, a global parameter called `PMSPEC` (from _plugin-manager specification_) is proposed. It can hold the following Latin letters each informing the plugin, that the plugin manager has support for a given feature: + +- `0` – the plugin manager provides the `ZERO` parameter, + +- `f` - … supports the `functions/` subdirectory, + +- `b` - … supports the `bin/` subdirectory, + +- `u` - … the unload function, + +- `U` - … the `@zsh-plugin-run-on-unload` call, + +- `p` – … the `@zsh-plugin-run-on-update` call, + +- `i` – … the `zsh_loaded_plugins` activity indicator, + +- `b` – … the `ZPFX` global parameter, + +- `s` – … the `PMSPEC` global parameter itself (i.e.: should be always present). + +The contents of the parameter describing a fully-compliant plugin manager should be: `0fuUpiPs`. + +The plugin can then verify the support by: + +```shell showLineNumbers +if [[ $PMSPEC != *P* ]]; then + path+=( "${0:h}/bin" ) +fi +``` + +### **STATUS:** [ global-parameter-with-capabilities ] + +- GitHub Search: [PMSPEC](https://github.com/search?q=%22export+PMSPEC=%22&type=code) + +## Zsh plugin-programming best practices + +The document is to define a **Zsh-plugin** but also to serve as an information source for plugin creators. Therefore, it covers also best practices information in this section. + +## Use of `add-zsh-hook` to install hooks + +Zsh ships with the function `add-zsh-hook`. It has the following invocation syntax: + +```shell +add-zsh-hook [ -L | -dD ] [ -Uzk ] hook function +``` + +The command installs a `function` as one of the supported zsh `hook` entries. which are one of: `chpwd`, `periodic`, `precmd`, `preexec`, `zshaddhistory`, `zshexit`, `zsh_directory_name`. For their meaning refer to the [Zsh documentation: #Hook-Functions][hook-functions]. + +## Use of `add-zle-hook-widget` to install Zle Hooks + +The zle editor is the part of the Zsh that is responsible for receiving the text from the user. It can be said that it’s based on widgets, which are nothing more than Zsh functions that are allowed to be run in Zle context, i.e. from the Zle editor (plus a few minor differences, like e.g.: the `$WIDGET` parameter that’s automatically set by the Zle editor). + +The syntax of the call is: + +```shell +add-zle-hook-widget [ -L | -dD ] [ -Uzk ] hook widgetname +``` + +The call resembles the syntax of the `add-zsh-hook` function. The only difference is that it takes a `widgetname`, not a function name and that the `hook` is one of: `isearch-exit`, `isearch-update`, `line-pre-redraw`, `line-init`, `line-finish`, `history-line-set`, or `keymap-select`. Their meaning is explained in the [Zsh documentation: #Special-Widgets][special-widgets]. + +The use of this function is recommended because it allows the installation **multiple** hooks per each `hook` entry. Before introducing the `add-zle-hook-widget` function the "normal" way to install a hook was to define a widget with the name of one of the special widgets. Now, after the function has been introduced in Zsh `5.3` it should be used instead. + +## Standard parameter naming + +There’s a convention already present in the Zsh world – to name array variables lowercase and scalars uppercase. It’s being followed by e.g.: the Zsh manual and the Z shell itself (e.g.: `REPLY` scalar and `reply` array, etc.). + +The requirement for the scalars to be uppercase should be, in my opinion, kept only for the global parameters. e.g.: it’s fine to name local parameters inside a function lowercase even when they are scalars, not only arrays. + +An extension to the convention is being proposed: to name associative arrays (i.e.: hashes) capitalized, i.e.: with only the first letter uppercase and the remaining letters lowercase. + +See [the next section](#standard-plugins-hash) for an example of such hash. In the case of the name consisting of multiple words each of them should be capitalized, e.g.: `typeset -A MyHash`. + +This convention will increase code readability and bring order to it. + +## Standard `Plugins` hash + +The plugin often has to declare global parameters that should live throughout a Zsh session. Following the [namespace pollution prevention](#preventing-function-pollution) the plugin could use a hash to store the different values. Additionally, the plugins could use a single hash parameter – called `Plugins` – to prevent pollution. + +An example value needed by the plugin: + +```shell showLineNumbers +typeset -gA Plugins +Plugins[MY_PLUGIN_REPO_DIR]="${0:h}" +``` + +This way all the data of all plugins will be kept in a single parameter, available for easy examination and overview (via e.g.: `varied Plugins`), and also not polluting the namespace. + +## Standard recommended [options][] + +The following code snippet is recommended to be included at the beginning of each of the main functions provided by the plugin: + +```shell showLineNumbers +builtin emulate -L zsh ${=${options[xtrace]:#off}:+-o xtrace} +builtin setopt extended_glob warn_create_global typeset_silent no_short_loops rc_quotes no_auto_pushd +``` + +It resets all the options to their default state according to the `zsh` emulation mode, with the use of the `local_options` option – so the options will be restored to their previous state when leaving the function. It then alters the emulation by `7` different options: + +- `${=${options[xtrace]:#off}:+-o xtrace}` – `xtrace` prints commands and their arguments as they are executed, this specific variable calls `xtrace` when needed, e.g.: when already active at the entry to the function. + +- `extended_glob` – enables one of the main Zshell features – the advanced, built-in regex-like globing mechanism, + +- `warn_create_global` – enables warnings to be printed each time a (global) variable is defined without being explicitly defined by a `typeset`, `local`, `declare`, etc. call; it allows to catch typos and missing localizations of the variables and thus prevent from writing a bad code, + +- `typeset_silent` – it allows to call `typeset`, `local`, etc. multiple times on the same variable; without it, the second call causes the variable contents to be printed first; using this option allows declaring variables inside loops, near the place of their use, which sometimes helps to write a more readable code, + +- `no_short_loops` – disables the short-loops syntax; this is done because when the syntax is enabled it limits the parser’s ability to detect errors (see this [zsh-workers post][] for the details), + +- `rc_quotes` – adds useful ability to insert apostrophes into an apostrophe-quoted string, by use of `''` inside it, e.g.: `'a string’s example'` will yield the string `a string’s example`, + +- `no_auto_pushd` - disables the automatic push of the directory passed to `cd` builtin onto the directory stack; this is useful because otherwise, the internal directory changes done by the plugin will pollute the global directory stack. + +## Standard recommended variables + +It’s good to localize the following variables at the entry of the main function of a plugin: + +```shell showLineNumbers +local MATCH REPLY; integer MBEGIN MEND +local -a match mbegin mend reply +``` + +The variables starting with `m` and `M` are being used by the substitutions utilizing `(#b)` and `(#m)` flags, respectively. They should not leak to the global scope. Also, their automatic creation would trigger the warning from the `warn_create_global` option. + +The `reply` and `REPLY` parameters are normally used to return an array or a scalar from a function, respectively – it’s the standard way of passing values from functions. + +Their use is naturally limited to the functions called from the main function of a plugin – they should not be used to pass data around e.g.: in between prompts, thus it’s natural to localize them in the main function. + +## Standard function name-space prefixes + +The recommendation is the purely subjective opinion of the author. + +It can evolve – if you have any remarks, don’t hesitate to [fill them](https://github.com/z-shell/zw/issues/new). + +## The problems solved by the proposition + +However, when adopted, the proposition will solve the following issues: + +1. Using the underscore `_` to namespace functions – this isn’t the right thing to do because the prefix is being already used by the completion functions, so the namespace is already filled up greatly and the plugin functions get lost in it. + +2. Not using a prefix at all – this is also an unwanted practice as it pollutes the command namespace of such an issue appearing. + +3. It would allow quickly discriminate between function types – e.g.: seeing the `:` prefix informs the user that it’s a hook-type function while seeing the `@` prefix informs the user that it’s an API-like function, etc. + +4. It also provides an improvement during programming, by allowing to quickly limit the number of completions offered by the editor, e.g.: for Vim’s Ctrl-P completing, when entering +Ctrl-P, then only a subset of the functions are being completed (see below for the type of the functions). **Note:** the editor has to be configured so that it accepts such special characters as part of keywords, for Vim it’s: `:set isk+=@-@,.,+,/,:` for all of the proposed prefixes. + +## The Proposed function-name prefixes + +The proposition of the standard prefixes is as follows: + +1. `.`: for regular private functions. Example function: `.prompt_zinc_get_value`. + +2. `→`: for hook-like functions, so it should be used e.g.: for the [Zsh hooks](#use-of-add-zsh-hook-to-install-hooks) and the [Zle hooks](#use-of-add-zle-hook-widget-to-install-zle-hooks), but also any other, custom hook-like mechanism in the plugin. Example function name: `→prompt_zinc_precmd`. + + 2.1. the previous version of the document recommended colon (`:`) for the prefix, however, it was problematic, because Windows doesn’t allow colons in file names, so it wasn’t possible to name an autoload function this way, + + 2.2. the arrow has a rationale behind it - it denotes the execution **coming back** to the function at a later time after it has been registered as a callback or a handler, + + 2.3. the arrow is easy to type on most keyboard layouts – it is Right-Alt+I; in case of problems with typing the character can be always copied – handler functions do occur in the code rarely, + + 2.4. Zsh supports any string as a function name because absolutely any string can be a **file** name – if there would be an exception in the name of the call-ables, then how would it be possible to run a script called "→abcd"? There are **no** exceptions, the function can be called even as a sequence of null bytes: + + ```shell showLineNumbers + ❯ $'\0'() { print hello } + ❯ $'\0' + hello + ``` + +3. `+`: for output functions, i.e.: for functions that print to the standard output and error or a log, etc. Example function name: `+prompt_zinc_output_segment`. + +4. `/`: for debugging functions, i.e: for functions that output debugs messages to the screen or a log or e.g.: gather some debug data. **Note:** the slash makes it impossible for such functions to be auto-loaded via the `autoload` mechanism. It is somewhat risky to assume, that this will never be needed for the functions, however, the limited number of available ASCII characters justifies such allocation. Example function name: `/prompt_zinc_dmsg`. + +5. `@`: for API-like functions, i.e: for functions that are on a boundary to a subsystem and expose their functionality through a well-defined, generally fixed interface. For example, this plugin standard [defines](#update-register-call) the function `@zsh-plugin-run-on-update`, which is exposing a plugin manager’s functionality in a well-defined way. + +## Example code utilizing the prefixes + +```shell showLineNumbers +.zinc_register_hooks() { + add-zsh-hook precmd :zinc_precmd + /zinc_dmsg "Installed precmd hook with the result: $?" + @zsh-plugin-run-on-unload "add-zsh-hook -d precmd :zinc_precmd" + +zinc_print "Zinc initialization complete" +} +``` + +## Preventing function pollution + +When writing a larger autoload function, it very often is the case that the function contains definitions of other functions. + +When the main function finishes executing, the functions are left defined. This might be undesired, e.g.: because of the command namespace pollution. + +The following snippet of code, when added at the beginning of the main function will automatically unset the sub-functions when leaving the main function to don't leak any functions into the global namespace: + +```shell showLineNumbers +typeset -g prjef +prjef=( ${(k)functions} ) +trap "unset -f -- \"\${(k)functions[@]:|prjef}\" &>/dev/null; unset prjef" EXIT +trap "unset -f -- \"\${(k)functions[@]:|prjef}\" &>/dev/null; unset prjef; return 1" INT +``` + +Replace the `prj*` prefix with your project name, e.g.: `rustef` for a `rust`-related plugin. The `*ef` stands for "entry functions". The snippet works as follows: + +1. The line `prjef=( ${(k)functions} )` remembers all the functions that are currently defined – which means that the list excludes the functions that are to be yet defined by the body of the main function. + +2. The code `unset -f — "${(k)functions[@]:|prjef}"` first does a subtraction of array contents – the `:|` substitution operator – of the functions that are defined at the moment of leaving of the function (the `trap`-s invoke the code at this moment) with the list of functions from the start of the main function – the ones stored in the variables `$prjef`. + +3. It then unsets the resulting list of the functions – being only the newly defined functions in the main function – by passing it to `unset -f …`. This way the functions defined by the body of the main (most often an autoload) function will be only set during the execution of the function. + +## Preventing parameter pollution + +When writing a plugin one often needs to keep a state during the Zsh session. To do this it is natural to use global parameters. However, when the number of the parameters grows one might want to limit it. + +With the following method, only a single global parameter per plugin can be sufficient: + +```shell showLineNumbers +typeset -A PlgMap +typeset -A SomeMap +typeset -a some_array + +PlgMap[state]=1 +SomeMap[state]=1 +some_array[1]=state +``` + +can be converted into: + +```shell showLineNumbers +typeset -A PlgMap + +PlgMap[state]=1 +PlgMap[SomeMap__state]=1 +PlgMap[some_array__1]=state +``` + +The use of this method is very unproblematic. The author reduced the number of global parameters in one of the projects by 21 by using an automatic conversion with Vim substitution patterns with back references without any problems. + +Following the [Standard Plugins Hash](#standard-plugins-hash) section, the plugin could even use a common hash name – `Plugins` – to lower the pollution even more. + + + + + + + +[zi]: https://github.com/z-shell/zi + +[comparison]: https://www.zsh.org/mla/workers/2017/msg01827.html + +[romkatv/powerlevel10k is using]: https://github.com/romkatv/powerlevel10k/blob/f17081ca/internal/p10k.zsh#L5390 + +[gitstatus]: https://github.com/romkatv/gitstatus + +[agkozak/agkozak-zsh-prompt is using]: https://github.com/agkozak/agkozak-zsh-prompt/blob/ed228952d68fea6d5cad3beee869167f76c59606/agkozak-zsh-prompt.plugin.zsh#L992-L1039 + +[agkozak/zsh-z is using]: https://github.com/agkozak/zsh-z/blob/16fba5e9d5c4b650358d65e07609dda4947f97e8/zsh-z.plugin.zsh#L680-L698 + +[agkozak/zhooks is using]: https://github.com/agkozak/zhooks/blob/628e1e3b8373bf31c26cb154f71c16ebe9d13b51/zhooks.plugin.zsh#L75-L82 + +[tj/git-extras]: https://github.com/tj/git-extras + +[zsh-workers post]: https://www.zsh.org/mla/workers/2011/msg01050.html + +[autoloading-functions]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Autoloading-Functions + +[special-widgets]: https://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Special-Widgets + +[hook-functions]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Hook-Functions + +[options]: https://zsh.sourceforge.io/Doc/Release/Options.html diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx new file mode 100644 index 00000000..018132a5 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/03_zsh_native_scripting_handbook.mdx @@ -0,0 +1,330 @@ +--- +id: zsh_handbook +title: 🔤 Zsh Native Scripting Handbook +sidebar_position: 3 +image: /img/png/theme/z/320x320.png +keywords: + - zsh-handbook +--- + + + +import ReadINIExample from "@site/src/components/Markdown/_read_ini_example.mdx"; + +## Information + +### @ is about keeping array form + +How do access all array elements in a shell? The standard answer: `use @ subscript`, i.e. `${array[@]}`. However, this is the Bash & Ksh way (and with the option `KSH_ARRAYS`, Zsh also works this way, i.e. needs `@` to access the whole array). Z shell **is different**: it is a `$array` that refers to all elements anyway. There is no need for the `@` subscript. + +So what use has `@` in the Zsh-world? It is: "`keep array form`" or "`do not join`". When is it activated? When the user quotes the array, i.e. invokes `"$array"`, he induces _joining_ of all array elements (into a single string). `@` is to have elements still quoted (so empty elements are preserved), but not joined. + +Two forms are available, `"$array[@]"` and `"${(@)array}"`. The first form has an additional effect – when an option `KSH_ARRAYS` is set, it indeed induces referencing to the whole array instead of a first element only. It should then use braces, i.e. `${array[@]}`, `"${array[@]}"` (`KSH_ARRAYS` requirement). + +In practice, if you'll use `@` as a subscript – `[@]`, not as a flag – `${(@)...}`, then you'll make the code `KSH_ARRAYS`-compatible. + +### extended_glob + +Glob-flags `#b` and `#m` require `setopt extended_glob`. Patterns utilizing `~` and `^` also require it. Extended-glob is one of the main features of Zsh. + +## Constructs + +### Reading a file + +```shell showLineNumbers +typeset -a lines +lines=( "${(@f)"$( 0 ? b : c ))`. The flexibility of Zsh allows such expressions also in a normal context. Above is an example. `:+` is "if not empty, substitute …" `:-` is "if empty, substitute …". You can save a great number of lines of code with those substitutions, it's normally at least 4-lines `if` condition or lengthy `&&`/`||` use. + +### Ternary expressions with `:#` substitution + +```shell showLineNumbers +var=abc; print ${${${(M)var:#abc}:+is abc}:-not abc} → is abc +var=abcd; print ${${${(M)var:#abc}:+is abc}:-not abc} → not abc +``` + +A one-line "if var = x, then …, else …". Again, can spare a great amount of boring code that makes a 10-line function a 20-line one. + +### Using built-in regular expressions engine + +```shell +[[ "aabbb" = (#b)(a##)*(b(#c2,2)) ]] && print ${match[1]}-${match[2]} → aa-bb +``` + +`\##` is: "1 or more". `(#c2,2)` is: "exactly 2". A few other constructs: `#` is "0 or more", `?` is "any character", `(a|b|)` is "a or b or empty match". `#b` enables the `$match` parameters. There's also `#m` but it has one parameter `$MATCH` for whole matched text, not for any parenthesis. + +Zsh patterns are a custom regular expressions engine. They are slightly faster than the `zsh/regex` module (used for the `=~` operator) and don't have that dependency (regex module can be not present, e.g. in the default static build of Zsh). Also, they can be used in substitutions, for example in the `//` substitution. + +### Skipping uniq + +```shell showLineNumbers +typeset -aU array; array=( a a b ); print $array → a b +typeset -a array; array=( a a b ); print ${(u)array} → a b +``` + +Enable the `-U` flag for the array so that it guards elements to be unique, or use the `u`-flag to make unique elements of an array. + +### Skipping awk + +```shell showLineNumbers +typeset -a list; list=( "a,b,c,1,e" "p,q,r,2,t" ); +print "${list[@]/(#b)([^,]##,)(#c3,3)([^,]##)*/${match[2]}}" → 1 2 +``` + +The pattern specifies 3 blocks of `[^,]##,` so 3 "not-comma multiple times, then comma", then the single block of "not-comma multiple times" in second parentheses -- and then replaces this with second parentheses. The result is the 4th column extracted from multiple lines of text, something `awk` is often used for. Another method is the use of the `s`-flag. For a single line of text: + +```shell +text="a,b,c,1,e"; print ${${(s:,:)text}[4]} → 1 +``` + +Thanks to in-substitution code-execution capabilities it's possible to use the `s`-flag to apply it to multiple lines: + +```shell showLineNumbers +typeset -a list; list=( "a,b,c,1,e" "p,q,r,2,t" ); +print "${list[@]/(#m)*/${${(s:,:)MATCH}[4]}}" → 1 2 +``` + +There is a problem with the `(s::)` flag that can be solved if Zsh is version `5.4` or higher: if there will be single input column, e.g. `list=( "column1" "a,b")` instead of two or more columns (i.e. `list=( "column1,column2" "a,b" )`), then `(s::)` will return **string** instead of 1-element **array**. So the index `[4]` in the above snippet will index a string, and show its 4th letter. Starting with Zsh 5.4, thanks to a patch by Bart Schaefer (`40640: the (A) parameter flag forces array result even if...`), it is possible to force **array**-kind of result even for a single column, by adding `(A)` flag, i.e.: + +```shell showLineNumbers +typeset -a list; list=( "a,b,c,1,e" "p,q,r,2,t" "column1" ); +print "${list[@]/(#m)*/${${(As:,:)MATCH}[4]}}" → 1 2 +print "${list[@]/(#m)*/${${(s:,:)MATCH}[4]}}" → 1 2 u +``` + +Side-note: `(A)` flag is often used together with the `::=` assignment-substitution and `(P)` flag, to assign arrays and hashes by name. + +### Searching arrays + +```shell showLineNumbers +typeset -a array; array=( a b " c1" d ); print ${array[(r)[[:space:]][[:alpha:]]*]} → c1 +``` + +`\[[:space:]]` contains unicode spaces. This is often used in conditional expression like `[[ -z ${array[(r)...]} ]]`. + +Note that [Skipping grep](#skipping-grep) that uses `:#` substitution can also be used to search arrays. + +### Code execution in `//` substitution + +```shell showLineNumbers +append() { gathered+=( $array[$1] ); } +functions -M append 1 1 append +typeset -a array; array=( "Value 1" "Other data" "Value 2" ) +typeset -a gathered; integer idx=0 +: ${array[@]/(#b)(Value ([[:digit:]]##)|*)/$(( ${#match[2]} > 0 ? append(++idx) : ++idx ))} +print $gathered → Value 1 Value 2 +``` + +Use of the `#b` glob flag enables math-code execution (and not only) in `/` and `//` substitutions. Implementation is very fast. + +### Serializing data + +```shell showLineNumbers +typeset -A hsh deserialized; hsh=( key value ) +serialized="${(j: :)${(qkv@)hsh}}" +deserialized=( "${(Q@)${(z@)serialized}}" ) +print ${(kv)deserialized} → key value +``` + +`j`-flag means join -- by spaces, in this case. Flags `kv` mean keys and values, interleaving. Important `q`-flag means: quote. So what is obtained is each key and value quoted, and put into a string separated by spaces. + +`z`-flag means: split as if Zsh parser would split. So quoting (with backslashes, double quoting, and others) is recognized. Obtained is array `( "key" "value")` which is then de-quoted with `Q`-flag. This yields original data, assigned to the hash `deserialized`. Use this to e.g. implement an array of hashes. + +Note: to be compatible with `setopt ksharrays`, use `[@]` instead of `(@)`, e.g.: `...( "${(Q)${(z)serialized[@]}[@]}" )` + +#### Tip: serializing with Bash + +```shell showLineNumbers +array=( key1 key2 ) +printf -v serialized "%q " "${array[@]}" +eval "deserialized=($serialized)" +``` + +This method works also with Zsh. The drawback is the use of `eval`, however, no problem may occur unless someone compromises the variable's value, but as always, `eval` should be avoided if possible. + +## Real-world examples + +### Testing for Git subcommand + +Following code checks, if there is a `git` subcommand `$mysub`: + +```shell +if git help -a | grep "^ [a-z]" | tr ' ' '\n' | grep -x $mysub > /dev/null > /dev/null; then +``` + +Those are `4` forks. The code can be replaced according to this guide: + +```shell showLineNumbers +local -a lines_list +lines_list=( ${(f)"$(git help -a)"} ) +lines_list=( ${(M)${(s: :)${(M)lines_list:# [a-z]*}}:#$mysub} ) +if (( ${#lines_list} > 0 )); then + … +fi +``` + +The result is just `1` fork. + +### Counting unquoted-only apostrophes + +A project was needing this to do some Zle line-continuation tricks (when you put a backslash-\\ at the end of the line and press enters – it is the line continuation that occurs at that moment). + +The required functionality is: in the given string, count the number of apostrophes, but _only the unquoted ones_. This means that only apostrophes with null or an even number of preceding backslashes should be accepted into the count: + +```shell showLineNumbers +buf="word'continue\'after\\\'afterSecnd\\''afterPair" +integer count=0 +: ${buf//(#b)((#s)|[^\\])([\\][\\])#(\'\'#)/$(( count += ${#match[3]} ))} +echo $count → 3 +``` + +The answer (i.e. the output) to the above presentation and example is: `3` (there are `3` unquoted apostrophes in total in the string kept in the variable `$buf`). + +Below follows a variation of the above snippet that doesn't use math-code execution: + +```shell showLineNumbers +buf="word'continue\'after\\\'afterSecnd\\''afterPair" +buf="${(S)buf//(#b)*((#s)|[^\\])([\\][\\])#(\'\'#)*/${match[3]}}"; buf=${buf%%[^\']##} +integer count=${#buf} +echo $count → 3 +``` + +This is possible thanks to `(S)` flag – non-greedy matching, `([\\][\\])#` trick – it matches only unquoted following `(\'\'##)` characters (which are the apostrophes) and a general strategy to replace `anything-apostrope(s)` (unquoted ones) with `the-apostrope(s)` (and then count them with `${#buf}`). + +## Tips and Tricks + +### Parsing INI file + +With Zshell `extended_glob` parsing an `ini` file is an easy task. It will not result in a nested-arrays data structure (Zsh doesn't support nested hashes), but the hash keys are intuitive such as `$DB_CONF[db1__host]`. + +The code should be placed in a file named `read-ini-file`, in `$fpath`, and `autoload read-ini-file` should be invoked. + + diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/99_contributors.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/99_contributors.mdx new file mode 100644 index 00000000..d2727e6f --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/99_contributors.mdx @@ -0,0 +1,267 @@ +--- +id: contributors +title: '🏆 Contributors' +sidebar_position: 4 +image: /img/png/theme/z/320x320.png +hide_title: false +hide_table_of_contents: false +description: Project contributors +keywords: + - contributors +draft: false +slug: contributors +--- + +import Link from "@docusaurus/Link"; +import Image from "@theme/IdealImage"; +import useBaseUrl from "@docusaurus/useBaseUrl"; +import ThemedImage from "@theme/ThemedImage"; + +```mdx-code-block + +``` + +Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated, our target support each other, and the projects we love . + +> To participate or support the project consider joining , translating , and sharing . + +## General + +```mdx-code-block + + + + + + + + + + + +
+ + +
+ Salvydas Lukosius + + 		+ + +
+ onokatio + + 		+ + +
+ Omelet + + 		+ + +
+ Sai + + 		+ + +
+ William Cooper + + 		+ + +
+ Farzat07 + +
+``` + +## Content + +```mdx-code-block + + + + + + + + + +
+ + +
+ Sebastian + + 		+ + +
+ Callista Chang + + 		+ + +
+ signed-log + + 		+ + +
+ 0xMRTT + +
+``` + +## Translations + +```mdx-code-block + + + + + + + + + + + +
+ + +
+ Colerar + + 		+ + +
+ Dongsen + + 		+ + +
+ nakayama900 + + 		+ + +
+ awarewen + + 		+ + +
+ Kazuma Miebori + + 		+ + +
+ syrinka + +
+``` + +## Participation + +```mdx-code-block + + + + + + + + +
+ + +
+ Benoit de Chezelles + + 		+ + +
+ Caleb Cushing + + 		+ + +
+ Kritiqual + +
+``` + + diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/_category_.json new file mode 100644 index 00000000..bb460971 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "👥 社区文档", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/index.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/index.mdx new file mode 100644 index 00000000..b7fac5c6 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-community/current/index.mdx @@ -0,0 +1,30 @@ +--- +id: 社区 +slug: / +title: 👥 社区文档 +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +keywords: + - documentation + - zsh-lovers + - 社区 + - gallery +--- + + + +```mdx-code-block +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +
+ +
+``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current.json new file mode 100644 index 00000000..94627c3c --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current.json @@ -0,0 +1,18 @@ +{ + "version.label": { + "message": "下一页", + "description": "The label for version current" + }, + "sidebar.SideBar.category.🌀 Annexes": { + "message": "🌀 附件", + "description": "The label for category 🌀 Annexes in sidebar SideBar" + }, + "sidebar.SideBar.category.📦 Packages": { + "message": "📦 软件包", + "description": "The label for category 📦 Packages in sidebar SideBar" + }, + "sidebar.SideBar.category.⚙️ Plugins": { + "message": "⚙️ Plugins", + "description": "The label for category ⚙️ Plugins in sidebar SideBar" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/_category_.json new file mode 100644 index 00000000..dfb962cc --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "🌐 生态系统", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx new file mode 100644 index 00000000..0365775f --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/0_overview.mdx @@ -0,0 +1,169 @@ +--- +id: overview +title: 🌀 What can Annexes do? +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: Annex Introduction +keywords: + - annex + - overview +--- + + + +1. Add a new Zi subcommand (i.e. the [command][command] that’s placed after the function `zi …` when calling Zi). + +2. Add new [ice-modifiers][ice-modifiers]. + +3. Register four types of hooks: + + 3.1. `atclone` hook – run after cloning any plugin or downloading any snippet. + + 3.2. `atpull` hook – run after pulling new commits (i.e. updating) for any plugin/snippet. + + 3.3. `atinit` hook – run before loading any plugin/snippet, after it has been set up (i.e. downloaded). + + 3.4. `atload` hook – run after loading any plugin/snippet. + +4. Register hooks for generating help text, shown by the `zi icemods` subcommand. + +## Recommended annexes + +### Common + +1. [z-a-bin-gem-node][bin-gem-node] +2. [z-a-readurl][readurl] +3. [z-a-patch-dl][patch-dl] +4. [z-a-rust][rust] + +### Additional + +1. [z-a-submods][submods] +2. [z-a-unscope][unscope] +3. [z-a-test][test] + +:::tip + +Use [meta-plugins](/ecosystem/annexes/meta-plugins) to install common annexes as a group: + +```shell +zi light-mode for z-shell/z-a-meta-plugins @annexes +``` + +To install common and additional annexes: + +```shell +zi light-mode for z-shell/z-a-meta-plugins @annexes+rec +``` + +::: + +## How to code them? + +Below is an example body of an `atclone` hook taken from [submods][submods] annex. + +It shows how to: + +1. Obtain the arguments passed to the hook. +2. Use an [ice-modifier][ice-modifiers]. +3. It also shows a useful snippet that will trim the whitespace in array elements (see `# (4) …` in the code). +4. Utilize the last hook argument – the plugin’s/snippet’s containing directory. + +```shell showLineNumbers +emulate -L zsh -o extended_glob -o warn_create_global -o typeset_silent + +[[ -z "${ZI_ICE[submods]}" ]] && return 0 + +# (1) – get arguments +[[ "$1" = plugin ]] && \ +local type="$1" user="$2" plugin="$3" id_as="$4" dir="$5" hook="$6" || \ +local type="$1" url="$2" id_as="$3" dir="$4" hook="$6" # type: snippet + +# (2) – we're interested only in plugins/snippets +# which have the submods'' ice in their load command +[[ -z ${ZI_ICE[submods]} ]] && return 0 + +local -a mods parts +local mod from + +# (3) – process the submods'' ice +mods=( ${(@s.;.)ZI_ICE[submods]} ) +for mod in "${mods[@]}"; do + parts=( "${(@s:->:)mod}" ) + # (4) Remove only leading and trailing whitespace + parts=( "${parts[@]//((#s)[[:space:]]##|[[:space:]]##(#e))/}" ) + + print "\nCloning submodule: ${parts[1]} to dir: ${parts[2]}" + from="https://github.com" + parts[1]="${from}/${parts[1]}" + # (5) – the use of the input argument: `$dir' + command git -C "$dir" clone --progress "${parts[1]}" "${parts[2]}" +done +``` + +The recommended method of creating a hook is to place its body into a file that starts with a right arrow `→` ([more information][the-proposed-function-name-prefixes], and also a `za-` prefix, e.g. `→za-myproject-atclone-hook` and then to mark it for autoloading via `autoload -Uz →za-myproject-atclone-hook`. Then register the hook, presumably in the `myproject.plugin.zsh` file, with the API call: + +`@zi-register-annex`: + +```shell showLineNumbers +@zi-register-annex myproject hook:atclone \ + →za-myproject-atclone-handler \ + →za-myproject-atclone-help-handler \ + "submods''" # register a new ice-modifier: submods'' +``` + +The general syntax of the API call is: + +```shell showLineNumbers +@zi-register-annex {project-name} \ + {hook: \ + {name-of-the-handler-function} \ + {name-of-the-HELP-handler-function} \ + "{ice-mod1}|{ice-mod2}|…" < hook-type >| subcommand: < new-subcommand-name > } +``` + +The last argument, i.e. the `|`-separated ice list, is optional. That’s all! After this loading the plugin `myproject` will set up the new [ice-modifier][ice-modifiers] `submods` that will have syntax `submods'{user}/{plugin} –> {output-dir}; …'` and will clone submodules when installing the original plugin or snippet! + +Example of the [submods][submods] ice-modifier to load the `zsh-autosuggestions` plugin via the Prezto module: `autosuggestions`: + +```shell showLineNumbers +zi ice svn submods'zsh-users/zsh-autosuggestions -> external' +zi snippet PZT::modules/autosuggestions +``` + +Check out the project which fully implements this idea, [z-a-submods][submods]. It e.g. also implements the `atpull` hook, i.e. supports the automatic update of the submodules. The `z-a-*` prefix is recommended for projects which indicate annexes. + +## 摘要 + +There are 2 or 3 subtypes for each of the hooks: + +1. `atinit` or `!atinit` – the `!` version is run before the `atinit` ice-modifier (i.e. before `zi ice atinit'echo this!'; …`), while the normal version runs after it. +2. `atload` or `!atload` – analogous to the `atinit` case: the `!` version runs before the `atload` ice-modifier (while the normal version runs after it). +3. `atclone` or `!atclone` – analogous to the `atinit` and `atload` cases. +4. `atpull`, `!atpull`, or `%atpull` – the first two are being run **only when there are new commits to be downloaded** during the update. The `%` version is being **always** run, regardless of whether the update will pull any actual commits or not, and it is being run **after** the `atpull` ice-modifier. + + + + + +[command]: /docs/guides/commands + +[ice-modifiers]: /docs/guides/syntax/ice-modifiers + +[the-proposed-function-name-prefixes]: /community/zsh_plugin_standard#the-proposed-function-name-prefixes + + + +[bin-gem-node]: https://github.com/z-shell/z-a-bin-gem-node + +[patch-dl]: https://github.com/z-shell/z-a-patch-dl + +[readurl]: https://github.com/z-shell/z-a-readurl + +[rust]: https://github.com/z-shell/z-a-rust + +[submods]: https://github.com/z-shell/z-a-submods + +[test]: https://github.com/z-shell/z-a-test + +[unscope]: https://github.com/z-shell/z-a-unscope diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx new file mode 100644 index 00000000..654a1f65 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/19_eval.mdx @@ -0,0 +1,125 @@ +--- +id: eval +title: 🌀 Eval +image: /img/png/theme/z/320x320.png +description: Annex - Eval documentation. +keywords: + - annex + - eval +draft: false +--- + + + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +The output of a slow initialization command is redirected to a file located within the plugin or snippets directory and sourced while loading. The next time the plugin or snippet is loaded, this file will be sourced skipping the need to run the initialization command. + +The ice-modifier `eval'…'` provided and handled by this annex creates a `cache` in the plugin or snippets directory which stores the output of the command and the cache is regenerated when: + +1. The plugin or snippet is updated. +2. The cache file is removed. +3. When running `zi recache`. + +:::note + +The optional preceding `!` flag means to store command output regardless of exit code. Otherwise `eval'…'` will avoid caching the output of code which returns a non-zero exit code. + +::: + +## Example invocations + + + + +```shell showLineNumbers +zi ice as"command" from"gh-r" \ + atclone"./zoxide init --cmd x zsh > init.zsh" \ + atpull"%atclone" src"init.zsh" nocompile'!' +zi light ajeetdsouza/zoxide +``` + +```shell showLineNumbers +zi ice atclone"dircolors -b LS_COLORS > init.zsh" \ + atpull"%atclone" pick"init.zsh" nocompile'!' \ + atload'zstyle ":completion:*" list-colors ${(s.:.)LS_COLORS}' +zi light trapd00r/LS_COLORS +``` + + + + +```shell {2} showLineNumbers +zi ice as"command" from"gh-r" \ + eval"./zoxide init --cmd x zsh" +zi light ajeetdsouza/zoxide +``` + +```shell {1} showLineNumbers +zi ice eval"dircolors -b LS_COLORS" \ + atload'zstyle ":completion:*" list-colors ${(s.:.)LS_COLORS}' +zi light trapd00r/LS_COLORS +``` + + + + + + +```shell showLineNumbers +if [[ "${+commands[kubectl]}" == 1 ]]; then + eval $(kubectl completion zsh) +fi +``` + + + + +```shell {2} showLineNumbers +zi ice id-as"kubectl_completion" has"kubectl" \ + eval"kubectl completion zsh" run-atpull +zi light z-shell/null +``` + + + + +## Install eval {#install-eval} + +:::info Source + +- + z-shell/z-a-eval + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-eval +``` + + + + +Add the following snippet in the `.zshrc` file: + +> Set value `Z_A_USECOMP=1` to enable TAB completion for subcommand `recache`. + +```shell showLineNumbers +zi ice atinit'Z_A_USECOMP=1' +zi light z-shell/z-a-eval +``` + + + + +This will register subcommand `recache` and `eval'…'` ice-modifier. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx new file mode 100644 index 00000000..f2b312b9 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/1_bin_gem_node.mdx @@ -0,0 +1,568 @@ +--- +id: bin-gem-node +title: 🌀 Bin Gem Node +image: /img/png/theme/z/320x320.png +description: Annex - Bin Gem Node documentation. +keywords: + - annex, + - bin-gem-node +--- + + + +import Tabs from "@theme/Tabs"; +import Link from "@docusaurus/Link"; +import TabItem from "@theme/TabItem"; +import Player from "@site/src/components/Player"; +import APITable from "@site/src/components/APITable"; +import Shortcuts from "@site/src/components/Markdown/_player_shortcuts.mdx"; + +An annex provides the following functionality: + +1. Run programs and scripts without adding anything to `$PATH`, +2. Install: [Ruby Gems][rubygems], [Node][node], and [Python][python] modules, with automatically set: + - [$GEM_HOME][gem-home] + - [$NODE_PATH][node-path] + - [$VIRTUALENV][virtualenv] +3. Run programs, scripts, and functions with automatic `cd` into the plugin or snippet directory, plus also with automatic standard output & standard error redirecting. +4. Source scripts through an automatically created function with the above `$GEM_HOME`, `$NODE_PATH`, `$VIRTUALENV`, and `cd` features available, +5. Create the so-called `shims` known from [rbenv][rbenv/rbenv] – the same feature as the first item of this enumeration – of running a program without adding anything to `$PATH` with all of the above features, however through an automatic **script** created in `$ZPFX/bin`, not a **function** (the first item uses a function-based mechanism), +6. Automatic updates of Ruby gems and Node modules during regular plugin and snippet updates with `zi update …`. + +The [sbin](#sbin-1) ice-modifier that creates forwarder-scripts instead of forwarder-functions created by the [fbin](#fbin-1) ice-modifier turned out to be the proper, best method for exposing binary programs and scripts. This way there is no need to add anything to `$PATH` – `z-a-bin-gem-node` will automatically create a function that will wrap the binary and provide it on the command line as if it was being placed in the `$PATH`. + +As previously mentioned, the function can automatically export `$GEM_HOME`, `$NODE_PATH`, `$VIRTUALENV` shell variables and also automatically cd into the plugin or snippet directory right before executing the binary and then cd back to the original directory after the execution is finished. As previously mentioned, instead of the function an automatically created script – the so-called `shim` – can be used for the same purpose and with the same functionality, so that the command is accessible practically fully normally – not only in the live Zsh session, only within which the functions created by [fbin](#fbin-1) exist, but also from any Zsh script. + +Suppose that we want to install the `junegunn/fzf` plugin from GitHub Releases, which contains only a single file – the `fzf` binary for the selected architecture. It is possible to do it in the standard way – by adding the plugin's directory to the `$PATH`. + +```shell +zi ice as'program' from'gh-r' +zi load junegunn/fzf +``` + +After this command, the `$PATH` variable will contain e.g.: + +```shell title="print $PATH" showLineNumbers +/home/sall/.zi/plugins/junegunn---fzf:/bin:/usr/bin:/usr/sbin:/sbin +``` + +For many such programs loaded as plugins, the PATH can become quite cluttered. I've had 26 entries before switching to `z-a-bin-gem-node`. To solve this, load with the use of [sbin](#sbin-1) ice-modifier provided and handled by `z-a-bin-gem-node`: + +```shell showLineNumbers +zi ice as'program' from'gh-r' sbin'fzf' +zi load junegunn/fzf +``` + +The `$PATH` will remain unchanged and a forwarder-script of `fzf` shim will be created in `$ZPFX/bin` (`~/.zi/polaris/bin` by default), which is being already added to the `$PATH` by Zi when it is being sourced: + +```shell title="cat $ZPFX/bin/fzf" showLineNumbers +#!/usr/bin/env zsh + +function fzf { + local bindir="/home/sall/.zi/plugins/junegunn---fzf" + "$bindir"/"fzf" "$@" +} + +fzf "$@" +``` + +Running the script will forward the call to the program accessed through an embedded path to it. Thus, no `$PATH` changes are needed. + +```mdx-code-block + +``` + +| Ice modifier | Description | +| :-------------- | :--------------------------------------------------------------------------------------------------------- | +| [sbin](#sbin-1) | Creates `shims` for binaries and scripts. | +| [fbin](#fbin-2) | Creates functions for binaries and scripts. | +| [gem](#gem-3) | Installs and updates gems + creates functions for gems binaries. | +| [node](#node-4) | Installs and updates node_modules + creates functions for binaries of the modules. | +| [pip](#pip-5) | Installs and updates python packages into a `virtualenv` + creates functions for binaries of the packages. | +| [fmod](#fmod-6) | Creates wrapping functions for other functions. | +| [fsrc](#fsrc-7) | Creates functions that source given scripts. | +| [ferc](#ferc-8) | The same as [fsrc](#fscr-7), but using an alternate script-loading method. | + +```mdx-code-block + +``` + +Function wrappers for binaries, scripts, gems, node_modules, python packages, etc: + +```mdx-code-block + +``` + +| Flag | Description | +| :--- | :-------------------------------------------------------------------------------------------------------------------- | +| `g` | Set `$GEM_HOME` variable to `{plugin-dir}`. | +| `n` | Set `$NODE_PATH` variable to `{plugin-dir}/node_modules`. | +| `p` | Set `$VIRTUALENV` variable to `{plugin-dir}/venv`. | +| `c` | `cd` to the plugin's directory before running the program and then cd back after it has been run. | +| `N` | Append `&>/dev/null` to the call of the binary, i.e. redirect both standard output and standard error to `/dev/null`. | +| `E` | Append `2>/dev/null` to the call of the binary, i.e. redirect standard error to `/dev/null`. | +| `O` | Append `>/dev/null` to the call of the binary, i.e. redirect standard output to `/dev/null`. | + +```mdx-code-block + +``` + +View all currently registered: + +- ice-modifiers: `zi icemods` +- subcommand: `zi subcmds` + +## `SBIN'…'` {#sbin-1} + +```shell +sbin'[{g|n|c|N|E|O}:]{path-to-binary}[ -> {name-of-the-script}]; …' +``` + +Creates the so-called `shim` known from `rbenv` – a wrapper script that forwards the call to the actual binary. The script is created always under the same, standard, and single `$PATH` entry: `$ZPFX/bin` (which is `~/.zi/polaris/bin` by default). The flags have the same meaning as with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice as'program' from'gh-r' sbin'fzf' +zi load junegunn/fzf +``` + +```shell title="cat $ZPFX/bin/fzf" showLineNumbers +#!/usr/bin/env zsh + +function fzf { + local bindir="/home/sall/.zi/plugins/junegunn---fzf" + local -xU PATH="$bindir":"$PATH" + "$bindir"/"fzf" "$@" +} + +fzf "$@" +``` + +:::note + +- as'program' (an alias: as'command') - used for the plugin to be added to $PATH when a plugin is not a file for sourcing. + +The [sbin](#sbin-1) ice-modifier can be empty, it will then try to create the shim for the trailing component of the [id-as][] ice, e.g.: + +- `id_as'exts/git-my'` → it'll check if a file `git-my` exists and if yes, will create the function `git-my`. +- `paulirish/git-open` → it'll check if a file `git-open` exists and if yes, will create the function `git-open`. + +The same trailing component would be set for the snippet URL, for any alphabetically first and executable file. + +::: + +## `FBIN'…'` {#fbin-2} + +```shell +fbin'[{g|n|c|N|E|O}:]{path-to-binary}[ -> {name-of-the-function}]; …' +``` + +Creates a wrapper function of the name the same as the last segment of the path or as `{name-of-the-function}`. + + + + + + + + + + +```shell showLineNumbers +zi ice from"gh-r" fbin"g:fzf -> myfzf" nocompile +zi load junegunn/fzf +``` + +```shell title="which myfzf" showLineNumbers +myfzf () { + local bindir="/home/sall/.zi/plugins/junegunn---fzf" + local -x GEM_HOME="/home/sall/.zi/plugins/junegunn---fzf" + local -xU PATH="/home/sall/.zi/plugins/junegunn---fzf"/bin:"$bindir":"$PATH" + "$bindir"/"fzf" "$@" +} +``` + +:::note + +- `nocompile` ice-modifier is used to skip file compilation when it is not required. + +::: + +## `GEM'…'` {#gem-3} + +```shell showLineNumbers +gem'{gem-name}; …' +gem'[{path-to-binary} <-] !{gem-name} [-> {name-of-the-function}]; …' +``` + +Installs the gem of name `{gem-name}` with `$GEM_HOME` set to the plugin's or snippet's directory. In other words, the gem and its dependencies will be installed locally in that directory. In the second form, it also creates a wrapper function identical to the one created with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice gem'!asciidoctor' id-as'asciidoctor' nocompile +zi load z-shell/0 +``` + +```shell title="which asciidoctor" showLineNumbers +asciidoctor () { + local bindir="/home/sall/.zi/plugins/asciidoctor/bin" + local -x GEM_HOME="/home/sall/.zi/plugins/asciidoctor" + local -xU PATH="/home/sall/.zi/plugins/asciidoctor"/bin:"$bindir":"$PATH" + "$bindir"/"asciidoctor" "$@" +} +``` + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `asciidoctor` gem. +- `id-as'asciidoctor'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `NODE'…'` {#node-4} + +```shell showLineNumbers +node'{node-module}; …' +node'[{path-to-binary} <-] !{node-module} [-> {name-of-the-function}]; …' +``` + +Installs the node module of name `{node-module}` inside the plugin's or snippet's directory. In the second form, it also creates a wrapper function identical to the one created with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice node'remark <- !remark-cli -> remark; remark-man' id-as'remark' nocompile +zi load z-shell/0 +``` + +```shell title="which remark" showLineNumbers +remark () { + local bindir="/home/sall/.zi/plugins/remark/node_modules/.bin" + local -x NODE_PATH="/home/sall/.zi/plugins/remark"/node_modules + local -xU PATH="/home/sall/.zi/plugins/remark"/node_modules/.bin:"$bindir":"$PATH" + "$bindir"/"remark" "$@" +} +``` + +In this case, the name of the binary program provided by the node module is different from its name, hence the second form with the `b <- a -> c` syntax has been used. + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `remark` Node module. +- `id-as'remark'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `PIP'…'` {#pip-5} + +```shell showLineNumbers +pip'{pip-package}; …' +pip'[{path-to-binary} <-] !{pip-package} [-> {name-of-the-function}]; …' +``` + +Installs the node module of name `{pip-package}` inside the plugin's or snippet's directory. In the second form, it also creates a wrapper function identical to the one created with `fbin'…'` ice. + + + + + + + + + + +```shell showLineNumbers +zi ice pip'youtube-dl <- !youtube-dl -> youtube-dl' id-as'youtube-dl' nocompile +zi load z-shell/0 +``` + +```shell title="which youtube-dl" showLineNumbers +youtube-dl () { + local bindir="/home/sall/.zi/plugins/youtube-dl/venv/bin" + local -x VIRTUALENV="/home/sall/.zi/plugins/youtube-dl"/venv + local -xU PATH="/home/sall/.zi/plugins/youtube-dl"/venv/bin:"$bindir":"$PATH" + "$bindir"/"youtube-dl" "$@" +} +``` + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `youtube-dl` pip package. +- `id-as'youtube-dl'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `FMOD'…'` {#fmod-6} + +```shell showLineNumbers +fmod'[{g|n|c|N|E|O}:]{function-name}; …' +fmod'[{g|n|c|N|E|O}:]{function-name} -> {wrapping-function-name}; …' +``` + +It wraps the given function with the ability to set `$GEM_HOME`, etc. – the meaning of the `g`, `n`, and `c` flags is the same as in the `fbin'…'` ice. + +Example: + + + + + + + + + + +```shell showLineNumbers +myfunc() { pwd; ls -1 }; zi ice fmod'cgn:myfunc' id-as'myfunc' nocompile +zi load z-shell/0 +``` + +```shell title="which myfunc" showLineNumbers +myfunc () { + local -x GEM_HOME="/home/sall/.zi/plugins/myfunc" + local -x NODE_PATH="/home/sall/.zi/plugins/myfunc"/node_modules + local oldpwd="/home/sall" + () { + setopt local_options no_auto_pushd + builtin cd -q "/home/sall/.zi/plugins/myfunc" + } + "myfunc--za-bgn-orig" "$@" + () { + builtin setopt local_options no_auto_pushd + builtin cd -q "$oldpwd" + } +} +``` + +```shell title="myfun" showLineNumbers +/home/sall/.zi/plugins/z-shell---0 +docs/ +LICENSE +README.md +``` + +:::note + +- `z-shell/0` - an empty repository to aid Zi's hooks, in this case, used to store the `myfunc` function files. +- `id-as'myfunc'` - used to assign a name instead of the `z-shell/0`. +- `nocompile` - used to skip file compilation when it is not required. + +::: + +## `FSCR'…'` {#fscr-7} + +```shell +fsrc'[{g|n|c|N|E|O}:]{path-to-script}[ -> {name-of-the-function}]; …' +``` + +## `FERC'…'` {#ferc-8} + +```shell +ferc'[{g|n|c|N|E|O}:]{path-to-script}[ -> {name-of-the-function}]; …' +``` + +Creates a wrapper function that at each invocation sources the given file. The second ice, `FERC'…'` works the same with the single difference that it uses `eval "$(<{path-to-script})"` instead of `source "{path-to-script}"` to load the script. + + + + + + + + + + +```shell showLineNumbers +zi ice fsrc"myscript -> myfunc" ferc"myscript" nocompile +zi load z-shell/0 +``` + +```shell title="which myfunc" showLineNumbers +myfunc () { + local bindir="/home/sall/.zi/plugins/z-shell---0" + local -xU PATH="$bindir":"$PATH" + () { + source "$bindir"/"myscript" + } "$@" +} +``` + +```shell title="which myscript" showLineNumbers +myscript () { + local bindir="/home/sall/.zi/plugins/z-shell---0" + local -xU PATH="$bindir":"$PATH" + () { + eval "$(<"$bindir"/"myscript")" + } "$@" +} +``` + +:::note + +- `nocompile` ice-modifier is used to skip file compilation when it is not required. + +The ices can be empty as the trailing component will be assigned with [id-as][] ice-modifier the same way as described in the [sbin](#sbin-1). + +::: + +## `shim-list` {#shim-list} + +An annex provides a subcommand – `shim-list` for shims currently stored in `$ZPFX/bin` management: + +Available flags are: + +```shell +zi shim-list [ -t | -i | -o | -s | -h ] +``` + +| Flag | Description | +| :----------------- | :--------------------------------------------------------------------------------------- | +| `-t` `--this-dir` | Instructs Zi to look for shims in the current directory instead of `$ZPFX/bin`. | +| `-i` `--from-ices` | Normally the code looks for the shim files by examining their contents (more info [^1]). | +| `-o` `--one-line` | Display the list of shim files without line breaks, in a single line, after spaces. | +| `-s` `--short` | Don't show the plugin/snippet that the shim belongs to. | +| `-h` `--help` | Shows usage information. | + +## Cygwin support {#cygwin-support} + +The [sbin](#sbin-1) ice-modifier has an explicit Cygwin support – it creates additional, **extra shim files** – Windows batch scripts that allow running the shielded applications from e.g.: Windows run dialog – if the `~/.zi/polaris/bin` directory is being added to the Windows `PATH` environment variable, for example (it is a good idea to do so, IMHO). The Windows shims have the same name as the standard ones (which are also being created, normally) plus the `.cmd` extension. You can test the feature by e.g.: installing Firefox from the Zi package via: + +```shell +zi pack=bgn for firefox +``` + +## Install bin-gem-node {#install-bin-gem-node} + +:::info Source + +- + z-shell/z-a-bin-gem-node + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-bin-gem-node +``` + + + + +Add the following snippet in the `.zshrc` file to install using the [unscope][] annex: + +```shell +zi light z-shell/z-a-unscope bgn +``` + + + + +This will register the [shim-list](#shim-list) subcommand and following ice-modifiers: + + + + + +[^1]: shims created by the `bin-gem-node` annex have a fixed structure, this option instructs Zi to show the list of shims that results from the [sbin](#sbin-1) ice-modifier of the loaded plugins. If a plugin for example has `sbin'git-open'`, means that such shim has already been created. + + + +[id-as]: /docs/guides/syntax/standard#id-as + +[unscope]: /ecosystem/annexes/unscope + + + +[gem-home]: https://guides.rubygems.org/command-reference/#gem-environment + +[node-path]: https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders + +[node]: https://github.com/npm/cli + +[python]: https://python.org + +[rbenv/rbenv]: https://github.com/rbenv/rbenv + +[rubygems]: https://github.com/rubygems/rubygems + +[virtualenv]: https://docs.python.org/3/tutorial/venv.html diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx new file mode 100644 index 00000000..0270e33f --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/20_test.mdx @@ -0,0 +1,52 @@ +--- +id: test +title: 🌀 Test +hide_title: false +hide_table_of_contents: false +image: /img/png/theme/z/320x320.png +description: Annex - Test documentation +keywords: + - annex + - test +draft: true +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import ImgShow from "@site/src/components/ImgShow"; + +An annex runs `zunit` and `make` tests if they are configured in the repository. + + + +Simply load it like any other plugin to make it active: + +```shell +zi light z-shell/z-a-test +``` + +
+ 📖 Configuration + +To run the tests in a verbose mode, issue: + +```shell +zstyle :zi:annex:test quiet 0 +``` + +To skip tests for a single plugin before installing or updating add the `notest` ice-modifier: + +```shell showLineNumbers +zi ice notest +zi load … +``` + +
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx new file mode 100644 index 00000000..8003a0d9 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/2_meta_plugins.mdx @@ -0,0 +1,243 @@ +--- +id: meta-plugins +title: 🌀 Meta Plugins +image: /img/png/theme/z/320x320.png +description: Annex meta-plugins documentation +keywords: + - annex + - meta-plugins +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import APITable from "@site/src/components/APITable"; + +An annex has the curated, optimal [ice-modifiers][] lists automatically applied. For more details refer to [z-a-meta-plugins.plugin.zsh][] file. + +:::tip + +- To create your group of plugins as meta-plugins propose them in a new [issue][issues/new] +- Prefix `@` used to avoid syntax conflicts, e.g: `zi light @` +- Before installing any plugin visit the original repository where available to verify that system is supported and meets other requirements + +::: + +## Usage of meta-plugins + +The following snippets are examples of how to install meta-plugins: + +```shell +zi light @annexes +``` + +```shell +zi light-mode for @annexes @zsh-users @console-tools +``` + +```shell showLineNumbers +zi light-mode for z-a-meta-plugins \ + @annexes @ext-git @zsh-users +``` + +```shell showLineNumbers +zi light-mode for @annexes \ + skip'zsh-completions' @zsh-users \ + skip'vivid exa tig' @console-tools +``` + +## Available meta-plugins + +```mdx-code-block + +``` + +| Meta-plugin name | Consisting plugins | +| ---------------- | --------------------------------------------------------------------------------------------------------------------- | +| @annexes | [bin-gem-node][], [readurl][], [patch-dl][], [rust][], [default-ice][], [unscope][] | +| @annexes+ | @annexes + [submods][], [test][] | +| @console-tools | [dircolors-material][] (package), [fd][], [bat][], [hexyl][], [hyperfine][], [vivid][], [exa][], [ripgrep][], [tig][] | +| @developer-tools | [color][], [revolver][], [zunit][], [gitignore.plugin.zsh][], [tig][] | +| @ext-git | [git-open][], [git-recent][], [git-my][], [git-quick-stats][], [git-now][], [git-extras][], [forgit][] | +| @fuzzy | [fzf][] (package), [fzy][] (package), [skim][], [peco][] | +| @fuzzy-src | fzf-go, [fzy][], skim-cargo, peco-go | +| @prezto | PZTM::archive, PZTM::directory, PZTM::utility | +| @py-utils | [pyenv][] (package) | +| @romkatv | [powerlevel10k][] | +| @rust-utils | rust-toolchain, cargo-extensions | +| @sharkdp | [fd][], [bat][], [hexyl][], [hyperfine][], [vivid][] | +| @z-shell | [F-Sy-H][], [H-S-MW][], [zsh-diff-so-fancy][] | +| @z-shell+ | [zsh-select][], [zconvey][], [zui][], [zflai][] | +| @zsh-users | [zsh-syntax-highlighting][], [zsh-autosuggestions][], [zsh-completions][] | +| @zsh-users+fast | [F-Sy-H][], [zsh-autosuggestions][], [zsh-completions][], [z-shell/zsh-fancy-completions][] | +| @zunit | [color][], [revolver][], [zunit][] | + +```mdx-code-block + +``` + +### Summary of the meta-plugins + +It consumes time to: + +- Constantly, over and over collect some new interesting plugins to install/load. +- Over and over reconstruct the new findings on the new machines. +- Constantly extend and tweak the ice list of each plugin, so that it's hard on the eyes, especially for an outsider. + +```mdx-code-block + +``` + +| Problem | Solution | +| :---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| (1) _finding new plugins_ | The annex contains a curated, broad list of plugins, e.g.: all the console tools like `fd`, `fzf`, `exa`, `ripgrep`, etc., | +| (2) _reconstructing the findings in new environments_ | It's easy to say and memorize e.g.: `zi for console-tools` – one label pulls a group of plugins and also the curated, optimal, default ice lists for each of them, | +| (3) _constant increase of complexity of the commands_ | The provided, hopefully, best/optimal ices for each plugin are handled transparently and automatically; care is given to each ice list so that the plugin loads without any glitches (e.g.: without the "No files for compilation found." message and other, even such slight issues). | + +```mdx-code-block + +``` + +Other unique benefits of the meta-plugins annex: + +```mdx-code-block + +``` + +| Benefit | Description | +| :---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Plugin dependencies | The meta-plugins implement a dependency mechanism: selecting a from-source built [ogham/exa][exa] will automatically pull in also the Rust compiler (available under the meta-plugin name: `rust-toolchain`). | +| Flexible disabling of chosen sub-plugins in any meta-plugin | A meta-plugin can contain many sub-plugins and it's possible to skip installing some of them by the **skip'plugin-1 plugin-2…'** ice, e.g.: `zi skip'ripgrep fd' for console-tools`. This way despite that some of the meta plugins are broad the user still has control over what's and how much is being installed. | +| Common from-source meta plugins | For the plugins that provide the binary programs it is often the case that a meta-plugin exists that'll build the program from the source (e.g.: **fuzzy** meta-plugin and its **fuzzy-src** counterpart). This might be handy e.g.: if there's no binary for our machine. | + +```mdx-code-block + +``` + +## Install meta-plugins {#install-meta-plugins} + +:::info Source + +- + z-shell/z-a-meta-plugins + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-meta-plugins +``` + + + + +This will register the `skip'…'` ice-modifier. + + + + + +[ice-modifiers]: /docs/guides/syntax/ice-modifiers + + + +[bat]: https://github.com/sharkdp/bat + +[bin-gem-node]: https://github.com/z-shell/z-a-bin-gem-node + +[color]: https://github.com/zdharma/color + +[default-ice]: https://github.com/z-shell/z-a-default-ice + +[dircolors-material]: https://github.com/z-shell/dircolors-material + +[exa]: https://github.com/ogham/exa + +[f-sy-h]: https://github.com/z-shell/F-Sy-H + +[fd]: https://github.com/sharkdp/fd + +[forgit]: https://github.com/wfxr/forgit + +[fzf]: https://github.com/z-shell/fzf + +[fzy]: https://github.com/z-shell/fzy + +[git-extras]: https://github.com/tj/git-extras + +[git-my]: https://github.com/davidosomething/git-my + +[git-now]: https://github.com/iwata/git-now + +[git-open]: https://github.com/paulirish/git-open + +[git-quick-stats]: https://github.com/arzzen/git-quick-stats + +[git-recent]: https://github.com/paulirish/git-recent + +[gitignore.plugin.zsh]: https://github.com/voronkovich/gitignore.plugin.zsh + +[h-s-mw]: https://github.com/z-shell/H-S-MW + +[hexyl]: https://github.com/sharkdp/hexyl + +[hyperfine]: https://github.com/sharkdp/hyperfine + +[issues/new]: https://github.com/z-shell/z-a-meta-plugins/issues/new + +[patch-dl]: https://github.com/z-shell/z-a-patch-dl + +[peco]: https://github.com/peco/peco + +[powerlevel10k]: https://github.com/romkatv/powerlevel10k + +[pyenv]: https://github.com/z-shell/pyenv + +[readurl]: https://github.com/z-shell/z-a-readurl + +[revolver]: https://github.com/zdharma/revolver + +[ripgrep]: https://github.com/BurntSushi/ripgrep + +[rust]: https://github.com/z-shell/z-a-rust + +[skim]: https://github.com/lotabout/skim + +[submods]: https://github.com/z-shell/z-a-submods + +[test]: https://github.com/z-shell/z-a-test + +[tig]: https://github.com/jonas/tig + +[unscope]: https://github.com/z-shell/z-a-unscope + +[vivid]: https://github.com/sharkdp/vivid + +[z-a-meta-plugins.plugin.zsh]: https://github.com/z-shell/z-a-meta-plugins/blob/main/z-a-meta-plugins.plugin.zsh + +[zconvey]: https://github.com/z-shell/zconvey + +[zflai]: https://github.com/z-shell/zflai + +[zsh-autosuggestions]: https://github.com/zsh-users/zsh-autosuggestions + +[zsh-completions]: https://github.com/zsh-users/zsh-completions + +[zsh-diff-so-fancy]: https://github.com/z-shell/zsh-diff-so-fancy + +[zsh-select]: https://github.com/z-shell/zsh-select + +[zsh-syntax-highlighting]: https://github.com/zsh-users/zsh-syntax-highlighting + +[zui]: https://github.com/z-shell/zui + +[zunit]: https://github.com/zdharma/zunit + +[z-shell/zsh-fancy-completions]: https://github.com/z-shell/zsh-fancy-completions diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx new file mode 100644 index 00000000..ae3f4e24 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/3_default_ice.mdx @@ -0,0 +1,76 @@ +--- +id: default-ice +title: 🌀 Default Ice +image: /img/png/theme/z/320x320.png +description: Annex - Default Ice documentation +keywords: + - annex + - default-ice +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex delivers the capability to set **default ices** for the next `zi` command, e.g: + +set default-ices: + +```shell +zi default-ice lucid from"gh-r" +``` + +this will download from GitHub releases (gh-r) and also use the lucid ice by default: + +```shell showLineNumbers +zi wait for \ + sbin junegunn/fzf-bin \ + sbin"**/pk" peco/peco +``` + +:::caution + +The `wait` ice cannot be made default by using this subcommand. + +::: + +## `default-ice` {#default-ice} + +An annex provides a subcommand – `default-ice` which has the following synopsis: + +```shell showLineNumbers +— default-ice [ -s | -c | -g | -t | -q | -h ] + + [ -s ] — Show currently set default ices + [ -c ] — Reset default ices + [ -g ] — Return current ices in REPLAY hash + [ -t ] — Show statistics + [ -q ] — Hide all messages + [ -h ] — This message +``` + +## Install default-ice {#install-default-ice} + +:::info Source + +- + z-shell/z-a-default-ice + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-default-ice +``` + + + + +This will register the [default-ice](#default-ice) subcommand. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx new file mode 100644 index 00000000..33efb751 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/4_patch-dl.mdx @@ -0,0 +1,72 @@ +--- +id: patch-dl +title: 🌀 Patch DL +image: /img/png/theme/z/320x320.png +description: Annex - Patch DL documentation +keywords: + - annex + - patch-dl +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import ImgShow from "@site/src/components/ImgShow"; + +An annex downloads files and applies patches and adds two ice-modifiers: + +first: + +```shell +zi ice dl'{URL} [-> {optional-output-file-name}]; …' … +``` + +second: + +```shell +zi ice patch'{file-name-with-the-patch-to-apply}; …' … +``` + +The annex will download the given `{URL}` under the path `{optional-output-file-name}` (if no file name given, then it is taken from last segment of the URL) in case of the `dl'…'` ice-modifier, and apply a patch given by the `{file-name-with-the-patch-to-apply}` in case of the `patch'…'` ice-modifier. You can use this functionality to download and apply patches. + +For example, to install `fbterm`, two patches are being needed, one to fix the operation, the other one to fix the build: + +```shell showLineNumbers +zi ice as"command" pick"$ZPFX/bin/fbterm" \ + dl"https://bugs.archlinux.org/task/46860?getfile=13513 -> ins.patch" \ + dl"https://aur.archlinux.org/cgit/aur.git/plain/0001-Fix-build-with-gcc-6.patch?h=fbterm-git" \ + patch"ins.patch; 0001-Fix-build-with-gcc-6.patch" \ + atclone"./configure --prefix=$ZPFX" \ + atpull"%atclone" make"install" reset +zi load izmntuk/fbterm +``` + +This command will result in: + + + +## Install patch-dl {#install-patch-dl} + +:::info Source + +- + z-shell/z-a-patch-dl + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-patch-dl +``` + + + + +This will register the `dl'…'` and `patch'…'` ice-modifiers. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx new file mode 100644 index 00000000..7b5637da --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/5_readurl.mdx @@ -0,0 +1,131 @@ +--- +id: readurl +title: 🌀 Read URL +image: /img/png/theme/z/320x320.png +description: Annex - Read URL documentation. +keywords: + - annex + - readurl +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex allows automatically downloading the newest version of a file to which the URL is hosted on a webpage. It works as follows: + +Invoke `snippet` (or simply pass the `https://…` address using the `for` syntax) on the web page that hosts the URL to the file to download, provide `dlink'…'` ice with the expected file-download URL replacing the version with the `%VERSION%` keyword, also provide `as'…'` ice with one of the following values: + +1. `readurl`, +2. `readurl|command`, +3. `readurl|completion`, +4. `readurl|null`. + +:::note + +The part after the `|` has the same meaning as in the normal `as'…'` ice. + +::: + +## Examples + +```shell showLineNumbers +zi id-as=fzf as='readurl|command' for \ + dlink='/junegunn/fzf/releases/download/%VERSION%/fzf-%VERSION%-linux_amd64.tar.gz' \ + https://github.com/junegunn/fzf/releases/ +``` + +The snippet is just an example. The same effect is obtained by loading as the `junegunn/fzf` plugin with `from'gh-r'` ice. + +As it can be seen, the `dlink'…'` can be a relative or an absolute path and also a full URL (i.e.: beginning with the `https://…` prefix). + +### Intermediate download page + +Sometimes, like it is in the case of the [terraform][terraform-link] command, the final download link isn't on the download page, but on a page, that's listed on it. In such a case use the `dlink0'…'` ice to provide the pattern for the additional, intermediate download page, e.g.: + +```shell showLineNumbers +zi id-as=terraform as='readurl|command' extract for \ + dlink0='/terraform/%VERSION%/' \ + dlink='/terraform/%VERSION%/terraform_%VERSION%_linux_386.zip' \ + https://releases.hashicorp.com/terraform/ +``` + +### Skipping `dlink'…'` ice + +Sometimes the URL of the download page differs from the URL of the archive in just a few `/`-sections. In such a case, it is possible to skip the `dlink'…'` ice by appending a `++`-separated fragment of the archive URL, like so: + +```shell showLineNumbers +zi as'readurl|command' extract for \ + http://domain.com/download-page++/archive.zip +``` + +If the archive URL has some different `/`-sections, then it's possible to strip the conflicting ones from the download URL by using `+++`, `++++`, etc. – the number of the `/`-section that'll be stripped equals to the number of the `+` minus 2. So, for example: + +```shell showLineNumbers +zi as'readurl|command' extract for \ + http://domain.com/download-page/removed-section+++/archive.zip +``` + +### Sorting the matched URLs / package versions + +Sometimes the download page doesn't list the package versions from newest to oldest, but in some other order. In such case, it's possible to sort the URLs / package versions by prepending the chosen `dlink` ice (`dlink0'…'` or `dlink'…'`) with the exclamation mark (`dlink'!…'`, etc.). See the next section for an example: + +### Filtering the matched URLs + +Sometimes some unwanted URLs match the `dlink'…'`/`dlink0'…'` regex/pattern. In such a case it's possible to filter them out by appending a filtering regex to the `dlink'…'` ice as: `dlink='the-main-regex~%the-unwanted-URLs-regex%'` (or the same for `dlink0'…'`). An example package that can benefit from this is the [Open Shift][open-shift-link] client, which doesn't sort the URLs from latest to the oldest – hence the exclamation mark (`!`) prepend – and it has special URLs like `stable-4.4` or `candidate-4.5` together with the regular version URLs (like `4.5.0-rc.1`): + +```shell showLineNumbers +zi id-as"ocp" as"readurl|command" for \ + dlink0'!%VERSION%~%(stable|latest|fast|candidate).*%' \ + dlink"openshift-client-windows-%VERSION%.zip" \ + https://mirror.openshift.com/pub/openshift-v4/clients/ocp/ +``` + +The above snippet of Zsh code / Zi invocation will sort the URLs (`dlink0'!…'`) and then filter out the special ones from the results (via `…~%(stable|latest|fast|candidate).*%`), this way selecting the latest version of the Open Shift client. + +### Other examples + +[Pulumi][pulumi-link], a tool to create, deploy and manage modern cloud software. + +```shell showLineNumbers +zi id-as'pulumi' as'readurl|null' for \ + dlink='https://get.pulumi.com/releases/sdk/pulumi-%VERSION%-linux-x64.tar.gz' \ + sbin'pulumi*' \ + https://www.pulumi.com/docs/get-started/install/versions/ +``` + +## Install readurl {#install-readurl} + +:::info Source + +- + z-shell/z-a-readurl + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-readurl +``` + + + + +This will register the `dlink'…'` and `dlink0'…'` ice-modifiers and also the special `as'readurl|…'` value of the `as'…'`. + + + + + + + +[open-shift-link]: https://www.openshift.com/ + +[pulumi-link]: https://www.pulumi.com/ + +[terraform-link]: https://releases.hashicorp.com/terraform diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx new file mode 100644 index 00000000..61e0575f --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/6_submods.mdx @@ -0,0 +1,54 @@ +--- +id: submods +title: 🌀 子模块 +image: /img/png/theme/z/320x320.png +description: Annex - Submods documentation. +keywords: + - annex + - submods +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex delivers the capability to clone additional submodules while installing a plugin or snippet. The submodules are then automatically updated on the `zi update …` command. + +Synopsis: + +```shell +submods'{user}/{plugin} -> {output directory}; …` +``` + +An example command utilizing the annex and its ice-modifier to load `zsh-autosuggestions` plugin via [Prezto module](/docs/getting_started/migration#pzt-modules) `autosuggestions`. + +```shell title='~/.zshrc' showLineNumbers +zi ice svn submods'zsh-users/zsh-autosuggestions -> external' +zi snippet PZT::modules/autosuggestions +``` + +## Install submods {#install-submods} + +:::info Source + +- + z-shell/z-a-submods + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-submods +``` + + + + +This will register the `submods'…'` ice-modifier. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx new file mode 100644 index 00000000..6e90e713 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/7_unscope.mdx @@ -0,0 +1,161 @@ +--- +id: unscope +title: 🌀 Unscope +image: /img/png/theme/z/320x320.png +description: Annex - Unscope IDs documentation +keywords: + - annex + - unscope +--- + + + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import Highlight from "@site/src/components/Highlight"; +import APITable from "@site/src/components/APITable"; + +An annex allows the installation of plugins without specifying the GitHub user name, as follows: + +1. On the installation of a plugin without any slashes (/) in its name the annex will query the GitHub API searching for `*/{the-name}`, sorting on stars. + +2. It first requires at least 10 forks on the candidates, then 2, then 0. + +3. After finding the best result it sets it as the **full** remote-id of the plugin, storing the ID on disk for later automatic use. + +4. For security, for such GH-API request to be made a newly added (by this annex) ice: `ghapi` is required to be given. + +5. Otherwise only the static database of mappings of short-plugin nicknames to the full scoped IDs will be searched. It contains many mappings, like, e.g.: `vi-reg → zsh-vi-more/evil-registers`, and some of the popular plugins, like, e.g.: `zsh-syntax-highlighting → zsh-users/zsh-syntax-highlighting` and more. + +## Static mappings + +:::info + +Fill [request](https://github.com/z-shell/z-a-unscope/issues/new/choose) to add new repositories with scoped IDs. + +::: + +Besides the GitHub-API querying, there's also a fixed, curated list of mappings of short names to the full GitHub IDs: + +```mdx-code-block + +``` + +| Short (Nick-) Name | GitHub ID / scoped ID | +| :-----------------------------------------------------------------------------: | :-------------------------------- | +| null | z-shell/null | +| z-a-readurl | z-shell/z-a-readurl | +| readurl | z-shell/z-a-readurl | +| rdurl | z-shell/z-a-readurl | +| z-a-patch-dl | z-shell/z-a-patch-dl | +| patch-dl | z-shell/z-a-patch-dl | +| z-a-submods | z-shell/z-a-submods | +| submods | z-shell/z-a-submods | +| z-a-rust | z-shell/z-a-rust | +| rust | z-shell/z-a-rust | +| z-a-bin-gem-node | z-shell/z-a-bin-gem-node | +| bin-gem-node | z-shell/z-a-bin-gem-node | +| bgn | z-shell/z-a-bin-gem-node | +| meta | z-shell/z-a-meta-plugins | +| metaplg | z-shell/z-a-meta-plugins | +| meta-plugins | z-shell/z-a-meta-plugins | +| archive | PZTM::archive | +| arch | PZTM::archive | +| directory | PZTM::directory | +| dir | PZTM::directory | +| environment | PZTM::environment | +| env | PZTM::environment | +| utility | PZTM::utility | +| util | PZTM::utility | +| fast-syntax-highlighting | z-shell/fast-syntax-highlighting | +| f-sy-h | z-shell/fast-syntax-highlighting | +| fsh | z-shell/fast-syntax-highlighting | +| history-search-multi-word | z-shell/history-search-multi-word | +| hsmw | z-shell/history-search-multi-word | +| zui | z-shell/zui | +| ZUI | z-shell/zui | +| zconvey | z-shell/zconvey | +| zconv | z-shell/zconvey | +| zbrowse | z-shell/zbrowse | +| zzcomplete | z-shell/zzcomplete | +| zzcomp | z-shell/zzcomplete | +| zzcom | z-shell/zzcomplete | +| zsh-autosuggestions | zsh-users/zsh-autosuggestions | +| autosuggestions | zsh-users/zsh-autosuggestions | +| autosug | zsh-users/zsh-autosuggestions | +| asug | zsh-users/zsh-autosuggestions | +| z-asug | zsh-users/zsh-autosuggestions | +| zsh-syntax-highlighting | zsh-users/zsh-syntax-highlighting | +| z-sy-h | zsh-users/zsh-syntax-highlighting | +| zsh-autocomplete | marlonrichert/zsh-autocomplete | +| autocomplete | marlonrichert/zsh-autocomplete | +| autocomp | marlonrichert/zsh-autocomplete | +| aucom | marlonrichert/zsh-autocomplete | +| acom | marlonrichert/zsh-autocomplete | +| z-aucom | marlonrichert/zsh-autocomplete | +| z-acom | marlonrichert/zsh-autocomplete | +| zsh-autopair | hlissner/zsh-autopair | +| autopair | hlissner/zsh-autopair | +| aupair | hlissner/zsh-autopair | +| aupa | hlissner/zsh-autopair | +| z-aupa | hlissner/zsh-autopair | +| evil-registers | zsh-vi-more/evil-registers | +| evil-reg | zsh-vi-more/evil-registers | +| vi-reg | zsh-vi-more/evil-registers | +| vireg | zsh-vi-more/evil-registers | +| vi-motions | zsh-vi-more/vi-motions | +| evil-mot | zsh-vi-more/vi-motions | +| vi-mot | zsh-vi-more/vi-motions | +| vimot | zsh-vi-more/vi-motions | +| vi-increment | zsh-vi-more/vi-increment | +| evil-inc | zsh-vi-more/vi-increment | +| vi-inc | zsh-vi-more/vi-increment | +| viinc | zsh-vi-more/vi-increment | +| vi-quote | zsh-vi-more/vi-quote | +| evil-qte | zsh-vi-more/vi-quote | +| vi-qte | zsh-vi-more/vi-quote | +| viqte | zsh-vi-more/vi-quote | +| directory-marks | zsh-vi-more/directory-marks | +| evil-dir-marks | zsh-vi-more/directory-marks | +| vi-dir-marks | zsh-vi-more/directory-marks | +| vi-dirma | zsh-vi-more/directory-marks | +| vidirma | zsh-vi-more/directory-marks | +| fd | sharkdp/fd | +| shark-fd | sharkdp/fd | +| bat | sharkdp/bat | +| shark-bat | sharkdp/bat | +| exa | ogham/exa | +| zsh-completions | zsh-users/zsh-completions | +| completions | zsh-users/zsh-completions | +| comps | zsh-users/zsh-completions | + +```mdx-code-block + +``` + +## Install unscope {#install-unscope} + +:::info Source + +- + z-shell/z-a-unscope + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-unscope +``` + + + + +This will allow scoped IDs to be searched and resolved. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx new file mode 100644 index 00000000..e699dade --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/8_linkbin.mdx @@ -0,0 +1,102 @@ +--- +id: linkbin +title: 🌀 Link Bin +image: /img/png/theme/z/320x320.png +description: Annex - Link Bin documentation. +keywords: + - annex + - linkbin +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +An annex exposes a binary program without modifying `$PATH` – `z-a-linkbin` and automatically creates a hard or soft link to the binary at `$ZPFX/bin` exposing the program to the command line as if it were being placed in `$PATH`. + +The command can then be accessed normally – not only in the live Zsh session but also from any Zsh script. The ice-modifier `lbin''` provided by the annex creates `links` for binaries and scripts. + +It creates the `link` that calls the actual binary. The link is created always under the same, standard and single `$PATH` entry: `$ZPFX/bin` + +## Soft link + +:::note + +The optional preceding `!` flag means creating a soft link instead of a hard link. + +::: + +Example: + +```shell {2} showLineNumbers +zi ice from'gh-r' as'program' \ + lbin'!fzf' +zi load junegunn/fzf +``` + +Check the output: + +```shell showLineNumbers +ls -l $ZPFX/bin/ | awk '{print $(NF-2),$(NF-1),$NF}' +fzf --version +``` + +## Hard link + +:::note + +The ice-modifier can contain globs as it will expand these when searching for the binary. + +::: + +Example: + +```shell {2} showLineNumbers +zi ice from'gh-r' as'program' \ + lbin'**fzf -> myfzf' +zi load junegunn/fzf +``` + +Check the output: + +```shell +ls -l $ZPFX/bin/ | awk '{print $(NF-2),$(NF-1),$NF}' +myfzf --version +``` + +## Auto nickname link + +If ice-modifier [id-as](/docs/guides/syntax/standard#id-as) is empty, then will try to create the link with a nickname as follows: + +1. Trailing component of the `id-as` ice-modifier, e.g.: `id-as'exts/git-my'` → it will check if a file `git-my` exists and if yes, create the link `git-my`. +2. The plugin name, e.g.: for `paulirish/git-open` it'll check if a file `git-open` exists and if yes, create the link `git-open`. +3. Trailing component of the snippet URL. +4. For any alphabetically first executable file. + +The above also applies if just `!` were passed. + +## Install linkbin {#install-linkbin} + +:::info Source + +- + z-shell/z-a-linkbin + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-linkbin +``` + + + + +This will register the `lbin'…'` ice-modifier. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx new file mode 100644 index 00000000..1a2e83ee --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/9_rust.mdx @@ -0,0 +1,164 @@ +--- +id: rust +title: 🌀 Rust +image: /img/png/theme/z/320x320.png +description: An annex installs rust and cargo packages. +keywords: + - annex + - rust +--- + + + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import Player from "@site/src/components/Player"; +import Shortcuts from "@site/src/components/Markdown/_player_shortcuts.mdx"; + +An annex installs rust and cargo packages locally inside the plugin or snippet directories. + + + + + + + + + + +## Usage of the annex + +The Zi annex provides ice-modifiers `rustup` and `cargo'…'`. + +The first one installs rust inside the plugin's folder using the official `rustup` installer and the second one has the following syntax: + +```shell +cargo'[{name-of-the-binary-or-path} <-] [[!][c|n|e|o]:]{crate-name} [-> {shim-script-name}]'` +``` + +| Flag | Description | +| ---- | ------------------------------------------------------------------------------------------------ | +| `N` | redirect both standard output and error to `/dev/null` | +| `E` | redirect standard error to `/dev/null` | +| `O` | redirect standard output to `/dev/null` | +| `c` | change the current directory to the plugin's or snippet's directory before executing the command | + +As the examples showed, the name of the binary to run and the shim name are by default equal to the name of the crate. Specifying `{binary-name} <- …` and/or `… -> {shim-name}` allows to override them. + +The crate can create so-called _shims_ – scripts that are exposed to the standard `$PATH`. The shim script is a wrapper around the binary that is installed by the crate. The shim script is created in the plugin's or snippet's directory and is named after the crate. The shim script is a shell script that sets up the environment variables and then runs the binary. + +Example of the _shim_ script: + +```shell showLineNumbers +#!/usr/bin/env zsh + +function lsd { + local bindir="/root/.zi/plugins/z-shell---null/bin" + local -x PATH="/root/.zi/plugins/z-shell---null"/bin:"$PATH" # -x means export + local -x RUSTUP_HOME="/root/.zi/plugins/z-shell---null"/rustup CARGO_HOME="/root/.zi/plugins/z-shell---null" + + "$bindir"/"lsd" "$@" +} + +lsd "$@" +``` + +As it can be seen shim ultimately provides the binary to the command line. + +
+ Use case examples + +Set up rust and the `lsd` crate with a shim `lsd` exposing the binary: + +```shell showLineNumbers +zi ice rustup cargo'!lsd' +zi load z-shell/0 +``` + +Set up rust and the `exa` crate with a shim `ls` exposing the `exa` binary: + +```shell showLineNumbers +zi ice rustup cargo'!exa -> ls' +zi load z-shell/0 +``` + +Set up rust and the `exa` and `lsd` crates: + +```shell showLineNumbers +zi ice rustup cargo'exa;lsd' +zi load z-shell/0 +``` + +Set up rust, then the `exa` and `lsd` crates, with their binaries exposed by altering `$PATH`: + +```shell showLineNumbers +zi ice rustup cargo'exa;lsd' as"command" pick"bin/(exa|lsd)" +zi load z-shell/0 +``` + +Set up rust and then the `exa` crate with shim standard error redirected to `/dev/null`: + +```shell showLineNumbers +zi ice rustup cargo'!E:exa' +zi load z-shell/0 +``` + +Just install rust and make it available globally in the system: + +```shell showLineNumbers +zi ice id-as"rust" wait"0" lucid rustup as"command" pick"bin/rustc" atload="export \ + CARGO_HOME=\$PWD RUSTUP_HOME=\$PWD/rustup" +zi load z-shell/0 +``` + +A little more complex rustup configuration that uses [bin-gem-node][annex-bin-gem-node] annex and installs the cargo completion provided with rustup, using the [for][for-syntax] syntax: + +```shell showLineNumbers +zi id-as=rust wait=1 as=null sbin="bin/*" lucid rustup \ + atload="[[ ! -f ${ZI[COMPLETIONS_DIR]}/_cargo ]] && zi creinstall rust; \ + export CARGO_HOME=\$PWD RUSTUP_HOME=\$PWD/rustup" for \ +z-shell/0 +``` + +
+ +## Install rust {#install-rust} + +:::info Source + +- + z-shell/z-a-rust + + +::: + + + + +Add the following snippet in the `.zshrc` file: + +```shell +zi light z-shell/z-a-rust +``` + + + + +This will register the `rustup` and `cargo'…'` ice-modifiers. + + + + + +[annex-bin-gem-node]: /ecosystem/annexes/bin-gem-node + +[for-syntax]: /docs/guides/syntax/for diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json new file mode 100644 index 00000000..11efc59c --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/annexes/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "🌀 附件", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/index.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/index.mdx new file mode 100644 index 00000000..14697758 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/index.mdx @@ -0,0 +1,26 @@ +--- +id: 生态系统 +slug: / +title: 🌐 生态系统 +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: 生态系统简介。 +--- + + + +```mdx-code-block +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +
+ +
+``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx new file mode 100644 index 00000000..4b9b04a8 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/01_synopsis.mdx @@ -0,0 +1,143 @@ +--- +id: synopsis +title: 📦 Synopsis +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: Introduction to packages. +keywords: + - package + - zpackage + - zsh-package + - packages-overview +--- + + + +The motivation for adding packages functionality: + +1. Zi is a flexible and feature-rich plugin manager, however, users often feel overwhelmed by its configuration. + +2. It has multiple package-manager-like features, such as: + + - get the plugin's Git repository OR release-package URL, + - get the list of the recommended [ice-modifiers][] for the plugin, + - there can be multiple lists of [ice-modifiers][], + - the ice-modifiers list is stored in profiles; there's at least one profile, default, + - the [ice-modifiers][] can be selectively overridden. + - automatically provide so-called shims (i.e.: forwarder scripts) for the binaries, + - extend `$PATH` to expose the binaries, + - it can run `Makefile` and more. + +3. In general, Zi has many hooks which allow surprising things, however, their content often evolves to a gradually better one and it's hard to keep track of all the current versions. + +:::info + +The [bin-gem-node][] annex is recommended, otherwise, some packages will fail to install due to missing functionality. + +::: + +## The [any-gem][] and [any-node][] packages + +They allow the installation of any Gem(s) or Node module(s) locally in a newly created plugin directory. For example: + +```shell showLineNumbers +zi pack param='GEM -> rails' for any-gem +zi pack param='MOD -> doctoc' for any-node +``` + +If the installation is used in the `.zshrc` file then use `id-as'…'`, then Zi knows that the package is already installed. + +:::note + +The Unicode arrow is allowed in Zi syntax as in the example below. + +::: + +```shell +zi id-as=jekyll pack param='GEM → jekyll' for any-gem +``` + +The binaries will be exposed without altering the PATH via shims. Shims are correctly removed when deleting a plugin with `zi delete …` The so-called packages are GitHub repositories holding a `package.json` file with the meta-data in them. This way you don't have to (but still can) specify ice-modifiers, which might be handy when the [ice-modifiers][] list is long and complex. + +## Introductory example + +This way, instead of the following command used to install `fzf`: + +```shell showLineNumbers +zi lucid as=program pick="$ZPFX/bin/(fzf|fzf-tmux)" \ + atclone="cp shell/completion.zsh _fzf_completion; \ + cp bin/(fzf|fzf-tmux) $ZPFX/bin" \ + make="PREFIX=$ZPFX install" for \ + junegunn/fzf +``` + +you only need: + +```shell +zi pack for fzf +``` + +to get the complete setup of the fuzzy finder, including: + +- the completion +- the additional executable script `fzf-tmux` + +The installation is like with package-manager because you don't need to invoke Zi anymore once installed to use `fzf` (that's because `fzf` is just a binary program and not e.g.: a shell function). You can also update the package with `zi update fzf` – it'll cause the project to refresh and rebuild, like with a "normal" package manager such as `apt-get`. However, it'll be more like to `emerge` from Gentoo, because the installation will be from the source… unless… the user will pick up a binary installation by profile argument specified in the `pack'…'` ice. + +## Pros of using the Zi package for regular software installations + +Using Zi to install software where one could use a regular package manager has several advantages: + +1. **Pro:** The Zi packages typically use the URLs to the official and _latest_ distributions of the software (e.g.: the [ecs-cli][] package, which uses the URL: `https://amazon-ecs-cli.s3.amazonaws.com/ecs-cli-linux-amd64-latest` when installing on Linux). + +2. **Pro:** You can influence the installation easily by specifying Zi ice-modifiers, e.g.: + + ```shell + zi pack=bgn atclone="cp fzy.1 $ZI[MAN_DIR]/man1" for fzy + ``` + + to install also the man page for the `fzy` fuzzy finder (this omission in the package will be fixed soon). + +3. **Pro:** The installation is much more flexible than a normal package manager. Example available degrees of freedom: + + - to install from Git or release-tarball, or a binary-release file, + - to install via shims or via extending `$PATH`, or by copying to `$ZPFX/bin`, + - to download files and apply patches to the source by using the `patch-dl` annex features. + +4. **Pro:** The installations are located in the user home directory, which doesn't require root access. Also, for Gems and Node modules, they are installed in their plugin directory, which can have advantages (e.g.: isolation allowing e.g: easy removal by `rm -rf …`). + +5. **Con:** You're somewhat "on your own", with no support from any package maintainer. + +Thus, summing up 1. with 4., it might be nice/convenient too, for example, have the latest ECS CLI binary installed in the home directory, without using root access and always the latest, and – summing up with 2. and 3. – to, for example, have always the latest `README` downloaded by additional ice: `dl'https://raw.githubusercontent.com/aws/amazon-ecs-cli/master/README.md'` (and then to have the `README` converted into a man page by the `remark` Markdown processor or other via an `atclone''` ice, as the tool doesn't have any official man page). + +## Adding your package + +1. Contact the author to have the repository at the [Z-Shell][z-shell] organization or set the [ZI\[PKG_OWNER\]][modify-settings]. + +2. Populate the `package.json` – I suggest grabbing the one for `fzf` or `doctoc` and doing a few substitutions like [doctoc][] → `your-project` and then simply filling the `default` profile in the `zi-ices` object – it is same as passing ice-modifiers to `zi ice …` but in JSON. + +3. The project name in the `package.json` should start with `zsh-`. The prefix will be skipped when specifying it with Zi. + +4. Commit and push. + + + + + +[bin-gem-node]: /ecosystem/annexes/bin-gem-node + +[ice-modifiers]: /docs/guides/syntax/ice-modifiers + +[modify-settings]: /docs/guides/customization#modify-settings + + + +[any-gem]: https://github.com/z-shell/any-gem + +[any-node]: https://github.com/z-shell/any-node + +[ecs-cli]: https://github.com/z-shell/ecs-cli + +[z-shell]: https://github.com/z-shell + +[doctoc]: https://github.com/z-shell/doctoc diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx new file mode 100644 index 00000000..15550756 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/02_usage.mdx @@ -0,0 +1,1022 @@ +--- +id: usage +title: 📦 Usage +image: /img/png/theme/z/320x320.png +description: Zi packages usage information. +keywords: + - zpackage + - 软件包 + - zsh-packages +--- + + + +import Emoji from "@site/src/components/Emoji"; +import APITable from "@site/src/components/APITable"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +## Package repositories + +For all the available packages use [GitHub search][github-search]. + +```mdx-code-block + +``` + +| Package Name | Description | +| :--------------------: | :-------------------------------------------------------------------------------------------------- | +| [any-node][] | The any Node module(s) locally in a newly created plugin directory. | +| [any-gem][] | The any Gem(s) locally in a newly created plugin directory. | +| [apr][] | The Apache Portable Runtime (APR) library. | +| [fzf][] | The fzf command-line fuzzy finder. | +| [fzy][] | The fzy command-line fuzzy finder. | +| [pyenv][] | The pyenv Python virtual environment manager. | +| [remark][] | The remark Markdown processor. | +| [doctoc][] | The doctoc Markdown processor. | +| [ls_colors][] | The LS_COLORS and setup a zsh-completion system color scheme. | +| [dircolors-material][] | The dircolors-material and set up a zsh-completion system color scheme. | +| [asciidoctor][] | The asciidoctor Markdown processor. | +| [system-completions][] | Moves the stock Zsh completions under the control of Zi. | +| [brew-completions][] | The Homebrew Shell Completion under the control of Zsh & Zi. | +| [ecs-cli][] | The AWS ECS CLI. | +| [subversion][] | The Subversion client. | +| [github-issues][] | The GitHub Issues client. | +| [github-issues-srv][] | The GitHub Issues server. | +| [firefox-dev][] | The Firefox Developer Edition. | +| [zsh][] | The Zsh mirror of zsh-users. | +| [nb][] | Bookmarking, and archiving with linking, tagging, search, Git syncing, Pandoc conversion, and more. | +| [zsh-bin][] | Package of statically-linked, hermetic, relocatable - romkatv/zsh-bin. | + +```mdx-code-block + +``` + +## Package profiles + +### Apache Portable Runtime (APR) library + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ +Download, build and install the latest Apache Portable Runtime. + +```shell +zi pack for apr +``` + +### `asciidoctor` Markdown processor + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + + + + + (default) +
+ +Download the Gem of asciidoctor locally with the [bin-gem-node][] annex. + +> Using the `@` prefix because of collision with the as'' ice. + +```shell +zi pack for @asciidoctor +``` + +### AWS ECS CLI + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + (default) + + + + + + +
+ + + + +Download the binary of the Amazon-ECS-CLI command. + +```shell +zi pack for ecs-cli +``` + + + + +Download the ECS-CLI binary with the use of the bin-gem-node annex. + +```shell +zi pack"bgn" for ecs-cli +``` + + + + +### `dircolors-material` color scheme + + + + + + + + + + + + + + + + + + + + +
+ Package source + TarballBinaryGitNodeGem
+ Status: + + + + + + (default) + + + + +
+ + + + +Download the default profile. + +```shell +zi pack for dircolors-material +``` + + + + +Download the "no-zsh-completion" profile. + +```shell +zi pack"no-zsh-completion" for dircolors-material +``` + + + + +Download the "no-color-swaps" profile. + +```shell +zi pack"no-color-swaps" for dircolors-material +``` + + + + +Download the minimal profile without altering the original theme. + +```shell +zi pack"minimal" for dircolors-material +``` + + + + +### `doctoc` Markdown processor + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + + + (default) + + +
+ +A download default profile with the Node package of doctoc. + +```shell +zi pack for doctoc +``` + +### Firefox Developer Edition + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + (default) + + + + + + +
+ + + + +Download the firefox-dev latest binary. + +```shell +zi pack for firefox-dev +``` + + + + +Download the firefox-dev latest binary with use of the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for firefox-dev +``` + + + + +### `fzf` command-line fuzzy finder + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ + + + +Download the package with the default profile. + +```shell +zi pack for fzf +``` + + + + +Download the package with the default profile + key bindings. + +```shell +zi pack"default+keys" for fzf +``` + + + + +Download the package with the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for fzf +``` + + + + +Download the package with the [bin-gem-node][] annex and with the key bindings. + +> The "+keys" variants are available for each profile. + +```shell +zi pack"bgn+keys" for fzf +``` + + + + +Download with the [bin-gem-node][] annex from GitHub repository. + +```shell +zi pack"bgn" git for fzf +``` + + + + +Download the binary from the GitHub releases. + +```shell +zi pack"binary" for fzf +``` + + + + +Download the binary from the GitHub releases and install using [bin-gem-node][] + shims. + +```shell +zi pack"bgn-binary" for fzf +``` + + + + +### `fzy` command-line fuzzy finder + + + + + + + + + + + + + + + + + + + + +
+ Package source: + TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ + + + +Download the package with the default profile. + +```shell +zi pack for fzy +``` + + + + +Download the package with the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for fzy +``` + + + + +Download with the [bin-gem-node][] annex from GitHub repository. + +```shell +zi pack"bgn" git for fzy +``` + + + + +Download normal ice list and override atclone'' ice to skip the contrib scripts + +```shell +zi pack"bgn" atclone'' for fzy +``` + + + + +### `LS_COLORS` color scheme + + + + + + + + + + + + + + + + + + +
+ Package source: + TarballGitNodeGem
+ Status: + + + + (default) + + + + +
+ + + + +Download the default profile. + +```shell +zi pack for ls_colors +``` + + + + +Download the "no-zsh-completion" profile. + +```shell +zi pack"no-zsh-completion" for ls_colors +``` + + + + +Download the "no-dir-color-swap" profile. + +```shell +zi pack"no-dir-color-swap" for ls_colors +``` + + + + +### Feature-rich note‑taking (`nb`) {#nb-pkg-profile} + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballGitNodeGem
+ Status: + + (default) + + + + + + +
+ +Default profile are using [bin-gem-node][] to set shims. + +```shell +zi pack for nb +``` + +### Python virtual environment manager - `pyenv` {#pyenv-pkg-profile} + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ + + + +Download the tarball with the default ice list. + +```shell +zi pack for pyenv +``` + + + + +Download the binary from the GitHub releases with the [bin-gem-node][] annex. + +```shell +zi pack"bgn" for pyenv +``` + + + + +Download with the [bin-gem-node][] annex from GitHub repository. + +```shell +zi pack"bgn" git for pyenv +``` + + + + +### `remark` Markdown processor + + + + + + + + + + + + + + + + + + +
+ Package source: + TarballGitNodeGem
+ Status: + + + + + + (default) + + +
+ + + + +Download the Node package of remark-CLI, remark-man and remark-HTML + +```shell +zi pack for remark +``` + + + + +Download the Node package of remark-CLI and remark-man + +```shell +zi pack"man-only" for remark +``` + + + + +Download the Node package of remark-CLI and remark-HTML + +```shell +zi pack"html-only" for remark +``` + + + + +### Subversion + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + (default) + + + + + + + + +
+ +Download, build and install the latest Subversion. + +> Dependency of Subversion: [APR][] + +```shell +zi pack for subversion +``` + +### Zsh mirror of zsh-users + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + (default) + + + + +
+ + + + +Install the newest Zsh. + +```shell +zi pack for zsh +``` + + + + +Install preferred Zsh version. + +```shell +zi pack"5.9" for zsh +zi pack"5.8.1" for zsh +zi pack"5.8" for zsh +zi pack"5.7.1" for zsh +zi pack"5.6.2" for zsh +zi pack"5.5.1" for zsh +zi pack"5.4.2" for zsh +zi pack"5.3.1" for zsh +zi pack"5.2.4" for zsh +zi pack"5.1.1" for zsh +``` + + + + +### Statically-linked, hermetic, relocatable Zsh + + + + + + + + + + + + + + + + + + + + +
+ Package source: + Source TarballBinaryGitNodeGem
+ Status: + + + + + + (default) + + + + +
+ + + + +Requires **root** access to install Zsh at `/usr/local` and will attempt to register it as a login shell. + +```shell +zi pack for zsh-bin +``` + + + + +Does not require **root** access, when install using [bin-gem-node][] to set shims. + +```shell +zi pack"bgn" for zsh-bin +``` + + + + +Does not require **root** access, will install to `~/.local`. + +```shell +zi pack"rootless" for zsh-bin +``` + + + + + + + + +[bin-gem-node]: /ecosystem/annexes/bin-gem-node + + + +[any-node]: https://github.com/z-shell/any-node + +[any-gem]: https://github.com/z-shell/any-gem + +[apr]: https://github.com/z-shell/apr + +[fzf]: https://github.com/z-shell/fzf + +[fzy]: https://github.com/z-shell/fzy + +[pyenv]: https://github.com/z-shell/pyenv + +[remark]: https://github.com/z-shell/remark + +[doctoc]: https://github.com/z-shell/doctoc + +[ls_colors]: https://github.com/z-shell/ls_colors + +[dircolors-material]: https://github.com/z-shell/dircolors-material + +[asciidoctor]: https://github.com/z-shell/asciidoctor + +[system-completions]: https://github.com/z-shell/system-completions + +[ecs-cli]: https://github.com/z-shell/ecs-cli + +[subversion]: https://github.com/z-shell/subversion + +[github-issues]: https://github.com/z-shell/github-issues + +[github-issues-srv]: https://github.com/z-shell/github-issues-srv + +[firefox-dev]: https://github.com/z-shell/firefox-dev + +[zsh]: https://github.com/z-shell/zsh + +[nb]: https://github.com/z-shell/nb + +[zsh-bin]: https://github.com/z-shell/zsh-bin + +[brew-completions]: https://github.com/z-shell/brew-completions + +[github-search]: https://github.com/search?q=topic%3Azpackage+org%3Az-shell&type=Repositories diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json new file mode 100644 index 00000000..761cb15a --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-ecosystem/current/packages/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "📦 软件包", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json new file mode 100644 index 00000000..dbcdde38 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,18 @@ +{ + "version.label": { + "message": "下一页", + "description": "The label for version current" + }, + "sidebar.SideBar.category.🚀 Getting Started": { + "message": "🚀 开始使用", + "description": "The label for category 🚀 Getting Started in sidebar SideBar" + }, + "sidebar.SideBar.category.💡 Guides": { + "message": "💡指南", + "description": "The label for category 💡 Guides in sidebar SideBar" + }, + "sidebar.SideBar.category.✍️ Syntax": { + "message": "✍️ 语法", + "description": "The label for category ✍️ Syntax in sidebar SideBar" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx new file mode 100644 index 00000000..f7ae4ef8 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/01_installation.mdx @@ -0,0 +1,281 @@ +--- +id: installation +title: ⚡️ 安装 +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: 安装指南 +keywords: + - 安装 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; + +## Quick setup {#quick-setup} + +将以下内容添加到 .zshrc 文件中： + + + + +```shell title="~/.zshrc" +source <(curl -sL init.zshell.dev); zzinit +``` + + + + +:::caution + +This setup method requires manually verifying the sha256 [checksum][checksum-txt] for a file lib/zsh/init.zsh every time the content is changed in the repository. + +::: + +```shell showLineNumbers title="~/.zshrc" +local cs_ok='7fab1ecb8d2ffbdb4aa98dd1e51cebaeaa4d8137e1de11938f3e0df24af262bb' +local cs_get=$(sha256sum <(curl -sL init.zshell.dev) | awk '{print $1}') +[[ $cs_ok == $cs_get ]] && { source <(curl -sL init.zshell.dev); zzinit; } || { + print -P "%F{160}▓▒░ Houston, we have a problem, the %F{226}$cs_get%F{160} do not match\!%f%b"; return 1 +} +unset cs_ok cs_get +``` + + + + +Reload the shell with exec zsh -il and run zi -h for usage information. + +## Automated setup {#automated-setup} + +:::tip + +- Verify the sha256 [checksum][checksum-txt] for file: lib/sh/install.sh +- If required append -b \ or -b \ e.g: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -i skip -b main +``` + +::: + + + + +Install and include minimal configuration to the .zshrc: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- +``` + + + + +Install and include minimal configuration with [loader](#loader): + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a loader +``` + +The installer will download the loader and add the snippet below to the .zshrc file. + +```shell showLineNumbers +if [[ -r "${XDG_CONFIG_HOME:-${HOME}/.config}/zi/init.zsh" ]]; then + source "${XDG_CONFIG_HOME:-${HOME}/.config}/zi/init.zsh" && zzinit +fi +``` + +:::tip + +The loader can be manually fetched from available [links](#loader) to any location on the system, and sourced from .zshrc or as shown in the [quick-setup](#quick-setup). + +::: + +Then reload the shell with: `exec zsh`. 全部完成了！ + + + + +Clone repository using default or if set custom values: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -i skip +``` + + + + +Install and include minimal configuration with recommended annexes: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a annex +``` + + + + +Install and include minimal configuration with recommended annexes and setup zdharma/zunit: + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a zunit +``` + + + + +## Manual Setup {#manual-setup} + +:::tip Related + +- [🏗 Configuration management](/docs/guides/customization#customizing-paths) + +::: + +设置安装位置并创建目录： + +```shell showLineNumbers +typeset -Ag ZI +typeset -gx ZI[HOME_DIR]="${HOME}/.zi" ZI[BIN_DIR]="${ZI[HOME_DIR]}/bin" +command mkdir -p "$ZI[BIN_DIR]" +``` + +For security reasons run function compaudit to check if the [completion system][completion-system] would use files owned by root or by the current user, or files in directories that are world or group-writable. + +如果失败，则将当前用户设置为目录的所有者，然后删除 group/others 的写入权限，并克隆存储库： + +```shell showLineNumbers +compaudit | xargs chown -R "$(whoami)" "$ZI[HOME_DIR]" +compaudit | xargs chmod -R go-w "$ZI[HOME_DIR]" +command git clone https://github.com/z-shell/zi.git "$ZI[BIN_DIR]" +``` + +To enable Zi, source the zi.zsh from the previously set up directory placing the following snippet in the .zshrc file: + +```shell title="~/.zshrc" showLineNumbers +typeset -A ZI +ZI[BIN_DIR]="${HOME}/.zi/bin" +source "${ZI[BIN_DIR]}/zi.zsh" +``` + +:::caution + +下面的两行必须放在上面的行之后，即在启用 Zi 之后。 + +::: + +启用 Zi 补全： + +```shell title="~/.zshrc" showLineNumbers +autoload -Uz _zi +(( ${+_comps} )) && _comps[zi]=_zi +``` + +## Post-install {#post-install} + +After a fresh install, it is recommended to reload the shell and recompile Zi with: + +- exec zsh -il +- zi self-update + +Run zi -h for available commands or [explore][collection-page] wiki to [extend][ecosystem-page], [customize][customization-page] and [create][zsh-plugin-standard] . + +If you have any issue or need help , lets [discuss][discuss] it or open an [issue][issue] on GitHub. + +It helps us to improve and make Zi better. Don't forget to help the project: share, contribute, or [translate][help-translate] . + +Let's glue a toolchain that works for us . + +## Have ideas? + +###  Suggest or request at playground + +```shell +sh -c "$(curl -fsSL get.zshell.dev)" -- -a ??? +``` + +##  Need warm-up? + +###  Docker Alpine + +```shell +docker run --rm -it ghcr.io/z-shell/zd:latest +``` + +### Turbo Zi in Docker + +If you create a Docker image that uses Zi, install Turbo-loaded plugins before the shell starts interactively, with the @zi-scheduler function in such a way, that it: + +- Install plugins without waiting for the prompt (i.e. it's script friendly). +- Install all plugins instantly, without respecting the wait argument. + +To accomplish this, use burst argument and call the @zi-scheduler function: + +```docker +RUN zsh -i -c -- '@zi-scheduler burst || true' +``` + +> - An example: [Dockerfile][dockerfile] +> - In action: [Playground][playground] + +## Zi Module: zpmod {#zi-module} + +The module transparently and automatically compiles sourced scripts and lists of all sourced files with the time the sourcing took in milliseconds on the left. + +- [⚙️ Wiki: zpmod][zpmod-page] +- [📦 Source: zpmod][z-shell/zpmod] + +## Available links {#available-links} + +[Status page][status] + +### Installer {#installer} + +| 服务 | URL | +| :--------- | ----------------------------------------------------------------------- | +| 带重定向 | https://get.zshell.dev | +| Cloudflare | https://src.zshell.dev/sh/install.sh | +| Git.io | https://git.io/get-zi | +| GitHub RAW | https://raw.githubusercontent.com/z-shell/zi-src/main/lib/sh/install.sh | + +### Loader {#loader} + +| 服务 | URL | +| :--------- | ---------------------------------------------------------------------- | +| 带重定向 | https://init.zshell.dev | +| Cloudflare | https://src.zshell.dev/zsh/init.zsh | +| Git.io | https://git.io/zi-loader | +| GitHub RAW | https://raw.githubusercontent.com/z-shell/zi-src/main/lib/zsh/init.zsh | + + + + + +[zpmod-page]: /ecosystem/plugins/zsh-modules#-z-shellzpmod + +[customization-page]: /docs/guides/customization + +[ecosystem-page]: /ecosystem + +[collection-page]: /community/category/-collection + +[zsh-plugin-standard]: /community/zsh_plugin_standard + + + +[checksum-txt]: https://raw.githubusercontent.com/z-shell/zi-src/main/lib/checksum.txt + +[completion-system]: https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Use-of-compinit + +[discuss]: https://github.com/orgs/z-shell/discussions/new + +[dockerfile]: https://github.com/robobenklein/configs/blob/master/Dockerfile + +[issue]: https://github.com/z-shell/zi/issues/new/choose + +[playground]: https://github.com/z-shell/playground + +[status]: https://status.zshell.dev + +[help-translate]: https://digitalclouds.crowdin.com/z-shell + +[z-shell/zpmod]: https://github.com/z-shell/zpmod diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx new file mode 100644 index 00000000..b1be9291 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/02_overview.mdx @@ -0,0 +1,510 @@ +--- +id: overview +title: ☑️ 一般概述 +image: /img/png/theme/z/320x320.png +description: Zi 使用概述 +--- + +import ImgShow from "@site/src/components/ImgShow"; +import Link from "@docusaurus/Link"; + +此概览包括以下内容： + +1. [Oh-My-Zsh & Prezto](/search?q=Oh+My+Zsh+%26+Prezto) +2. [Completions](/search?q=completions) +3. [Turbo mode](/search?q=turbo+mode) +4. [Ice modifiers](/search?q=ice+modifiers) + +## 加载插件和片段 + +```shell showLineNumbers +zi load z-shell/H-S-MW +zi light zsh-users/zsh-syntax-highlighting +``` + +上面的命令显示了两种加载基本插件的方式。 If you want to source local or remote files (using a direct URL), you can do so with a `snippet`. + +```shell +zi snippet +``` + +Such lines should be added to `.zshrc`. Snippets are cached locally, use the `-f` option to download a fresh version of a snippet, or `zi update {URL}`. Use `zi update --all` to update all snippets and plugins. + +Using `load` causes reporting to be enabled – you can track what the plugin does, view the information with `zi report {plugin-name}`, and then also unload the plugin with `zi unload {plugin-name}`. + +Using `light` is a faster loading without tracking and reporting about the plugin but also withdrawing the ability to unload it. + +Using `load` or `light`: + +```shell showLineNumbers +zi load # Load with reporting/investigating. +zi light # Load without reporting/investigating. +``` + +带着跟踪报告加载 history-search-multi-word 插件： + +```shell +zi load z-shell/H-S-MW +``` + +不带跟踪报告加载两个普通插件： + +```shell showLineNumbers +zi light zsh-users/zsh-autosuggestions +zi light z-shell/F-Sy-H +``` + +片段: + +```shell +zi snippet https://gist.githubusercontent.com/hightemp/5071909/raw/ +``` + +:::note + +In turbo mode loading, the slowdown by plugin tracking is done in the background and does not affect the user experience, i.e., loading with `zi light` and `zi load` has the same effect. + +::: + +## Oh-My-Zsh, Prezto + +To load Oh-My-Zsh and Prezto plugins, use the `snippet` feature. Snippets are **single files** downloaded by `curl`, `wget`, etc., automatic detection of the download tool is being performed, directly from the URL: + +```shell showLineNumbers +zi snippet 'https://github.com/robbyrussell/oh-my-zsh/raw/master/plugins/git/git.plugin.zsh' +zi snippet 'https://github.com/sorin-ionescu/prezto/blob/master/modules/helper/init.zsh' +``` + +Also, for Oh-My-Zsh and Prezto, you can use `OMZ::` and `PZT::` shorthands: + +```shell showLineNumbers +zi snippet OMZ::plugins/git/git.plugin.zsh +zi snippet PZT::modules/helper/init.zsh +``` + +此外，GitHub 支持通过 Subversion 协议加载片段。 This allows loading snippets that are multi-file (for example, a Prezto module can consist of two or more files, e.g. `init.zsh` and `alias.zsh`). + +Default files that will be sourced are: `*.plugin.zsh`, `init.zsh`, `*.zsh-theme`: + +指向目录的URL： + +```shell {2} showLineNumbers +zi ice svn +zi snippet PZT::modules/docker +``` + +## Snippet 和性能 + +Using `curl`, `wget`, etc. along with Subversion allows us to almost completely avoid code dedicated to Oh-My-Zsh and Prezto, and also to other frameworks. 它提供了更好的性能，因为它对内存的占用很低，加载时间更短。 + +## Ice 修饰符 + +The command `zi ice` provides [ice modifiers][1] for the single Zi command, i.e., `zi ice ; zi load some/plugin`, after loading some/plugin the ice-modifier has to be set again. + +“冰”是一种添加物，例如添加到饮料或咖啡中 —— 在 Zi 里，冰修饰符将是下一条 Zi 命令的添加物。 +“冰”也是会融化的东西，所以它不会留存很久 —— 在 Zi 里，这意味着它的效果只能作用于一条命令。 + +Using one other ice modifier "**pick**" users can explicitly **select the file to source**: + +```shell {1} showLineNumbers +zi ice svn pick"init.zsh" +zi snippet PZT::modules/git +``` + +The content of the ice-modifier is simply put into `"…"`, `'…'`, `$'…'`. No need for `":"` after the ice-modifier name (although it's allowed: as the equal sign `=`, e.g. `pick="init.zsh"` or `pick=init.zsh`). + +This way editors like `vim` and `emacs` and also `zsh-users/zsh-syntax-highlighting` and `z-shell/F-Sy-H` will highlight the contents of ice-modifiers. + +## 关于 as"program" + +A plugin might not be a file for sourcing, but a command to be added to `$PATH`. To obtain this effect, use ice-modifier `as` with value `program` (or an alias value `command`). + +```shell {1} showLineNumbers +zi ice as"program" cp"httpstat.sh -> httpstat" pick"httpstat" +zi light b4b4r07/httpstat +``` + +The above command will add plugin directory to `$PATH`, copy file `httpstat.sh` into `httpstat` and add execution rights (`+x`) to the file selected with `pick`, i.e. to `httpstat`. Another ice-mod exists, `mv`, which works like `cp` but **moves** a file instead of **copying** it. `mv` is run before `cp`. + +:::tip + +The `cp` and `mv` ices (and also some other ones, like `atclone`) are being run when the plugin or snippet is being _installed_. To test them again first delete the plugin or snippet (example: `zi delete PZT::modules/osx`). + +::: + +## Ice 修饰符: atpull'…' + +Copying file is safe for doing later updates – original files of the repository are unmodified and `Git` will report no conflicts. However, `mv` also can be used, if a proper `atpull`, an ice-modifier ran at **update** of the plugin: + +```shell showLineNumbers +zi ice as"program" mv"httpstat.sh -> httpstat" \ + pick"httpstat" atpull'!git reset --hard' +zi light b4b4r07/httpstat +``` + +If `atpull` starts with an exclamation mark, then it will be run before `git pull`, and before `mv`. Nevertheless, `atpull`, `mv`, and `cp` are run **only if new commits are to be fetched**. + +So in summary, when the user runs `zi update b4b4r07/httpstat` to update this plugin, and there are new commits, what happens first is that `git reset --hard` is run – and it **restores** original `httpstat.sh`, **then** `git pull` is ran and it downloads new commits (doing fast-forward), **then** `mv` is running again so that the command is `httpstat` not `httpstat.sh`. + +This way the `mv` ice can be used to induce permanent changes into the plugin's contents without blocking the ability to update it with `git` or with `subversion` in the case of snippets. + +:::info + +For exclamation marks to not be expanded by Zsh an interactive session, use `'…'` not `"…"` to enclose contents of `atpull` [ice-modifier](/search?q=ice-modifier). + +::: + +## Ice 修饰符: subscribe'…' + +Ice修饰符延迟加载加载一个插件，同时检查给定文件的修改时间。当给定文件发生变化时，它就会触发插件或片段的加载。 + +Copy and paste the example below to the terminal or add it to the `.zshrc` file and reload the shell with `exec zsh`. + +```shell {1} showLineNumbers +zi ice subscribe'{~/files-*,/tmp/files-*}' id-as'z-sub' lucid \ + atload'+zi-message "{profile}I have been loaded{nl}\ + {auto}\`Zi Rocks ♥\`"' notify"Yes that is cool ♥ " +zi load z-shell/0 +``` + +按照上面订阅的内容更新文件，测试 Ice 修饰符： + +```shell +touch ~/files-1 +``` + +该插件或片段将随着文件的更新而被 source 。 + +## 片段 as'…' program + +Commands can also be added to `$PATH` using **snippets**: + +```shell {2} showLineNumbers +zi ice mv"httpstat.sh -> httpstat" \ + pick"httpstat" as"program" +zi snippet https://github.com/b4b4r07/httpstat/blob/master/httpstat.sh +``` + +:::tip + +Snippets also support `atpull`, e.g. `atpull'!svn revert'`. There’s also an `atinit` ice-modifier, executed before each loading of plugin or snippet. + +::: + +## 片段 as'…' completion + +By using the `as'…'` ice modifier with the value `completion` you can point the `snippet` subcommand directly to a completion file: + +```shell {1} showLineNumbers +zi ice as"completion" +zi snippet https://github.com/docker/cli/blob/master/contrib/completion/zsh/_docker +``` + +## 补全管理 + +Zi允许在每个插件中禁用和启用每个补全。 尝试安装一个提供补全的热门插件： + +```shell {1} showLineNumbers +zi ice blockf +zi light zsh-users/zsh-completions +``` + +The first command, the `blockf` ice, will block the traditional method of adding completions. Zi uses this method, based on symlinks instead of adding several directories to `$fpath`. Zi will automatically **install** completions of a newly downloaded plugin. + +要卸载或安装补全： + +卸载： + +```shell +zi cuninstall zsh-users/zsh-completions +``` + +安装： + +```shell +zi creinstall zsh-users/zsh-completions +``` + +### 列出可用补全 + +To see what completions **all** plugins provide, in tabular formatting and with the name of each plugin: + +```shell +zi clist +``` + +This command is adapted for plugins like `zsh-users/zsh-completions`, which provide many completions – listing will have `3` completions per line, and a smaller number of terminal pages can be occupied like this: + + + +To show more completions per line by providing an **argument** to `clist`, e.g.: `zi clist 6`, will show: + + + +### 启用/禁用 - 补全 + +可以禁用补全功能，并使用其他补全功能，例如 Zsh 的内置补全。 The commands are very basic, they only need completion **name**: + +Disable `cmake` completion: + +```shell +zi cdisable cmake +``` + +Enable `cmake` completion: + +```shell +zi cenable cmake +``` + +Command `zi csearch` will **search** all plugin directories for available completions: + + + +## 对子目录的 subversion + +In general, to use **subdirectories** of Github projects as snippets add `/trunk/{path-to-dir}` to the URL: + +```shell showLineNumbers +zi ice svn +zi snippet https://github.com/zsh-users/zsh-completions/trunk/src +``` + +:::tip + +For Oh-My-Zsh and Prezto, the OMZ:: and PZT:: prefixes work without the need to add the `/trunk/` infix, however, the path should point to a directory, not to a file. + +::: + +```shell showLineNumbers +zi ice svn +zi snippet PZT::modules/docker +``` + +## Turbo Mode (Zsh >= 5.3) {#turbo-mode-zsh--53} + +The ice-modifier `wait` allows the user to postpone the loading of a plugin to the moment when the processing of `.zshrc` is finished and the first prompt is shown. + +它就像 Windows 的逻辑 —— 启动过程中，它首先显示一个桌面，然后在后台继续加载数据。 这种做法有缺点，但肯定比 10 分钟的空白屏幕要好。 但在 Zi 中，这种方法没有任何缺点 —— 没有延迟、冻结等问题。—— 在加载插件的过程中，命令行仍然完全可用，无论以这种方法加载了多少插件。 + +:::info + +Turbo will speed up Zsh startup by **50%–80%**. 例如，从 200 ms 加速到 40 ms。 + +::: + +:::note + +需要 Zsh 5.3 及以上的版本。 + +::: + +To use turbo mode add `wait` ice to the target plugin in one of the following ways: + +```shell {2} showLineNumbers +PS1="READY > " +zi ice wait'!0' +zi load halfo/lambda-mod-zsh-theme +``` + +This sets plugin `halfo/lambda-mod-zsh-theme` to be loaded `0` seconds after `.zshrc`. It will fire up after c.a. 1 ms of showing the basic prompt `READY >`. + +You probably won't load the prompt in such a way, however, it is a good example in which turbo mode can be observed. The exclamation mark causes Zi to reset the prompt after loading the plugin – commonly needed for themes. The same with Prezto prompts, with a longer delay: + +```shell showLineNumbers +zi ice svn silent wait'!1' atload'prompt smiley' +zi snippet PZT::modules/prompt +``` + +Using `zsh-users/zsh-autosuggestions` without any drawbacks: + +```shell showLineNumbers +zi ice wait lucid atload'!_zsh_autosuggest_start' +zi light zsh-users/zsh-autosuggestions +``` + +### Turbo mode is the key to the performance + +Turbo 模式可以异步地加载，这在插件数量增加时作用重大。 Usually used as `zi ice wait''`. + +:::note + +The `wait` is equivalent to `wait'0'`. + +::: + +```shell showLineNumbers +zi ice wait +zi load z-shell/H-S-MW +``` + +2秒后加载： + +```shell showLineNumbers +zi ice wait'2' +zi load z-shell/H-S-MW +``` + +Also can be used in `light` and `snippet`: + +```shell showLineNumbers +zi ice wait +zi snippet https://gist.githubusercontent.com/hightemp/5071909/raw/ +``` + +### Turbo mode & lucid + +Turbo and lucid are the most used options because turbo mode is verbose and may require an option for quiet and this can be achieved with the `lucid`. + +```shell showLineNumbers +zi ice wait lucid +zi load z-shell/H-S-MW +``` + +## 带有复杂命令行提示符的 Turbo 模式 + +For some, mostly advanced themes the initialization of the prompt is being done in a `precmd`-hook, i.e.; in a function that gets called before each prompt. The hook is installed by the [add-zsh-hook][12] Zsh function by adding its name to the `$precmd_functions` array. + +To make the prompt fully initialized after turbo mode loading in the middle of the prompt the same situation as with the `zsh-autosuggestions` plugin, the hook should be called from `atload'…'` ice. + +First, find the name of the hook function by examining the `$precmd_functions` array. For example, for the `robobenklein/zinc` theme, they'll be two functions: `prompt_zinc_setup` and `prompt_zinc_precmd`: + +```shell title="print $precmd_functions" +_zsh_autosuggest_start prompt_zinc_setup prompt_zinc_precmd +``` + +Then, add them to the ice list in the `atload'…'` ice: + +```shell {2} showLineNumbers +zi ice wait'!' lucid nocd \ + atload'!prompt_zinc_setup; prompt_zinc_precmd' +zi load robobenklein/zinc +``` + +The exclamation mark in `atload'!…'` is to track the functions allowing the plugin to be unloaded, as described [here](/docs/guides/syntax/standard#atclone-atpull-atinit-atload). 它可能对接下来描述的命令行多重提示符设置很有用。 + +### Turbo 方式的总结 + +Autosuggestions use the `precmd` hook, which is being called right after processing `.zshrc` – `precmd` hooks are being called **right before displaying each prompt**. + +Turbo mode with the empty `wait` ice will postpone the loading `1` ms after that, so `precmd` will not be called at that first prompt. 这将使自动提示在第一行提示符无法支持这些命令。 + +**However** the given `atload'…'` ice-modifier fixes this, it calls the same function that `precmd` would, right after loading autosuggestions, resulting in the same behavior of the plugin. + +The ice called `lucid` causes the under-prompt message saying `Loaded zsh-users/zsh-autosuggestions` that normally appears for every Turbo-loaded plugin to not show. + +## Automatic condition based - load & unload + +Ices `load` and `unload` allow defining when you want plugins active or inactive: + +Load when in `~/tmp`: + +```shell {1} showLineNumbers +zi ice load'![[ $PWD = */tmp* ]]' unload'![[ $PWD != */tmp* ]]' \ + atload'!promptinit; prompt sprint3' +zi load z-shell/zprompts +``` + + + +Load when NOT in `~/tmp`: + +```shell {1} showLineNumbers +zi ice load'![[ $PWD != */tmp* ]]' unload'![[ $PWD = */tmp* ]]' +zi load russjohnson/angry-fly-zsh +``` + + + +Two prompts, each active in different directories. This technique can be used to have plugin-sets, e.g. by defining parameter `$PLUGINS` with possible values like `cpp`, `web`, `admin` and by setting `load` / `unload` conditions to activate different plugins on `cpp`, on `web`, etc. + +:::note + +- The difference with `wait` is that `load` / `unload` are constantly active, not only till the first activation. Note that for the unloading of a plugin to work the plugin needs to be loaded with tracking, so `zi load …` and not `zi light …`. + +Tracking causes a slight slowdown, however, this doesn’t influence Zsh startup time when using turbo mode. + +::: + +### A Glance at the prompts + +:::tip + +See: multiple prompts or more information. It contains more real-world examples of a multi-prompt setup, which is close to what the author uses in his setup. + +::: + +This is [powerlevel10k](https://github.com/romkatv/powerlevel10k), [pure](https://github.com/sindresorhus/pure), [starship](https://github.com/starship/starship) sample: + +Load powerlevel10k theme: + +```shell title="~/.zshrc" showLineNumbers +zi ice depth"1" +zi light romkatv/powerlevel10k +``` + +Load pure theme: + +> will pick the `async.zsh` library and will source it. + +```shell {1} title="~/.zshrc" showLineNumbers +zi ice pick"async.zsh" src"pure.zsh" +zi light sindresorhus/pure +``` + +Load starship theme: + +> - pick `starship` binary as a command, from the GitHub release. +> - setup `starship` using `atclone` and create `init.zsh` and `completion`. +> - the `atpull'…'` behavior same as `atclone'…'` and but is used when running `zi update`. +> - `src` will source `init.zsh`. + +```shell {2} {3} title="~/.zshrc" showLineNumbers +zi ice as"command" from"gh-r" \ + atclone"./starship init zsh > init.zsh; ./starship completions zsh > _starship" \ + atpull"%atclone" src"init.zsh" +zi light starship/starship +``` + +### Common use cases {#common-use-cases} + +Load the pure theme, with the **zsh-async** library that's bundled with it. + +```shell title="~/.zshrc" showLineNumbers +zi ice pick"async.zsh" src"pure.zsh" +zi light sindresorhus/pure +``` + +Binary release in the archive, from GitHub. After automatic unpacking, it provides the program "fzf". + +```shell title="~/.zshrc" showLineNumbers +zi ice from"gh-r" as"program" +zi light junegunn/fzf +``` + +One other binary release needs renaming from `docker-compose-Linux-x86_64`. This can be done by [ice modifier][1]: `mv'{from} -> {to}'`. + +There are multiple packages per single version for OS X, Linux, and Windows – the ice-modifier `bpick` is utilized to select the Linux package – in this case - not required, Zi will grep operating system name and architecture automatically when there's no `bpick`. + +```shell title="~/.zshrc" showLineNumbers +zi ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*" +zi load docker/compose +``` + +Handle completions without loading any plugin, see the `clist` command. This one is to be run just once, in an interactive session. + +```shell title="~/.zshrc" +zi creinstall %HOME/my_completions +``` + +If you are interested to try out more then check out the [playground repository](https://github.com/z-shell/playground) where users have uploaded the `~/.zshrc` and other Zi configurations. Feel free to [submit](https://github.com/z-shell/playground/issues/new?template=request-to-add-zshrc-to-the-zi-configs-repo.md) your `~/.zshrc` configuration. + +Additional examples: [collection](/community/gallery/collection). + + + + + +[1]: /search?q=ice+modifiers + +[12]: /community/zsh_plugin_standard#use-of-add-zsh-hook-to-install-hooks diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx new file mode 100644 index 00000000..54c009a5 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/03_migration.mdx @@ -0,0 +1,476 @@ +--- +id: migration +title: ♻️ 迁移 +image: /img/png/theme/z/320x320.png +description: Migration Guide +keywords: + - prezto + - oh-my-zsh +--- + +import Link from "@docusaurus/Link"; + +## Oh-My-Zsh + +### OMZ shorthand syntax + +```shell title="~/.zshrc" showLineNumbers +zi snippet # Raw syntax with URL +zi snippet OMZ:: # Shorthand OMZ:: (http://github.com/ohmyzsh/ohmyzsh/raw/master/) +zi snippet OMZL:: # Shorthand OMZ::lib (http://github.com/ohmyzsh/ohmyzsh/raw/master/lib) +zi snippet OMZT:: # Shorthand OMZ::themes (http://github.com/ohmyzsh/ohmyzsh/raw/master/themes) +zi snippet OMZP:: # Shorthand OMZ::plugins (http://github.com/ohmyzsh/ohmyzsh/raw/master/plugins) +``` + +### OMZ library + +Importing the [clipboard][omz/clipboard] and [termsupport][omz/termsupport] from the OMZ library example: + +Raw syntax: + +```shell title="~/.zshrc" showLineNumbers +zi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh +zi snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh +``` + +OMZ shorthand syntax: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZ::lib/clipboard.zsh +zi snippet OMZ::lib/termsupport.zsh +``` + +OMZL shorthand syntax: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZL::clipboard.zsh +zi snippet OMZL::termsupport.zsh +``` + +Example of more advanced, library loading using subversion: + +```shell title="~/.zshrc" showLineNumbers +if (( $+commands[svn] )) { + sni=({git,theme-and-appearance,prompt_info_functions,history,completion,vcs_info}.zsh) + zi is-snippet has'svn' for svn \ + multisrc'${sni[*]}' pick'/dev/null' \ + atinit'typeset -gx COMPLETION_WAITING_DOTS=true \ + HISTSIZE=290000 SAVEHIST=290000 HISTFILE=${ZSH_CACHE_DIR}/.history;' \ + OMZ::lib + unset sni +} else { + +zi-message "{auto}Subversion not installed!" +} +``` + +### OMZ plugins + +```diff title="~/.zshrc" showLineNumbers +- plugins=( +- git +- dotenv +- rake +- rbenv +- ruby +-) + ++ zi snippet OMZP::git ++ zi snippet OMZP::dotenv ++ zi snippet OMZP::rake ++ zi snippet OMZP::rbenv ++ zi snippet OMZP::ruby +``` + +Example of more advanced, conditional turbo loading: + +```shell title="~/.zshrc" showLineNumbers +zi is-snippet wait lucid for \ + atload"unalias grv g" \ + OMZP::{git,sudo,encode64,extract} \ + if'[[ -d /opt/google-cloud-sdk ]]' \ + OMZP::gcloud \ + if'[[ -f /etc/os-release ]] && source /etc/os-release && [[ "$ID" = arch ]]' \ + OMZP::archlinux \ + if'[[ -d ~/.nvm ]]' \ + OMZP::nvm \ + if'[[ -d ~/.ssh ]]' \ + OMZP::ssh-agent \ + if'[[ -d ~/.gnupg ]]' \ + OMZP::gpg-agent \ + if'[[ "$OSTYPE" = *-gnu ]]' \ + OMZP::gnu-utils \ + has'pip' \ + OMZP::pip \ + has'python' \ + OMZP::python +``` + +:::tip + +Bundle the example above to a single file: + +`zi snippet 有些主题可能需要额外的配置，它可以从主题配置文件中确定。 + +- Load `git` library +- Load the `git` plugin +- Load library dependencies +- Enable `setopt prompt_subst` + +If any of the above are not in order or missing, the theme will break similar as shown below: + +```shell +… $(build_prompt) … +``` + +If the `Git` library is not loaded or loaded in the wrong order, then it may appear similar to the following: + +```shell showLineNumbers +........:1: command not found: git_prompt_status +........:1: command not found: git_prompt_short_sha +``` + +If you encounter any issue with the theme, OMZ support libraries are to be loaded + +- If your theme isn't colored when it should, you will want to load `theme-and-appearance.zsh` + +- If you encounter an error message similar to: + +```shell showLineNumbers +zsh: command not found: ruby_prompt_info +``` + +You need to load `prompt_info_functions.zsh` + +All together it looks like this: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZL::git.zsh +zi snippet OMZP::git +zi snippet OMZL::theme-and-appearance.zsh +zi snippet OMZL::prompt_info_functions.zsh +``` + +Then load the prompt: + +```shell showLineNumbers +setopt prompt_subst +zi snippet OMZT::robbyrussell +``` + +### External theme sample: [NicoSantangelo/Alpharized][] + +Load with OMZ: + +```shell title="~/.zshrc" +ZSH_THEME="alpharized" +``` + +Load `git` library from OMZ: + +```shell title="~/.zshrc" +zi snippet OMZL::git.zsh +``` + +Load `git` plugin from OMZ: + +```shell title="~/.zshrc" showLineNumbers +zi snippet OMZP::git +zi cdclear -q +``` + +Then load the prompt: + +```shell title="~/.zshrc" showLineNumbers +setopt prompt_subst +zi light NicoSantangelo/Alpharized +``` + +## Prezto + +### PZT shorthand syntax + +```shell title="~/.zshrc" showLineNumbers +zi snippet # Raw syntax with URL +zi snippet PZT:: # Shorthand PZT:: (https://github.com/sorin-ionescu/prezto/tree/master/) +zi snippet PZTM:: # Shorthand PZT::modules/ (https://github.com/sorin-ionescu/prezto/tree/master/modules/) +``` + +### PZT modules {#pzt-modules} + +Importing the [environment](https://github.com/sorin-ionescu/prezto/tree/master/modules/environment/README.md) and [terminal](https://github.com/sorin-ionescu/prezto/tree/master/modules/terminal/README.md) Prezto modules example: + +Raw syntax + +```shell title="~/.zshrc" showLineNumbers +zi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/environment/init.zsh +zi snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/terminal/init.zsh +``` + +PZT shorthand syntax: + +```shell title="~/.zshrc" showLineNumbers +zi snippet PZT:: +zi snippet PZT::modules/environment +zi snippet PZT::modules/terminal +``` + +PZTM shorthand syntax: + +```shell title="~/.zshrc" showLineNumbers +zi snippet PZTM:: +zi snippet PZTM::environment +zi snippet PZTM::terminal +``` + +Prezto modules: + +```diff title="~/.zshrc" showLineNumbers +- zstyle ':prezto:load' pmodule 'git' +- zstyle ':prezto:load' pmodule 'environment' 'terminal' + ++ zi snippet PZTM::git ++ zi is-snippet for PZTM::environment PZTM::terminal +``` + +Available Prezto modules: + +| Module name | Description | +| -------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | +| [archive](https://github.com/sorin-ionescu/prezto/blob/master/modules/archive/README.md) | Provides functions to list and extract archives. | +| [autosuggestions](https://github.com/sorin-ionescu/prezto/blob/master/modules/autosuggestions/README.md) | Integrates `zsh-autosuggestions` plugin into Prezto. | +| [command-not-found](https://github.com/sorin-ionescu/prezto/tree/master/modules/command-not-found/README.md) | Loads the `command-not-found` tool on macOS or Debian-based distributions. | +| [completion](https://github.com/sorin-ionescu/prezto/tree/master/modules/completion/README.md) | Sets TAB completion and provides additional completions from the `zsh-completions`. | +| [directory](https://github.com/sorin-ionescu/prezto/tree/master/modules/directory/README.md) | Sets directory options and defines directory aliases. | +| [dnf](https://github.com/sorin-ionescu/prezto/tree/master/modules/dnf/README.md) | Defines `dnf` aliases. | +| [docker](https://github.com/sorin-ionescu/prezto/tree/master/modules/docker/README.md) | Defines `docker` aliases and functions. | +| [dpkg](https://github.com/sorin-ionescu/prezto/tree/master/modules/dpkg/README.md) | Defines `dpkg` aliases and functions. | +| [editor](https://github.com/sorin-ionescu/prezto/tree/master/modules/editor/README.md) | Sets key bindings. | +| [emacs](https://github.com/sorin-ionescu/prezto/tree/master/modules/emacs/README.md) | Enables Emacs dependency management. | +| [environment](https://github.com/sorin-ionescu/prezto/tree/master/modules/environment/README.md) | Sets general shell options and defines environment variables. | +| [fasd](https://github.com/sorin-ionescu/prezto/tree/master/modules/fasd/README.md) | Maintains a frequently used file and directory list for fast access. | +| [git](https://github.com/sorin-ionescu/prezto/tree/master/modules/git/README.md) | Enhances the Git by providing aliases, functions and by exposing repository status information to prompts. | +| [gnu-utility](https://github.com/sorin-ionescu/prezto/tree/master/modules/gnu-utility/README.md) | Provides for the interactive use of GNU utilities on non-GNU systems. | +| [gpg](https://github.com/sorin-ionescu/prezto/tree/master/modules/gpg/README.md) | Provides for an easier use of GPG by setting up `gpg-agent`. | +| [haskell](https://github.com/sorin-ionescu/prezto/tree/master/modules/haskell/README.md) | Enables local Haskell package installation. | +| [helper](https://github.com/sorin-ionescu/prezto/tree/master/modules/helper/README.md) | Provides helper functions for developing modules. | +| [history-substring-search](https://github.com/sorin-ionescu/prezto/tree/master/modules/history-substring-search/README.md) | Integrates zsh-history-substring-search into Prezto. | +| [history](https://github.com/sorin-ionescu/prezto/tree/master/modules/history/README.md) | Sets history options and defines history aliases. | +| [homebrew](https://github.com/sorin-ionescu/prezto/tree/master/modules/homebrew/README.md) | Defines Homebrew aliases. | +| [macports](https://github.com/sorin-ionescu/prezto/tree/master/modules/macports/README.md) | Defines MacPorts aliases and adds MacPorts directories to path variables. | +| [node](https://github.com/sorin-ionescu/prezto/tree/master/modules/node/README.md) | Provides utility functions for Node.js and loads `npm` completion. | +| [ocaml](https://github.com/sorin-ionescu/prezto/tree/master/modules/ocaml/README.md) | Initializes OCaml package management. | +| [osx](https://github.com/sorin-ionescu/prezto/tree/master/modules/osx/README.md) | Defines macOS aliases and functions. | +| [pacman](https://github.com/sorin-ionescu/prezto/tree/master/modules/pacman/README.md) | Provides aliases and functions for the Pacman package manager and frontends. | +| [perl](https://github.com/sorin-ionescu/prezto/tree/master/modules/perl/README.md) | Enables local Perl module installation on macOS and defines aliases. | +| [prompt](https://github.com/sorin-ionescu/prezto/tree/master/modules/prompt/README.md) | Loads prompt themes. | +| [python](https://github.com/sorin-ionescu/prezto/tree/master/modules/python/README.md) | Enables local Python and local Python package installation. | +| [rails](https://github.com/sorin-ionescu/prezto/tree/master/modules/rails/README.md) | Defines Ruby on Rails aliases. | +| [rsync](https://github.com/sorin-ionescu/prezto/tree/master/modules/rsync/README.md) | Defines `rsync` aliases. | +| [ruby](https://github.com/sorin-ionescu/prezto/tree/master/modules/ruby/README.md) | Configures Ruby local gem installation, loads version managers, and defines aliases. | +| [screen](https://github.com/sorin-ionescu/prezto/tree/master/modules/screen/README.md) | Defines GNU Screen aliases and provides for auto launching it at start-up. | +| [spectrum](https://github.com/sorin-ionescu/prezto/tree/master/modules/spectrum/README.md) | Provides for easier use of 256 colors and effects. | +| [ssh](https://github.com/sorin-ionescu/prezto/tree/master/modules/ssh/README.md) | Provides for an easier use of SSH by setting up `ssh-agent`. | +| [syntax-highlighting](https://github.com/sorin-ionescu/prezto/tree/master/modules/syntax-highlighting/README.md) | Integrates `zsh-syntax-highlighting` into Prezto. | +| [terminal](https://github.com/sorin-ionescu/prezto/tree/master/modules/terminal/README.md) | Sets terminal window and tab titles. | +| [tmux](https://github.com/sorin-ionescu/prezto/tree/master/modules/tmux/README.md) | Defines `tmux` aliases and provides for auto launching it at start-up. | +| [utility](https://github.com/sorin-ionescu/prezto/tree/master/modules/utility/README.md) | Defines general aliases and functions. | +| [wakeonlan](https://github.com/sorin-ionescu/prezto/tree/master/modules/wakeonlan/README.md) | This module provides a wrapper around the wakeonlan tool. | +| [yum](https://github.com/sorin-ionescu/prezto/blob/master/modules/autosuggestions/README.md) | Defines yum aliases. | + +Use `zi ice svn` if multiple files require an entire subdirectory. + +- [docker](https://github.com/sorin-ionescu/prezto/tree/master/modules/docker/README.md) +- [git](https://github.com/sorin-ionescu/prezto/tree/master/modules/git/README.md) + +```shell title="~/.zshrc" showLineNumbers +zi ice svn +zi snippet PZTM::docker + +zi ice svn +zi snippet PZTM::git +``` + +Use `zi ice as"null"` no `*.plugin.zsh`, `init.zsh`, `*.zsh-theme*` files exist in module directory. + +- [archive](https://github.com/sorin-ionescu/prezto/tree/master/modules/archive/README.md): + +```shell title="~/.zshrc" showLineNumbers +zi ice svn as"null" +zi snippet PZTM::archive +``` + +Use `zi ice atclone"git clone "` if module have external module. + +- [completion](https://github.com/sorin-ionescu/prezto/tree/master/modules/completion/README.md): + +```shell title="~/.zshrc" showLineNumbers +zi ice svn blockf \ + atclone"git clone --recursive https://github.com/zsh-users/zsh-completions.git external" +zi snippet PZTM::completion +``` + +Use `blockf` to prevent any unnecessary additions to `fpath`, as Zi manages `fpath`. + +:::tip + +What is `zstyle`? + +- Official (zsh.sourceforge.net): [zsh/zutil](https://zsh.sourceforge.net/Doc/Release/Zsh-Modules.html#The-zsh_002fzutil-Module) +- StackExchange: [What does `zstyle` do?][about-zstyle] + +::: + +Available + +## Zgen + +### Load OMZ library + +```diff title="~/.zshrc" showLineNumbers +- zgen oh-my-zsh + ++ zi snippet OMZL:: +``` + +### 加载 OMZ 插件 + +```diff title="~/.zshrc" showLineNumbers +- zgen oh-my-zsh + ++ zi snippet OMZP:: +``` + +### Load Prezto modules + +```diff title="~/.zshrc" showLineNumbers +- zgen prezto + ++ zi snippet PZTM:: +``` + +Load repositories as prezto plugins: + +```diff title="~/.zshrc" showLineNumbers +- zgen pmodule + ++ zi ice ver"" ++ zi load +``` + +### Summarized Zgen + +:::info + +For the `location`: refer src, pick, multisrc ice-modifier. + +::: + +```diff title="~/.zshrc" showLineNumbers +- zgen load [location] [branch] + ++ zi ice ver"[branch]" ++ zi load +``` + +## Zplug 基础知识 + +```diff title="~/.zshrc" showLineNumbers +- zplug , tag1:, tag2: + ++ zi ice tag1"" tag2"" ++ zi load +``` + +### Tag comparison + +- `as` => `as` +- `use` => `pick`, `src`, `multisrc` +- `ignore` => None +- `from` => `from` +- `at` => `ver` +- `rename-to` => `mv`, `cp` +- `dir` => Selection(`pick`, …) with rename +- `if` => `if` +- `hook-build` => `atclone`, `atpull` +- `hook-load` => `atload` +- `frozen` => None +- `on` => None +- `defer` => `wait` +- `lazy` => `autoload` +- `depth` => `depth` + + + + + + + +[about-zstyle]: https://unix.stackexchange.com/questions/214657/what-does-zstyle-do + +[nicosantangelo/alpharized]: https://github.com/nicosantangelo/Alpharized + +[omz/ag]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/ag + +[omz/clipboard]: https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh + +[omz/docker]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker + +[omz/fd]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/fd + +[omz/gitfast]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/gitfast + +[omz/history-substring-search]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/history-substring-search + +[omz/osx]: https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/macos + +[omz/termsupport]: https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/_category_.json new file mode 100644 index 00000000..5880481d --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting_started/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "🚀 开始使用", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/01_commands.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/01_commands.mdx new file mode 100644 index 00000000..8464f54c --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/01_commands.mdx @@ -0,0 +1,262 @@ +--- +id: commands +title: 🛠 Commands +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: Zi subcommands and functionality +slug: commands +--- + + + +import Link from "@docusaurus/Link"; +import APITable from "@site/src/components/APITable"; +import ZiTabCompletion from "@site/src/components/Markdown/_zi_tab_completion.mdx"; + +## Updates {#updates-upgrades} + +To update and recompile Zi run `zi self-update` in the command line. To update all plugins and snippets, issue `zi update`. To update all in parallel (up to 40 at the time) `zi update -p 40` If you wish to update only a single plugin/snippet instead issue `zi update `. A list of commits will be shown if any. + +Some plugins require acting each time they're updated. One way you can do this is by using the `atpull'…'` ice modifier. For example, writing `zi ice atpull'./configure'` before loading a plugin will execute `./configure` after a successful update. Refer to [ice-modifiers][1] for more information. + +The ice-modifiers for any plugin or snippet are stored in their directory in a `._zi` subdirectory, hence the plugin doesn't have to be loaded to be correctly updated. There's one other file created there, `.zi_lstupd` – it holds the log of the new commits pulled-in in the last update. + +Self-update & compile: + +```shell +zi self-update +``` + +Update plugins and snippets: + +```shell showLineNumbers +zi update --all +zi update --reset +zi update --quiet +``` + +Update plugins or snippets: + +```shell showLineNumbers +zi update --plugins +zi update --snippets +``` + +Update specific plugins. Default is GitHub but can specify any with ice [from'…'](/search?q=from): + +```shell +zi update / +``` + +Plugin parallel update plugins: + +```shell +zi update --parallel +``` + +Increase the number of jobs in a concurrent set to 40 + +```shell +zi update --parallel 40 +``` + +## Compinit + +:::note + +Calling `compinit` once is a huge performance gain, for example, shell startup time with double `compinit`: **0.980** sec, with `cdreplay` and single `compinit`: **0.156** sec. + +::: + +### Calling `compinit` without turbo mode + +With no turbo mode in use, compinit can be called normally, i.e.: as `autoload compinit; compinit`. This should be done after loading all plugins and before possibly calling `zi cdreplay`. The `cdreplay` subcommand is provided to re-play all caught `compdef` calls. The `compdef` calls are used to define a completion for a command. For example, `compdef _git git` defines that the `git` command should be completed by a `_git` function. The `compdef` function is provided by the `compinit` call. + +As it should be called later, after loading all of the plugins, Zi provides its own `compdef` function that catches (i.e.: records in an array) the arguments of the call, so that the loaded plugins can freely call `compdef`. Then, the `cdreplay` (compdef-replay) can be used, after `compinit` will be called (and the original `compdef` function will become available), to execute all detected `compdef` calls. + +```shell title="~/.zshrc" showLineNumbers +source ~/.zi/bin/zi.zsh + +zi load "some/plugin" + +(…) + +compdef _gnu_generic fd # this will be intercepted by ZI, because as the compinit + # isn't yet loaded, thus there's no such function `compdef'; yet + # ZI provides its own `compdef' function which saves the + # completion-definition for later possible re-run with `zi + # cdreplay' or `zicdreplay' (the second one can be used in hooks + # like atload'…', atinit'…', etc.) + +(…) + +zi load "other/plugin" + +autoload -Uz compinit +compinit + +zi cdreplay -q # -q is for quiet; actually, run all the `compdef's saved before + #`compinit` call (`compinit' declares the `compdef' function, so + # it cannot be used until `compinit' is run; ZI solves this + # via intercepting the `compdef'-calls and storing them for later + # use with `zi cdreplay') +``` + +### Calling `compinit` with turbo mode + +If you load completions using `wait'…'` [turbo mode][2] then you can add `atinit'zicompinit'` to the syntax-highlighting plugin (which should be the last one loaded, as their (2 projects, [zsh-syntax-highlighting][3] & [F-Sy-H][4]) documentation state), or `atload'zicompinit'` to last completion-related plugin. `zicompinit` is a function that just runs `autoload compinit; compinit`, created for convenience. + +Alternatively, the `zicompinit` can be replaced with `zicompinit_fast` which checks the cached `.zcompdump` and determines when to regenerate the file. This restricts checking it once a day, as compinit doesn't always need to modify the compdump and compiles mapped to share in the background in multiple shells. + +There's also `zicdreplay` which will replay any caught compdefs so you can also do: `atinit'zicompinit; zicdreplay'`, etc. + +It is recommended to run the `compinit` call in the `atinit` or `atload` hook of the last related plugin with the use of the helper functions `zicompinit`,`zicdreplay` & `zicdclear` as shown below: + +```shell {10} title="~/.zshrc" showLineNumbers +source ~/.zi/bin/zi.zsh + +# Load using the for-syntax +zi wait lucid for \ + "some/plugin" + +zi wait lucid for \ + "other/plugin" + +zi wait lucid atload"zicompinit; zicdreplay" blockf for \ + zsh-users/zsh-completions +``` + +### Ignoring compdefs + +If you want to ignore compdefs provided by some plugins or snippets, place their load commands before commands loading other plugins or snippets, and issue `zi cdclear` (or `zicdclear`, designed to be used in hooks like `atload'…'`): + +```shell showLineNumbers +source ~/.zi/bin/zi.zsh +zi snippet OMZP::git +zi cdclear -q # <- forget completions provided by Git plugin + +zi load "some/plugin" + +(…) + +zi load "other/plugin" + +autoload -Uz compinit +compinit +zi cdreplay -q # <- execute compdefs provided by rest of plugins +zi cdlist # look at gathered compdefs +``` + +The `cdreplay` is important if you use plugins like `OMZP::kubectl` or `asdf-vm/asdf` because these plugins call `compdef`. + +Following commands are passed to `zi …` to obtain described effects. + +## Loading and unloading + +| Command | Description | +| :------------------: | ------------------------------------------------------------------------------------------------- | +| `load` `'…'` | Load plugin, can also receive absolute local path. | +| `light` `-b` `'…'` | Light plugin load, without reporting/investigating. `-b` – investigate `bindkey`-calls only. [^1] | +| `unload` `-q` `'…'` | Unload plugin loaded with `zi load …`. `-q` – quiet. | +| `snippet` `-f` `URL` | Source local (full path) or remote file (URL). `-f` – don't use cache (force re-download). [^2] | + +## Completions management + +| Command | Description | +| :------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------- | +| `clist` `columns` or `completions` `columns` | List completions in use, with `columns` completions per line. `zi clist 5` will for example print 5 completions per line. Default is 3. | +| `cdisable` `'…'` | Disable completion. | +| `cenable` `'…'` | Enable completion. | +| `creinstall` `-q` `-Q` `'…'` | Install completions for the plugin, can also receive absolute local path. `-q` – quiet. `-Q` - quiet all. | +| `cuninstall '…'` | Uninstall completions for the plugin. | +| `csearch` | Search for available completions from any plugin. | +| `compinit` | Refresh installed completions. | +| `cclear` | Clear stray and improper completions. | +| `cdlist` | Show compdef replay list. | +| `cdreplay` `-q` | Replay compdefs (to be done after compinit). `-q` – quiet. | +| `cdclear` `-q` | Clear compdef replay list. `-q` – quiet. | + +## Tracking of the active session + +| Command | Description | +| :--------------: | ----------------------------------------------------- | +| `dtrace, dstart` | Start investigating what's going on in the session. | +| `dstop` | Stop investigating what's going on in the session. | +| `dunload` | Revert changes recorded between `dstart` and `dstop`. | +| `dreport` | Report what was going on in the session. | +| `dclear` | Clear report of what was going on in the session. | + +## Reports and statistics + +| Command | Description | +| :-----------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `times` `-s` `-m` `-a` | Statistics on plugin load times, sorted in order of loading. `-s` – use seconds instead of milliseconds. `-m` – show plugin loading moments and `-a` both. | +| `zstatus` | Overall ZI status. | +| `report` `'…'` `--all` | Show plugin report. `--all` – do it for all plugins. | +| `loaded` | Show loaded plugins | +| `list` `keyword` | Filter loaded plugins with only 'keyword' | +| `ls` | List snippets in a formatted and colorized manner. Requires **tree** program. | +| `status` `'…'` or `URL` `--all` | Git status for plugin or svn status for the snippet. `--all` – do it for all plugins and snippets. | +| `recently` `time-spec` | Show plugins that changed recently, the argument is e.g. 1 month 2 days. | +| `bindkeys` | Lists bindkeys set up by each plugin. | + +## Compiling + +| Command | Description | +| :-----------------------: | ----------------------------------------------------------------------- | +| `compile` `'…'` `--all` | Compile plugin. `--all` – compile all plugins. | +| `uncompile` `'…'` `--all` | Remove compiled version of the plugin. `--all` – do it for all plugins. | +| `compiled` | List plugins that are compiled. | + +## Other commands + +| Command | Description | +| :------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `self-update` | Updates and compiles Zi. | +| `update` `-q` `-r` `'…'` or `--all` | Update all plugins and snippets with `--all` – for quiet `-q` – execute `git reset --hard` or `svn revert` before pulling changes with `-r`. | +| `ice '…'` | Add ice to next command, argument e.g.: from"gitlab". | +| `delete` `'…'` or `--clean` `--all` | Remove plugin or snippet from disk (good to forget wrongly passed ice-modifiers) `--all` – delete plugins and snippets that are not loaded with `--clean`. | +| `cd '…'` | Jump into the plugin's directory. Also support snippets if fed with URL. | +| `edit '…'` | Edit plugin's file with set $EDITOR. | +| `glance '…'` | Look at plugin's source (pygmentize, source-highlight). | +| `stress '…'` | Test plugin for compatibility with a set of options. | +| `changes '…'` | View plugin's git log. | +| `create '…'` | Create plugin (also together with GitHub repository). | +| `srv` `service-id` `{command}` | Control a service, command can be: stop,start,restart,next,quit; `next` moves the service to another Z shell. | +| `recall '…'` `URL` | Fetch saved ice modifiers and construct `zi ice '…'` command. | +| `env-whitelist` `-v` `-h` `{env..}` | Allows to specify names or patterns of variables left unchanged during an unload – verbose `-v` – help `-h`. | +| `module` | Manage binary Zsh module shipped with ZI, see `zi module help`. | +| `add-fpath` `fpath` `-f` `--front` `'…'` `sub-directory` | Adds given plugin (not yet snippet) directory to `$fpath`. If the second argument is given, it is appended to the directory path. [^3] | +| `run` `-l` `plugin` `{command}` | Runs the given command in the given plugin's directory. [^4] | + +## Help & manual + +| Command | Description | +| :--------: | ------------------ | +| `-h, help` | Usage information. | +| `man` | Manual. | + +## Commands available using ^TAB completion + + + + + + + +[^1]: There's also `light-mode` ice which can be used to induce the no-investigating (i.e.: _light_) loading, regardless of the command used. +[^2]: The URL can use the following shorthands: `PZT::` (Prezto), `PZTM::` (Prezto module), `OMZ::` (Oh-My-Zsh), `OMZP::` (OMZ plugin), `OMZL::` (OMZ library), `OMZT::` (OMZ theme), e.g.: `PZTM::environment`, `OMZP::git`, etc. +[^3]: The `'…'` can be an absolute path, i.e.: it's possible to also add regular directories. If the option `-f` or `--front` is given, the directory path is prepended instead of appended to `$fpath`. +[^4]: If the option `-l` will be given then the plugin should be skipped – the option will cause the previous plugin to be reused. + + + +[1]: /search/?q=ice-modifiers + +[2]: /search?q=turbo+mode + + + +[3]: https://github.com/zsh-users/zsh-syntax-highlighting + +[4]: https://github.com/z-shell/F-Sy-H diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/02_customization.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/02_customization.mdx new file mode 100644 index 00000000..556e8abc --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/02_customization.mdx @@ -0,0 +1,331 @@ +--- +id: customization +title: 🏗 Configuration management +sidebar_position: 2 +image: /img/png/theme/z/320x320.png +description: User preferences, environment, and configuration. +keywords: + - config + - preferences +--- + + + +import APITable from "@site/src/components/APITable"; +import MultiplePromptsExample from "@site/src/components/Markdown/_multiple_prompts_example.mdx"; + +## Hash parameter + +:::info Related + +- [standard parameter naming][] + +::: + +Set the initial hash definition and custom values, before enabling Zi. + +Example: + +```shell showLineNumbers +typeset -A ZI +ZI[BIN_DIR]="some/custom/path/to/bin" +source "${ZI[BIN_DIR]}/zi.zsh" +``` + +### Customize paths {#customizing-paths} + +```mdx-code-block + +``` + +| Hash Field | Default | Description | +| ------------------------------------ | ----------------------------- | ---------------------------------------------- | +| `ZI[HOME_DIR]` | `$HOME/.zi` | Where Zi should create all working directories | +| `ZI[BIN_DIR]` | `$HOME/.zi/bin` | Directory where Zi code resides | +| `ZI[COMPLETIONS_DIR]` | `$ZI[HOME_DIR]/completions` | Completion working directory | +| `ZI[CACHE_DIR]` | `$HOME/.cache/zi` | Cache directory | +| `ZI[CONFIG_DIR]` | `$HOME/.config/zi` | Directory for configuration files | +| `ZI[MAN_DIR]` | `$ZPFX/man` | Directory to store manpages | +| `ZI[LOG_DIR]` | `$ZI[CACHE_DIR]/log` | Directory to store log files | +| `ZI[PLUGINS_DIR]` | `$ZI[HOME_DIR]/plugins` | Plugins working directory | +| `ZI[SNIPPETS_DIR]` | `$ZI[HOME_DIR]/snippets` | Snippets working directory | +| `ZI[ZCOMPDUMP_PATH]` | `${ZI[CACHE_DIR]}/.zcompdump` | Path to `.zcompdump` file | +| `ZI[ZMODULES_DIR]` | `$ZI[HOME_DIR]/zmodules` | Zsh modules working directory | +| [ZPFX][global-parameter-with-prefix] | `$ZI[HOME_DIR]/polaris` | Directory to store binary and related files | + +```mdx-code-block + +``` + +### Modify settings {#modify-settings} + +```mdx-code-block + +``` + +| Hash Field | Default | Description | +| -------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ZI[OPTIMIZE_OUT_DISK_ACCESSES]` | `undefined` | If set to `1`, will skip checking if a turbo-loaded object exists on the disk. This option can give a performance gain of about 10 ms out of 150 ms (e.g: Zsh will start up in 140 ms instead of 150 ms). | +| `ZI[COMPINIT_OPTS]` | `undefined` | Options for `compinit` call (e.g: done by `zicompinit`), commonly used with `-C` to speed up loading | +| `ZI[MUTE_WARNINGS]` | `undefined` | If set to `1`, mutes some warnings, specifically the `plugin already registered` warning | +| `ZI[PKG_OWNER]` | `z-shell` | Owner of the [packages][] (`zi pack …`) | + +```mdx-code-block + +``` + +## Non-GitHub (Local) Plugins {#non-github-local-plugins} + +Use the `create` subcommand with user name `_local` (the default) to create the plugin's skeleton in `$ZI[PLUGINS_DIR]`. It will be not connected with the GitHub repository (because of the user name being `_local`). To enter the plugin's directory use the `cd` command with just the plugin's name (without `_local`, it's optional). + +If the username is not `_local`, then Zi will create a repository also on GitHub and set up the correct repository origin. + +## Extending Git {#extending-git} + +Several projects provide git extensions. Installing them with Zi has many benefits: + +- all files are under `$HOME` – no administrator rights are needed, +- declarative setup (like Chef or Puppet) – copying `.zshrc` to a different account brings also git-related setup, +- easy update by e.g: `zi update --all`. + +Below is a configuration that adds multiple git extensions, loaded in Turbo mode, 1 second after prompt, with the use of the [bin-gem-node][z-shell/z-a-bin-gem-node] annex: + +```shell title="~/.zshrc" showLineNumbers +zi as'null' wait'1' lucid for \ + sbin Fakerr/git-recall \ + sbin cloneopts paulirish/git-open \ + sbin paulirish/git-recent \ + sbin davidosomething/git-my \ + sbin iwata/git-now \ + sbin atload'export _MENU_THEME=legacy' \ + arzzen/git-quick-stats \ + sbin'bin/git-dsf;bin/diff-so-fancy' \ + z-shell/zsh-diff-so-fancy \ + make'PREFIX=$ZPFX install' \ + tj/git-extras +``` + +The target directory for installed files is `$ZPFX` - `~/.zi/polaris` by default. + +With [meta-plugins][z-shell/z-a-meta-plugins] consisting of: + +Annexes: + +1. [z-shell/z-a-readurl][], +2. [z-shell/z-a-patch-dl][], +3. [z-shell/z-a-rust][], +4. [z-shell/z-a-bin-gem-node][]. + +Git tools: + +1. [paulirish/git-open][], +2. [paulirish/git-recent][], +3. [davidosomething/git-my][], +4. [arzzen/git-quick-stats][], +5. [iwata/git-now][], +6. [tj/git-extras][], +7. [wfxr/forgit][]. + +just run: + +```shell +zi light-mode for z-shell/z-a-meta-plugins @annexes @ext-git +``` + +## [Zsh option][zsh-options]: `setopt` {#zsh-option-setopt} + +[Options][zsh-options] are primarily referred to by name. These names are case insensitive and underscores are ignored. For example, `allexport` is equivalent to `A__lleXP_ort`. + +The sense of an option name may be inverted by preceding it with `no`, so `setopt No_Beep` is equivalent to `unsetopt beep`. This inversion can only be done once, so `nonobeep` is not a synonym for `beep`. Similarly, `tify` is not a synonym for `nonotify` (the inversion of `notify`). + +### History optimization {#history-optimization} + + + +```shell title="~/.zshrc" showLineNumbers +setopt append_history # Allow multiple sessions to append to one Zsh command history. +setopt extended_history # Show timestamp in history. +setopt hist_expire_dups_first # Expire A duplicate event first when trimming history. +setopt hist_find_no_dups # Do not display a previously found event. +setopt hist_ignore_all_dups # Remove older duplicate entries from history. +setopt hist_ignore_dups # Do not record an event that was just recorded again. +setopt hist_ignore_space # Do not record an Event Starting With A Space. +setopt hist_reduce_blanks # Remove superfluous blanks from history items. +setopt hist_save_no_dups # Do not write a duplicate event to the history file. +setopt hist_verify # Do not execute immediately upon history expansion. +setopt inc_append_history # Write to the history file immediately, not when the shell exits. +setopt share_history # Share history between different instances of the shell. +``` + +### Other tweaks {#other-tweaks} + +```shell title="~/.zshrc" showLineNumbers +setopt auto_cd # Use cd by typing directory name if it's not a command. +setopt auto_list # Automatically list choices on ambiguous completion. +setopt auto_pushd # Make cd push the old directory onto the directory stack. +setopt bang_hist # Treat the '!' character, especially during Expansion. +setopt interactive_comments # Comments even in interactive shells. +setopt multios # Implicit tees or cats when multiple redirections are attempted. +setopt no_beep # Don't beep on error. +setopt prompt_subst # Substitution of parameters inside the prompt each time the prompt is drawn. +setopt pushd_ignore_dups # Don't push multiple copies directory onto the directory stack. +setopt pushd_minus # Swap the meaning of cd +1 and cd -1 to the opposite. +``` + +## Style the [completion system][completion-system-configuration] with: `zstyle` {#style-the-completion-system-with-zstyle} + +What does `zstyle` do? - [unix.stackexchange.com/what-does-zstyle-do][what-does-zstyle-do] + +The `zstyle` handles the obvious style control for the [completion system][completion-system-configuration], but it seems to cover more than just that. e.g., the vcs_info module relies on it for the display of git status in your prompt. You can start by looking at the few explanatory paragraphs in `man zshmodules` in the `zstyle` section. + +### Fuzzy matching of completions {#fuzzy-matching-of-completions} + + + +```shell title="~/.zshrc" showLineNumbers +zstyle ':completion:*' completer _complete _match _approximate +zstyle ':completion:*:match:*' original only +zstyle -e ':completion:*:approximate:*' max-errors 'reply=($((($#PREFIX+$#SUFFIX)/3>7?7:($#PREFIX+$#SUFFIX)/3))numeric)' +``` + +### Pretty completions {#pretty-completions} + +```shell title="~/.zshrc" showLineNumbers +zstyle ':completion:*:matches' group 'yes' +zstyle ':completion:*:options' description 'yes' +zstyle ':completion:*:options' auto-description '%d' +zstyle ':completion:*:corrections' format ' %F{green}-- %d (errors: %e) --%f' +zstyle ':completion:*:descriptions' format ' %F{yellow}-- %d --%f' +zstyle ':completion:*:messages' format ' %F{purple} -- %d --%f' +zstyle ':completion:*:warnings' format ' %F{red}-- no matches found --%f' +zstyle ':completion:*:default' list-prompt '%S%M matches%s' +zstyle ':completion:*' format ' %F{yellow}-- %d --%f' +zstyle ':completion:*' group-name '' +zstyle ':completion:*' verbose yes +zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=*' 'l:|=* r:|=*' +zstyle ':completion:*:functions' ignored-patterns '(_*|pre(cmd|exec))' +zstyle ':completion:*' use-cache true +zstyle ':completion:*' rehash true +``` + +### Do menu-driven completion {#do-menu-driven-completion} + +```shell +zstyle ':completion:*' menu select +``` + +### Color completion for [some things][color-completion-using-zsh-modules-on] {#color-completion-for-some-things} + +```shell +zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS} +``` + +## Disabling System-Wide `compinit` Call (Ubuntu) {#disabling-system-wide-compinit-call-ubuntu} + +On Ubuntu users might get surprised that e.g. their completions work while they didn't call `compinit` in their `.zshrc`. That's because the function is being called in `/etc/zshrc`. + +To disable this call – what is needed to avoid the slowdown and if the user loads any completion-equipped plugins, i.e. almost on 100% – add the following line to `~/.zshenv` to skip the not helping Ubuntu global compinit: + +```shell title="~/.zshenv" +skip_global_compinit=1 +``` + +## Multiple prompts {#multiple-prompts} + +```mdx-code-block + +``` + +| Syntax | Description | +| ----------- | :---------------------------------------------------------------- | +| `load'…'` | Condition that when fulfilled will cause the plugin to be loaded. | +| `unload'…'` | Same as above, but will unload the plugin. | + +```mdx-code-block + +``` + +:::note + +`zi light …` loads the plugin without tracking it, while `zi load` tracks the plugin. To be able to unload the plugin, it has to be loaded with `zi load …` instead of `zi light …`. + +::: + +| Syntax | Description | +| ------------ | :---------------------------------------------------------------------------------------------------- | +| `atload'!…'` | Run the `precmd` hooks to make the prompts fully initialized when loaded in the middle of the prompt. | +| `precmd` | Hooks are normally run before each **new** prompt. | + +:::info + +Exclamation mark causes the effects of the functions to be tracked. + +::: + +To allow better unloading, conditions are checked every second, you can use conditions like: + +```mdx-code-block + +``` + +| Condition | Description | +| ------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `![[ $PWD == *github* ]]` | Change prompt after changing directory to `*github*`. | +| `![[ $MYPROMPT = 1 ]]` | Change prompt when variable `MYPROMPT = 1` is true. | +| `![[ … ]]` | The exclamation mark causes the prompt to be reset after loading or unloading the plugin `pick'/dev/null'` – disable sourcing of the default-found file. | +| `multisrc'…'` | Source multiple files. | +| `lucid` | Don't show the under-prompt message that says e.g: `Loaded geometry-zsh/geometry`. | +| `nocd` | Don't cd into the plugin's directory when executing the `atload'…'`. | +| `atload'…'` | This ice can make the path that's displayed by the theme point to that directory. | + +```mdx-code-block + +``` + +### Loading and unloading themes (8 examples) {#loading-and-unloading-themes-8-examples} + + + + + + + +[global-parameter-with-prefix]: /community/zsh_plugin_standard#global-parameter-with-prefix + +[软件包]: /ecosystem/packages/synopsis + +[standard parameter naming]: /community/zsh_plugin_standard#standard-parameter-naming + + + +[arzzen/git-quick-stats]: https://github.com/arzzen/git-quick-stats + +[color-completion-using-zsh-modules-on]: https://linuxshellaccount.blogspot.com/2008/12/color-completion-using-zsh-modules-on.html + +[completion-system-configuration]: https://zsh.sourceforge.io/Doc/Release/Completion-System.html#Completion-System-Configuration + +[davidosomething/git-my]: https://github.com/davidosomething/git-my + +[iwata/git-now]: https://github.com/iwata/git-now + +[paulirish/git-open]: https://github.com/paulirish/git-open + +[paulirish/git-recent]: https://github.com/paulirish/git-recent + +[tj/git-extras]: https://github.com/tj/git-extras + +[wfxr/forgit]: https://github.com/wfxr/forgit + +[what-does-zstyle-do]: https://unix.stackexchange.com/questions/214657/what-does-zstyle-do/239980 + +[z-shell/z-a-bin-gem-node]: https://github.com/z-shell/z-a-bin-gem-node + +[z-shell/z-a-meta-plugins]: https://github.com/z-shell/z-a-meta-plugins + +[z-shell/z-a-patch-dl]: https://github.com/z-shell/z-a-patch-dl + +[z-shell/z-a-readurl]: https://github.com/z-shell/z-a-readurl + +[z-shell/z-a-rust]: https://github.com/z-shell/z-a-rust + +[zsh-options]: https://zsh.sourceforge.io/Doc/Release/Options.html diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx new file mode 100644 index 00000000..3deae97b --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/03_benchmark.mdx @@ -0,0 +1,137 @@ +--- +id: benchmark +title: ⏲ Benchmarking +sidebar_position: 3 +image: /img/png/theme/z/320x320.png +description: Benchmarking, Profiling & Statistics +keywords: + - statistics + - benchmark + - profiling + - reporting +--- + + + +import APITable from "@site/src/components/APITable"; +import ReportZprofExample from "@site/src/components/Markdown/_report_zprof_example.mdx"; + +:::info + +Run `zi analytics` to see the available commands for statistics and reporting. + +::: + +## Profile plugins + +```shell title="~/.zshrc" showLineNumbers +zi ice atinit'zmodload zsh/zprof' \ + atload'zprof | head -n 20; zmodload -u zsh/zprof' +zi light z-shell/F-Sy-H +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ----------- | :----------------------------------------------------------------------------------------------------------------------- | +| `atinit'…'` | loads the `zsh/zprof` module, shipped with Zsh, before loading the plugin – this starts the profiling. | +| `atload'…'` | works after loading the plugin – shows profiling results `zprof / head`, unloads `zsh/zprof` - this stops the profiling. | + +```mdx-code-block + +``` + +While in effect, only a single plugin, in this case, `z-shell/F-Sy-H`, will be profiled. + +The rest plugins will go on completely normally, as when plugins are loaded with `light` - reporting is disabled. + +Less code is being run in the background, the automatic data gathering, during loading of a plugin, for the reports and the possibility to unload the plugin will be activated and the functions will not appear in the `zprof` report. + +Example `zprof` report: + + + +The first column is the time in milliseconds: + +- It denotes the amount of time spent in a function in total +- For example, `--zi-shadow-autoload` consumed 10.71 ms of the execution time + +The fourth column is also a time in milliseconds, but it denotes the amount of time spent on executing only of function's **own code**, it doesn't count the time spent in **descendant functions** that is called from the function: + +- For example, `--zi-shadow-autoload` spent 8.71 ms on executing only its code + +The table is sorted in the **self-time** column. + +## Profile `.zshrc` startup + +### Method 1 + +> `PROFILE_STARTUP=true` to enable profiling. + +Place the snippet below at the top of `.zshrc`. + +```shell title="~/.zshrc" showLineNumbers +PROFILE_STARTUP=false + +if [[ "$PROFILE_STARTUP" == true ]]; then + zmodload zsh/zprof + PS4=$'%D{%M%S%.} %N:%i> ' + exec 3>&2 2>$HOME/startlog.$$ + setopt xtrace prompt_subst +fi +``` + +:::info PS4 Prompt Expansion + +Zsh Sourceforge docs: [Prompt Expansion][prompt-expansion] + +::: + +Place at the bottom of `.zshrc` + +```shell title="~/.zshrc" showLineNumbers +if [[ "$PROFILE_STARTUP" == true ]]; then + unsetopt xtrace + exec 2>&3 3>&-; zprof > ~/zshprofile$(date +'%s') +fi +``` + +The next time your `.zshrc` is sourced it will generate 2 files in the `$HOME` directory. + +### Method 2 + +Store multiple values to a variable: + +```shell title="~/.zshrc" showLineNumbers +# Set variable +typeset -Ag ZLOGS +# Message to store +zmsg() { ZLOGS+=( "\n[$1]: ${(M)$(( SECONDS * 1000 ))#*.?} ms" ); } + +# Start profiling +typeset -F4 SECONDS=0 + +# + +zmsg "Loaded functions" + +# + +zmsg "Loaded something else" + +# + +zmsg "Done" +``` + +Then use the `$ZLOGS` variable to retrieve: + +```shell title="print $ZLOGS" showLineNumbers +[Loaded functions]: 0.0 ms +[Loaded something else]: 0.0 ms +[Done]: 0.1 ms +``` + +[prompt-expansion]: https://zsh.sourceforge.net/Doc/Release/Prompt-Expansion.html diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/_category_.json new file mode 100644 index 00000000..4aa0fa32 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "💡指南", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx new file mode 100644 index 00000000..e4d13465 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/01_standard.mdx @@ -0,0 +1,801 @@ +--- +id: standard +title: 🔀 Standard Syntax +sidebar_position: 1 +toc_max_heading_level: 3 +image: /img/png/theme/z/320x320.png +description: The fundamental syntax documentation. +keywords: + - syntax + - standard + - how-to-use + - fundamental +--- + + + +import ImgShow from "@site/src/components/ImgShow"; +import APITable from "@site/src/components/APITable"; + +## Introduction + +Zi provides two syntax types for structured statements or expressions: + +- Standard syntax +- The ["For"][for-syntax] syntax + +It is up to the user which syntax to use, but it is highly recommended to familiarize yourself with both of them. In this example, we will use an empty repository [z-shell/0](https://github.com/z-shell/0) to practice the basics of the standard syntax. + +- Execute the following command in your terminal: + +```shell +zi load z-shell/0 +``` + +Successfully installed the Zsh plugin which usually contains all the setup instructions as described in the [Zsh plugin standard](https://wiki.zshell.dev/community/zsh_plugin_standard). + +A snippet is a single file with a portion of reusable source code, machine code, or text and requires a full path or URL to the file. + +> - Execute the following command in your terminal: + +```shell +zi snippet https://raw.githubusercontent.com/z-shell/zi-src/main/lib/zsh/snippets/welcome.zsh +``` + +Success! But not always everything is so easy and simple, also sometimes we want certain things to happen at certain times or conditions. This can be achieved using [ice-modifiers][ice-mods]. + +The top line contains ice-modifiers, and the bottom line is the plugin. + +> - Execute the following commands in your terminal: + +```shell showLineNumbers +zi ice id-as'zsh/plugin' atinit'print "Hello World!"' +zi load z-shell/0 +``` + +This registered the plugin under the [plugin ID](#id-as) `zsh/plugin` instead of `z-shell/0`. This will work as expected e.g. `zi update zsh/plugin`, `zi remove zsh/plugin`, etc. The "Hello World!" printed before loading the plugin + +Let's install again with more ice-modifiers. + +> - Execute the following commands in your terminal: + +```shell showLineNumbers +zi ice id-as'final/countdown' \ + atinit'+zi-message "{bapo}Cloned!"' \ + atclone'+zi-message "{quos}Boom!"' \ + atload'+zi-message "{apo}Loaded!"' countdown +zi load z-shell/0 +``` + +## Order of execution {#order-of-execution} + +The order of execution of related ice-modifiers is as follows: + +```shell showLineNumbers + atinit'' → + atpull'!' → + make'!!' → + mv'' → + cp'' → + make'!' → + atclone'' / atpull'' → + make'!' → + [ plugin script loading ] → + src'' → + multisrc'' → + atload'' +``` + +### A few remarks {#a-few-remarks} + +- The syntax automatically detects if the object is a snippet or a plugin, by checking if the object is an URL, i.e.: if it starts with `http*://` or `OMZ::`, etc. +- To load a local-file snippet (which will be treated as a local-directory plugin by default) use the `is-snippet` ice, +- To load a plugin in `light` mode use the `light-mode` ice. +- If the plugin name collides with an ice name, precede the plugin name with `@`, e.g.: `@sharkdp/fd` (collides with the `sh` ice, ZI will take the plugin name as `sh"arkdp/fd"`), see the next section for an example. + +### Syntax alternatives {#syntax-alternatives} + +Zi supports alternatives such as the equal (`=`) syntax: + +```shell showLineNumbers +zi ice id-as=equal atload="print Hello World" +zi load z-shell/0 +``` + +The colon (`:`) syntax: + +```shell showLineNumbers +zi ice id-as:colon atload:"print Hello World" +zi load z-shell/0 +``` + +And also – in conjunction with all of the above – the GNU syntax: + +```shell showLineNumbers +zi ice id-as=GNU --atload="print Hello World" +zi load z-shell/0 +``` + +The syntax alternatives can utilize the highlighting of editors like Vim – and have the strings and ice expressions colorized with a distinct color. However, with [zi-vim-syntax][] the syntax definition can be superseded with the highlighting specifically for Zi. syntax definition can be superseded with the highlighting specifically for Zi. + +### Utilizing "make" {#utilizing-make} + +Vim repository on GitHub – a typical source code that needs compilation, Zi can manage the run of `./configure` and other `make` stuff. Ice-modifier `pick` adds the binary program to `$PATH`. You could also install the package under the path $ZPFX. + +```shell title="~/.zshrc" showLineNumbers +zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \ + atpull"%atclone" make pick"src/vim" +zi light vim/vim +``` + +The `make'…'` ice could also be: `make"install PREFIX=$ZPFX"`, if "install" wouldn't be the only, default target. + +:::info + +[$ZPFX][zpfx] is provided by Zi, it is set to `~/.zi/polaris` by default. However, it can be changed by specifying the `$ZPFX=` target. + +::: + +```shell title="~/.zshrc" showLineNumbers +zi ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX" +zi light tj/git-extras +``` + +The `Makefile` of the project above has only 2 tasks: + +1. 安装目标。 +2. 构建安装所需的脚本。 + +The `Makefile` with 2 tasks, can use: + +1. `make"all install PREFIX=…"`, +2. `pick'…'` will `chmod +x` all matching files and add `$ZPFX/bin/` to `$PATH`. + +### Compiling programs {#compiling-programs} + +```shell showLineNumbers +zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \ + atpull"%atclone" make pick"src/vim" +zi light vim/vim +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ------------------ | :---------------------------------------------------------------------------------------- | +| `as'program'` | Add file selected by `pick'…'` to `$PATH`, and do not source it. | +| `atclone'…'` | Execute code after downloading. | +| `atpull'%atclone'` | Execute the same code `atclone'…'` is given, but after successful update. | +| `make` | Run `make` after `atclone'…'` and `atpull'…'` (note: `make'!'` will execute before them). | +| `pick'src/vim'` | Set the executable flag on `src/vim`, hint that `src/` should be added to `$PATH`. | + +```mdx-code-block + +``` + +The same but with **installation** (`make install`) under [$ZPFX][zpfx] by default: + +```shell showLineNumbers +zi ice as'program' atclone'rm -f src/auto/config.cache; \ + ./configure --prefix=$ZPFX' atpull'%atclone' make'all install' pick'$ZPFX/bin/vim' +zi light vim/vim +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ------------------ | :------------------------------------------------------------------------------------------- | +| `as'program'` | As above. | +| `atclone'…'` | As above **plus** pass `--prefix=$ZPFX` to `./configure`, to set the installation directory. | +| `atpull'%atclone'` | As above. | +| `make` | As above, but also run the `install` target. | +| `pick'src/vim'` | as above, but for a different path `$ZPFX/bin/vim`. | + +```mdx-code-block + +``` + +### LS_COLORS {#ls_colors} + +A repository [trapd00r/LS_COLORS][trapd00r-ls_colors] provides a file with color definitions for GNU `ls` command, and also for [ogham/exa][ogham-exa]. Typically one does `eval $( dircolors -b $HOME/LS_COLORS)` to process this file and set the environment for `ls`. This means `dircolors` is run by every shell startup. It costs much time to create a fork and program, i.e., the `dircolors` binary needs to be loaded to obtain and process the color definitions. The following invocation solves this problem: + +```shell showLineNumbers +zi ice atclone'dircolors -b LS_COLORS > clrs.zsh' \ + atpull'%atclone' pick"clrs.zsh" nocompile'!' \ + atload'zstyle ":completion:*" list-colors ${(s.:.)LS_COLORS}' +zi light trapd00r/LS_COLORS +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ------------------ | :------------------------------------------------------------------------------------------ | +| `atclone'…'` | Generate shell script, passing it to `eval`. More: [^1] | +| `atpull'%atclone'` | Do the same at any update of the plugin. More: [^2] | +| `pick"clrs.zsh"` | Source the previously generated file `clrs.zsh`. | +| `nocompile'!'` | Invokes compilation **after** the `atclone'…'` and the [exclamation][] mark causes this. | +| `atload'…'` | Additionally sets up the Zsh completion to use the colors provided by the trapd00r package. | + +```mdx-code-block + +``` + +This way, except for the plugin installation and update, `dircolors` isn't run, just normal sourcing is done. The everyday sourced file, i.e. `clrs.zsh`, is being compiled to speed up the loading. + +### Direnv {#direnv} + +The project [direnv/direnv][direnv-direnv] registers itself in the Z shell to modify the environment on directory change. This registration is most often done by `eval "$(direnv hook zsh)"` added to `.zshrc`. + +```shell showLineNumbers +zi ice as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' \ + atpull'%atclone' src"zhook.zsh" +zi light direnv/direnv +``` + +- `make'!'` – execute `make` before `atclone'…'` and before `atpull'…'` (see `make` above), +- `src'zhook.zsh'` – source file `zhook.zsh`. + +In general, `direnv` works by hooking up to Zsh. The code that does this is provided by the program `direnv` (built by `make'…'`). + +Above `atclone'…'` puts this code into file `zhook.zsh`, `src''` sources it. This way `direnv hook zsh` is executed only on clone and update, and Zsh starts faster. + +#### Glance at the 'for' syntax {#glance-at-the-for-syntax} + +The drawback of this standard procedure is that the `direnv` binary is run on every shell startup and significantly slows it down. Zi allows to solve this in the following way: + +```shell showLineNumbers +zi as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' \ + atpull'%atclone' pick"direnv" src"zhook.zsh" for \ + direnv/direnv +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ------------------ | :----------------------------------------------------------------------------------------------------------------------------- | +| `make'!'` | Compile `direnv`, the exclamation mark means: run the `make` first, before `atclone'…'` and `atpull'…'` hooks. | +| `atclone'…'` | As soon as the plugin is installed generate the registration code and save it to `zhook.zsh`, instead of passing it to `eval`. | +| `atpull'%atclone'` | The `atclone'…'` runs on **installation** while `atpull'…'` runs on **update** of the plugin. | +| `src'zhook.zsh'` | Load generated registration code | +| `pick'direnv'` | Ensure `+x` permission on the binary | +| `as'program'` | The plugin is a program, there's no main file to the source. | + +```mdx-code-block + +``` + +In this method, the registered code is generated once on every installation or update, then sourced without running `direnv` itself. The project is also available as a binary [GitHub releases][gh-releases]. This distribution can be installed by: + +```shell showLineNumbers +zi from"gh-r" as"program" mv"direnv* -> direnv" \ + atclone'./direnv hook zsh > zhook.zsh' atpull'%atclone' \ + pick"direnv" src="zhook.zsh" for \ + direnv/direnv +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ------------------------- | :------------------------------------------------------------------------- | +| `from'gh-r'` | Install from `direnv` from GitHub Github releases. | +| `mv'direnv* -> direnv'` | After installation, rename `direnv.linux-386` or similar file to `direnv`. | +| `atclone'…'`, `atpull'…'` | Same above example. | +| `pick'direnv'` | Same above example. | +| `as'program'` | Same above example. | + +```mdx-code-block + +``` + +## `extract'…'` {#extract} + +A swiss-knife tool for unpacking all kinds of archives – the `extract'…'` ice. It works in two modes – automatic mode and fixed mode. + +Automatic mode: + +It is active if the ice is empty (or contains only flags). It works as follows: + +1. At first, a recursive search for files of known [file extensions](#supported-file-formats) located not deeper than in a sub-directory is being performed. All such found files are then extracted. + - The directory-level limit is to skip extraction of some helper archive files, which are typically located somewhere deeper in the directory tree. +2. **If** no such files will be found, then a recursive search for files of known archive **types** will be performed. This is done by running the `file` Unix command on each file in the plugin or snippet directory and then grepping the output for strings like `Zip`, `bzip2`, etc. All such discovered files are then extracted. + - The directory-level requirement is imposed during this stage. The files located deeper than in a sub-directory are omitted. +3. If no archive files will be discovered then no action is being performed and also no warning message is being printed. + +Fixed mode: + +It is active when a filename is being passed as the `extract`'s argument, e.g.: `zi extract=archive.zip for z-shell/null`. Multiple files can be specified – separated by spaces. In this mode all and only the specified files are being extracted. + +Filenames with spaces: + +The filenames with spaces are supported when correctly passing such filenames to an `extract` with the non-breaking spaces for the original in-filename. + +The non-breaking space is easy to type by pressing right ALT and the SPACE. + +Flags: + +The value of the ice can begin with two special characters: + +1. Exclamation mark (`!`), i.e.: `extract='!…'` – it'll cause the files to be moved one directory level up upon unpacking, +2. Two exclamation marks (`!!`), i.e.: `extract='!!…'` – it'll cause the files to be moved two directory-level up upon unpacking, +3. Dash (`-`), i.e.: `extract'-…'` – it'll prevent removal of the archive after unpacking. + - This flag allows comparing timestamps with the server in case of snippet-downloaded file – it will prevent unnecessary downloads during `zi update`, as the timestamp of the archive file on the disk will be first compared with the HTTP last-modification time header. + +The flags can be combined in any order: `extract'!-'`. + +## `ziextract` {#ziextract} + +Sometimes a more uncommon unpacking operation is needed. In such a case you can directly use the function that implements the ice – it is called `ziextract`. + +It recognizes the following options: + +1. `--auto` – runs the automatic extraction. +2. `--move` – performs the one-directory-level-up move of the files after unpacking. +3. `--move2` – performs the two-directory-level-up move of the files after unpacking. +4. `--norm` - prevents the archive file removal. +5. And also one option specific only to the function: `--nobkp`, which prevents clearing the plugin's directory before the extraction. – All files besides the archive are being moved into the `._backup` directory after extraction is done. - `extract` ice also skips creating the backup **if** more than one archive is found or given as the argument. + +### Supported file formats {#supported-file-formats} + +Zip, rar, tar.gz, tar.bz2, tar.xz, tar.7z, tar, tgz, tbz2, gz, bz2, txz, xz, 7z, exe, deb, OS X (dmg). + +## `from'…'` {#from} + +To install and load a plugin whose repository is private - e.g: requires providing credentials to log in – use the `from'…'` ice in the following way: + +```shell showLineNumbers +zi ice from"user@github.com" +zi load user/fsh-auto-themes +``` + +Current preset: + +```mdx-code-block + +``` + +| Ice name | Domain name / URL | +| ---------- | :----------------------------------- | +| ge | gitee.com | +| gitee | gitee.com | +| github | github.com | +| gh | github.com | +| gitlab | gitlab.com | +| gl | gitlab.com | +| notabug | notabug.org | +| nb | notabug.org | +| bitbucket | bitbucket.org | +| bb | bitbucket.org | +| github-rel | github.com/$remote_url_path/releases | +| gh-r | github.com/$remote_url_path/releases | +| cygwin | cygwin | + +```mdx-code-block + +``` + +:::note + +If the `from'…'` ice isn't one of the above tables, then **it is treated as a domain name** and inserted into the domain position into the `git clone` URL: + +```shell +git clone https://{from-ice-contents}/user/plugin +``` + +In order to change the protocol, use the `proto'…'` ice. + +::: + +## `id-as'…'` {#id-as} + +Load a plugin or snippet with a nickname with the `id-as'…'` ice-modifier. For example, one could try to load [docker/compose][docker-compose] from GitHub binary releases: + +```shell showLineNumbers +zi ice as"program" from"gh-r" mv"docker-c* -> docker-compose" +zi light "docker/compose" +``` + +This registers the plugin under the ID `docker/compose`. Now suppose the user would want to also load a completion from the project's GitHub repository (not the binary release catalog) which is also available under the GitHub URL **…/docker/compose**. The two IDs, both being "docker/compose", will collide. + +The solution to this problem – the `id-as'…'` (to be read as _identify-as_) ice to which this document is devoted: by using the `id-as'…'` ice the user can resolve the conflict by loading the completion under a kind of a _nickname_, for example under "_dc-complete_", by issuing the following commands: + +```shell showLineNumbers +zi ice as"completion" id-as"dc-complete" +zi load docker/compose +``` + +The plugin (of the type `completion`) is now seen under ID `dc-complete`: + +```shell showLineNumbers +zi list | grep -i dc-complete +dc-complete +``` + +Issuing `zi report dc-complete` will work as with regular command: + +```shell showLineNumbers +zi report dc-complete + +Plugin report for dc-complete +------------------------------- + +Completions: +_docker-compose [enabled] +``` + +The same method applies to nickname snippets. For instance, use it to create handy IDs in place of long URLs: + +```shell showLineNumbers +zi ice as"program" id-as"git-unique" +zi snippet https://github.com/Osse/git-scripts/blob/master/git-unique +``` + +The commands `zi update git-unique`, and `zi delete git-unique` will work as expected and e.g. `zi times` will show the _nickname_-ID `git-unique` instead of the long URL. + +- `id-as'auto'`: + +There's a special value to the `id-as'…'` ice – `auto`. It causes the nickname to be automatically set to the last component of the plugin name or snippet URL. For example: + +```shell showLineNumbers +zi ice as"program" id-as"auto" +zi snippet https://github.com/Osse/git-scripts/blob/master/git-unique +``` + +will work the same as before, e.g: if the ice used was `id-as'git-unique'`. Will work as if id-as'zsh-autopair' was passed: + +```shell showLineNumbers +zi ice wait lucid id-as"auto" +zi load hlissner/zsh-autopair +``` + +- empty `id-as'…'`: + +An empty `id-as'…'` will work the same as `id-as'auto'` as if id-as'zsh-autopair' was passed, e.g: + +```shell showLineNumbers +zi ice wait lucid id-as +zi load hlissner/zsh-autopair +``` + +## `wait'…'` {#wait} + +:::note + +Turbo mode, i.e. the `wait'…'` is ice that implements it - needs Zsh >= 5.3. + +::: + +```shell showLineNumbers +zi ice wait'0' # or just: zi ice wait +zi light wfxr/forgit +``` + +- waits for prompt, +- instantly ("0" seconds) after prompt loads given plugin. + +```shell showLineNumbers +zi ice wait'[[ -n ${ZLAST_COMMANDS[(r)cras*]} ]]' +zi light z-shell/zi-crasis +``` + +- screencast that presents the feature: + + + +- `$ZLAST_COMMANDS` is an array built by [F-Sy-H][z-shell-f-sy-h], it contains commands currently entered at prompt, +- `(r)` searches for an element that matches a given pattern (`cras*`) and returns it, +- `-n` means: not-empty, so it will be true when users enter "cras", +- after 1 second or less, Zi will detect that the `wait'…'` condition is true, and load the plugin, which provides command _crasis_, + +```shell showLineNumbers +zi ice wait'[[ $PWD = */github || $PWD = */github/* ]]' +zi load unixorn/git-extra-commands +``` + +it waits until the user enters a `github` directory. Turbo mode also supports a suffix – the letter a, `b`, or `c`. The meaning is illustrated by the following example: + +```shell showLineNumbers +zi ice wait"0b" as"command" pick"wd.sh" atinit"echo Firing 1" lucid +zi light mfaerevaag/wd +zi ice wait"0a" as"command" pick"wd.sh" atinit"echo Firing 2" lucid +zi light mfaerevaag/wd +``` + +will output: + +```shell showLineNumbers +Firing 2 +Firing 1 +``` + +As can be seen, the second plugin has been loaded first. That's because there are now three sub-slots (the `a`, `b`, and `c`) into which the plugin/snippet loadings can be put. Plugins from the same time slot with suffix `a` will be loaded before plugins with suffix `b`, etc. + +In other words, instead of `wait'1'`, you can enter `wait'1a'`, `wait'1b'`, and `wait'1c'` – this **imposes the loading order** of the **commands** regardless of actual execution time. + +## `src'…'` `pick'…'` `multisrc'…'` {#src-pick-multisrc} + +Normally `src'…'` can be used to specify the additional file to the source: + +```shell showLineNumbers +zi ice pick'powerless.zsh' src'utilities.zsh' +zi light martinrotter/powerless +``` + +| Syntax | Description | +| :-------: | :--------------------------------------------------------------------------------------------------------- | +| `pick'…'` | Provide the main file to the source - like `*.sh`, otherwise alphabetically first matched file is sourced. | +| `src'…'` | Provide a second file to the source - not a pattern - plain file name. | + +### The `svn` ice {#the-svn-ice} + +However, via `atload'…'` ice one can provide a simple loop to source more files: + +```shell showLineNumbers +zi ice svn pick'completion.zsh' \ + atload'local f; for f in git.zsh misc.zsh; do source $f done' +zi snippet OMZ::lib +``` + +| Syntax | Description | +| :---------: | :--------------------------------------------------------------------------------------------------------------------------------- | +| `svn` | Use Subversion to clone `OMZ::lib` (the whole Oh-My-Zsh `lib/` directory). More [^3]. | +| `atload'…'` | Code isn't tracked and cannot be unloaded. The `atload'…'` is executed after loading main files `pick'…'` and `src'…'`. More [^4]. | + +### The `multisrc'…'` ice {#the-multisrc-ice} + +Loads **multiple** files enumerated with spaces as the separator (e.g. `multisrc'misc.zsh grep.zsh'`) and also using brace-expansion syntax (e.g. `multisrc'{misc,grep}.zsh')`. Example: + +```shell showLineNumbers +zi ice svn pick'completion.zsh' \ + multisrc'git.zsh functions.zsh {history,grep}.zsh' +zi snippet OMZ::lib +``` + +All possible ways to use the `multisrc'…'` ice-modifier: + +```shell +zi ice depth'1' multisrc='lib/{functions,misc}.zsh' pick'/dev/null' +zi load robbyrussell/oh-my-zsh +``` + +Can use patterns: + +```shell showLineNumbers +zi ice svn multisrc'{funct*,misc}.zsh' pick'/dev/null' +zi snippet OMZ::lib +``` + +```shell showLineNumbers +zi ice svn multisrc'misc.zsh functions.zsh' pick'/dev/null' +zi snippet OMZ::lib +``` + +Will use the array's value at the moment of plugin load: + +> This can matter when using turbo mode. + +```shell showLineNumbers +array=({functions,misc}.zsh) +zi ice svn multisrc"\$array" pick'/dev/null' +zi snippet OMZ::lib +``` + +Compatible with KSH_ARRAYS option: + +```shell showLineNumbers +array=({functions,misc}.zsh) +zi ice svn multisrc"${array[*]}" pick'/dev/null' +zi snippet OMZ::lib +``` + +Hack with Zi: the ice's contents are simply `eval`-uated like follows: eval "reply=($multisrc)". + +So it might get handy on an occasion to pass code there, but first, you must close the paren and then don't forget to assign `reply`, and to provide a trailing opening paren. In the code be careful to not redefine any variable used internally by Zi – e.g.: `i` is safe: + +```shell showLineNumbers +array=({functions,misc}.zsh) +zi ice svn multisrc'); local i; for i in $array; do reply+=( ${i/.zsh/.sh} ); done; ((1)' pick'/dev/null' +zi snippet OMZ::lib +``` + +Extended with the [for][for-syntax] syntax which can in some situations replace a typical `multisrc'…'` loading. The idea of this syntax is to source multiple snippets with a single command. + +Instead of: + +```shell showLineNumbers +zi ice multisrc'(functions|misc|completion).zsh' +zi snippet OMZ::lib +``` + +it's possible to write: + +```shell showLineNumbers +zi for \ + OMZL::functions.zsh \ + OMZL::misc.zsh \ + OMZL::completion.zsh +``` + +which is somewhat easier on the eyes. + +:::info Important Property + +The multiple snippets loaded with the `for` syntax are being loaded _separately_, which means that they will not cause a longer keyboard blockage, which could have been noticeable – when loading in turbo mode. + +::: + +The Zi scheduler will distribute the work over time and will allow activation of the keyboard in between the snippets. The `multisrc'…'` way doesn't work this way – sourcing many files may cause a noticeable keyboard freeze (in turbo mode). + +## `atclone'…'` `atpull'…'` `atinit'…'` `atload'…'` {#atclone-atpull-atinit-atload} + +There are four code-receiving ice-modifiers: `atclone'…'`, `atpull'…'`, `atinit'…'`, `atload'…'`. + +Their role is to **receive a portion of Zsh code and execute it in specific moments of the plugin life-cycle**. + +| Syntax | Execution moment | +| :----------: | :-------------------------------------------------------------- | +| `atclone'…'` | **after cloning** the associated plugin or snippet to the disk. | +| `atpull'…'` | **after updating** the associated plugin or snippet. | +| `atinit'…'` | **before loading** of the associated plugin or snippet. | +| `atload'…'` | **after loading** of the associated plugin or snippet. | + +For convenience, you can use each of the ices multiple times in a single `zi ice …` invocation – all commands will run in the given order. + +The `atpull'…'` ice recognizes a special value: `%atclone`, so the code looks: `atpull'%atclone'`. It causes the contents of the `atclone'…'` ice to be copied into the contents of the `atpull'…'` ice. + +This is handy when the same tasks have to be performed on clone **and** on the update of plugin or snippet, like e.g.: in the [direnv example](#direnv). + +### `atload'!…'` with exclamation mark preceded + +The [wrap'…'](#wrap) The ice-modifier allows the track and unload of plugins that defer their initialization to a function and run later after sourcing the plugin's script – When the function call, the plugin is then fully initialized. + +However, if the function is being called from the `atload'…'` ice, then the _exclamation mark_-preceded method can be used with `atload'…'` contents. The exclamation mark causes the effects of the execution of the code passed to `atload'…'` ice to be recorded. + +### Use case for `atload'…'` + +For example, in the following invocation: + +```shell showLineNumbers +zi ice id-as'test' atload'!PATH+=:~/share' +zi load z-shell/null +``` + +the `$PATH` is being changed within `atload'…'` ice. Zi's tracking registers `$PATH` changes and withdraws them on the plugin unload and shows loading information: + +```shell title="zi report test" showLineNumbers +Report for test plugin +---------------------- +Source (reporting enabled) + +PATH elements added: +/home/sg/share +``` + +As it can be seen, the `atload'…'` code is being correctly tracked and can be unloaded & viewed. Below is the result of using the `unload'…'` subcommand to unload the `test` plugin: + +```shell title="zi unload test" showLineNumbers +--- Unloading plugin: test --- +Removing PATH element /home/user/share +Unregistering plugin test +Plugin report saved to $LASTREPORT +``` + +The same example as in the [wrap'…'](#use-case-for-wrap) article, but using the _exclamation mark_-preceded `atload'…'` instead of `wrap'…'`: + +Load when - `MYPROMPT == 4` + +```shell showLineNumbers +zi ice load'![[ $MYPROMPT = 4 ]]' unload'![[ $MYPROMPT != 4 ]]' \ + atload'!source ~/.p10k.zsh; _p9k_precmd' +zi load romkatv/powerlevel10k +``` + +## `wrap'…'` {#wrap} + +The `wrap' …'` ice-modifier allows extending the tracking (e.g.: the gathering of the report and unloading data) of a plugin beyond the moment of sourcing its main file(s). It works by wrapping the given functions with a tracking-enabling and disabling snippet of code. This is useful especially with prompts, as they very often do their initialization in the first call to their `precmd` [hook][hook-functions] function. + +For example, [romkatv/powerlevel10k][romkatv-powerlevel10k] works this way. The ice takes a list of function names, with the elements separated by `;`: + +```shell +zi ice wrap"func1;func2;…" +``` + +### Use case for `wrap'…'` {#use-case-for-wrap} + +Therefore, to load and unload for the example powerlevel10k prompt in the fashion of [multiple prompts][multiple-prompts] article, the `precmd` function of the plugin – called `_p9k_precmd`, to get the name of the function do `echo $precmd_functions` after loading a theme, should be passed to `wrap'…'` ice. + +Load when `MYPROMPT == 4` + +```shell showLineNumbers +zi ice load'![[ $MYPROMPT = 4 ]]' unload'![[ $MYPROMPT != 4 ]]' \ + atload'source ~/.p10k.zsh; _p9k_precmd' wrap'_p9k_precmd' +zi load romkatv/powerlevel10k +``` + +This way the actions done during the first call to `_p9k_precmd()` will be normally recorded, which can be viewed in the report of the [romkatv/powerlevel10k][romkatv-powerlevel10k] theme: + +```shell title="zi report romkatv/powerlevel10k" showLineNumbers +Report for romkatv/powerlevel10k plugin +--------------------------------------- +Source powerlevel10k.zsh-theme (reporting enabled) +Autoload is-at-least with options -U -z + +(…) + +Note: === Starting to track function: _p9k_precmd === +Zle -N p9k-orig-zle-line-finish _zsh_highlight_widget_zle-line-finish +Note: a new widget created via zle -N: p9k-orig-zle-line-finish +Zle -N -- zle-line-finish _p9k_wrapper__p9k_zle_line_finish +Autoload vcs_info with options -U -z +Zstyle :vcs_info:* check-for-changes true + +(…) + +Zstyle :vcs_info:* get-revision false +Autoload add-zsh-hook with options -U -z +Zle -F 22_gitstatus_process_response_POWERLEVEL9K +Autoload_gitstatus_cleanup_15877_0_16212/docs/guides/syntax/wrap +Zle -N -- zle-line-pre-redraw _p9k_wrapper__p9k_zle_line_pre_redraw +Note: a new widget created via zle -N: zle-line-pre-redraw +Zle -N -- zle-keymap-select _p9k_wrapper__p9k_zle_keymap_select +Note: === Ended tracking function:_p9k_precmd === + +Functions created: ++vi-git-aheadbehind +vi-git-remotebranch + +(…) +``` + +Summary of `wrap'…'`: + +As it can be seen, the creation of four additional Zle-widgets has been recorded - `Zle -N …` lines. They will be properly deleted/restored on the plugin unload with `MYPROMPT=3` as an example and the shell state will be clean, ready to load a new prompt. + + + + + +[^1]: Save it to a file. The `atclone'…'` is being run on the **installation** while the `atpull'…'` hook is being run on an **update** of the [**trapd00r/LS_COLORS**][trapd00r-ls_colors] plugin. +[^2]: The `%atclone` is just a special string that denotes the `atclone'…'` hook and is copied onto the `atpull'…'` hook. +[^3]: Note that `atload'…'` uses apostrophes, not double quotes, to put `$f` into the string, `atload'…'`'s code is automatically being run **within the snippet's or plugin's directory**. +[^4]: Unless you load a plugin (not a snippet) with `zi load …` and prepend the value of the ice with an exclamation mark. Example: `atload'!local f; for …'`. + + + +[for-syntax]: /docs/guides/syntax/for + +[ice-mods]: /docs/guides/syntax/ice-modifiers + +[exclamation]: /search?q=exclamation+mark + +[zpfx]: /docs/guides/customization#$ZPFX + +[multiple-prompts]: /docs/guides/customization#multiple-prompts + + + +[trapd00r-ls_colors]: https://github.com/trapd00r/LS_COLORS + +[ogham-exa]: https://github.com/ogham/exa + +[direnv-direnv]: https://github.com/direnv/direnv + +[gh-releases]: https://github.com/direnv/direnv/releases/ + +[zi-vim-syntax]: https://github.com/z-shell/zi-vim-syntax + +[docker-compose]: https://github.com/docker/compose + +[z-shell-f-sy-h]: https://github.com/z-shell/F-Sy-H + +[hook-functions]: https://zsh.sourceforge.net/Doc/Release/Functions.html#Hook-Functions + +[romkatv-powerlevel10k]: https://github.com/romkatv/powerlevel10k diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx new file mode 100644 index 00000000..c841a62b --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/02_for.mdx @@ -0,0 +1,266 @@ +--- +id: for +title: ✨ The "For" Syntax +sidebar_position: 2 +image: /img/png/theme/z/320x320.png +description: The "For" Syntax documentation +keywords: + - for + - syntax + - how-to-use + - the-for-syntax +--- + + + +import APITable from "@site/src/components/APITable"; + +The `for` syntax is the most popular, more concise, and more optimized. The single command will work the same as the [standard syntax][standard-syntax] invocation. + +It allows providing common/default ice-modifiers for a set of plugins or to source multiple files with the ices: [src, pick, multisrc][src-pick-multisrc]. + +:::tip + +To find more information about anything use [search][3] or just CTRL+K. + +::: + +```shell showLineNumbers +zi light-mode for \ + zsh-users/zsh-autosuggestions \ + z-shell/F-Sy-H \ + z-shell/H-S-MW \ + pick"async.zsh" src"pure.zsh" \ + sindresorhus/pure +``` + +It is best presented by real-world examples: + +```shell showLineNumbers +zi wait"3" lucid for as"null" \ + sbin Fakerr/git-recall \ + sbin paulirish/git-open \ + sbin paulirish/git-recent \ + sbin davidosomething/git-my \ + make"PREFIX=$ZPFX install" iwata/git-now \ + make"PREFIX=$ZPFX" tj/git-extras +``` + +The above single command installs 6 plugins ([git extension][2] packages), with the base ices `as"null" wait"3" lucid` that are common to all of the plugins and 6 plugin-specific add-on ice-modifiers. + +Load a few useful binary packages from the [GitHub releases][1], utils: + +```shell showLineNumbers +zi for as"null" wait"2" lucid from"gh-r" \ + mv"exa* -> exa" sbin ogham/exa \ + mv"fd* -> fd" sbin"fd/fd" @sharkdp/fd \ + sbin"fzf" junegunn/fzf +``` + +:::note + +- `sbin'…'` is an [ice][3] added by the [bin-gem-node][4] [annex][5], it provides the command to the command line without altering `$PATH`. +- If the name of the command is the same as the name of the plugin, the ice contents can be skipped. + +::: + +[Turbo][6] load some plugins, without any plugin-specific ices: + +```shell showLineNumbers +zi wait lucid for \ + hlissner/zsh-autopair \ + urbainvaes/fzf-marks +``` + +Load two [Oh-My-Zsh][7] files as [snippets][8], in turbo mode: + +```shell showLineNumbers +zi wait lucid for \ + OMZ::lib/git.zsh \ + atload"unalias grv" \ + OMZ::plugins/git/git.plugin.zsh +``` + +Popular plugin set with [turbo][6] and The "For": + +```shell {1} showLineNumbers +zi wait lucid light-mode for \ + atinit"zicompinit; zicdreplay" \ + z-shell/F-Sy-H \ + atload"_zsh_autosuggest_start" \ + zsh-users/zsh-autosuggestions \ + blockf atpull'zi creinstall -q .' \ + zsh-users/zsh-completions +``` + +```mdx-code-block + +``` + +| Syntax | Description | +| ------------ | :------------------------------------------------------------------------------------------- | +| `wait` | Load 0 seconds (about 5 ms exactly) after prompt ([turbo mode][6]). | +| `lucid` | Silence the under-prompt messages ("`Loaded {name of the plugin}`"). | +| `light-mode` | Load the plugin in `light` mode. [^1]. | +| `atpull'…'` | Execute after updating the plugin – the command in the ice will install any new completions. | +| `atinit'…'` | Execute code before loading plugin. | +| `atload'…'` | Execute code after loading the plugin. | +| `zicompinit` | Equals to `autoload compinit; compinit`. | +| `zicdreplay` | Execute `compdef …` calls by plugins. More below [^2]. | + +```mdx-code-block + +``` + +## Oh-My-Zsh, [turbo][6] Oh-My-Zsh and the The "For" syntax + +### Without [turbo mode][6] and The "For" + +```shell showLineNumbers +# A. +setopt prompt_subst + +# B. +zi snippet OMZL::git.zsh + +# C. +zi ice atload"unalias grv" +zi snippet OMZP::git + +# D. +zi for OMZL::prompt_info_functions.zsh OMZT::gnzh + +# E. +zi snippet OMZP::colored-man-pages + +# F. +zi ice as"completion" +zi snippet OMZP::docker/_docker + +# G. +zi ice atinit"zicompinit; zicdreplay" +zi light z-shell/F-Sy-H +``` + +### With [turbo mode][6] and The "For" + +```shell showLineNumbers +# A. +setopt prompt_subst + +# B, C. +zi wait lucid for \ + OMZL::git.zsh \ + atload"unalias grv" \ + OMZP::git + +# Provide a simple prompt till the theme loads to visualize the effect. +PS1="READY >" + +# D. +zi wait'!' lucid for \ + OMZL::prompt_info_functions.zsh \ + OMZT::gnzh + +# E, F, G. +zi wait lucid for \ + atinit"zicompinit; zicdreplay" \ + z-shell/fast-syntax-highlighting \ + OMZP::colored-man-pages \ + as"completion" \ + OMZP::docker/_docker +``` + +:::info + +**A** - Most themes use this option. + +**B, C** - OMZ themes use this library and some others use also the plugin. It provides many aliases – `atload'…'` showing how to disable some of them (e.g.: to use the program `rgburke/grv`). + +**D** - Set OMZ theme. Loaded separately because the theme needs the `!` passed to the `wait` ice to reset the prompt after loading the snippet in turbo mode. + +**E, F, G** - Some plugins: + +1. syntax-highlighting, loaded possibly early for a better user experience). +2. example functional plugin. +3. docker completion. + +::: + +The above setup loads everything after the prompt, because of the preceding `wait` ice. That is called **turbo mode**, which shortens Zsh startup time by 50%-80%, e.g. instead of 200 ms, it'll be getting your shell started up after **40 ms**. + +Try both setups on the daily basis to notice the difference. The features of Zi can do much more than this simple example. + +### `zi-turbo '…' for …` {#zi-turbo--for-} + +The `zi-turbo` is a function to simplify `wait`: + +```shell showLineNumbers +zi-turbo() { + zi depth'3' lucid ${1/#[0-9][a-c]/wait"${1}"} "${@:2}" +} +``` + +Then use the `for` syntax in the imposed loading order: + +```shell {1,6,10,15} showLineNumbers +zi-turbo '0a' for \ + OMZL::git.zsh \ + OMZL::compfix.zsh \ + OMZL::functions.zsh \ + +zi-turbo '0b' for \ + OMZL::prompt_info_functions.zsh OMZL::spectrum.zsh \ + OMZL::clipboard.zsh OMZL::termsupport.zsh OMZL::directories.zsh + +zi-turbo '0c' for \ + OMZP::sudo OMZP::encode64 \ + atload"unalias grv g" OMZP::git \ + OMZP::gcloud OMZP::nvm OMZP::gem OMZP::rust + +zi-turbo '1a' for \ + MichaelAquilina/zsh-you-should-use +``` + +## Summary + +In general, [turbo mode][6] can be optionally enabled only for a subset of plugins or for all plugins. + +Syntax-highlighting plugins, like [F-Sy-H][11] or [zsh-syntax-highlighting][12], theoretically expect to be loaded last, even after the completion initialization as `compinit` function. + +However, in practice, you just have to ensure that such plugin is loaded after plugins that are issuing `compdef` – which means completions that aren't using the underscore-starting function file; the completion initialization still has to be performed before the syntax-highlighting plugin, hence the `atinit'…'` ice, which will load `compinit` right before loading the plugin, the syntax-highlighting and suggestions plugins are loaded early for a better user experience. + + + + + +[^1]: Then the tracking of plugin, activity report gathering, accessible via the `zi report {plugin-name}` subcommand) is being disabled. Note that for turbo mode, the performance gains are almost `0`, so in this mode, you can load all plugins with the tracking and the `light-mode` ice can be removed from the command. +[^2]: They were recorded and `compinit` can be called later. `compinit` provides the `compdef` function, so it must be run before issuing the taken-over `compdef`s with `zicdreplay`. + + + +[1]: /search/?q=GH-R + +[2]: /search/?q=git+ext + +[3]: /search/?q=ice + +[4]: /search/?q=bin+gem+node + +[5]: /search/?q=annex + +[6]: /search/?q=turbo+mode + +[7]: /search/?q=oh+my+zsh + +[8]: /search/?q=snippets + +[standard-syntax]: /docs/guides/syntax/standard + +[src-pick-multisrc]: /docs/guides/syntax/standard#src-pick-multisrc + + + +[11]: https://github.com/z-shell/F-Sy-H + +[12]: https://github.com/zsh-users/zsh-syntax-highlighting diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx new file mode 100644 index 00000000..dc0390a5 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/03_ice_modifiers.mdx @@ -0,0 +1,227 @@ +--- +id: ice-modifiers +title: 🧊 Ice Modifiers +sidebar_position: 4 +image: /img/png/theme/z/320x320.png +description: Ice Modifiers Documentation +slug: ice-modifiers +--- + +import Image from "@theme/IdealImage"; +import ZIceImg from "/img/png/theme/ice_180x170.png"; +import APITable from "@site/src/components/APITable"; + +:::info FAQ: What is ice? + +What is ice + +The ice is something that melts in a drink, though in Zi syntax, it means adding an ice-modifier that's temporary because it disappears – which means that the ice-modifier will last only for the next Zi command. + +::: + +An ice-modifiers are [passed][alternate-syntax] to `zi ice …` to obtain described effects, additionally can be added with [annexes][12]. To see all available ice-modifiers run `zi icemods`. + +Some ice-modifiers are highlighted and clicking on them will take you to the appropriate Wiki page for an extended explanation. You may safely assume that given ice works with both plugins and snippets unless explicitly stated otherwise. + +## Ice effects {#ice-effects} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :-------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `as` | Can be `as"program"` (alias: `as"command"`), and will cause to add script/program to `$PATH` instead of sourcing (see `pick`). Can also be `as"completion"` – use with plugins or snippets in whose only underscore-starting `_*` files you are interested in. [^8] | +| [id-as][6] | Nickname a plugin or snippet, e.g. create a short handler for the long-URL snippet. | +| `teleid` | 有效的远程 ID（即：URL、GitHub 用户名/存储库、包名等）。 | +| `compile` | Pattern (possible `{…}` expansion, like `{a/*,b*}`) to select additional files to compile, e.g. `compile"(pure \| async).zsh"`for`sindresorhus/pure`. | +| `nocompile` | Don't try to compile `pick`-pointed files. If passed the exclamation mark (i.e. `nocompile'!'`), then do compile, but after `make'…'` and `atclone'…'` (useful if Makefile installs some scripts, to point `pick'…'` at the location of their installation). | +| `service` | Make the following plugin or snippet a _service_, which will run in the background, and only in a single Zshell instance. See [#zservice][7] topic. | +| `reset-prompt` | Reset the prompt after loading the plugin/snippet (by issuing `zle .reset-prompt`). Note: normally it's sufficient to precede the value of `wait'…'` ice with `!`. | +| [bindmap][8] | To hold `;`-separated strings like `Key(s)A -> Key(s)B`, e.g. `^R -> ^T; ^A -> ^B`. In general, `bindmap'…'` changes bindings (done with the `bindkey` builtin) the plugin does. The example would cause the plugin to map Ctrl-T instead of Ctrl-R, and Ctrl-B instead of Ctrl-A. **Does not work with snippets.** | +| [trackbinds][8] | Shadow but only `bindkey` calls even with `zi light …`, i.e. even with investigating disabled (fast loading), to allow `bindmap` to remap the key-binds. The same effect has the `zi light -b …`, i.e. additional `-b` option to the `light`-subcommand. **Does not work with snippets.** | +| [wrap][9] | Takes a `;`-separated list of function names to be investigated (meaning gathering report and unloading data) **once** during execution. It works by wrapping the functions with an investigating-enabling and disabling snippet of code. [^9] | +| `aliases` | Load the plugin with the aliases mechanism enabled. Use plugins that define **and use** aliases in their scripts. | +| `light-mode` | Load the plugin without investigating, i.e., the same as the `light` command. Useful with the "for" syntax, where there is no `load` nor `light` subcommand | +| [extract][10] | Performs archive extraction supporting multiple formats like `zip`, `tar.gz`, etc., and OS X `dmg` images. [^10] | +| `subst` | Substitute the given string into another string when sourcing the plugin script, e.g.: `zi subst'autoload → autoload -Uz' …`. | +| `autoload` | Autoload the given functions (from their files). Equivalent to calling `atinit'autoload the-function'`. Supports renaming of the function – pass `'… → new-name'` or `'… -> new-name'`, e.g.: `zi autoload'fun → my-fun; fun2 → my-fun2'`. | + +```mdx-code-block + +``` + +## Cloning options {#cloning-options} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :-------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `proto` | Change protocol to `git`,`ftp`,`ftps`,`ssh`, `rsync`, etc. The default is `https`. **Does not work with snippets.** | +| [from](standard#from) | Clone plugin from a given site. Supported are `from"github"` (default), `…"github-rel"`, `…"gitlab"`, `…"bitbucket"`, `…"notabug"` (short names: `gh`, `gh-r`, `gl`, `bb`, `nb`). Can also be a full domain name e.g: for GitHub enterprise. **Does not work with snippets.** | +| `ver` | Used with `from"gh-r"` (i.e. downloading a binary release, e.g. for use with `as"program"`) – selects which version to download. Default is latest, can also be explicit `ver"latest"`. Works also with regular plugins, and checkouts e.g. `ver"branch"`, i.e. a specific version. **Does not work with snippets.** | +| `bpick` | Used to select which release from GitHub Releases to download, e.g. `zi ice from"gh-r" as"program" bpick"*Darwin*"; zi load docker/compose`. **Does not work with snippets.** | +| `depth` | Pass `--depth` to `git`. I.e., limit how much history to download. **Does not work with snippets.** | +| `cloneopts` | Pass the contents of `cloneopts` to `git clone`. Defaults to `--recursive`. I.e., change cloning options. Pass empty ice to disable recursive cloning. **Does not work with snippets.** | +| `pullopts` | Pass the contents of `pullopts` to `git pull` used when updating plugins. **Does not work with snippets.** | +| `svn` | Use Subversion for downloading snippets. GitHub supports the `SVN` protocol, which allows cloning of subdirectories as snippets, e.g. `zi ice svn; zi snippet OMZP::git`. Other ice `pick` can be used to select a file to the source (default are: `*.plugin.zsh`, `init.zsh`, `*.zsh-theme`). **Does not work with plugins.** | + +```mdx-code-block + +``` + +## Selection of files (source '…') {#selection-of-files-source} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| [pick][1] | Select the file to source, or the file to set as a command, when using `snippet --command` or the ice `as"program"`. More below [^1]. | +| [src][1] | Specify an additional file to source after the main file or after setting up command via `as"program"`. It is not a pattern but a plain filename. | +| [multisrc][1] | Allows specifying multiple files for sourcing, enumerated with spaces as the separators. More below [^2]. | + +```mdx-code-block + +``` + +## Conditional loading {#conditional-loading} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :------------: | ------------------------------------------------------------------------------------------------------------------------ | +| [wait][2] | Postpone loading a plugin or snippet. For `wait'1'`, loading is done `1` second after the prompt. [^3]. | +| [load][3] | A condition to check which should cause the plugin to load. [^4]. | +| [unload][3] | A condition to check to cause the plugin to unload. More below [^5]. | +| `cloneonly` | Don't load the plugin/snippet, only download it. | +| `if` | Load plugin/snippet only when a given condition is true. Example: [^6]. | +| `has` | Load plugin or snippet only when given command is available (in $PATH), e.g. `zi ice has'git' …`. | +| `subscribe` | Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. `subscribe'{~/files-*,/tmp/files-*}'`. | +| `trigger-load` | Creates a function that loads the associated plugin/snippet, with an option. More below [^7]. | + +```mdx-code-block + +``` + +## Plugin output {#plugin-output} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :----------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `silent` | Mute plugin's or snippet's `stderr` & `stdout`. Also, skip the `loaded …` message under the prompt for `wait`, etc. loaded plugins, and completion-installation messages. | +| `lucid` | Skip `loaded …` message under prompt for `wait`, etc. loaded plugins (a subset of `silent`). | +| `notify` | Output given message under-prompt after successfully loading a plugin/snippet. In case of problems with the loading, output a warning message and the return code. If starts with `!` it will then always output the given message. Hint: if the message is empty, then it will just notify about problems. | + +```mdx-code-block + +``` + +## Completions {#completions} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :-------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockf` | Disallow plugin to modify `fpath`. Useful when a plugin wants to provide completions traditionally. Manage completions using Zi and block the plugins to expose them. | +| `nocompletions` | Skip plugin completions detection and installation. Completions can be installed anytime using: `zi creinstall {plugin-name}`. | + +```mdx-code-block + +``` + +## Command execution after cloning, updating or loading {#command-execution-after-cloning-updating-or-loading} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `mv` | Move file after cloning or update (only for new commits). Example: `mv "fzf-* -> fzf"`. It uses `->` as a separator for old and new file names. Also works with snippets. | +| `cp` | Copy file after cloning or update (only for new commits). Example: `cp "docker-c* -> dcompose"`. Ran after `mv`. | +| [atclone][4] | Run command after cloning, within plugin's directory, e.g. `zi ice atclone"echo cloned"`. Ran also after downloading the snippet. | +| [atpull][4] | Run command after updating (only for new commits), within the plugin's directory. If starts with "!" then the command will be run before `mv` & `cp` ices and before `git pull` or `svn update`. Otherwise is run after `mv` & `cp` ices. Use the `atpull'%atclone'` to repeat `atclone` ice-modifier. | +| [atinit][4] | Run command after directory setup (cloning, checking, etc.) of the plugin/snippet before loading it. | +| [atload][4] | Run the given command within the plugin's directory after loading. Can be used with snippets. Passed code can be preceded with `!`, to be investigated (when using `load`, not `light`). | +| `run-atpull` | Always run the atpull hook (when updating), not exclusively for new commits. | +| `nocd` | Don't switch the current directory to the plugin's directory when evaluating the above ice-modifiers `atinit'…'`, `atload'…'`, etc. | +| [make][5] | Run the `make` command after cloning or updating and executing the `mv`, `cp`, `atpull`, `atclone` ice-modifiers. Can obtain argument, e.g. `make"install PREFIX=/opt"`. If the value starts with `!` then `make` is run before `atclone` and `atpull` ice-modifiers, e.g. `make'!'`. | +| `countdown` | Causes an interruptive (Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing `atclone'…'`, `atpull'…'` and `make` ices-modifiers. | +| `reset` | Invokes `git reset --hard HEAD` for plugins or `svn revert` for SVN snippets before pulling any new changes. This way `git` or `svn` will not report conflicts if some changes were done by e.g.: `atclone'…'` ice-modifier. For file snippets and `gh-r` plugins, it invokes `rm -rf *`. | + +```mdx-code-block + +``` + +## Sticky-Emulation Of other shells {#sticky-emulation-of-other-shells} + +```mdx-code-block + +``` + +| Ice-modifier | Description | +| :-------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `sh`, `!sh` | Source the plugin's (or snippet's) script with `sh` emulation so that also all functions declared within the file will get a **sticky** emulation assigned and invoked with the `sh` emulation set-up. The `!sh` version switches additional options that are rather not important from the portability perspective. | +| `bash`, `!bash` | The same as `sh`, but with the `SH_GLOB` option disabled, for "Bash" regular expressions to work. | +| `ksh`, `!ksh` | The same as `sh`, but emulating the `ksh` shell. | +| `csh`, `!csh` | The same as `sh`, but emulating the `csh` shell. | + +```mdx-code-block + +``` + + + + + +[^1]: This pattern will alphabetically match and choose the first file e.g: `zi ice pick"*.plugin.zsh"; zi load …`. +[^2]: Example: `multisrc'misc.zsh grep.zsh'` and also using brace-expansion syntax: `multisrc'{misc,grep}.zsh'` also supports patterns. +[^3]: For `wait'[[ … ]]'`, `wait'(( … ))'`, loading is done when given condition is meet. For `wait'!…'`, the prompt is reset after load. Zsh can start 80% (i.e.: 5x) faster thanks to postponed loading. **Fact:** when `wait` is used without a value, it works as `wait'0'`. +[^4]: It will load once, the condition can be still true, but will not trigger the second load, unless the plugin is unloaded earlier, see `unload`. E.g.: `load'[[ $PWD = */github* ]]'`. +[^5]: It will unload once, then only if loaded again e.g: `unload'[[ $PWD != */github* ]]'`. +[^6]: Example: `zi ice if'[[ -n "$commands[otool]" ]]'; zi load …` or `zi ice if'[[ $OSTYPE = darwin* ]]'; zi load …`. +[^7]: To use the option, precede the ice content with `!` to automatically forward the call afterward, to a command of the same name as the function. Can obtain multiple functions to create – separate with `;`. +[^8]: The third possible value is `as"null"` – a shorthand for `pick"/dev/null" nocompletions` – i.e.: it disables the default script-file sourcing and also the installation of completions. +[^9]: In summary, `wrap` allows to extend the investigating beyond the moment of loading of a plugin. An example use is to `wrap` a precmd function of a prompt (like `_p9k_precmd()` of powerlevel10k) or other plugins that _postpones its initialization till the first prompt_ (like e.g.: zsh-autosuggestions). **Does not work with snippets.** +[^10]: If it has no value, then it works in the _auto_ mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known **type** – the type is being read by the `file` Unix command. If not empty, then takes the names of the files to extract. Refer to the Wiki page for further information. + + + + + +[8]: /docs/guides/syntax/bindkey + +[9]: /docs/guides/syntax/standard#wrap + +[10]: /docs/guides/syntax/standard#extract + +[12]: /ecosystem/annexes/overview + +[alternate-syntax]: /docs/guides/syntax/standard#the-alternative-syntaxes + +[1]: /docs/guides/syntax/standard#src-pick-multisrc + +[2]: /docs/guides/syntax/standard#wait + +[3]: /docs/guides/customization#multiple-prompts + +[4]: /docs/guides/syntax/standard#atclone-atpull-atinit-atload + +[5]: /docs/guides/syntax/standard#the-make-syntax + +[6]: /docs/guides/syntax/standard#id-as + + + +[7]: https://github.com/search?q=topic%3Azservice+org%3Az-shell&type=Repositories diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx new file mode 100644 index 00000000..decb71d6 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/10_bindkey.mdx @@ -0,0 +1,143 @@ +--- +id: bindkey +title: 🗒 Bindkeys Map +sidebar_position: 5 +image: /img/png/theme/z/320x320.png +description: Usage bindmap & bindkey. +keywords: + - syntax + - bindkey + - bindmap + - how-to-use +--- + + + +## Bindkey + +The `bindkey` key mappings can be very confusing to decipher. It can use multiple different notations but it's smart to use the same key notation throughout your configuration. You can print all of your current key bindings in the current keymap with `bindkey`. To print the full `bindkey` command to add to your `.zshrc` file use `bindkey -L`. + +In general, you'll bind a widget so a key sequence or a key with a modifier. This can be declared in [caret notation][5] using `^`, using [escape sequences][6] using `\`, in octal (`\NNN`), hex (`\xNN`), or Unicode (`\uNNNN`). None of these are particularly great for people to read. This is also tricky because it depends on your keyboard, operating system, and shell. + +Here are some basics: + +- `\e`, `\E`, = Escape +- `^[` = Alt key (on some keyboards this is the same as escape) +- `^?` = Delete +- `^X`, `^` = Control + +The keys that come after the modifier can add more confusion. + +## Delete key binding + +To delete a key binding you can use `bindkey -d $KEYS`. Make sure you don't delete the characters you need for typing. + +## The `bindmap'…'` keybindings {#bindmap} + +Sometimes plugins call [bindkey][1] to assign keyboard shortcuts. This can cause problems because multiple plugins can bind the same keys. + +Also, the user might want a different binding(s), which will require complicated, additional `bindkey` commands in `.zshrc`. + +Zi provides a solution to this problem – the ability to remap the bindkeys with a short [ice-modifier][2] `bindmap'…'`. + +### Examples for `bindmap'…'` + +Map Ctrl-G instead of Ctrl-R for the history searcher. + +```shell +zi bindmap'^R -> ^G' for z-shell/history-search-multi-word +``` + +Map Ctrl-Shift-Left and Ctrl-Shift-Right used by URxvt instead of the Xterms' ones. Load with the bindkey-tracking ↔ with light-loading for anything else. + +Could also separate the bindmaps with a semicolon, i.e.: + +```shell +bindmap'"\\e[1\;6D" -> \\e[1\;5D ; "\\e[1\;6C" -> ^[[1\;5C' \ +``` + +```shell showLineNumbers +zi wait light-mode trackbinds bindmap'"\\e[1\;6D" -> \\e[1\;5D"' \ + bindmap'"\\e[1\;6C" -> ^[[1\;5C' pick'dircycle.zsh' for \ + michaelxmcbride/zsh-dircycle +``` + +Map space to regular space and Ctrl-Space to the `globalias` widget, which expands the alias entered on the left, provided by OMZ globalias plugin. + +```shell showLineNumbers +zi bindmap='!" " -> magic-space; !"^ " -> globalias' nocompletions \ + depth=1 pick=plugins/globalias/globalias.plugin.zsh for \ + ohmyzsh/ohmyzsh +``` + +### Explanation + +The `bindmap'…'` ice has two modes of operation: normal and exclamation-mark (`bindmap'!…'`). In the first mode, the remapping is being done from-key to-key, i.e.: `bindmap'fromkey -> to-key'`. + +The given key is changed to the second given key in the `bindkey` command while loading the plugin. In the second mode, the remapping is being done from-key to-widget, e.g: `bindmap'!from-key -> to-widget'`. + +In this mode, the given key is being mapped to the given widget instead of the widget specified in the `bindkey` command e.g.: + +Instead of: + +```shell showLineNumbers +bindkey "^ " magic-space +bindkey " " globalias +``` + +The actual call that'll be done will be: + +```shell showLineNumbers +bindkey "^ " globalias +bindkey " " magic-space +``` + +For the `bindmap='!" " -> magic-space; !"^ " -> globalias'` ice. + +### Using `bindmap'…'` in light mode {#trackbinds} + +When the investigation mode is on i.e.: + +- when the full loading mode is being used, default in the `for` syntax, and when `zi load …` is used, then the `bindmap'…'` ice works normally. + +In the non-investigation: + +- the [light mode](/search/?q=light+mode) – activated when `zi light …` or the `light-mode` ice is being used – the `bindmap'…'` is unavailable, unless the `trackbinds` ice is specified: + +With the use of the light-mode ice and the for-syntax: + +```shell showLineNumbers +zi light-mode for trackbinds bindmap'^R -> ^G' \ + z-shell/history-search-multi-word +``` + +With the use of the traditional syntax: + +```shell showLineNumbers +zi ice trackbinds bindmap'^R -> ^G' +zi light z-shell/history-search-multi-word +``` + +### Using the UPAR shorthands + +There are four special values that can be used on the left side of the bind-map: UPAR, DOWNAR, LEFTAR, RIGHTAR. They'll match up arrow, down arrow, etc. So that it's possible to do: + +```shell +zi bindmap='LEFTAR -> ^F; RIGHTAR -> ^G' … +``` + +The benefit of using the UPAR, … shorthands is that they cover multiple possible cursor-key codes for each of the cursor keys so that they'll work regardless of the terminal is used. + + + + + +[1]: /search/?q=bindkey + +[2]: /search/?q=ice+modifier + + + +[5]: https://en.wikipedia.org/wiki/Caret_notation + +[6]: https://en.wikipedia.org/wiki/Escape_sequence diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json new file mode 100644 index 00000000..a9ee6eec --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/syntax/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "✍️ 语法", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx new file mode 100644 index 00000000..963d5a30 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/index.mdx @@ -0,0 +1,127 @@ +--- +id: intro +slug: / +title: 🎉 Introduction +sidebar_position: 1 +image: /img/png/theme/z/320x320.png +description: Introduction to a Swiss Army Knife for Zsh, formerly known as zplugin, zinit. +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Link from "@docusaurus/Link"; +import Image from "@theme/IdealImage"; +import ImgShow from "@site/src/components/ImgShow"; +import ZGitImg from "@site/static/img/png/theme/branch_box.png"; + +Z-Shell + + + + +The [RubyGems](https://rubygems.org) and [$GEM_HOME](https://guides.rubygems.org/command-reference/#gem-environment) are automatically managed by the [bin-gem-node](/ecosystem/annexes/bin-gem-node) annex or installed by the [any-gem](https://github.com/z-shell/any-gem) package. + + + + +The [Node](https://www.npmjs.com) modules and [$NODE_PATH](https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders) are automatically managed by the [bin-gem-node](/ecosystem/annexes/bin-gem-node) annex or installed by the [any-node](https://github.com/z-shell/any-node) package. + + + + +The [Python](https://python.org) modules, [$VIRTUALENV](https://docs.python.org/3/tutorial/venv.html) are automatically managed by the [bin-gem-node](/ecosystem/annexes/bin-gem-node) annex. + + + + +The [Rust](https://crates.io) packages are managed by the [rust](/ecosystem/annexes/rust) annex. + + + + +Install and control almost everything from GitHub: [Annexes](/ecosystem/category/-annexes), [Packages](/ecosystem/category/-packages), [Gallery of Invocations](/community/gallery/collection). + + + + +## Fast and feature-rich + +- [Meta plugins][meta-plugins] allow installing groups of plugins via a single, friendly label. +- [Packages](/ecosystem/category/-packages) offload the user from providing long and complex commands. +- [Annexes](ecosystem/category/-annexes) allow extending the plugin manager with new features. +- [Turbo][turbo-mode-zsh--53] mode yields **50-80%** faster Zsh startup. + +## Neat and flexible + +- [Customize paths][customizing-paths], use [multiple prompts][multiple-prompts] or create [your own][non-github-local-plugins] plugins. +- Supports [Oh My Zsh][oh-my-zsh-prezto] and [Prezto][oh-my-zsh-prezto] plugins and libraries. ([migration][help-migrate]). +- Does not use $FPATH, loading multiple plugins doesn't clutter $FPATH with the same number of entries, e.g: 10, 15, or more. +- Code is immune to KSH_ARRAYS and other options typically causing compatibility problems. +- Do not require root access, and provide many workarounds e.g: setting so-called **shims** locally. + +## Familiarize and control + +- [Visualize and manage][commands] elements of the plugin: + - **aliases**, **functions**, **bindkeys**, **zle widgets**, **completions**, **variables**. +- Quickly [familiarize][reports-and-statistics] yourself with rich and easy-to-digest information. +- [Load or unload][loading-and-unloading] plugins, use the ability to [manage][completions-management] completions. +- Docker [playground][configs-playground], test or propose configurations. + +## Summary + + + + + + + + + + + + +[commands]: /docs/guides/commands + +[completions-management]: /docs/guides/commands#completions-management + +[customizing-paths]: /docs/guides/customization#customizing-paths + +[loading-and-unloading]: /docs/guides/commands#loading-and-unloading + +[meta-plugins]: /search?q=meta+plugins + +[help-migrate]: /docs/getting_started/migration + +[multiple-prompts]: /docs/guides/customization#multiple-prompts + +[non-github-local-plugins]: /docs/guides/customization#non-github-local-plugins + +[oh-my-zsh-prezto]: /docs/getting_started/overview#oh-my-zsh-prezto + +[reports-and-statistics]: /docs/guides/commands#reports-and-statistics + +[turbo-mode-zsh--53]: /docs/getting_started/overview#turbo-mode-zsh--53 + + + +[configs-playground]: https://github.com/z-shell/playground diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/zi_code.mdx b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/zi_code.mdx new file mode 100644 index 00000000..07e22431 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/zi_code.mdx @@ -0,0 +1,85 @@ +--- +id: code +title: 🔖 代码文档 +image: /img/png/theme/z/320x320.png +description: The documentation lists all functions, interactions between them, their comments, and features. +keywords: + - code + - zi-code + - documentation + - code-explained +--- + + + +import APITable from "@site/src/components/APITable"; + +:::info + +Documentation is automatically updated every `Thursday` at `4:30 UTC` at [z-shell/docs][]. + +::: + +```mdx-code-block + +``` + +| File | Document format | Description | +| -------------------- | --------------------------------- | ------------------------------------------------------------- | +| [zi.zsh][2] | [adoc][3], [pdf][4], [html][5] | The main script which is always loaded, in `.zshrc` | +| [side.zsh][6] | [adoc][7], [pdf][8], [html][9] | Functions, loaded by `install.zsh` and `autoload.zsh` scripts | +| [install.zsh][10] | [adoc][11], [pdf][12], [html][13] | Functions used only when installing a plugin or snippet | +| [autoload.zsh][14] | [adoc][15], [pdf][16], [html][17] | Functions used only in interactive `Zi` invocations | +| [additional.zsh][18] | [adoc][19], [pdf][20], [html][21] | Additional support for functions | + +```mdx-code-block + +``` + + + + + + + +[z-shell/docs]: https://github.com/z-shell/docs + +[2]: https://github.com/z-shell/zi/blob/main/zi.zsh + +[3]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/zi.zsh.adoc + +[4]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/zi.zsh.pdf + +[5]: https://z-shell.github.io/docs/code/html/zi.zsh.html + +[6]: https://github.com/z-shell/zi/blob/main/lib/zsh/side.zsh + +[7]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/side.zsh.adoc + +[8]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/side.zsh.pdf + +[9]: https://z-shell.github.io/docs/code/html/side.zsh.html + +[10]: https://github.com/z-shell/zi/blob/main/lib/zsh/install.zsh + +[11]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/install.zsh.adoc + +[12]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/install.zsh.pdf + +[13]: https://z-shell.github.io/docs/code/html/install.zsh.html + +[14]: https://github.com/z-shell/zi/blob/main/lib/zsh/autoload.zsh + +[15]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/autoload.zsh.adoc + +[16]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/autoload.zsh.pdf + +[17]: https://z-shell.github.io/docs/code/html/autoload.zsh.html + +[18]: https://github.com/z-shell/zi/blob/main/lib/zsh/additional.zsh + +[19]: https://github.com/z-shell/docs/blob/main/code/zsdoc/asciidoc/additional.zsh.adoc + +[20]: https://github.com/z-shell/docs/blob/main/code/zsdoc/pdf/additional.zsh.pdf + +[21]: https://z-shell.github.io/docs/code/html/additional.zsh.html diff --git a/i18n/zh-Hans/docusaurus-theme-classic/footer.json b/i18n/zh-Hans/docusaurus-theme-classic/footer.json new file mode 100644 index 00000000..9d276cca --- /dev/null +++ b/i18n/zh-Hans/docusaurus-theme-classic/footer.json @@ -0,0 +1,66 @@ +{ + "link.title.Knowledge Base": { + "message": "知识库", + "description": "The title of the footer links column with title=Knowledge Base in the footer" + }, + "link.title.Community": { + "message": "社区", + "description": "The title of the footer links column with title=Community in the footer" + }, + "link.title.More": { + "message": "更多", + "description": "The title of the footer links column with title=More in the footer" + }, + "link.title.Legal": { + "message": "法律条款", + "description": "The title of the footer links column with title=Legal in the footer" + }, + "link.item.label.Introduction": { + "message": "介绍", + "description": "The label of footer link with label=Introduction linking to /docs" + }, + "link.item.label.Ecosystem": { + "message": "生态系统", + "description": "The label of footer link with label=Ecosystem linking to /ecosystem" + }, + "link.item.label.Community": { + "message": "社区", + "description": "The label of footer link with label=Community linking to /community" + }, + "link.item.label.Discussions": { + "message": "讨论", + "description": "The label of footer link with label=Discussions linking to https://discussions.zshell.dev" + }, + "link.item.label.GitHub": { + "message": "GitHub", + "description": "The label of footer link with label=GitHub linking to https://github.com/orgs/z-shell" + }, + "link.item.label.Matrix": { + "message": "Matrix", + "description": "The label of footer link with label=Matrix linking to https://matrix.to/#/#zshell:matrix.org" + }, + "link.item.label.Zsh Manual": { + "message": "Zsh 手册", + "description": "The label of footer link with label=Zsh Manual linking to https://zsh.sourceforge.io/Doc/Release/zsh_toc.html" + }, + "link.item.label.Localization": { + "message": "本地化", + "description": "The label of footer link with label=Localization linking to https://translate.zshell.dev" + }, + "link.item.label.Uptime Status": { + "message": "正常运行时间", + "description": "The label of footer link with label=Uptime Status linking to https://status.zshell.dev" + }, + "link.item.label.Privacy Policy": { + "message": "隐私政策", + "description": "The label of footer link with label=Privacy Policy linking to legal/PRIVACY" + }, + "link.item.label.Code of Conduct": { + "message": "行为准则", + "description": "The label of footer link with label=Code of Conduct linking to legal/CODE_OF_CONDUCT" + }, + "copyright": { + "message": "Copyright © 2023 Z-Shell Community", + "description": "The footer copyright" + } +} diff --git a/i18n/zh-Hans/docusaurus-theme-classic/navbar.json b/i18n/zh-Hans/docusaurus-theme-classic/navbar.json new file mode 100644 index 00000000..b45ba40d --- /dev/null +++ b/i18n/zh-Hans/docusaurus-theme-classic/navbar.json @@ -0,0 +1,22 @@ +{ + "title": { + "message": "Z-Shell", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "A Swiss Army Knife for Zsh Unix shell", + "description": "The alt text of navbar logo" + }, + "item.label.Docs": { + "message": "文档", + "description": "Navbar item with label Docs" + }, + "item.label.Ecosystem": { + "message": "生态系统", + "description": "Navbar item with label Ecosystem" + }, + "item.label.Community": { + "message": "社区", + "description": "Navbar item with label Community" + } +}