mfileparse

PURPOSE ^

Parsing of an M-file to obtain synopsis, help and references

SYNOPSIS ^

function s = mfileparse(mfile, mdirs, names, options)

DESCRIPTION ^

Parsing of an M-file to obtain synopsis, help and references
  S = MFILEPARSE(MFILE, MDIRS, NAMES, OPTIONS) parses the M-file MFILE looking
  for synopsis (function), H1 line, subroutines and todo tags (if any).
  It also fills in a boolean array indicating whether MFILE calls M-files 
  defined by MDIRS (M-files directories) AND NAMES (M-file names).
  The input OPTIONS comes from M2HTML: fields used are 'verbose', 'global'
  and 'todo'.
  Output S is a structure whose fields are:
     o synopsis: char array (empty if MFILE is a script)
     o h1line: short one-line description into the first help line
     o subroutine: cell array of char containing subroutines synopsis
     o hrefs: boolean array with hrefs(i) = 1 if MFILE calls mdirs{i}/names{i}
     o todo: structure containing information about potential todo tags

  See also M2HTML

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function s = mfileparse(mfile, mdirs, names, options)
0002 %Parsing of an M-file to obtain synopsis, help and references
0003 %  S = MFILEPARSE(MFILE, MDIRS, NAMES, OPTIONS) parses the M-file MFILE looking
0004 %  for synopsis (function), H1 line, subroutines and todo tags (if any).
0005 %  It also fills in a boolean array indicating whether MFILE calls M-files
0006 %  defined by MDIRS (M-files directories) AND NAMES (M-file names).
0007 %  The input OPTIONS comes from M2HTML: fields used are 'verbose', 'global'
0008 %  and 'todo'.
0009 %  Output S is a structure whose fields are:
0010 %     o synopsis: char array (empty if MFILE is a script)
0011 %     o h1line: short one-line description into the first help line
0012 %     o subroutine: cell array of char containing subroutines synopsis
0013 %     o hrefs: boolean array with hrefs(i) = 1 if MFILE calls mdirs{i}/names{i}
0014 %     o todo: structure containing information about potential todo tags
0015 %
0016 %  See also M2HTML
0017 
0018 %  Copyright (C) 2003 Guillaume Flandin <Guillaume@artefact.tk>
0019 %  $Revision: 1.1 $Date: 2008-09-03 08:36:22 $
0020 
0021 narginchk(3,4);
0022 if nargin == 3,
0023     options = struct('verbose',1, 'globalHypertextLinks',0, 'todo',0);
0024 end
0025 
0026 %- Delimiters used in strtok: some of them may be useless (% " .), removed '.'
0027 strtok_delim = sprintf(' \t\n\r(){}[]<>+-*~!|\\@&/,:;="''%%');
0028 
0029 %- Open for reading the M-file
0030 if options.verbose
0031     fprintf('Processing file %s...\n',mfile);
0032 end
0033 fid = openfile(mfile,'r');
0034 it = 0; % line number
0035 
0036 %- Initialize Output
0037 s = struct('synopsis',   '', ...
0038            'h1line',     '', ...
0039            'subroutine', {{}}, ...
0040            'hrefs',      sparse(1,length(names)), ...
0041            'todo',       struct('line',[],'comment',{{}}), ...
0042            'ismex',      zeros(size(mexexts)));
0043 
0044 %- Initialize flag for synopsis cont ('...')
0045 flagsynopcont = 0;
0046 %- Look for synopsis and H1 line
0047 %  Help is the first set of contiguous comment lines in an m-file
0048 %  The H1 line is a short one-line description into the first help line
0049 while 1
0050     tline = fgetl(fid);
0051     if ~ischar(tline), break, end
0052     it = it + 1;
0053     tline = deblank(fliplr(deblank(fliplr(tline))));
0054     %- Synopsis line
0055     if ~isempty(strmatch('function',tline))
0056         s.synopsis = tline;
0057         if ~isempty(strmatch('...',fliplr(tline)))
0058             flagsynopcont = 1;
0059             s.synopsis = deblank(s.synopsis(1:end-3));
0060         end
0061     %- H1 Line
0062     elseif ~isempty(strmatch('%',tline))
0063         % allow for the help lines to be before the synopsis
0064         if isempty(s.h1line)
0065             s.h1line = fliplr(deblank(tline(end:-1:2)));
0066         end
0067         if ~isempty(s.synopsis), break, end
0068     %- Go through empty lines
0069     elseif isempty(tline)
0070         
0071     %- Code found. Stop.
0072     else
0073         if flagsynopcont
0074             if isempty(strmatch('...',fliplr(tline)))
0075                 s.synopsis = [s.synopsis tline];
0076                 flagsynopcont = 0;
0077             else
0078                 s.synopsis = [s.synopsis deblank(tline(1:end-3))];
0079             end
0080         else
0081             break;
0082         end
0083     end
0084 end
0085 
0086 %- Global Hypertext Links option
0087 %  If false, hypertext links are done only among functions in the same
0088 %  directory.
0089 if options.globalHypertextLinks
0090     hrefnames = names;
0091 else
0092     indhref = find(strcmp(fileparts(mfile),mdirs));
0093     hrefnames = {names{indhref}};
0094 end
0095 
0096 %- Compute cross-references and extract subroutines
0097 %  hrefs(i) is 1 if mfile calls mfiles{i} and 0 otherwise
0098 while ischar(tline)
0099     % Remove blanks at both ends
0100     tline = deblank(fliplr(deblank(fliplr(tline))));
0101     
0102     % Split code into meaningful chunks
0103     splitc = splitcode(tline);
0104     for j=1:length(splitc)
0105         if isempty(splitc{j}) | ...
0106             splitc{j}(1) == '''' | ...
0107             ~isempty(strmatch('...',splitc{j}))
0108             % Forget about empty lines, char strings or conts
0109         elseif splitc{j}(1) == '%'
0110             % Cross-references are not taken into account in comments
0111             % Just look for potential TODO line
0112             if options.todo
0113                 if ~isempty(strmatch('% TODO %',splitc{j}))
0114                     s.todo.line   = [s.todo.line it];
0115                     s.todo.comment{end+1} = splitc{j}(9:end);
0116                 end
0117             end
0118         else
0119             % detect if this line is a declaration of a subroutine
0120             if ~isempty(strmatch('function',splitc{j}))
0121                 s.subroutine{end+1} = splitc{j};
0122             else
0123                 % get list of variables and functions
0124                 symbol = {};
0125                 while 1
0126                     [t,splitc{j}] = strtok(splitc{j},strtok_delim);
0127                     if isempty(t), break, end;
0128                     symbol{end+1} = t;
0129                 end
0130                 if options.globalHypertextLinks
0131                     s.hrefs = s.hrefs + ismember(hrefnames,symbol);
0132                 else
0133                     s.hrefs(indhref) = s.hrefs(1,indhref) + ...
0134                                        ismember(hrefnames,symbol);
0135                 end
0136             end
0137         end
0138     end
0139     tline = fgetl(fid);
0140     it = it + 1;
0141 end    
0142 
0143 fclose(fid);
0144 
0145 %- Look for Mex files
0146 [pathstr,name] = fileparts(mfile);
0147 samename = dir(fullfile(pathstr,[name    '.*']));
0148 samename = {samename.name};
0149 for i=1:length(samename)
0150     [dummy, dummy, ext{i}] = fileparts(samename{i});
0151 end
0152 s.ismex = ismember(mexexts,ext);

Generated on Fri 22-Aug-2008 15:38:13 by m2html © 2003