function newPat = namedPattern(pat,name,description)
%namedPattern Creates a pattern with a named pattern
%   NEWPAT = namedPattern(PAT) returns a pattern with a named pattern that
%   contains PAT and is named with the inputname of PAT.
%
%   NEWPAT = namedPattern(PAT,NAME) returns a pattern with a named pattern 
%   that contains PAT and is named NAME.
%
%   NEWPAT = namedPattern(PAT,NAME,DESCRIPTION) returns a pattern with a 
%   named pattern that contains PAT, is named NAME, and displays
%   DESCRIPTION for its display.
%
%   Examples
%       localPart = lettersPattern;
%       localPart = namedPattern(localPart);
%
%       domainName = lettersPattern;
%       domainName = namedPattern(domainName);
%
%       tld = "com" | "gov" | "net";
%       tld = namedPattern(tld);
%
%       domain = namedPattern(domainName + "." + tld, "domain");
%
%       emailAddress = localPart + "@" + domain;
% 
%       % emailAddress = 
%       % 
%       %   pattern
%       % 
%       %   Matching:
%       % 
%       %     localPart + "@" + domain
%       % 
%       %   Using subpatterns:
%       % 
%       %     localPart   : lettersPattern
%       %     domain      : domainName + "." + tld
%       %       domainName: lettersPattern
%       %       tld       : "com" | "gov" | "net"
%
%       STR = "Contact foo@bar.com or foo@baz.net";
%
%       extract(STR, emailAddress)     % returns ["foo@bar.com";"foo@baz.net"]
%
%       emailAddress.domain = "baz.net";
%
%       extract(STR, emailAddress)     % returns "foo@baz.net"
%
%   See also pattern, maskedPattern, contains, extract, replace.

% Copyright 2019-2020 The MathWorks, Inc.

    narginchk(1,3);

    try
        if nargin == 1
            name = inputname(1);
            if isempty(name)
               error(message('MATLAB:pattern:MissingName')); 
            end
        end
        
        if nargin < 3
            newPat = matlab.internal.pattern.namedPattern(pat,name);    
        else
            newPat = matlab.internal.pattern.namedPattern(pat,name,description);
        end
        
    catch e
       throw(e); 
    end
end
