## Copyright (C) 2018-2019 Sahil Yadav <yadavsahil5198@gmail.com>
##
## This file is part of Octave.
##
## Octave is free software: you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation, either version 3 of the License, or
## (at your option) any later version.
##
## Octave is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING.  If not, see
## <https://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @deftypefn  {} {@var{output} =} weboptions ()
## @deftypefnx {} {@var{output} =} weboptions (@var{name1}, @var{value1}, @dots{})
##
## Specify parameters for RESTful web services.
##
## @code{weboptions} with no inputs returns a default @code{weboptions} object
## to specify parameters for a request to a web service.  A @code{weboptions}
## object can be an optional input argument to the @code{webread},
## @code{websave}, and ## @code{webwrite} functions.
##
## Multiple name and value pair arguments may be specified in any order as
## @var{name1}, @var{value1}, @var{name2}, @var{value2}, etc.
##
## The option names must match @strong{exactly} one of those specified in the
## table below.
##
## The following options are available:
##
## @itemize @bullet
## @item
## @samp{CharacterEncoding} --- Specify the character encoding of the data:
##
## @samp{auto} (default), @samp{UTF-8}, @samp{US-ASCII}
## @samp{auto} chooses an encoding based on the content-type of the data.
##
## @item
## @samp{UserAgent} --- Specify the User Agent for the connection.
##
## Default value is @samp{GNU Octave/version}, where @samp{version} is the
## current version of Octave as returned by @code{version}.
##
## @item
## @samp{Timeout} --- Specify the timeout value for the connection in seconds.
##
## Default is 10 seconds.  @samp{Inf} is not currently supported.
##
## @item
## @samp{Username} --- User identifier for a basic HTTP connection.
##
## Default is NULL@.  It must be a string.
##
## @item
## @samp{Password} --- User authentication password for HTTP connection.
##
## Default is NULL@.  It must be a string or character vector.
## Programming Note: If you display a @code{weboption} object with the Password
## property set, the value is displayed as a string containing
## @qcode{\"*\"}.  However, the object stores the value of the Password
## property as plain text.
##
## @item
## @samp{KeyName} --- Specify the name of an additional key to be added to
## the HTTP request header.  It should be coupled with @samp{KeyValue}.  It
## must be a string or character vector.
##
## @item
## @samp{KeyValue} --- Specify the value of the key @samp{KeyName}.
##
## @samp{KeyName} must be present in order to assign to this field.
##
## @item
## @samp{HeaderFields} --- Specify the header fields for the connection.
##
## Names and values of header fields, specified as an m-by-2 array of strings
## or cell array of character vectors to add to the HTTP request header.
## HeaderFields@{i,1@} is the name of a field and HeaderFields@{i,2@} is its
## value.
##
## @example
## @group
## weboptions ("HeaderFields", @{"Content-Length" "78";"Content-Type" "application/json"@})
## Creates a weboptions object that contains two header fields: Content-Length
## with value 78 and Content-Type with value application/json.
## @end group
## @end example
##
## @item
## @samp{ContentType} --- Specify the content type of the data.
##
## The following values are available:
## @samp{auto}, @samp{text}, @samp{json}
##
## Default is @samp{auto}.  It automatically determines the content type.
## All other formats like @samp{audio}, @samp{binary}, etc.@: available in
## @sc{matlab} are not currently supported.
##
## @item
## @samp{ContentReader} --- Not yet implemented.  Only for @sc{matlab}
## compatibility.
##
## @item
## @samp{MediaType} --- Not yet implemented.  Only for @sc{matlab}
## compatibility.
##
## @item
## @samp{RequestMethod} --- Specifies the type of request to be made.
##
## The following methods are available:
## @samp{get}, @samp{put}, @samp{post}, @samp{delete}, @samp{patch}
##
## @code{webread} and @code{websave} use the HTTP GET method.  @code{webwrite}
## uses the HTTP POST method as default.
##
## @item
## @samp{ArrayFormat} -- Not yet implemented.  Only for @sc{matlab}
## compatibility.
##
## @item
## @samp{CertificateFilename} --- Not yet implemented.  Only for @sc{matlab}
## compatibility.
## @end itemize
##
## @seealso{webwrite, webread, websave}
## @end deftypefn

