Main Content

inputParser

関数の入力パーサー

このページをすべて展開する

説明

inputParser オブジェクトを使用すると、入力パーサー スキームを作成して関数の入力を管理できます。入力をチェックするには、必須の引数、オプションの引数および名前と値のペアの引数の検証関数を定義できます。オプションとして、大文字小文字の区別、構造体配列入力および入力パーサー スキームにない入力など、解析動作を調整するプロパティを設定できます。

入力パーサー スキームを定義した後に、関数 parse を呼び出します。inputParser は入力に関する情報を格納します。

入力の名前と値格納場所
入力パーサー スキームに一致するResults プロパティ
関数に渡されないため、既定値が割り当てられるUsingDefaults プロパティ
入力パーサー スキームに一致しないUnmatched プロパティ

作成

構文

p = inputParser

説明

例

p = inputParser は既定のプロパティ値をもつ入力パーサー オブジェクトを作成します。

プロパティ

すべて展開する

引数名のチェック時に大文字小文字を区別するかどうかのインジケーター。false または true (あるいは 0 または 1) として指定します。既定では、引数名の一致に関して大文字小文字は区別されません。たとえば、'a' は 'A' と一致します。一致で大文字と小文字を区別するには、CaseSensitive を true (または 1) に設定します。

このプロパティ値は logical 値として格納されます。

エラー メッセージに表示する関数名。文字ベクトルまたは string スカラーとして指定します。既定では、FunctionName は空の文字ベクトル ('') です。通常、FunctionName を検証している関数の名前に設定します。これにより、関数 parse が無効な入力引数を検出した場合、その関数名を使用してエラーをレポートします。

このプロパティ値は文字ベクトルとして格納されます。

データ型: char | string

入力パーサー スキームで入力が検出されない場合にエラーをスローする一致インジケーター。false または true (あるいは 0 または 1) として指定します。既定では、関数 parse は、入力引数名が入力パーサー スキームで定義されたものと一致しない場合にエラーをスローします。このエラーを非表示にして、入力引数の名前と値を格納するには、KeepUnmatched を true (または 1) に設定します。inputParser は一致しなかった入力引数の名前と値を Unmatched プロパティに格納します。

このプロパティ値は logical 値として格納されます。

部分的に一致した入力名を有効として受け入れる部分一致インジケーター。false または true (あるいは 0 または 1) として指定します。既定では、入力パーサー スキーム内のパラメーター名の冒頭の部分文字列である入力パラメーター名は有効であり、入力値はそのパラメーターと一致します。入力パラメーターに一致する候補が複数存在する場合、MATLAB® はエラーをスローします。入力パラメーター名が、CaseSensitive プロパティに従って入力パーサー スキーム内の名前に完全一致する必要がある場合は、PartialMatching を false (または 0) に設定します。

部分一致は、関数 addParameter を使用して入力パーサー スキームに追加する引数でのみサポートされます。

  • StructExpand プロパティの値が true (または 1) の場合、inputParser は入力パラメーター名に対応する構造体フィールド名について部分一致をサポートしていません。

  • PartialMatching と KeepUnmatched の両方が true (または 1) の場合、MATLAB はエラーをスローしません。代わりに、あいまいなパラメーター名を Unmatched プロパティに格納します。

このプロパティ値は logical 値として格納されます。

構造体を単一の入力、または一連のパラメーターの名前と値のペアとして解釈する構造体インジケーター。false または true (あるいは 0 または 1) として指定します。既定では、inputParser は構造体を個別の入力に展開します。各フィールド名は入力パラメーター名に対応します。構造体を単一の入力引数と見なすには、StructExpand を false (または 0) として指定します。

このプロパティ値は logical 値として格納されます。

この プロパティ は読み取り専用です。

入力パーサー スキームで定義される引数名。文字ベクトルの cell 配列として格納されます。スキームに入力引数を追加する各関数は、Parameters プロパティを更新します。このような関数には addRequired、addOptional、および addParameter があります。

データ型: cell

この プロパティ は読み取り専用です。

有効な入力引数の名前、および対応する値として指定される結果。構造体として格納されます。有効な入力引数は、入力パーサー スキームで定義された引数に一致する名前をもつものです。Results 構造体の各フィールドは、入力パーサー スキーム内の引数の名前に対応します。関数 parse によって Results プロパティが入力されます。

