octave_packages/m/general/genvarname.m

   1 ## Copyright (C) 2008-2012 Bill Denney, Robert Platt
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {@var{varname} =} genvarname (@var{str})
  21 ## @deftypefnx {Function File} {@var{varname} =} genvarname (@var{str}, @var{exclusions})
  22 ## Create unique variable(s) from @var{str}.  If @var{exclusions} is
  23 ## given, then the variable(s) will be unique to each other and to
  24 ## @var{exclusions} (@var{exclusions} may be either a string or a cellstr).
  25 ##
  26 ## If @var{str} is a cellstr, then a unique variable is created for each
  27 ## cell in @var{str}.
  28 ##
  29 ## @example
  30 ## @group
  31 ## x = 3.141;
  32 ## genvarname ("x", who ())
  33 ##   @result{} x1
  34 ## @end group
  35 ## @end example
  36 ##
  37 ## If @var{wanted} is a cell array, genvarname will make sure the returned
  38 ## strings are distinct:
  39 ##
  40 ## @example
  41 ## @group
  42 ## genvarname (@{"foo", "foo"@})
  43 ##   @result{}
  44 ##      @{
  45 ##        [1,1] = foo
  46 ##        [1,2] = foo1
  47 ##      @}
  48 ## @end group
  49 ## @end example
  50 ##
  51 ## Note that the result is a char array/cell array of strings, not the
  52 ## variables themselves.  To define a variable, @code{eval()} can be
  53 ## used.  The following trivial example sets @code{x} to @code{42}.
  54 ##
  55 ## @example
  56 ## @group
  57 ## name = genvarname ("x");
  58 ## eval ([name " = 42"]);
  59 ##   @result{} x =  42
  60 ## @end group
  61 ## @end example
  62 ##
  63 ## Also, this can be useful for creating unique struct field names.
  64 ##
  65 ## @example
  66 ## @group
  67 ## x = struct ();
  68 ## for i = 1:3
  69 ##   x.(genvarname ("a", fieldnames (x))) = i;
  70 ## endfor
  71 ##   @result{} x =
  72 ##      @{
  73 ##        a =  1
  74 ##        a1 =  2
  75 ##        a2 =  3
  76 ##      @}
  77 ## @end group
  78 ## @end example
  79 ##
  80 ## Since variable names may only contain letters, digits and underscores,
  81 ## genvarname replaces any sequence of disallowed characters with
  82 ## an underscore.  Also, variables may not begin with a digit; in this
  83 ## case an underscore is added before the variable name.
  84 ##
  85 ## Variable names beginning and ending with two underscores "__" are valid but
  86 ## they are used internally by octave and should generally be avoided, therefore
  87 ## genvarname will not generate such names.
  88 ##
  89 ## genvarname will also make sure that returned names do not clash with
  90 ## keywords such as "for" and "if".  A number will be appended if necessary.
  91 ## Note, however, that this does @strong{not} include function names,
  92 ## such as "sin".  Such names should be included in @var{avoid} if necessary.
  93 ## @seealso{isvarname, exist, tmpnam, eval}
  94 ## @end deftypefn
  95
  96 ## Authors: Rob Platt <robert.platt@postgrad.manchester.ac.uk>
  97 ##          Bill Denney <bill@denney.ws>
  98
  99 function varname = genvarname (str, exclusions)
 100
 101   strinput = ischar (str);
 102   ## Process the inputs
 103   if (nargin < 2)
 104     exclusions = {};
 105   elseif (ischar (exclusions))
 106     if (rows (exclusions) != 1)
 107       error ("genvarname: if more than one exclusion is given, it must be a cellstr");
 108     endif
 109     exclusions = {exclusions};
 110   elseif (! iscellstr (exclusions))
 111     error ("genvarname: EXCLUSIONS must be a string or a cellstr");
 112   endif
 113   if (ischar (str))
 114     if (rows (str) != 1)
 115       error ("genvarname: if more than one STR is given, it must be a cellstr");
 116     endif
 117     str = {str};
 118   elseif (! iscellstr (str))
 119     error ("genvarname: STR must be a string or a cellstr");
 120   endif
 121
 122   validchars = cstrcat ("A":"Z", "a":"z", "0":"9", "_");
 123
 124   varname = cell (size (str));
 125   for i = 1:numel (str)
 126     ## Perform any modifications to the varname to make sure that it is
 127     ## a valid variable name.
 128
 129     ## remove invalid characters
 130     str{i}(! ismember (str{i}, validchars)) = "_";
 131     ## do not use keywords
 132     if (iskeyword (str{i}))
 133       str{i} = cstrcat ("_", str{i});
 134     endif
 135     ## double underscores at the beginning and end are reserved variables
 136     underscores = (str{i} == "_");
 137     if (any (underscores))
 138       firstnon = find (!underscores, 1);
 139       lastnon = find (!underscores, 1, "last");
 140       str{i}([1:firstnon-2, lastnon+2:end]) = [];
 141     endif
 142     ## The variable cannot be empty
 143     if (isempty (str{i}))
 144       str{i} = "x";
 145     endif
 146     ## it cannot start with a number
 147     if (ismember (str{i}(1), "0":"9"))
 148       str{i} = cstrcat ("_", str{i});
 149     endif
 150
 151     ## make sure that the variable is unique relative to other variables
 152     ## and the exclusions list
 153     excluded = any (strcmp (str{i}, exclusions));
 154     if (excluded && ismember (str{i}(end), "0":"9"))
 155       ## if it is not unique and ends with a digit, add an underscore to
 156       ## make the variable name more readable ("x1_1" instead of "x11")
 157       str{i}(end+1) = "_";
 158     endif
 159     varname(i) = str(i);
 160     idx = 0;
 161     while excluded
 162       idx++;
 163       varname{i} = sprintf("%s%d", str{i}, idx);
 164       excluded = any (strcmp (varname{i}, exclusions));
 165     endwhile
 166     exclusions(end+1) = varname(i);
 167   endfor
 168
 169   if strinput
 170     varname = varname{1};
 171   endif
 172
 173 endfunction
 174
 175 ## Tests
 176 ## a single argument
 177 %!assert(genvarname("a"), "a")
 178 ## a single argument with a non-conflicting exception
 179 %!assert(genvarname("a", "b"), "a")
 180 ## a single argument with a conflicting exception
 181 %!assert(genvarname("a", "a"), "a1")
 182 ## a single argument as a cell
 183 %!assert(genvarname({"a"}), {"a"})
 184 %!assert(genvarname({"a"}, "b"), {"a"})
 185 %!assert(genvarname({"a"}, {"b"}), {"a"})
 186 %!assert(genvarname({"a"}, "a"), {"a1"})
 187 %!assert(genvarname({"a"}, {"a"}), {"a1"})
 188 ## Test different arguments
 189 ## orientation
 190 %!assert(genvarname({"a" "b"}), {"a" "b"})
 191 %!assert(genvarname({"a";"b"}), {"a";"b"})
 192 %!assert(genvarname({"a" "a"}), {"a" "a1"})
 193 %!assert(genvarname({"a" "b";"c" "d"}), {"a" "b";"c" "d"})
 194 %!assert(genvarname({"a" "a" "a";"a" "a" "a"}), {"a" "a2" "a4";"a1" "a3" "a5"})
 195 ## more than one repetition
 196 %!assert(genvarname({"a" "a" "a"}), {"a" "a1" "a2"})
 197 %!assert(genvarname({"a" "a" "a"}, {"a" "a1" "a2"}), {"a3" "a4" "a5"})
 198 ## more than one repetition not in order
 199 %!assert(genvarname({"a" "b" "a" "b" "a"}), {"a" "b" "a1" "b1" "a2"})
 200 ## Variable name munging
 201 %!assert (genvarname ("__x__"), "_x_")
 202 %!assert (genvarname ("123456789"), "_123456789")
 203 %!assert (genvarname ("_$1__"), "_1_")
 204 %!assert (genvarname ("__foo__", "_foo_"), "_foo_1")
 205 %!assert (genvarname ("1million_and1", "_1million_and1"), "_1million_and1_1")
 206 %!assert (genvarname ({"", "", ""}), {"x", "x1", "x2"})
 207 %!assert (genvarname ("if"), "_if")
 208 %!assert (genvarname ({"if", "if", "if"}), {"_if", "_if1", "_if2"})