関数入力の解析

この例では、必須の入力とオプションの入力を定義して、入力パーサーを使ってオプションの入力に既定値を代入し、カスタム関数へのすべての入力を検証する方法を示します。

入力パーサーは入力を検証して既定値を代入する一貫した方法を提供し、コードのロバスト性と管理性を向上させます。入力を検証するには既存の MATLAB® 関数を利用するか、独自の検証ルーチンを記述することができます。

手順 1.関数を定義する。

printPhoto.m というファイルに関数を作成します。関数 printPhoto ではファイル名が必須入力ですが、オプションとして仕上げ (光沢またはつや消し)、色空間 (RGB または CMYK)、幅および高さを入力できます。

function printPhoto(filename,varargin)

関数宣言ステートメントで、まず必須の入力を指定します。オプションの入力をサポートするには varargin を使用します。

手順 2.inputParser オブジェクトを作成する。

関数内で inputParser を呼び出してパーサー オブジェクトを作成します。

p = inputParser;

手順 3.スキームに入力を追加する。

addRequired、addOptional または addParameter を使用して、関数内の解析スキームに入力を追加します。オプションの入力には既定値を指定します。

各入力に対し、入力をチェックしてスカラー論理値 (true か false) またはエラーを返す、検証関数へのハンドルを指定することができます。検証関数には、既存の MATLAB 関数 (ischar や isnumeric など) または独自に作成した関数 (無名関数やローカル関数など) を使用できます。

関数 printPhoto において filename は必須の入力です。finish と color をオプションの入力として定義し、width と height をオプションのパラメーター値のペアとして定義します。

defaultFinish = 'glossy';
validFinishes = {'glossy','matte'};
checkFinish = @(x) any(validatestring(x,validFinishes));

defaultColor = 'RGB';
validColors = {'RGB','CMYK'};
checkColor = @(x) any(validatestring(x,validColors));

defaultWidth = 6;
defaultHeight = 4;

addRequired(p,'filename',@ischar);
addOptional(p,'finish',defaultFinish,checkFinish)
addOptional(p,'color',defaultColor,checkColor)
addParameter(p,'width',defaultWidth,@isnumeric)
addParameter(p,'height',defaultHeight,@isnumeric)

addRequired または addOptional で追加する入力は、"位置" 引数です。位置入力を指定して関数を呼び出す際は、解析スキームに追加される順序に従ってこれらの値を指定します。

addParameter で追加される入力は位置引数ではないため、height の値を渡すのは width の前後いずれでも構いません。ただし、パラメーター値の入力の場合、入力の値と共にその名前 (height または width) を渡す必要があります。

関数がオプションの入力 string または文字ベクトルと、名前と値の引数を受け入れる場合、オプションの入力用に検証関数を指定します。これを行わないと、入力パーサーでオプションの string または文字ベクトルがパラメーター名として解釈されます。たとえば、検証関数 checkFinish では、printPhoto によって 'glossy' が無効なパラメーター名ではなく finish の値として解釈されるようにします。

手順 4.解析を調整するプロパティを設定する (オプション)。

既定の設定で入力パーサーは、大文字と小文字の区別、関数名、構造体配列入力およびスキームにない追加のパラメーター名と値を許可するかどうかについての仮定を実行します。プロパティを使用すると、こうした動作を明示的に定義することができます。プロパティはドット表記を使って設定しますが、これは構造体配列に値を代入する方法と似ています。

printPhoto によって入力スキームに一致しない追加パラメーター値の入力が受け入れられように、入力パーサーの KeepUnmatched プロパティを設定します。

p.KeepUnmatched = true;

KeepUnmatched が false (既定の設定) の場合、入力がスキームに一致しないと入力パーサーでエラーが発生します。

手順 5.入力を解析する。

関数内で parse メソッドを呼び出します。関数のすべての入力の値を渡します。

parse(p,filename,varargin{:})

手順 6.関数で入力を使用する。

解析後の入力にアクセスするには inputParser オブジェクトの以下のプロパティを使用します。

  • Results — スキームにあるすべての入力の名前と値が格納された構造体配列

  • Unmatched — 関数に渡された、スキームに含まれていないパラメーターの名前と値が格納された構造体配列 (KeepUnmatched が true の場合)

  • UsingDefaults — 関数に渡されなかったため既定の値が代入されたオプション入力の名前が格納された cell 配列

関数 printPhoto 内で、一部の入力の値を表示します。

disp(['File name: ',p.Results.filename])
disp(['Finish: ', p.Results.finish])

if ~isempty(fieldnames(p.Unmatched))
   disp('Extra inputs:')
   disp(p.Unmatched)
end
if ~isempty(p.UsingDefaults)
   disp('Using defaults: ')
   disp(p.UsingDefaults)
end

手順 7.関数を呼び出す。

入力パーサーでは、各入力を次のように受け取ることを予期しています。

  • まず、必須の入力を、addRequired で解析スキームに追加された順序で受け取る。

  • オプションの位置入力を、addOptional で解析スキームに追加された順序で受け取る。

  • 位置入力を、パラメーターの名前と値のペア入力の前に受け取る。

  • パラメーターの名前と値を Name1,Value1,...,NameN,ValueN の形式で受け取る。

有効なものと無効なものを含めて、入力の組み合わせをいくつか printPhoto に渡します。

printPhoto('myfile.jpg')
File name: myfile.jpg
Finish: glossy
Using defaults: 
    'finish'    'color'    'width'    'height'
printPhoto(100)
Error using printPhoto (line 23)
The value of 'filename' is invalid. It must satisfy the function: ischar.
printPhoto('myfile.jpg','satin')
Error using printPhoto (line 23)
The value of 'finish' is invalid. Expected input to match one of these strings:

'glossy', 'matte'

The input, 'satin', did not match any of the valid strings. 

printPhoto('myfile.jpg',height=10,width=8)
File name: myfile.jpg
Finish: glossy
Using defaults: 
    'finish'    'color'

R2021a より前のバージョンで名前と値の引数を使用する場合、string または文字ベクトルとして名前を渡し、名前と値をコンマで区切ります。以下に例を示します。

printPhoto('myfile.jpg','height',10,'width',8)

n 番目の位置入力の値を渡すには、その前 (n – 1) の入力の値を指定するか、入力をパラメーター名と値のペアとして渡します。たとえば、以下の関数呼び出しでは finish (既定値 'glossy') と color に同じ値が代入されます。

printPhoto('myfile.gif','glossy','CMYK')  % positional

printPhoto('myfile.gif',color='CMYK')   % name and value

参考

|

トピック