%FIND_SYSTEM Find items within Simulink systems
%   OBJECTS=FIND_SYSTEM searches loaded block diagram systems and returns a cell array containing
%   block diagrams and blocks in hierarchical order.
%
%   OBJECTS=FIND_SYSTEM(SYSTEM) returns SYSTEM and its blocks in hierarchical order.
%
%   OBJECTS=FIND_SYSTEM(CONSTRAINT1,VALUE1,CONSTRAINT2,VALUE2,...) searches all loaded block
%   diagrams and returns a cell array containing block diagrams and blocks in hierarchical order
%   that meet the criterion specified by one or more CONSTRAINT, VALUE pairs.
%
%   OBJECTS=FIND_SYSTEM(SYSTEM,CONSTRAINT1,VALUE1,CONSTRAINT2,VALUE2,...) searches SYSTEM and
%   returns a cell array containing block diagrams and blocks in hierarchical order that meet the
%   criterion specified by one or more CONSTRAINT, VALUE pairs.
%
%   SYSTEM is either a scalar or cell array of block diagram system elements. Each element can be a
%   path name or handle. You obtain the handle for a system using get_param(SYSTEM,'handle'). An
%   element can be a block diagram or the path to an element within a block diagram, e.g. a system
%   can be a block diagram, block, etc. There are three types of block diagram systems, 'model',
%   'subsystem', and 'library'.
%
%   OBJECTS is a cell array of path names or handles to block diagram system elements. Path names
%   are returned when you specify SYSTEM as a path name or a cell array of path names and are not
%   using the 'FindAll', 'on' constraint; otherwise handles are returned.
%
%   There are two types of constraints, general constraints and object parameter constraints. The
%   general constraints must come *before* the object parameter constraints.
%
%   General CONSTRAINT, VALUE pairs:
%   -------------------------------
%   Case is ignored for CONSTRAINTS, e.g. 'SearchDepth' and 'searchDepth' are equivalent.
%
%   'SearchDepth', INTEGER
%        Limit search to a specific depth in the block diagram hierarchy. A value of 0 searches only
%        the top-level of the specified systems. A value of 1, searches the top-level of all systems
%        and the blocks in the top-level of each system.
%        Example: to find all open block diagrams, use
%           >> find_system('SearchDepth',0)
%        Example: to find all blocks at in the top layer of SYSTEM, use
%           >> find_system(SYSTEM,'SearchDepth',1,'Type','Block')
%           where SYSTEM could be a block diagram, e.g. 'myModel' or it could be a layer within a
%           block diagram, e.g. 'myModel/SubsystemName'.
%        Example: to find all Goto blocks in top-level layer of SYSTEM, use
%           >> find_system(SYSTEM,'SearchDepth',1,'BlockType','Goto')
%
%   'FindAll', 'off' (default) | 'on'
%        If 'on', search block diagrams, blocks, annotations, lines, and ports.
%        When 'on', the result from FIND_SYSTEM is always a vector of handles.
%        If 'off', search only block diagrams and blocks.
%        Example: to find all blocks starting with 'a' with result as a vector of handles, use:
%          >> find_system(bdroot,'FindAll','on','Regexp','on','Type','block','Name','^a')
%
%   'FirstResultOnly', 'off' (default) | 'on'
%        If 'on' return only the first result and then stop the search.
%
%   'Type', 'block_diagram' | 'block' | 'line' | 'port' | 'annotation'
%        Default is to return 'block_diagram' and 'block' objects.
%        'block_diagram' includes any type of block diagram: 'model', 'subsystem', or 'library'.
%        Example: to find all open block diagram systems, use
%          >> systems = find_system('Type','block_diagram')
%          and for a given block diagram system,
%          >> get_param(system{idx},'BlockDiagramType')
%          will return the block diagram system type, 'model', 'subsystem', or 'library'.
%        Example: find all block diagram systems and separate them into their types:
%          names:      All loaded block diagram systems
%          models:     All block diagrams of type 'model'
%          subsystems: All block diagrams of type 'subsystem'
%          libraries:  All block diagrams of type 'library'
%          >> names      = find_system('Type','block_diagram')
%          >> selectFcn  = @(name,type)isequal(type,get_param(name,'BlockDiagramType'));
%          >> models     = names(cellfun(@(name)selectFcn(name,'model'),names))
%          >> subsystems = names(cellfun(@(name)selectFcn(name,'subsystem'),names))
%          >> libraries  = names(cellfun(@(name)selectFcn(name,'library'),names))
%        Example: to find all annotations, in SYSTEM use
%          >> annotations = find_system(SYSTEM,'FindAll','on','Type','annotation')
%
%   'FollowLinks', 'off' (default) | 'on'
%        If 'on', resolve and search library links.
%        If 'off', library links are treated as individual blocks and search will not descend
%        beneath them.
%
%   'LookUnderMasks', 'graphical' (default) | 'off' / 'none' | 'functional' | 'on' / 'all'
%        Constrains the search from looking into different types of masked subsystems. A masked
%        block consists can consist of up to three items: icon drawing commands,
%        parameters & dialog, initialization commands which create a mask workspace.
%        See HASMASKICON, HASMASKDLG, HASMASK.
%
%        * 'graphical'     : Search inside masked subsystems with only icon drawing commands.
%        * 'off' or 'none' : Do not search inside masked subsystems.
%        * 'functional'    : Search inside masked subsystems with icon drawing commands and/or a
%                            workspace created by the initialization commands.
%        * 'on' or 'all'   : Search inside all masked subsystems.
%
%        Example: to find all blocks including masked blocks, in SYSTEM use
%          >> find_system(SYSTEM,'LookUnderMasks','on','FollowLinks','on')
%
%   'LoadFullyIfNeeded', 'on' (default) | 'off'
%        If 'on', fully load any partially loaded block diagrams. By default, block diagram
%        libraries are partially loaded to resolve library links. When find_system searches them,
%        it will finish loading the library.
%
%   'IncludeCommented', 'off' (default) | 'on'
%        If 'on', include commented blocks in the search.
%
%   'CaseSensitive', 'on' (default) | 'off'
%        If 'on' values of object parameter constraints are case sensitive.
%        If 'off' values of object parameter constraints are not case sensitive.
%        Example: to find all blocks whose name is 'Gain' in SYSTEM, use
%          >> find_system(SYSTEM,'Name','Gain')  % or equivalently
%          >> find_system(SYSTEM,'CaseSensitive','on','Name','Gain')
%        Example: to find all blocks whose name is 'gain', ignoring case, in SYSTEM use
%          >> find_system(SYSTEM,'CaseSensitive','off','Name','gain')
%
%   'RegExp', 'off' (default) | 'on'
%        If 'on', the VALUE of the object parameter constraints is a MATLAB regexp.
%        Example: to find all block types that have 'port' in the type,
%           e.g. Inport, Outport, etc. use
%           >> find_system(SYSTEM,'RegExp','on','BlockType','port')
%        Example: to find all blocks whose name start with an 'x' in SYSTEM, use
%           >> find_system(SYSTEM,'Regexp','on','Name','^x')
%        Example: to find all block names starting with 'gain' ignoring case and optionally 
%           followed by a number, use
%           >> find_system(SYSTEM,'RegExp','on','Name','^(?i:gain)\d*$')
%
%   'MatchFilter', @fcn
%        Select model elements using @fcn, a function handle, which is invoked by find_system.
%        find_system traverses the Simulink block diagram starting at SYSTEM. Using @fcn you 
%        can process each element that is seen during the traversal. @fcn should return match
%        set to true if the element is to be returned by find_system. @fcn should set prune 
%        to false if that branch (subsystem) of the tree should be trimmed from the search.
%        
%        [match, prune] = fcn(element)
%           element - Handle of the model element (block, line, annotation) being processed.
%           match   - Logical. If false, do not return the element in the find_system answer.
%           prune   - Optional logical (default false). If true, skip search of the current
%                     element, which only applies to subsystems.
%
%        Example: to find all Gain blocks with gain value in between 5 to 10 use:
%           function [match] = gainFiveToTen(el)
%               match = false;
%               if strcmp(get_param(el,'Type'),'block') && strcmp(get_param(el,'BlockType'),'Gain')
%                   gainValue = str2double(get_param(el, 'Gain'));
%                   match = gainValue >= 5 && gainValue <= 10;
%               end
%           end
%           >> find_system(SYSTEM,'MatchFilter',@gainFiveToTen);
%
%        Variants
%          Simulink provides the following post-compile match filters for variant block processing:
% 
%          @Simulink.match.activeVariants      : match blocks which are active in simulation.
%          @Simulink.match.codeCompileVariants : match blocks which are part of generated code.
%
%          Example: to find all blocks active in simulation use
%            >> set_param(SYSTEM, 'SimulationCommand', 'update');
%            >> find_system(SYSTEM, 'MatchFilter', @Simulink.match.activeVariants);
%
%          Example: to find blocks that will be in the generated code, use
%            >> MODEL([],[],[],'compileForCodegen')
%            >> find_system(MODEL, 'MatchFilter', @Simulink.match.codeCompileVariants);
%            >> MODEL([],[],[],'term')
%
%   'Variants', 'ActiveVariants' (default) | 'AllVariants' | 'ActivePlusCodeVariants'
%        Constrains the search from looking into Variant Subsystems
%          - 'ActiveVariants' : Search in only the active choices
%          - 'AllVariants' : Search in all variant choices
%          - 'ActivePlusCodeVariants' : Search all choices of variant subsystems with 
%            'VariantActivationTime' set to 'code compile', otherwise search in only the 
%            active variants choices.
%
%        The 'Variants' constraint applies only to Variant Subsystems that have the
%        VariantControlMode set to 'expression' or 'label'. Use the 
%        find_system function with the MatchFilter option to operate on all 
%        types of variant blocks.
% 
%   Object parameter CONSTRAINT, VALUE pairs:
%   ----------------------------------------
%   Object parameter constraints must come *after* the above general constraints.
%
%   'BlockDialogParams', 'VALUE'
%        Return blocks which have a block dialog parameter that contains the specified value.
%        Example: to find all blocks that have the string 'k' specified in one or more of its
%          block dialog parameters, use
%          >> find_system(SYSTEM,'BlockDialogParams','k')
%
%   'PARAMETER', 'VALUE'
%        All other constraints correspond to object parameters and that must match the specified
%        value. If the object doesn't have the specified parameter, the constraint is not
%        satisfied, and the object will not be returned.
%        Example: to find all blocks who have a parameter named 'ExternalReset' and whose value
%          is 'none', use
%          >> find_system(SYSTEM,'ExternalReset','none')
%        Example: to find all Gain blocks whose block name is Gain1 in SYSTEM, use
%          >> find_system(SYSTEM,'Name','Gain1','BlockType','Gain')
%        Example: to find all blocks in SYSTEM whose foreground color is black, use
%          >> find_system(SYSTEM,'ForegroundColor','black')
%        Example: to find all Gain blocks that have the value '1' in SYSTEM, use
%          >> gainBlocks = find_system(SYSTEM,'BlockType','Gain')
%          >> gainsWithValue1 = find_system(gainBlocks,'Gain','1')
%
%   See also SET_PARAM, GET_PARAM

%
%   Copyright 1990-2020 The MathWorks, Inc.
%   Built-in function.

% LocalWords:  el