データ型: struct

この プロパティ は読み取り専用です。

入力パーサー スキームに一致しない、不一致の入力の名前と値。構造体として格納されます。KeepUnmatched プロパティが false (または 0) に設定されている場合 (既定)、またはすべての入力が入力パーサー スキームに一致した場合、Unmatched はフィールドのない 1 行 1 列の構造体になります。それ以外の場合、Unmatched 構造体の各フィールドは、入力パーサー スキームで定義された引数に一致しない入力引数の名前に対応します。

関数 parse によって Unmatched プロパティが入力されます。

データ型: struct

この プロパティ は読み取り専用です。

関数に明示的に渡されない入力。文字ベクトルの cell 配列として格納されます。これらの入力引数には、Results プロパティの既定値が割り当てられます。関数 parse によって UsingDefaults プロパティが入力されます。

データ型: cell

オブジェクト関数

addOptional入力パーサー スキームにオプションの位置引数を追加
addParameterオプションの名前と値のペア引数を入力パーサー スキームに追加
addRequired入力パーサー スキームに必須の位置引数を追加
parse関数入力の解析
addParamValue(非推奨) オプションの名前と値のペア引数を入力パーサー スキームに追加

入力パーサー スキームは、関数 addRequired、addOptional、addParameter を任意の順序で呼び出すことで定義できます。ただし、入力パーサーを使用する関数を呼び出した場合、引数は次の順序で渡されます。

  1. 必須の引数

  2. 任意のオプションの位置引数

  3. 名前と値のペア

例

すべて折りたたむ

必須およびオプションの引数の妥当性をチェックします。

関数をファイル findArea.m に作成します。関数 findArea には入力引数 width が必須で、可変数の追加入力を受け入れます。入力パーサー スキームは、次の引数の条件を指定します。

  • width (必須の引数)。必須の引数は位置引数であるため、width は関数 findArea の最初の引数でなければなりません。入力パーサーは、width が正の数値スカラーであるかをチェックします。

  • height (オプション引数)。オプション引数は位置引数であるため、height が関数 findArea の引数である場合、2 番目の引数でなければなりません。入力パーサーは、height が正の数値スカラーであるかをチェックします。

  • 'units' および関連付けられた値 (名前と値のペア)。名前と値のペアはオプションです。関数 findArea を呼び出すときに、位置引数の後に名前と値のペアを任意の順序で指定します。入力パーサーは、'units' の値が string であるかをチェックします。

  • 'shape' および関連付けられた値 (別の名前と値のペア)。入力パーサーは、'shape' の値が配列 expectedShapes に含まれているかをチェックします。

function a = findArea(width,varargin)
   defaultHeight = 1;
   defaultUnits = 'inches';
   defaultShape = 'rectangle';
   expectedShapes = {'square','rectangle','parallelogram'};

   p = inputParser;
   validScalarPosNum = @(x) isnumeric(x) && isscalar(x) && (x > 0);
   addRequired(p,'width',validScalarPosNum);
   addOptional(p,'height',defaultHeight,validScalarPosNum);
   addParameter(p,'units',defaultUnits,@isstring);
   addParameter(p,'shape',defaultShape,...
                 @(x) any(validatestring(x,expectedShapes)));
   parse(p,width,varargin{:});
   
   a = p.Results.width*p.Results.height; 
end

関数 findArea を複数回呼び出します。入力パーサーは、これらの関数呼び出しのいずれでもエラーをスローしません。

a = findArea(7);
a = findArea(7,3);
a = findArea(13,'shape','square');
a = findArea(13,'units',"miles",'shape','square');

入力パーサー スキームに一致しない引数を指定して関数を呼び出します。width 入力に数値以外の値を指定します。

a = findArea('text')
Error using findArea (line 14)
The value of 'width' is invalid. It must satisfy the function: @(x)isnumeric(x)&&isscalar(x)&&(x>0).

'shape' にサポートされていない値を指定します。

a = findArea(4,12,'shape','circle')
Error using findArea (line 14)
The value of 'shape' is invalid. Expected input to match one of these values:

'square', 'rectangle', 'parallelogram'

The input, 'circle', did not match any of the valid values.
ライブ スクリプトを開く

