inputParser

함수의 입력값 구문 분석기

설명

참고

arguments 블록을 사용하는 입력 인수 유효성 검사가 inputParser보다 권장됩니다. 추가적인 정보는 함수 인수 유효성 검사 항목을 참조하십시오.

inputParser 객체를 사용하면 입력값 구문 분석기 체계를 생성하여 함수에 대한 입력값을 관리할 수 있습니다. 입력값을 확인할 수 있도록 필수 인수, 선택적 인수 및 이름-값 쌍의 인수에 대한 유효성 검사(Validation) 함수를 정의할 수 있습니다. 선택적으로, 대/소문자 구분 처리, 구조체형 배열 입력 및 입력값 구문 분석기 체계에 없는 입력 등과 같은 구문 분석 동작을 조정하기 위해 속성을 설정할 수 있습니다.

입력값 구문 분석기 체계를 정의한 후, parse 함수를 호출하십시오. inputParser에 입력값에 대한 정보가 저장됩니다.

입력 이름과 값	저장 위치
일치하는 입력값 구문 분석기 체계	`Results` 속성
함수에 전달되지 않아서, 디폴트 값이 할당됨	`UsingDefaults` 속성
일치하는 입력값 구문 분석기 체계 없음	`Unmatched` 속성

생성

구문

p = inputParser

설명

p = inputParser는 디폴트 속성값을 사용하여 입력값 구문 분석기 객체를 만듭니다.

예제

속성

모두 확장

`CaseSensitive` — 대/소문자를 구분할지 여부에 대한 표시자
`false` (디폴트 값) | `true`

인수 이름을 학인할 때 대/소문자를 구분할지 여부에 대한 표시자로, false 또는 true(또는, 0이나 1)로 지정됩니다. 기본적으로 인수 이름 일치 여부는 대/소문자를 구분하지 않습니다. 예를 들어, 'a'는 'A'와 일치합니다. 대소문자를 구분하는 일치의 경우에는 CaseSensitive를 true(또는 1)로 설정합니다.

이 속성값은 논리형 값으로 저장됩니다.

`FunctionName` — 오류 메시지에 대한 함수의 이름
빈 문자형 벡터, `''`입니다. (디폴트 값) | 문자형 벡터 | string형 스칼라

오류 메시지에 표시할 함수의 이름으로, 문자형 벡터 또는 string형 스칼라로 지정됩니다. 기본적으로, FunctionName은 빈 문자형 벡터('')입니다. 일반적으로, FunctionName을 검증하는 함수의 이름으로 설정합니다. 그러면, parse 함수가 잘못된 입력 인수를 발견할 경우, 함수 이름을 사용하여 오류를 보고합니다.

이 속성값은 문자형 벡터로 저장됩니다.

데이터형: char | string

`KeepUnmatched` — 일치 표시자
`false` (디폴트 값) | `true`

입력값 구문 분석기 체계에서 입력값이 검색되지 않을 때 오류를 생성하는 일치 표시자로, false 또는 true(또는, 0이나 1)로 지정됩니다. 기본적으로, 입력 인수 이름이 입력값 구문 분석기 체계에서 정의한 이름과 일치하지 않으면 parse 함수는 오류를 생성합니다. 오류를 표시하지 않고 입력 인수 이름과 값을 저장하려면 KeepUnmatched를 true(또는 1)로 설정하십시오. inputParser는 일치하지 않는 입력 인수 이름과 값을 Unmatched 속성에 저장합니다.

이 속성값은 논리형 값으로 저장됩니다.

`PartialMatching` — 부분 일치 표시자
`true` (디폴트 값) | `false`

부분적으로 일치하는 입력 이름을 유효한 것으로 허용하기 위한 부분 일치 표시자로, true 또는 false(또는, 1이나 0)으로 지정됩니다. 기본적으로, 입력값 구문 분석기 체계에서 파라미터 이름의 선행 부분문자열은 입력 파라미터 이름으로써 유효하고, 입력값은 해당 파라미터와 일치하게 됩니다. 입력 파라미터에 대해 여러 가지 일치 가능성이 있는 경우, MATLAB^®은 오류를 발생시킵니다. CaseSensitive 속성을 반영하여, 입력 파라미터 이름이 입력값 구문 분석기 체계의 이름과 정확하게 일치해야 하도록 하려면 PartialMatching을 false(또는 0)로 설정하십시오.

