1 ## Copyright (C) 2008-2012 Bill Denney, Robert Platt
3 ## This file is part of Octave.
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.
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.
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/>.
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).
26 ## If @var{str} is a cellstr, then a unique variable is created for each
32 ## genvarname ("x", who ())
37 ## If @var{wanted} is a cell array, genvarname will make sure the returned
38 ## strings are distinct:
42 ## genvarname (@{"foo", "foo"@})
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}.
57 ## name = genvarname ("x");
58 ## eval ([name " = 42"]);
63 ## Also, this can be useful for creating unique struct field names.
69 ## x.(genvarname ("a", fieldnames (x))) = i;
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.
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.
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}
96 ## Authors: Rob Platt <robert.platt@postgrad.manchester.ac.uk>
97 ## Bill Denney <bill@denney.ws>
99 function varname = genvarname (str, exclusions)
101 strinput = ischar (str);
102 ## Process the inputs
105 elseif (ischar (exclusions))
106 if (rows (exclusions) != 1)
107 error ("genvarname: if more than one exclusion is given, it must be a cellstr");
109 exclusions = {exclusions};
110 elseif (! iscellstr (exclusions))
111 error ("genvarname: EXCLUSIONS must be a string or a cellstr");
115 error ("genvarname: if more than one STR is given, it must be a cellstr");
118 elseif (! iscellstr (str))
119 error ("genvarname: STR must be a string or a cellstr");
122 validchars = cstrcat ("A":"Z", "a":"z", "0":"9", "_");
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.
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});
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]) = [];
142 ## The variable cannot be empty
143 if (isempty (str{i}))
146 ## it cannot start with a number
147 if (ismember (str{i}(1), "0":"9"))
148 str{i} = cstrcat ("_", str{i});
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")
163 varname{i} = sprintf("%s%d", str{i}, idx);
164 excluded = any (strcmp (varname{i}, exclusions));
166 exclusions(end+1) = varname(i);
170 varname = varname{1};
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
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"})