function addedObjects = add(targetObject, options)
%TARGET.ADD    Add target object to internal database.
%   addedObjects = TARGET.ADD(targetObject) adds the specified
%   target object and any associated target objects to an internal database
%   and returns a vector of the added objects. If an object already exists
%   in the database, then it is not returned in the output. By default,
%   the target data is available only for the current session.
%
%   addedObjects = TARGET.ADD(..., Name, Value) configures the object using
%   one or more name-value pair arguments.
%   Supported argument names include:
%
%   UserInstall         Controls persistence of target objects over
%                       sessions. If false (default), target object is
%                       available only for the current session. If true,
%                       target object persists over multiple sessions.
%
%   SuppressOutput      Controls text output. If false (default), text is
%                       printed to the Command Window with information
%                       about the added target objects. If true, this
%                       output is suppressed.
%
%   See also TARGET.CREATE, TARGET.GET, TARGET.REMOVE

%   Copyright 2018-2022 The MathWorks, Inc.

    arguments (Input)
        targetObject (1, :) target.Object
        options.UserInstall (1, 1) logical = false
        options.SuppressOutput (1, 1) logical = false
    end
    arguments (Output)
        addedObjects target.Object {mustBeVector(addedObjects, "allow-all-empties")}
    end

    internalObject = targetframework.internal.user.commandline.matlab.Helpers.unwrapValues(targetObject);
    namedargs = namedargs2cell(options);

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

    addedObjects = targetframework.internal.user.commandline.matlab.Helpers.wrapValues(addedInternalObjects);
end
