tutorial

function  tutorial
% tutorial function for 'handles' object
%
% requires 'handles' object, samplelib1.m samplelib2.m
% version 1.0
% INPUT(s): NONE
% OUTPUT(s): NONE
%
% (c) Mihai Moldovan 2002
% [e-mail]


% --------------------------------------------------------------------
% THE PROBLEM
% --------------------------------------------------------------------

% The initial MATLAB programming model assumed that each function is in a separate file.
% When the programs became more complex the 'subfunctions' were introduced. The idea 
% was that subfunctions are helper functions that can't be accessed from outside the 
% primary function file. This paradigm changed again with the GUIDE implementation.
% The callbacks in the *.fig file are passed to the primary function in the *.m file
% that distributes them to the subfunctions using a 'FEVAL switchyard'. What's next?
%
% One idea will be to consider a more 'object oriented' view. Objects are supported
% by MATLAB but their practical use is shaded by the complexity of implementation.
% When looking at function files like objects, it will be nice to consider 
% the subfunctions as methods of the primary functions. In this case subfunctions
% became simply available from outside their function files. Something like:
%
% argout=somefunction.somesubfunction(argin1, argin2, ...);

% --------------------------------------------------------------------
% THE SOLUTION
% --------------------------------------------------------------------

% MATLAB provides a mechanism to access functions by their handles.
% In principle if you know the handle of a function or a subfunction,
% you can call it from anywhere. I implemented this mechanism in an
% 'functionsclass' object. To use it:

% f=functionsclass;
% argout=f.somefunction.somesubfunction(argin1, argin2, ...);
% argout=f.somefunction(argin1, argin2, ...);


% --------------------------------------------------------------------
% THE IMPLEMENTATION
% --------------------------------------------------------------------

% when using an object it is required the the parent folder
% is the current folder or is in the MATLAB path
addpath(pwd)

% for the purpose of this tutorial we clear all object classes
clear classes

% clear the command window
clc

% --------------------------------------------------------------------

help functionsclass

% --------------------------------------------------------------------

% the first step is to create an object
% this will call the constructor method that builds
% the 'cache' property - the only property of the object.
% 'cache' is listed whenever MATLAB displays the contents of the object

f=functionsclass

% --------------------------------------------------------------------

% we can check the object class
class(f)


% --------------------------------------------------------------------
%we can list the methods of h
methods(f)


% We define only the standard set of methods that
% enable the class to behave in a consistent and logical way
% within the MATLAB environment.


% The public methods in the @HANDLES folder
% handles - the constructor
% set/get - Accesses 'Cache' property.
% subsref - Enables indexed reference: 'object.function.subfunction' 
%           This is the main method of handles object
% char    - Converts to a MATLAB char data type by listing the contents 
%           of the 'cache' property 
% display - Called whenever MATLAB displays the contents the object 
%           (e.g., when an expression is entered without terminating with a
%            semicolon); it is based on the 'char' method

% NOTE:     there is no 'destructor' method in MATLAB


% The private methods in the @HANDLES\PRIVATE folder
% subhandles   - It will get the handles to the subfunctions in a structure
%                mostly like the 'guihandles'   
% subfunctions - Pharses a function file and extract the names of its subfunctions
% functionfile - Returns the filepath of the function based on MATLAB priorities

% NOTE:          The subfunctions is called from an external function 
%                by it's handle because is NOT in the public path



% --------------------------------------------------------------------
%To call the samplelib1 SIMPLY type
x=f.samplelib1 ('test')

% Note: this notation triggered the subsref method 
% the samplelib returns no value so x=[]

% --------------------------------------------------------------------

%To call the subfunction echo3 in function samplelib2 SIMPLY type
x=f.samplelib1.echo2 ('test2')

% Note: You can get the handle any .m function that matlab can use
%       Including this tutorial.m

% --------------------------------------------------------------------
%The subfunction handle extraction is a complex operation
%This is why the cache property was implemented
%To see how this works we are going to time the operations using tic/toc

tic 
x=f.samplelib2.echo3 ('test3') 
toc

% and now from cache

tic 
x=f.samplelib2.echo3 ('test3')
toc

% --------------------------------------------------------------------
% to list the cache you shoud just display the object

f

% Note this calls the display method

% --------------------------------------------------------------------
% to read the cache in a variable invoke the get method

v=get (f,'Cache')

% each function is represented in the cache as a nested structure
% .name
% .handle
% .subfunctions (variable structure of handles)

% to list the subfunctions of the first functon in cache
v{1}.subfunctions

% --------------------------------------------------------------------
% we can create a new object with the same 'Cache'
% MATLAB does this by managing the workspace
x=f
% Note that in this case the handles constructor method is NOT called 

% --------------------------------------------------------------------
% If for some reason we want to clear the cache of an object
% We need to set it's property to empty

%From the MATLAB help we find that:
%
% <<
% In MATLAB, there is no passing of variables by reference.
% When writing methods that update an object, you
% must pass back the updated object and use an assignment statement. 
% For instance, this call to the set method updates the name field of the object A 
% and returns the updated object.
% A = set(A,'name','John Smith');
% >>

% In our case this means that we should write:
f=set (f,'Cache',[])

% however IT IS POSSIBLE to simulate passing variables by reference
% Check the handles set metod for implementation details
% This will also work
set (x,'Cache',[])

x

%NOTE the same technique is used in subsref to update the cache

% --------------------------------------------------------------------
%To clear the objects
clear f x