Document declaration utility

NEWS

@@ -18,6 +18,10 @@
         to resume pattern matching with the next item unless in the
         POSIXly-correct mode.
     - Dollar-single-quotes are now supported.
+    - Declaration utility semantics is now supported. Assignment-like
+      arguments to the `export`, `local`, `readonly`, and `typeset`
+      built-ins are now expanded in the same way as assignments are
+      expanded.
     - After the `bg` built-in resumed a job, the `!` special parameter
       expands to the process ID of the job.
     - An interactive shell no longer exits on an error in the `exec`

NEWS.ja

@@ -16,6 +16,9 @@
       - 非標準の拡張として `;|` もしくは `;;&` で区切ることで次の分岐
         からパターンマッチングを再開させることもできる
     - ドル一重引用符に対応した
+    - 宣言ユーティリティに対応した。`export`, `local`, `readonly`,
+      `typeset` 組込みの引数は、それが変数代入の形式をしているならば
+      変数代入と同様のやり方で展開されるようになった
     - `bg` 組込みでジョブを再開した後は `!` 特殊パラメータはジョブの
       プロセス ID に展開されるようになった
     - POSIX 準拠モードであっても、対話シェルが `exec` 組込みで失敗した

doc/exec.txt

@@ -16,6 +16,10 @@ link:syntax.html#simple[A simple command] is executed as follows:
   If an error occurs during expansion, the execution of the simple command is
   aborted with a non-zero exit status.
   +
+  Tokens are usually expanded in a multi-field context, but tokens that look
+  like assignments are only subjected to the four expansions if the command is
+  a <<declaration-utility,declaration utility>>.
+  +
   In the following steps, the first word of the expansion results is referred
   to as dfn:[command name], and the other words as dfn:[command arguments].
   If there is only one word of the expansion results, there are no command
@@ -122,6 +126,35 @@ The exit status of the simple command is that of the command string in this
 case.
 --
 
+[[declaration-utility]]
+=== Declaration utility
+
+dfn:[Declaration utilities] are a predefined set of command names that have
+special word expansion semantics. If a simple command is a declaration
+utility and a word token in the simple command has a form of assignment, the
+word is link:expand.html[expanded] in the same manner as an assignment.
+
+Declaration utilities are detected when commands are parsed (rather than when
+command words are expanded), so a command name word that expands to a
+declaration utility name does not trigger the declaration utility expansion
+semantics.
+
+[NOTE]
+Some shells other than yash detects declaration utilities after a command name
+word is expanded, which allows dynamically produced declaration utility names.
+
+The following link:builtin.html[built-ins] are the declaration utilities in
+yash:
+
+. link:_export.html[+export+]
+. link:_local.html[+local+]
+. link:_readonly.html[+readonly+]
+. link:_typeset.html[+typeset+]
+
+Additionally, the link:_command.html[+command+ built-in] is treated as a
+declaration utility if the name is followed by another word that names a
+declaration utility.
+
 [[search]]
 === Command search
 

doc/expand.txt

@@ -6,7 +6,7 @@
 
 dfn:[Word expansion] is substitution of part of a word with another particular
 string.
-There are seven types of word expansions:
+There are many types of word expansions:
 
 . <<tilde,Tilde expansion>>
 . <<params,Parameter expansion>>
@@ -16,10 +16,12 @@ There are seven types of word expansions:
 . <<split,Field splitting>>
 . <<glob,Pathname expansion>> (globbing)
 
-These types of expansions are performed in the order specified above.
-
 Tilde expansion, parameter expansion, command substitution, and arithmetic
-expansion are called the dfn:[four expansions].
+expansion are called the dfn:[four expansions], and are performed in the order
+of appearance. After them, brace expansion, field splitting, and pathname
+expansion are optionally performed in that order if the expansion is being
+performed in a multi-field context, that is, when a whole list of words is
+being expanded at once to produce a list of fields.
 
 [[tilde]]
 == Tilde expansion

doc/ja/exec.txt

