Custom Toolbox Strategies

You can extend the ToolboxToolbox to support additional types of toolbox by implementing a new subclass of the TbToolboxStrategy class. See the current strategy implementations for inspiration.

Mandatory Methods

TbToolboxStrategy declares two abstract methods which your subclass must implement.

obtain()

You must implement the obtain() method so that the toolbox is downloaded/located/cloned, etc., as appropriate.

[command, status, message] = obtain(obj, record, toolboxRoot, toolboxPath);

The ToolboxToolbox will supply the following inputs. You should use these to figure out what to fetch and where to store it:

Input	Interpretation
obj	The object itself.
record	A toolbox record struct. See Toolbox-Records-and-Types.
toolboxRoot	The toolbox folder where all obtained toolboxes are located.
toolboxPath	The specific subfolder where this toolbox should be saved.

You should return the following outputs to communicate with the ToolboxToolbox and users.

Output	Interpretation
command	An informal string indicating what you are trying to do, like "git clone" or similar.
status	Numeric status code that resulted from the command, 0 indicates success, non-zero indicates failure.
message	A string result or error message that resulted from the command.

update()

You must implement the update() method so that the toolbox is updated as appropriate. The inputs and outputs are the same as for the obtain() method.

[command, status, message] = update(obj, record, toolboxRoot, toolboxPath);

When deploying a record, the ToolboxToolbox will decide whether to call obtain(), update(), or neither, depending on the result of the strategy's checkIfPresent() method and the value of the record's update field.

Optional Methods

TbToolboxStrategy implements three methods which your subclass may choose to re-implement.

toolboxPath()

The toolboxPath() method chooses the specific subfolder where a toolbox should be saved.

[toolboxPath, displayName] = toolboxPath(obj, toolboxRoot, record, varargin)

The default behavior is to choose a folder inside the given toolboxRoot, based on the record's name, flavor, and subfolder fields. See tbToolboxPath().

Input	Interpretation
obj	The object itself.
toolboxRoot	The toolbox folder where all obtained toolboxes are located.
record	A toolbox record struct. See Toolbox-Records-and-Types.
withSubfolder	Optional named parameter, whether the returned path should include the record's subfolder or not. By default, the subfolder should be omitted.

Output	Interpretation
toolboxPath	The specific subfolder where a toolbox should be saved.
displayName	A human-readable name based on the record's name and flavor fields.

checkIfPresent()

The checkIfPresent() determines whether a toolbox has already been obtained.

isPresent = checkIfPresent(obj, record, toolboxRoot, toolboxPath)

The default behavior is to check whether the given toolboxPath is a folder that exists and is not empty.

Input	Interpretation
obj	The object itself.
record	A toolbox record struct. See Toolbox-Records-and-Types.
toolboxRoot	The toolbox folder where all obtained toolboxes are located.
toolboxPath	The specific folder where this toolbox should be saved.

Output	Interpretation
isPresent	Whether or not the toolbox has already been obtained.

addToPath()

The addToPath() method adds the toolbox to the Matlab path.

toolboxPath = addToPath(obj, record, toolboxPath)

The default behavior is to use genpath() on the given toolboxPath and to add the resulting path values to the Matlab path using addpath(). Unnecessary folders like ".git" will be removed. The toolbox will be added to the top or bottom of the Matlab path based on the record's pathPlacement field. See tbAddToolboxPath().

Input	Interpretation
obj	The object itself.
record	A toolbox record struct. See Toolbox-Records-and-Types.
toolboxPath	The specific toolbox folder that should be added to the path.

Output	Interpretation
toolboxPath	The specific toolbox folder that was added to the path.

Using Your Custom Class

Once you have written your custom strategy, you can refer to it from toolbox records using the name of the class. See Toolbox-Records-and-Types.