env_capture(varargin)

function env = env_capture(varargin)
% function env = env_capture(varargin)
%  Capture the scope/environment of the caller. This is useful
%  to snapshot in a running function all local (and local global)
%  including persistent variables with their bindings.
% 
%  If no arguments provided, returns all bindings from caller context.
% Example execution:
%  env = env_capture('ignore', 'ans', 'maxbytes',  100);
%
% Optional Input:
% varargin = keyword/argument pair: (keyed on first letter of keyword)
%    +-------+----------+------------------------------------+
%    |keyword|  value   |            description             |
%    |       |(example) |                                    |
%    +-------+----------+------------------------------------+
%    |   m   |   1000   |     maximum number of bytes of     |
%    |       |          |         varibles to capture        |
%    +-------+----------+------------------------------------+
%    |   i   |  'ans'   |      variable name to ignore       |
%    +-------+----------+------------------------------------+
% 
% Output:
%  env = <struct> whose fieldnames are the variables declared/bound
%                 in the scope of the caller and whose values are the
%                 values of the variables.
%
% Note: multiple variables can be ignored like in the following:
%       env_capture('ignore', 'ans', 'ignore', 'beta', 'maxbytes', 1000);
%
% Author: David Weinstein ([e-mail])


    %% initialize output
    env = struct();
    
    %% determine variables in scope of caller, return if none.
    cntx  = evalin('caller', 'whos');
    vars  = {cntx.name};
    sizes = [cntx.bytes];
    
    if isempty(vars), return, end

    %% deal with input arguments (keyword/arg pairs)
    if nargin >= 2
        argin_vars = {varargin{1:2:end}};
        argin_vals = {varargin{2:2:end}};
        
        for kk = 1:length(argin_vars)
            cur_var = argin_vars{kk};
            cur_val = argin_vals{kk};
            filter_p = 0;
            keep_inds = [];
            
            switch cur_var(1)        
                case 'm'
                    opt_max_byte_size = cur_val;
                    %% filter some of the variables away (if optional
                    %% argument provided)
                    keep_inds = find( sizes <= opt_max_byte_size );
                    filter_p = 1;
                case 'i'
                    ignore_var = cur_val;
                    bad_inds   = strmatch(ignore_var, vars, 'exact');
                    keep_inds  = setdiff( (1:length(vars)), bad_inds );
                    filter_p = 1;
            end
            
            if filter_p
                vars  = {vars{keep_inds}};
                sizes = sizes(keep_inds);
            end
        end
    end
        
    %% preallocate the space for values; bind them. 
    vals = cell(1,length(vars));
    
    for kk = 1:length(vars),
        vals{kk} = evalin('caller', vars{kk});
    end
    
    %% bind the return environment
    env = cell2struct(vals, vars, 2);

    return
%%%%%