function varargout = readvars(filename,varargin)
%READVARS Creates variables by reading from a file.
%    Use the READVARS function to create variables by reading
%    column-oriented data from a file. READVARS automatically determines
%    the file format from its extension as described below.
%
%    [Var1, Var2, ...] = READVARS(FILENAME) creates variables by reading
%    from a file. The requested outputs of READVARS are a one-to-one
%    mapping of the columns stored in the file.
%
%      FILENAME can be one of these:
%
%       - For local files, FILENAME can be a full path that contains
%         a filename and file extension. FILENAME can also be a relative
%         path to the current folder, or to a folder on the MATLAB path.
%         For example, to import a file on the MATLAB path:
%
%            readvars("patients.xls");
%
%       - For files from an Internet URL or stored at a remote location,
%         FILENAME must be a full path using a Uniform Resource Locator
%         (URL). For example, to import a remote file from Amazon S3,
%         specify the full URL for the file:
%
%            readvars("s3://bucketname/path_to_file/my_table.xls");
%
%         To read tabular data from a web page, specify the URL; if the
%         URL points to an HTML resource, but does not end in ".html" 
%         or ".htm", also specify the file type:
%
%            url = "https://www.mathworks.com/matlabcentral/cody/groups/78";
%            readvars(url,"FileType","html");
%
%         For more information on accessing remote data, see "Work with
%         Remote Data" in the documentation.
%
%    [Var1, Var2, ...] = READVARS(FILENAME,OPTS) creates variables by
%    reading from a file stored at LOCATION using the supplied
%    ImportOptions OPTS. OPTS specifies selected variable names, variable
%    types, and other information regarding the location of the data.
%
%    [Var1, Var2, ...] = READVARS(___, Name,Value) specifies additional
%    parameters using one or more name-value pair arguments.
%
%   Name-Value Pairs for both TEXT and SPREADSHEET files:
% --------------------------------------------------------
%   "FileType"             -   Specify the file as "text" or "spreadsheet".
%
%   "Range"                - The range to consider when detecting data.
%                             Specified using any of the following syntaxes:
%                             - Starting cell: A string or character vector
%                               containing a column letter and a row number,
%                               or a 2 element numeric vector indicating
%                               the starting row and column.
%                             - Rectangular range: A start and end cell separated
%                               by colon, e.g. "C2:N15", or a four element
%                               numeric vector containing start row, start
%                               column, end row, end column, e.g. [2 3 15 13].
%                             - Row range: A string or character vector
%                               containing a starting row number and ending
%                               row number, separated by a colon.
%                             - Column range: A string or character vector
%                               containing a starting column letter and
%                               ending column letter, separated by a colon.
%                             - Starting row number: A numeric scalar
%                               indicating the first row where data is found.
%
%   "NumHeaderLines"       -   The number of header lines in the file.
%
%   "TreatAsMissing"       -   Text which is used in a file to represent
%                              missing data, e.g. "NA".
%   
%   "ExpectedNumVariables" -   The expected number of variables.   
%
%
%   "TextType"             -   "char" or "string" the type to use for
%                              text variables.
%
%   "DatetimeType"         -   "datetime", "text", or "exceldatenum" the
%                              type to use for dates.
%                              Note: "exceldatenum" not allowed for text
%
%   "WebOptions"            -  HTTP(s) request options, specified as a 
%                              weboptions object. 
%
%   Name-Value Pairs for TEXT only :
% -----------------------------------
%   "Delimiter"                  -   The delimiter(s) to use in the file.
%
%   "NumHeaderLines"             -   The number of header lines in the
%                                    file.
%
%   "CommentStyle"               -   The style of comments in the file.
%
%   "LineEnding"                 -   The line ending for the file.
%
%   "DateLocale"                 -   The locale used to interpret month and
%                                    day names in datetime text. LOCALE
%                                    must be a character vector or scalar
%                                    string in the form xx_YY. See the
%                                    documentation for DATETIME for more
%                                    information.
%
%   "Encoding"                   -   The text encoding of the file.
%
%   "DurationType"               -   "duration" or "text" the type to use
%                                    for duration.
%
%   "Whitespace"                 -   Characters to treat as whitespace.
%
%   "DecimalSeparator"           -   Character used to separate the integer
%                                    part of a number from the decimal part
%                                    of the number.
%
%   "ThousandsSeparator"         -   Character used to separate the
%                                    thousands place digits.
%
%   "TrimNonNumeric"             -   Logical used to specify that prefixes
%                                    and suffixes must be removed leaving 
%                                    only the numeric data. 
%
%   "ConsecutiveDelimitersRule"  -   What to do with consecutive delimiters
%                                    that appear in the file.
%                                 * "split" - each delimiter separates a
%                                             single field
%                                 * "join"  - groups of delimiters separate
%                                             single fields
%                                 * "error" - Ignored for detection
%                                             (treated as "split"), but the
%                                             resulting read will error.
%
%   "LeadingDelimitersRule"      -   What to do with delimiters at the beginning of a line.
%
%   Name-Value Pairs for SPREADSHEETS only :
% ------------------------------------------
%   "UseExcel"                  - Whether or not to read the spreadsheet
%                                 file using Microsoft(R) Excel(R) on 
%                                 Windows(R):
%                                 true  - Opens an instance of Microsoft Excel
%                                         to read the file on a Windows system
%                                         with Excel installed.
%                                 false - Does not open an instance of Microsoft
%                                         Excel to read the file. This is the
%                                         default setting.
%
%   "Sheet"                     - The sheet from which to read the table.
%
%   "DataRange"                 - Where the table data is located.
%
%
%   Parameters which are also accepted with import options. These may have
%   slightly different behavior when used with import options:
%
%   Name-Value Pairs supported with Import Options OPTS:
% -------------------------------------------------------
%
%       Supported for all file types:
%         "WebOptions" -   HTTP(s) request options, specified as a 
%                          weboptions object.
%
%       Text only parameters:
%         "DateLocale" -   Override the locale used when importing dates.
%         "Encoding"   -   Override the encoding defined in import options.
%
%       Spreadsheet only parameters:
%         "Sheet"      -   Override the sheet value in the import options.
%         "UseExcel"   -   Same behavior as READVARS without import options.
%
%
%   See also READCELL, READMATRIX, READTABLE, READTIMETABLE.

%   Copyright 2018-2021 The MathWorks, Inc.

try
    if any(cellfun(@(arg) isa(arg,"matlab.io.ImportOptions"),varargin),'all')
        error(message('MATLAB:textio:io:OptsSecondArg','readvars'))
    end

    func = matlab.io.internal.functions.FunctionStore.getFunctionByName("readvars");
    C = onCleanup(@()func.WorkSheet.clear());
    [varargout{1:nargout}] = func.validateAndExecute(filename,varargin{:});
catch ME
    throw(ME);
end