부분 일치는 사용자가 addParameter 함수를 사용하여 입력값 구문 분석기 체계에 추가한 인수에서만 지원합니다.

StructExpand 속성의 값이 true(또는 1)이면 inputParser는 입력 파라미터 이름에 대응하는 구조체 필드 이름에 대해 부분 일치를 지원하지 않습니다.
PartialMatching과 KeepUnmatched가 모두 true(또는 1)이면, MATLAB은 오류를 생성하지 않습니다. 대신, 모호한 파라미터 이름을 Unmatched 속성에 저장합니다.

이 속성값은 논리형 값으로 저장됩니다.

`StructExpand` — 구조체 표시자
`true` (디폴트 값) | `false`

구조체를 단일 입력이나 일련의 파라미터 이름-값 쌍으로 해석하는 구조체 표시자로, true 또는 false(또는, 1이나 0)로 지정됩니다. 기본적으로, inputParser는 구조체를 개별 입력으로 확장하여, 각 필드 이름이 입력 파라미터 이름에 대응하게 합니다. 구조체를 단일 입력 인수로 간주하려면 StructExpand를 false(또는 0)로 지정하십시오.

이 속성값은 논리형 값으로 저장됩니다.

`Parameters` — 인수 이름
읽기 전용: 문자형 벡터로 구성된 셀형 배열

읽기 전용 속성입니다.

입력값 구문 분석기 체계에 정의된 인수 이름으로, 문자형 벡터로 구성된 셀형 배열로 저장됩니다. 체계에 입력 인수를 추가하는 각 함수는 Parameters 속성을 업데이트합니다. 이러한 함수로는 addRequired, addOptional, addParameter가 있습니다.

데이터형: cell

`Results` — 결과
읽기 전용: 구조체

읽기 전용 속성입니다.

유효한 입력 인수의 이름과 그에 대응하는 값으로 지정된 결과로, 구조체로 저장됩니다. 유효한 입력 인수는 입력값 구문 분석기 체계에 정의된 인수와 일치하는 이름을 가진 인수입니다. Results 구조체의 각 필드는 입력값 구문 분석기 체계에 있는 인수의 이름에 대응합니다. parse 함수가 Results 속성을 채웁니다.

데이터형: struct

`Unmatched` — 일치하지 않는 입력값
읽기 전용: 구조체

읽기 전용 속성입니다.

입력값 중에서 입력값 구문 분석기 체계와 일치하지 않는 입력 이름과 값으로, 구조체로 저장됩니다. KeepUnmatched 속성이 디폴트 값인 false(또는 0)로 설정되거나 모든 입력값이 입력값 구문 분석기 체계와 일치하면 Unmatched는 필드가 없는 1×1 구조체입니다. 그렇지 않으면, Unmatched 구조체의 각 필드는 입력값 구문 분석기 체계에 정의된 인수와 일치하지 않는 입력 인수의 이름에 대응합니다.

parse 함수는 Unmatched 속성을 채웁니다.

데이터형: struct

`UsingDefaults` — 함수에 명시적으로 전달되지 않은 입력값
읽기 전용: 문자형 벡터로 구성된 셀형 배열

읽기 전용 속성입니다.

함수에 명시적으로 전달되지 않은 입력값으로, 문자형 벡터로 구성된 셀형 배열로 저장됩니다. 이러한 입력 인수에는 Results 속성에서 디폴트 값이 할당됩니다. parse 함수가 UsingDefaults 속성을 채웁니다.

데이터형: cell

객체 함수

`addOptional`	입력값 구문 분석기 체계에 선택적 위치 인수 추가
`addParameter`	입력값 구문 분석기 체계에 선택적 이름-값 쌍의 인수 추가
`addRequired`	입력값 구문 분석기 체계에 필수 위치 인수 추가
`parse`	함수 입력값 구문 분석
`addParamValue`	(권장되지 않음) 입력값 구문 분석기 체계에 선택적 이름-값 쌍의 인수 추가

addRequired, addOptional, addParameter 함수를 순서와 상관없이 호출하여 입력값 구문 분석기 체계를 정의할 수 있습니다. 그러나, 입력값 구문 분석기를 사용하는 함수를 호출할 때 인수는 다음 순서로 전달됩니다.

필수 인수
임의 선택적 위치 인수
임의 이름-값 쌍

예제

모두 축소

입력 유효성 검사

필수 인수와 선택적 인수의 유효성을 검사합니다.