エラーを発生させる代わりに、入力スキームにはないパラメーター名と値入力を保存します。 

default = 0;
value = 1;

p = inputParser;
p.KeepUnmatched = true;
addOptional(p,'expectedInputName',default)
parse(p,'extraInput',value);

次のように不一致のパラメーター名と値を表示します。 

p.Unmatched
ans = struct with fields:
    extraInput: 1

関数の入力をチェックするときに大文字小文字を区別します。

p = inputParser;
p.CaseSensitive = true;
defaultValue = 0;
addParameter(p,'InputName',defaultValue)

parse(p,'inputname',10)
'inputname' is not a recognized parameter. For a list of valid name-value pair arguments, see the documentation for this function.
ライブ スクリプトを開く

構造体引数を名前と値のペアに展開します。 

s.input1 = 10;
s.input2 = 20;
default = 0;

p = inputParser;
addParameter(p,'input1',default)
addParameter(p,'input2',default)
parse(p,s)

p.Results
ans = struct with fields:
    input1: 10
    input2: 20

StructExpand プロパティを false に設定することで、構造体を単一の引数として受け入れます。 

s2.first = 1;
s2.random = rand(3,4,2);
s2.mytext = 'some text';

p = inputParser;
p.StructExpand = false;
addRequired(p,'structInput')
parse(p,s2)

results = p.Results
results = struct with fields:
    structInput: [1x1 struct]


fieldList = fieldnames(p.Results.structInput)
fieldList = 3x1 cell
    {'first' }
    {'random'}
    {'mytext'}

ユーザーに関する情報を解析し、解析がパスした場合に、その情報を cell 配列に追加する関数を作成します。

関数 addPerson を作成し、関数 validateattributes を使用する入力パーサー スキームを含めます。関数 addPerson はユーザーのリストを受け入れ、必要に応じてこのリストを変更し、その後リストを返します。関数を呼び出すたびに新規オブジェクトが作成されることを防ぐために、永続的な inputParser オブジェクトを使用します。

function mlist = addPerson(mlist,varargin)
    persistent p
    if isempty(p)
        p = inputParser;
        p.FunctionName = 'addPerson';
        addRequired(p,'name',@(x)validateattributes(x,{'char'},...
            {'nonempty'}))
        addRequired(p,'id',@(x)validateattributes(x,{'numeric'},...
            {'nonempty','integer','positive'}))
        addOptional(p,'birthyear',9999,@(x)validateattributes(x,...
            {'numeric'},{'nonempty'}))
        addParameter(p,'nickname','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
        addParameter(p,'favColor','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
    end
    
    parse(p,varargin{:})
    
    if isempty(mlist)
        mlist = fieldnames(p.Results)';
    end
    mlist = [mlist; struct2cell(p.Results)'];
end

空のリストを作成し、そのリストにユーザーを追加します。

pList = {};
pList = addPerson(pList,78,'Joe');
Error using addPerson
The value of 'name' is invalid. Expected input to be one of these types:

char

Instead its type was double.

Error in addPerson (line 19)
parse(p,varargin{:})

解析は失敗します。これは、関数が引数を正しくない順序で受け取り、name に値 78 を代入しようとするためです。このエントリは pList に追加されません。

さらに数名のユーザーをリストに追加します。

pList = addPerson(pList,'Joe',78);
pList = addPerson(pList,'Mary',3,1942,'favColor','red');
pList = addPerson(pList,'James',182,1970,'nickname','Jimmy')
pList =

  4×5 cell array

    'birthyear'    'favColor'    'id'     'name'     'nickname'
    [     9999]    '-'           [ 78]    'Joe'      '-'       
    [     1942]    'red'         [  3]    'Mary'     '-'       
    [     1970]    '-'           [182]    'James'    'Jimmy'

ヒント

  • 関数 addOptional で入力パーサー スキームに追加された引数は位置引数です。このため、関数に渡されるときと同じ順序でこれらを入力パーサー スキームに追加します。

  • 入力パーサー スキームに個々の引数を追加するには、addOptional を使用します。オプションの名前と値のペアを解析する場合は、関数 addParameter を使用します。

拡張機能

バージョン履歴

R2007a で導入

参考

| | |

トピック