@@ -12,6 +12,8 @@
 link:syntax.html#simple[単純コマンド]は以下の手順に従って実行されます。
 
 . 単純コマンドに含まれる、変数代入とリダイレクト以外のトークンを全て{zwsp}link:expand.html[展開]します。展開エラーが発生した場合は、この単純コマンドの実行は中止されます (このとき単純コマンドの終了ステータスは非 0 です)。
+  +
+  通常、トークンには全ての種類の展開が行われます。しかし、コマンドが<<declaration-utility,宣言ユーティリティ>>の場合は代入形式のトークンは四種展開のみが行われます。
   +
   以下、展開の結果得られた最初の単語をdfn:[コマンド名]、それ以外の単語をdfn:[コマンド引数]と呼びます。得られた単語が一つの場合は、コマンド引数は存在しません。得られた単語が一つもない場合は、コマンド名もコマンド引数も存在しません。
 . コマンド名が存在する場合、単純コマンドに対する{zwsp}link:redir.html[リダイレクト]を実行します。リダイレクトに含まれるトークンの展開はここで行われます。リダイレクトエラーが発生した場合は、この単純コマンドの実行は中止されます (このとき単純コマンドの終了ステータスは非 0 です)。リダイレクトに含まれるトークンの展開時のエラーはリダイレクトエラーに含まれます。
@@ -52,6 +54,26 @@ ifndef::basebackend-html[`eval -i -- "${COMMAND_NOT_FOUND_HANDLER-}"`]
 が実行されます。ただしこのとき{zwsp}link:params.html#positional[位置パラメータ]はコマンド名とコマンド引数に一時的に置き換えられます。またこのコマンドの実行中に定義された<<localvar,ローカル変数>>はこのコマンドの終了時に削除されます。このコマンドの実行時には link:params.html#sv-handled[++HANDLED++ ローカル変数]が空文字列を値としてあらかじめ定義されます。このコマンドの実行後にこの変数の値が空文字列でなくなっていれば、このコマンドの終了ステータスがこの単純コマンドの終了ステータスとなり、コマンドが見つからなかったことはエラーとはみなされません。
 --
 
+[[declaration-utility]]
+=== 宣言ユーティリティ
+
+dfn:[宣言ユーティリティ]は予めシェル内で定義されている特殊なコマンド名であり、通常とは異なる単語展開動作を行います。単純コマンドが宣言ユーティリティである場合、代入形式のトークンは代入と同様に{zwsp}link:expand.html[展開]されます。
+
+宣言ユーティリティはコマンドが読み込まれる時に認識されます。(コマンドが実行される時ではありません。)
+そのため、単語が展開された結果が宣言ユーティリティの名前になる場合でもそれは宣言ユーティリティとしては認識されません。
+
+[NOTE]
+Yash 以外のシェルでは、単語展開の結果に応じて宣言ユーティリティが認識され、その後に続く他のトークンの展開方法に反映されるものもあります。
+
+Yash では以下の{zwsp}link:builtin.html[組込みコマンド]が宣言ユーティリティとなります:
+
+. link:_export.html[+export+]
+. link:_local.html[+local+]
+. link:_readonly.html[+readonly+]
+. link:_typeset.html[+typeset+]
+
+また、{zwsp}link:_command.html[+command+ 組込み]は +command+ に続くトークンが宣言ユーティリティである場合に宣言ユーティリティとして認識されます。
+
 [[search]]
 === コマンドの検索
 

doc/ja/expand.txt

@@ -14,7 +14,8 @@
 . <<split,単語分割>>
 . <<glob,パス名展開>>
 
-これらの展開は上に挙げた順序で行われます。特に最初の四つ (チルダ展開・パラメータ展開・コマンド置換・数式展開) をdfn:[四種展開]といいます。
+特に最初の四つ (チルダ展開・パラメータ展開・コマンド置換・数式展開) をdfn:[四種展開]といいます。これらは単語内に現れた順に展開されます。
+単語のリストを一度に展開しようとしている場合は、四種展開の後でブレース展開・単語分割・パス名展開がこの順に行われます。
 
 [[tilde]]
 == チルダ展開