function remove(targetType, targetObjectId, options)
%TARGET.REMOVE Remove target objects from internal database.
%   TARGET.REMOVE(targetObject) removes the specified target objects from
%   an internal database, using their type and identifier. targetObject can
%   be a scalar or vector of target objects. If the target object was added
%   with data persistence ('UserInstall' set to true), TARGET.REMOVE will
%   end data persistence across sessions.
%
%   TARGET.REMOVE(targetType, targetObjectId) removes a target object from
%   the database using the specified type and identifier. If a target
%   object does not exist in the database, no action is performed.
%
%   TARGET.REMOVE(..., Name, Value) removes the specified target object
%   from the database using the name-value pairs.
%   Supported argument names include:
%
%   IncludeAssociations If value is false (default), only the specified
%                       target object is removed. If value is true, all
%                       associated targets are also removed.
%
%   SuppressOutput      Controls text output. If false (default), text is
%                       printed to the Command Window with information
%                       about the removed target objects. If true, this
%                       output is suppressed.
%
%   See also TARGET.CREATE, TARGET.ADD, TARGET.GET

%   Copyright 2018-2022 The MathWorks, Inc.

    arguments (Input)
        targetType {mustBeTextOrTarget}
        targetObjectId string {mustBeVector(targetObjectId, "allow-all-empties")} = string.empty()
    end
    arguments (Input)
        options.IncludeAssociations (1, 1) logical = false
        options.SuppressOutput (1, 1) logical = false
    end

    % Process first two arguments.
    if isempty(targetObjectId)

        mustBeA(targetType, "target.Object");
        targetDescription = {targetframework.internal.user.commandline.matlab.Helpers.unwrapValues(targetType)};
    else

        mustBeNonzeroLengthText(targetType);
        arrayfun(@(x) target.internal.validators.mustBeTarget(x), convertCharsToStrings(targetType));

        targetDescription = {targetType, targetObjectId};
    end

    namedargs = namedargs2cell(options);

    % Catch any error thrown by the internal APIs and rethrow it by hiding
    % the stack.
    try
        target.internal.remove(targetDescription{:}, namedargs{:});
    catch exception
        throwAsCaller(exception);
    end
end

function mustBeTextOrTarget(argument)

    if isa(argument, "handle")
        mustBeA(argument, "target.Object");
    else
        mustBeNonzeroLengthText(argument);
    end
end