findArea.m 파일에 함수를 만듭니다. findArea 함수는 width 입력 인수를 필요로 하고 가변적인 개수의 추가 입력값을 허용합니다. 입력값 구문 분석기 체계는 다음 인수 조건을 지정합니다.

width (필수 인수). 필수 인수가 위치 입력값이므로, width는 findArea 함수의 첫 번째 인수여야 합니다. 입력값 구문 분석기는 width가 양의 스칼라 숫자형인지 확인합니다.
height(선택적 인수). 선택적 인수가 위치 인수이므로 height가 findArea 함수의 인수이면 이 인수는 두 번째 인수여야 합니다. 입력값 구문 분석기는 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: [1×1 struct]

fieldList = fieldnames(p.Results.structInput)

fieldList = 3×1 cell
    {'first' }
    {'random'}
    {'mytext'}

`validateattributes`를 사용하여 입력값 구문 분석

사람에 대한 정보를 구문 분석하고, 구문 분석 결과가 통과인 경우 셀형 배열에 정보를 추가하는 함수를 생성합니다.

함수 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 함수를 사용하십시오.

확장 기능

모두 확장

스레드 기반 환경
MATLAB®의 `backgroundPool`을 사용해 백그라운드에서 코드를 실행하거나 Parallel Computing Toolbox™의 `ThreadPool`을 사용해 코드 실행 속도를 높일 수 있습니다.

inputParser 함수는 스레드 기반 환경을 완전히 지원합니다. 자세한 내용은 스레드 기반 환경에서 MATLAB 함수 실행하기 항목을 참조하십시오.

버전 내역

R2007a에 개발됨

참고 항목

validateattributes | validatestring | varargin | arguments

inputParser

설명

생성

구문

설명

속성

CaseSensitive — 대/소문자를 구분할지 여부에 대한 표시자 false (디폴트 값) | true

FunctionName — 오류 메시지에 대한 함수의 이름 빈 문자형 벡터, ''입니다. (디폴트 값) | 문자형 벡터 | string형 스칼라

KeepUnmatched — 일치 표시자 false (디폴트 값) | true

PartialMatching — 부분 일치 표시자 true (디폴트 값) | false

StructExpand — 구조체 표시자 true (디폴트 값) | false

Parameters — 인수 이름 읽기 전용: 문자형 벡터로 구성된 셀형 배열

Results — 결과 읽기 전용: 구조체

Unmatched — 일치하지 않는 입력값 읽기 전용: 구조체

UsingDefaults — 함수에 명시적으로 전달되지 않은 입력값 읽기 전용: 문자형 벡터로 구성된 셀형 배열

객체 함수

예제

입력 유효성 검사

추가 파라미터 값 입력

대/소문자 구분

구조체형 배열 입력

validateattributes를 사용하여 입력값 구문 분석

팁

확장 기능

스레드 기반 환경 MATLAB®의 backgroundPool을 사용해 백그라운드에서 코드를 실행하거나 Parallel Computing Toolbox™의 ThreadPool을 사용해 코드 실행 속도를 높일 수 있습니다.

버전 내역

참고 항목

도움말 항목

`CaseSensitive` — 대/소문자를 구분할지 여부에 대한 표시자
`false` (디폴트 값) | `true`

`FunctionName` — 오류 메시지에 대한 함수의 이름
빈 문자형 벡터, `''`입니다. (디폴트 값) | 문자형 벡터 | string형 스칼라

`KeepUnmatched` — 일치 표시자
`false` (디폴트 값) | `true`

`PartialMatching` — 부분 일치 표시자
`true` (디폴트 값) | `false`

`StructExpand` — 구조체 표시자
`true` (디폴트 값) | `false`

`Parameters` — 인수 이름
읽기 전용: 문자형 벡터로 구성된 셀형 배열

`Results` — 결과
읽기 전용: 구조체

`Unmatched` — 일치하지 않는 입력값
읽기 전용: 구조체

`UsingDefaults` — 함수에 명시적으로 전달되지 않은 입력값
읽기 전용: 문자형 벡터로 구성된 셀형 배열

`validateattributes`를 사용하여 입력값 구문 분석

스레드 기반 환경
MATLAB®의 `backgroundPool`을 사용해 백그라운드에서 코드를 실행하거나 Parallel Computing Toolbox™의 `ThreadPool`을 사용해 코드 실행 속도를 높일 수 있습니다.