classdef weboptions < handle
  properties
    CharacterEncoding = "auto";
    UserAgent = ["GNU Octave/", version()];
    Timeout = 10;
    Username = "";
    Password = "";
    KeyName = "";
    KeyValue = "";
    HeaderFields = {};
    ContentType = "auto";
    ContentReader = "";
    MediaType = "auto";
    RequestMethod = "auto";
    ArrayFormat = "csv";
    CertificateFilename = "";
  endproperties

  methods
    function f = weboptions (varargin)
      if (rem (numel (varargin), 2) != 0)
        error ("weboptions: invalid number of arguments");
      else
        h = cell2struct (varargin(2:2:end), varargin(1:2:end), 2);
        if (numfields (h) > 14)
          error ("weboptions: invalid number of arguments");
        endif

        if (isfield (h, "CharacterEncoding"))
          f.CharacterEncoding = h.CharacterEncoding;
          h = rmfield (h, "CharacterEncoding");
        endif

        if (isfield (h, "UserAgent"))
          f.UserAgent = h.UserAgent;
          h = rmfield (h, "UserAgent");
        endif

        if (isfield (h, "Timeout"))
          f.Timeout = h.Timeout;
          h = rmfield (h, "Timeout");
        endif

        if (isfield (h, "Username"))
          f.Username = h.Username;
          h = rmfield (h, "Username");
        endif

        if (isfield (h, "Password"))
          f.Password = h.Password;
          h = rmfield (h, "Password");
        endif

        if (isfield (h, "KeyName"))
          f.KeyName = h.KeyName;
          h = rmfield (h, "KeyName");
        endif

        if (isfield (h, "KeyValue"))
          f.KeyValue = h.KeyValue;
          h = rmfield (h, "KeyValue");
        endif

        if (isfield (h, "HeaderFields"))
          f.HeaderFields = h.HeaderFields;
          h = rmfield (h, "HeaderFields");
        endif

        if (isfield (h, "ContentType"))
          f.ContentType = h.ContentType;
          h = rmfield (h, "ContentType");
        endif

        if (isfield (h, "ContentReader"))
          f.ContentReader = h.ContentReader;
          h = rmfield (h, "ContentReader");
        endif

        if (isfield (h, "MediaType"))
          f.MediaType = h.MediaType;
          h = rmfield (h, "MediaType");
        endif

        if (isfield (h, "RequestMethod"))
          f.RequestMethod = h.RequestMethod;
          h = rmfield (h, "RequestMethod");
        endif

        if (isfield (h, "ArrayFormat"))
          f.ArrayFormat = h.ArrayFormat;
          h = rmfield (h, "ArrayFormat");
        endif

        if (isfield (h, "CertificateFilename"))
          f.CertificateFilename = h.CertificateFilename;
          h = rmfield (h, "CertificateFilename");
        endif

        if (! isempty (fieldnames (h)))
          field = fieldnames (h){1};
          error (["weboptions: Undefined field " field]);
        endif
      endif
    endfunction

    function f = set.CharacterEncoding (f, value)
      if (! any (strcmpi (value, {"UTF-8", 'US-ASCII', "auto"})));
        error ("weboptions: Invalid CharacterEncoding value");
      else
        f.CharacterEncoding = value;
      endif
    endfunction

    function f = set.UserAgent (f, value)
      if (! ischar (value) && ! isrow (value));
        error ("weboptions: UserAgent must be a string");
      else
        f.UserAgent = value;
      endif
    endfunction

    function f = set.Timeout (f, value)
      if (! isreal (value) || ! isscalar (value)
          || floor(value) != value || value < 0)
        error ("weboptions: invalid Timeout value");
      else
        f.Timeout = value;
      endif
    endfunction

    function f = set.Username (f, value)
      if (! ischar (value) && ! isrow (value))
        error ("weboptions: Username must be a string");
      else
        f.Username = value;
      endif
    endfunction

    function f = set.Password (f, value)
      if (! ischar (value) && ! isrow (value))
        error ("weboptions: Password must be a string");
      else
        f.Password = value;
      endif
    endfunction

    function f = set.KeyName (f, value)
      if (! ischar (value) && ! isrow (value))
        error ("weboptions: invalid KeyName value");
      else
        f.KeyName = value;
      endif
    endfunction

    function f = set.KeyValue (f, value)
      if (isempty (f.KeyName) && ! isempty (value))
        error ("weboptions: field KeyName empty.  Cannot set KeyValue.");
      else
        f.KeyValue = value;
      endif
    endfunction

    function f = set.HeaderFields (f, value)
      if (! isempty (value))
        if (! iscellstr (value) || ! ismatrix (value))
          error ("weboptions: HeaderFields must be array of strings or a cell array");
        elseif (columns (value) != 2)
          error ("weboptions: HeaderFields must be of size m-by-2");
        endif
      endif
      f.HeaderFields = value;
    endfunction

    function f = set.ContentType (f, value)
      if (! isempty (value))
        if (! any (strcmpi (value, {"auto", "json", "text"})))
          error ("weboptions: invalid ContentType value");
        endif
      endif
      f.ContentType = value;
    endfunction

    function f = set.ContentReader (f, value)
      f.ContentReader = value;
    endfunction

    function f = set.MediaType (f, value)
      f.MediaType = value;
    endfunction

    function f = set.RequestMethod (f, value)
      if (! isempty (value))
        if (! any (strcmpi (value, {"auto", "get", "put", "post",...
                                    "delete", "patch"})))
          error ("weboptions: invalid RequestMethod value");
        endif
      endif
      f.RequestMethod = value;
    endfunction

    function f = set.ArrayFormat (f, value)
      if (! isempty (value))
        if (! any (strcmpi (value, {"csv", "json", "php", "repeating"})))
          error ("weboptions: invalid ArrayFormat value");
        endif
      endif
      f.ArrayFormat = value;
    endfunction

    function f = set.CertificateFilename (f, value)
      f.CertificateFilename = value;
    endfunction

    function display (f)
      Timeout = int2str (f.Timeout);
      Password = repmat ("*", 1, numel (num2str (f.Password)));

      if (! isempty (f.ContentReader))
        ContentReader = ['["', strjoin(f.ContentReader, '", "'), '"]'];
      else
        ContentReader = "[]";
      endif

      if (! isempty (f.HeaderFields))
        HeaderFields = ['{"', strjoin(f.HeaderFields, '", "'), '"}'];
      else
        HeaderFields = "{}";
      endif

      if (! isempty (f.KeyValue))
        KeyValue = num2str (f.KeyValue);
      else
        KeyValue = "''";
      endif

      printf ("%s =", inputname (1));
      output = ["\n\n   weboptions with properties:     \n",...
                "\n      CharacterEncoding: '", f.CharacterEncoding, "'",...
                "\n              UserAgent: '", f.UserAgent, "'",...
                "\n                Timeout: " , Timeout, "",...
                "\n               Username: '", f.Username, "'",...
                "\n               Password: '", Password, "'",...
                "\n                KeyName: '", f.KeyName, "'",...
                "\n               KeyValue: " , KeyValue,...
                "\n            ContentType: '", f.ContentType, "'",...
                "\n          ContentReader: " , ContentReader,...
                "\n              MediaType: '", f.MediaType, "'",...
                "\n          RequestMethod: '", f.RequestMethod, "'",...
                "\n            ArrayFormat: '", f.ArrayFormat, "'",...
                "\n           HeaderFields: " , HeaderFields,...
                "\n    CertificateFilename: '", f.CertificateFilename, "'\n"];
      disp (output);
    endfunction

  endmethods

endclassdef