手順 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 オブジェクトの以下のプロパティを使用します。

関数 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.関数を呼び出す。

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

有効なものと無効なものを含めて、入力の組み合わせをいくつか 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