ja-JP/about_Enum.help.txt
|
TOPIC about_Enum 簡単な説明 enum ステートメントは列挙型を宣言します。列挙型は、列挙子リストと 呼ばれる名前付きラベルの集合から成る独立した型です。 詳細な説明 enum ステートメントを使うと、厳密に型指定されたラベルの集合を作成 できます。その列挙型をコードの中で使えば、解析やスペルミスのチェックを 行う必要がなくなります。 列挙型は内部的には開始値 0 の整数値型として表現されます。既定では、 PowerShell の列挙型は基になる型として System.Int32 ([int]) を使います。 既定では、PowerShell はリストの最初のラベルに値 0 を割り当てます。 既定では、残りのラベルには連続する整数が割り当てられます。 構文 定義の中では、ラベルに任意の整数値を与えることができます。値を割り当て なかったラベルは、次の整数値を取ります。 enum ラベルには文字、アンダースコア、数字だけを使えますが、数字で 始めることはできません。ラベルを引用符付き文字列にすることはできず、 引用符なしの文字列として解析される必要があります。ラベルはキーワード ではなく文字列として解析されます。そのため、言語キーワード (return など) と同じ名前のラベルを作成することも可能です。 列挙型では次の構文を使います。 - 整数列挙型の定義構文 [[<attribute>]...] enum <enum-name> { <label> [= <int-value>] ... } - 基になる型を指定する列挙型の定義構文 [[<attribute>]...] enum <enum-name> : <underlying-type-name> { <label> [= <int-value>] ... } - フラグ列挙型の定義構文 [[<attribute>]...] [Flags()] enum <enum-name>[ : <underlying-type-name>] { <label 0> [= 1] <label 1> [= 2] <label 2> [= 4] <label 3> [= 8] ... } - 列挙型へのアクセス構文 [<enum-name>]::<label> 例 例 1 - 最小限の列挙型 次のコードブロックは、3 つのラベルを持つ MarkdownUnorderedListCharacter 列挙型を定義します。どのラベルにも 明示的な値を割り当てていません。 enum MarkdownUnorderedListCharacter { Asterisk Dash Plus } 次のコードブロックは、整数値と文字列値が列挙型にキャストされたときに どのように振る舞うかを示します。 $ValuesToConvert = @(0, 'Asterisk', 1, 'Dash', 2, 'Plus') foreach ($Value in $ValuesToConvert) { [MarkdownUnorderedListCharacter]$EnumValue = $Value [pscustomobject]@{ AssignedValue = $Value Enumeration = $EnumValue AreEqual = $Value -eq $EnumValue } } AssignedValue Enumeration AreEqual ------------- ----------- -------- 0 Asterisk True Asterisk Asterisk True 1 Dash True Dash Dash True 2 Plus True Plus Plus True 列挙型の値と等しい整数をキャストすると、その列挙型が返されます。 列挙型のラベルと同じ文字列をキャストすると、その列挙型が返されます。 例 2 - 明示的な値と同義語を持つ列挙型 次の例は、メディアファイルに対応するオブジェクトの列挙型を示します。 この定義では music、picture、video の基になる値に明示的な値を割り 当てています。明示的な割り当ての直後のラベルは、次の整数値を取り ます。別のラベルに同じ値を割り当てることで同義語を作成できます。 ogg、oga、mogg や jpg、jpeg、または mpg、mpeg の構築された値を 参照してください。 enum MediaTypes { unknown music = 10 mp3 aac ogg = 15 oga = 15 mogg = 15 picture = 20 jpg jpeg = 21 png video = 40 mpg mpeg = 41 avi m4v } GetEnumNames() メソッドは列挙型のラベルの一覧を返します。 [MediaTypes].GetEnumNames() GetEnumValues() メソッドは列挙型の値の一覧を返します。 [MediaTypes].GetEnumValues() 注意: GetEnumNames() と GetEnumValues() は同じ結果 (名前付きの値の 一覧) を返すように見えます。しかし内部的には、GetEnumValues() は値を列挙してから値を名前にマップします。一覧を注意深く見ると、 ogg、oga、mogg は GetEnumNames() の出力には現れますが、 GetEnumValues() の出力には ogg だけが表示されることに気付きます。 jpg、jpeg や mpg、mpeg でも同じことが起こります。PowerShell が 同義語の値に対して返す名前は決定論的ではありません。 特定の値に関連付けられた名前を取得するには GetEnumName() メソッドを 使います。1 つの値に複数の名前が関連付けられている場合、このメソッド は最初に定義された名前を返します。 [MediaTypes].GetEnumName(15) # 結果: ogg 各ラベルに値を指定するには、[<enum-name>]::<label> という構文を 使います。 [MediaTypes]::png [MediaTypes]::png -eq 22 # 結果: png / True 例 3 - フラグとしての列挙型 次のコードブロックは、ビットフラグの集合として FileAttributes 列挙型を作成します。各ラベルの値は、前のラベルの値の 2 倍です。 [Flags()] enum FileAttributes { Archive = 1 Compressed = 2 Device = 4 Directory = 8 Encrypted = 16 Hidden = 32 } [FileAttributes]$file1 = [FileAttributes]::Archive [FileAttributes]$file1 += [FileAttributes]::Compressed [FileAttributes]$file1 += [FileAttributes]::Device "file1 attributes are: $file1" [FileAttributes]$file2 = [FileAttributes]28 ## => 16 + 8 + 4 "file2 attributes are: $file2" file1 attributes are: Archive, Compressed, Device file2 attributes are: Device, Directory, Encrypted 特定のフラグが設定されているかをテストするには、バイナリ比較演算子 -band を使います。 PS > ($file2 -band [FileAttributes]::Device) -eq [FileAttributes]::Device True PS > ($file2 -band [FileAttributes]::Archive) -eq [FileAttributes]::Archive False HasFlag() メソッドを使って特定のフラグが設定されているかをテストする こともできます。 PS > $file1.HasFlag([FileAttributes]::Device) True PS > $file1.HasFlag([FileAttributes]::Hidden) False 例 4 - パラメーターとしての列挙型 次の例では、関数 ConvertTo-LineEndingRegex が InputObject パラメーター を型 EndOfLine で定義しています。 enum EndOfLine { CR = 1 LF = 2 CRLF = 3 } function ConvertTo-LineEndingRegex { [CmdletBinding()] param ( [Parameter(ValueFromPipeline)] [EndOfLine[]]$InputObject ) process { switch ($InputObject) { CR { '\r' } LF { '\n' } CRLF { '\r\n' } } } } [EndOfLine]::CR | ConvertTo-LineEndingRegex 'CRLF' | ConvertTo-LineEndingRegex ConvertTo-LineEndingRegex 2 無効なラベル名や数値を指定すると、関数はエラーを発生させます。 例 5 - 基になる型を指定する列挙型 PowerShell 6.2 以降では、基になる型を指定して列挙型を定義できます。 基になる型として有効な整数型は次のとおりです。 byte, sbyte, short, ushort, int, uint, long, ulong 列挙型のメソッド Format Format() 静的メソッドは、指定した列挙型、値、書式文字列に対して 書式設定された文字列出力を返します。出力は、指定した書式文字列を 使って値の ToString メソッドを呼び出した場合と同じです。 [System.Enum]::Format([<enum-name>], <value>, <format-string>) [<enum-name>]::Format([<enum-name>], <value>, <format-string>) 有効な書式文字列は G または g、D または d、X または x、F または f です。 GetEnumName GetEnumName() リフレクションメソッドは、特定の列挙型の値に対する 名前を返します。1 つの値に複数の名前が関連付けられている場合、 最初に定義された名前を返します。 [<enum-name>].GetEnumName(<value>) GetEnumNames GetEnumNames() リフレクションメソッドは、すべての列挙型の値の名前を 文字列として返します。出力には同義語も含まれます。 [<enum-name>].GetEnumNames() GetEnumUnderlyingType GetEnumUnderlyingType() リフレクションメソッドは、列挙型の値の 基になる型を返します。 [<enum-name>].GetEnumUnderlyingType() GetEnumValues GetEnumValues() リフレクションメソッドは、列挙型に定義されたすべての 値を返します。 [<enum-name>].GetEnumValues() GetEnumValuesAsUnderlyingType GetEnumValuesAsUnderlyingType() リフレクションメソッドは、列挙型に 定義されたすべての値を基になる型として返します。 [<enum-name>].GetEnumValuesAsUnderlyingType() HasFlag HasFlag インスタンスメソッドは、フラグ列挙型の値に対してビット フラグが設定されているかを判定します。 <enum-value>.HasFlag(<enum-flag-value>) IsDefined IsDefined() 静的メソッドは、入力値が列挙型に定義されていれば $true を、そうでなければ $false を返します。 [System.Enum]::IsDefined([<enum-name>], <value>) [<enum-name>]::IsDefined([<enum-name>], <value>) ToString ToString() インスタンスメソッドは、列挙型の値のラベルを返します。 これは列挙型の値が出力として表示される際の既定のビューでもあります。 必要に応じて書式文字列を指定して表示方法を制御できます。 <enum-value>.ToString([<format-string>]) 注意: 特定の値に同義語を定義した列挙型では、ToString() の出力に依存する コードを書かないでください。このメソッドは値の有効な名前のいずれ かを返す可能性があります。 列挙型の値の同義語 同じ整数値に異なる名前を与える列挙型を定義できます。その場合、同じ 基になる値を指す名前は同義語と呼ばれます。同義語を持つ列挙型を定義する ときは、同義語の値が特定の名前に変換されることに依存するコードを書かない でください。文字列を列挙型の値に変換するコードは確実に書けます。列挙型の 値自体を扱うときは、文字列としてではなく、列挙型の値またはその基になる型 として比較してください。 フラグとしての列挙型 列挙型の一般的な用途の 1 つは、相互排他的な値の集合を表すことです。 しかし、列挙型オブジェクトの値が複数のメンバーを含み、各メンバーが 列挙値内のビットフィールドを表す場合もあります。FlagsAttribute を使うと、 列挙型がユーザーが組み合わせ可能なフラグとしてのビットフィールドから 成ることを示せます。 フラグとしての列挙型が正しく動作するには、各ラベルの整数値を 2 のべき乗 に設定する必要があります。ラベルに値を指定しない場合、PowerShell は前の ラベルより 1 大きい値を設定します。 特定のフラグが設定されているかを判定するには、値に対して HasFlag() メソッドを使うか、バイナリ比較演算子 -band を使います。 パラメーターとしての列挙型 enum を型として使うコマンドレットパラメーターを定義できます。enum を パラメーターの型として指定すると、ユーザーはパラメーター値の自動補完と 検証を利用できます。引数補完は enum の有効なラベルの一覧を提案します。 パラメーターの型が enum の場合、次のいずれも指定できます。 [<EnumType>]::<Label> のような列挙型 列挙型のラベルを文字列として 列挙型の数値 基になる型を指定する列挙型 PowerShell 6.2 以降では、基になる型を指定して列挙型を定義できます。 基になる型を指定せずに列挙型を定義すると、PowerShell は基になる型として [int] (System.Int32) を使って列挙型を作成します。 列挙型の基になる型は整数数値型である必要があります。有効な型は次の とおりです。 byte - System.Byte sbyte - System.SByte short - System.Int16 ushort - System.UInt16 int - System.Int32 uint - System.UInt32 long - System.Int64 ulong - System.UInt64 Update-TypeData による拡張メソッドの定義 列挙型の宣言の中でメソッドを定義することはできません。列挙型の機能を 拡張するには、Update-TypeData コマンドレットを使って列挙型に ScriptMethod メンバーを定義します。 型アクセラレーターによる列挙型のエクスポート 既定では、PowerShell モジュールは PowerShell で定義されたクラスや列挙型を 自動的にエクスポートしません。これらのカスタム型は、using module ステートメントを呼び出さない限りモジュールの外では使えません。 ただし、モジュールが型アクセラレーターを追加すると、その型アクセラレーター はユーザーがモジュールをインポートした直後にセッションで利用可能になります。 PowerShell モジュールからの列挙型の手動インポート Import-Module と #Requires ステートメントは、モジュールで定義された関数、 エイリアス、変数だけをインポートします。列挙型はインポートされません。 モジュールがクラスや列挙型を定義していても型アクセラレーターを追加して いない場合は、using module ステートメントを使ってインポートします。 開発中の変更コードの読み込み スクリプトモジュールの開発中は、コードを変更してから Force パラメーター 付きの Import-Module で新しいバージョンのモジュールを読み込むのが一般的 です。これはルートモジュールの関数への変更に対してのみ機能します。 最新バージョンを実行していることを確実にするには、新しいセッションを開始 する必要があります。 制限事項 - PowerShell で定義した列挙型の値に属性を付けることはできません。 列挙型の宣言自体には付けられます (ビットフラグの集合として定義する ための FlagsAttribute など)。 回避策: なし - 列挙型の定義の中でメソッドを定義することはできず、PowerShell は C# のような拡張メソッドの定義をサポートしません。 回避策: Update-TypeData コマンドレットを使って列挙型に ScriptMethod メンバーを定義します。 関連項目 about_Classes about_Hash_Tables about_Using Update-TypeData ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |