function hh = boundaryline(varargin)
%BOUNDARYLINE Draw boundary line plot
%
%   BOUNDARYLINE( X, Y ) plots a boundary line specified by the
%   X data, X, and Y data, Y.
%   The boundary line hatches extend from a fixed space and length along the
%   boundary line.
%
%   BOUNDARYLINE( X, Y, LINESPEC ) plots a boundary line specified by the
%   X data X, Y data Y, and line specification LINESPEC.
%
%   BOUNDARYLINE(___, Name,Value ) plots a boundary line specified by one or more
%   Name,Value pairs.  Adjust the look of the boundary line with the
%   'Hatches', 'HatchLength', 'HatchTangency', 'HatchAngle', 'HatchSpacing', and
%   'FlipBoundary' properties.
%
%   BOUNDARYLINE(AX, ___) plots a boundary line on the specified axes AX instead
%   of the current axes (gca).
%
%   H = BOUNDARYLINE(___) returns a boundaryline object.
%
% Inputs:
%   AX       :Optional scalar handle to a valid axes. By default, BOUNDARYLINE 
%             plots to the current axes. 
%             To get the current axes, use the gca function.
%
%   X        :Numeric vector of X coordinate data. The function uses this data to
%             plot the X coordinates of the boundary line.
%
%   Y        :Numeric vector of Y coordinate data. The function uses this data to
%             plot the Y coordinates of the boundary line.
%
%   LINESPEC :Scalar string specifying the line specification for the
%             plotted boundaryline.
%             LINESPEC is made of one element from any or all the following 3 columns.
%          Line Color:         Marker Style:           Line Style:
%          b     blue          .     point              -     solid
%          g     green         o     circle             :     dotted
%          r     red           x     x-mark             -.    dashdot
%          c     cyan          +     plus               --    dashed
%          m     magenta       *     star             (none)  no line
%          y     yellow        s     square
%          k     black         d     diamond
%          w     white         v     triangle (down)
%                              ^     triangle (up)
%                              <     triangle (left)
%                              >     triangle (right)
%                              p     pentagram
%                              h     hexagram
%
% Name,Values
%   Hatches      :String specifying the hatches style for the boundary line.
%                 The hatch angle is determined by the hatches type:
%                   '/' :Forward slant.
%                   '\' :Backward slant.
%                   '|' :Perpendicular slant.
%
%                 The length of the string determines the hatch spacing. The
%                 more hatches specified, the closer the spacing. For example:
%
%                 boundaryline(X, Y, 'Hatches', '//') is a half-spaced forward slant.
%
%                 boundaryline(X, Y, 'Hatches', '|') is a single-spaced perpendicular slant.
%
%                 boundaryline(X, Y, 'Hatches', '\\\') is a third-spaced backward slant.
%
%                 The 'Hatches' property works in with 'HatchTangency',
%                 'HatchLength' and 'FlipBoundary'.
%                 For fine control of the hatch segments, use 'HatchAngle' and 'HatchSpacing'.
%
%   FlipBoundary :Scalar on-off switch to flip the HatchAngle 180 degrees.
%                 Must be one of the following:
%                   'on'  :Flip HatchAngle 180 degrees.
%                   'off' :Do not Flip HatchAngle.
%                 Default is 'off'.
%
%   HatchTangency :Scalar on-off switch specifying the hatch angle tangency rule.
%                 Must be one of the following:
%                   'on'  :HatchAngle is relative to the tangent of the line segment.
%                          Tangency is determined by the line integral
%                          traversing from the start to the end of
%                          the X and Y data.
%                   'off' :HatchAngle is relative to 0.
%                 Default is 'on'.
%
%   HatchLength   :Scalar numeric value specifying the length of the hatch segments.
%                  HatchLength is relative to the normalized frame between
%                  [0,1]. For best results, use a decimal value below 1 for
%                  the hatch length.
%
%   HatchAngle    :Scalar numeric value specifying the angle of the
%                  hatch segments in degrees.
%                  The function automatically calculates HatchAngle if 'Hatches' is specified.
%
%   HatchSpacing  :Scalar numeric value specifying the spacing between hatch segments.
%                  The function automatically calculates HatchSpacing if 'Hatches' is specified.
%                  HatchSpacing is relative to the normalized length of the boundary
%                  line, where the line is normalized to be of length 1.
%                  A spacing of 0.25 means a hatch every 0.25 units along the
%                  normalized line, [0, 0.25, 0.5, 0.75, 1], which equals 5 hatches total.
%
%   Color        :String specifying the color of the boundary line.
%                 This property overrides the color specified by LINESPEC.
%
%   LineStyle    :String specifying the style of the boundary line.
%                 This property overrides the line style specified by LINESPEC.
%
%   LineWidth    :Scalar numeric value specifying the width of the boundary line.
%
%   HatchSpacingMode :Scalar string specifying the hatch spacing mode.
%                     Must be one of the following:
%                       'auto'   :Automatically calculate the hatch
%                                 spacing based on 'Hatches'.
%                       'manual' :Hatch spacing is manually set to a constant.
%                     By default, HatchSpacingMode is 'auto'.
%
%   HatchAngleMode   :Scalar string specifying the hatch angle mode.
%                     Must be one of the following:
%                       'auto'   :Automatically calculate the hatch
%                                 angle based on 'Hatches'.
%                       'manual' :Manually set the hatch angle.
%                     By default, HatchAngleMode is 'auto'.
%
%   To see a list of line object properties and their current values,
%   run GET(H), where H is a boundaryline object.
%   To see a list of boundaryline object properties and their allowed values,
%   run SET(H), where H is a boundaryline object.
%
% Outputs:
%   H :Scalar Aero.graphics.primitive.BoundaryLine object.
%
% Examples:
%   Plot a boundary line of a sine wave:
%     x = linspace(0, 2*pi);
%     y = sin(x);
%     b = boundaryline(x,y)
%
%   Plot a linear boundary line using half-spaced hatches:
%     b = boundaryline([0,1],[0,1], 'Hatches','//')
%
%   Plot a circle boundary line and flip the boundary after creation:
%     t = linspace(0, 2*pi);
%     x = cos(t);
%     y = sin(t);
%     b = boundaryline(x,y)
%     b.FlipBoundary = true
%
%   Plot a red, dashed and dotted, square boundary line on a specified axes:
%     a = gca;
%     boundaryline(a, [0,1,1,0,0], [0,0,1,1,0], 'r-.')

% Copyright 2021 The MathWorks, Inc.

narginchk(2,inf);

args = matlab.graphics.internal.convertStringToCharArgs(varargin);

% get the parent nvp g2447291
[args, cax] = Aero.internal.namevalues.getAxesFromFirstArgumentOrNameValuePair(args);

if isa(cax,"matlab.graphics.axis.PolarAxes") || ...
        isa(cax,"matlab.graphics.axis.GeographicAxes") || ...
        isa(cax,"matlab.graphics.chart.Chart")

    % boundaryline can only be parented to cartesian axes.
    error(message("MATLAB:hg:InvalidParent",'BoundaryLine', ...
        fliplr(strtok(fliplr(class(cax)), '.'))));
end

% Parse remaining args
try
    pvpairs = parseBoundaryLineInputs(args);
catch ME
    throw(ME)
end

h = Aero.graphics.primitive.BoundaryLine("Parent",cax,pvpairs{:});

if nargout > 0
    hh = h;
end

end