1######################################################################## 2## 3## Copyright (C) 2012-2021 The Octave Project Developers 4## 5## See the file COPYRIGHT.md in the top-level directory of this 6## distribution or <https://octave.org/copyright/>. 7## 8## This file is part of Octave. 9## 10## Octave is free software: you can redistribute it and/or modify it 11## under the terms of the GNU General Public License as published by 12## the Free Software Foundation, either version 3 of the License, or 13## (at your option) any later version. 14## 15## Octave is distributed in the hope that it will be useful, but 16## WITHOUT ANY WARRANTY; without even the implied warranty of 17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18## GNU General Public License for more details. 19## 20## You should have received a copy of the GNU General Public License 21## along with Octave; see the file COPYING. If not, see 22## <https://www.gnu.org/licenses/>. 23## 24######################################################################## 25 26## -*- texinfo -*- 27## @deftypefn {} {@var{val} =} getpref ("@var{group}", "@var{pref}") 28## @deftypefnx {} {@var{val} =} getpref ("@var{group}", "@var{pref}", @var{default}) 29## @deftypefnx {} {@{@var{val1}, @var{val2}, @dots{}@} =} getpref ("@var{group}", @{"@var{pref1}", "@var{pref2"}, @dots{}@}) 30## @deftypefnx {} {@var{prefstruct} =} getpref ("@var{group}") 31## @deftypefnx {} {@var{prefstruct} =} getpref () 32## Return the preference value corresponding to the named preference @var{pref} 33## in the preference group @var{group}. 34## 35## The named preference group must be a string. 36## 37## If @var{pref} does not exist in @var{group} and @var{default} is specified, 38## create the preference with value @var{default} and return @var{default}. 39## 40## The preference @var{pref} may be a string or cell array of strings. If it 41## is a cell array of strings then a cell array of preferences is returned. 42## 43## The corresponding default value @var{default} may be any Octave value, 44## .e.g., double, struct, cell array, object, etc. Or, if @var{pref} is a cell 45## array of strings then @var{default} must be a cell array of values with the 46## same size as @var{pref}. 47## 48## If neither @var{pref} nor @var{default} are specified, return a structure 49## of preferences for the preference group @var{group}. 50## 51## If no arguments are specified, return a structure containing all groups of 52## preferences and their values. 53## @seealso{addpref, setpref, ispref, rmpref} 54## @end deftypefn 55 56function retval = getpref (group, pref, default) 57 58 if (nargin > 3) 59 print_usage (); 60 endif 61 62 if (nargin == 0) 63 retval = loadprefs (); 64 elseif (nargin == 1) 65 if (! ischar (group)) 66 error ("getpref: GROUP must be a string"); 67 endif 68 prefs = loadprefs (); 69 if (isfield (prefs, group)) 70 retval = prefs.(group); 71 else 72 ## FIXME: Is this the right behavior, or should it produce an error? 73 retval = []; 74 endif 75 else 76 if (! (ischar (pref) || iscellstr (pref))) 77 error ("getpref: PREF must be a string or cellstr"); 78 endif 79 80 grp = getpref (group); 81 82 if (ischar (pref)) 83 if (isfield (grp, pref)) 84 retval = grp.(pref); 85 elseif (nargin == 3) 86 addpref (group, pref, default); 87 retval = default; 88 else 89 error ("getpref: preference %s does not exist in GROUP %s", 90 pref, group); 91 endif 92 else 93 if (nargin != 2 && ! size_equal (pref, default)) 94 error ("getpref: size mismatch for PREF and DEFAULT"); 95 endif 96 97 for i = 1:numel (pref) 98 if (isfield (grp, pref{i})) 99 retval{i} = grp.(pref{i}); 100 elseif (nargin == 3) 101 addpref (group, pref{i}, default{i}); 102 retval{i} = default{i}; 103 else 104 error ("getpref: preference %s does not exist in GROUP %s", 105 pref{i}, group); 106 endif 107 endfor 108 endif 109 endif 110 111endfunction 112 113 114%!test 115%! HOME = getenv ("HOME"); 116%! tmp_home = tempname (); 117%! save_default_options ("-binary", "local"); 118%! unwind_protect 119%! mkdir (tmp_home); 120%! setenv ("HOME", tmp_home); 121%! 122%! addpref ("group1", "pref1", [1 2 3]); 123%! addpref ("group2", {"prefA", "prefB"}, {"StringA", {"StringB"}}); 124%! 125%! exp.group1.pref1 = [1 2 3]; 126%! exp.group2.prefA = "StringA"; 127%! exp.group2.prefB = {"StringB"}; 128%! obs = getpref (); 129%! assert (obs, exp); 130%! 131%! assert (getpref ("group1"), exp.group1); 132%! assert (getpref ("group2"), exp.group2); 133%! assert (getpref ("group3"), []); 134%! 135%! assert (getpref ("group1", "pref1"), [1 2 3]); 136%! assert (getpref ("group2", "prefA"), "StringA"); 137%! assert (getpref ("group2", "prefB"), {"StringB"}); 138%! assert (getpref ("group1", "pref2", "New_Value"), "New_Value"); 139%! assert (getpref ("group1", "pref2"), "New_Value"); 140%! fail ('getpref ("group1", "no_such_pref")', ... 141%! "preference no_such_pref does not exist in GROUP group1"); 142%! 143%! assert (getpref ("group2", {"prefA", "prefB"}), {"StringA", {"StringB"}}); 144%! assert (getpref ("group2", {"prefA", "prefC"}, {1, "StringC"}), 145%! {"StringA", "StringC"}); 146%! assert (getpref ("group2", "prefC"), "StringC"); 147%! fail ('getpref ("group1", {"p1", "p2"}, 1)', ... 148%! "size mismatch for PREF and DEFAULT"); 149%! fail ('getpref ("group2", {"prefA", "prefD"})', 150%! "preference prefD does not exist in GROUP group2"); 151%! 152%! unwind_protect_cleanup 153%! unlink (fullfile (tmp_home, ".octave_prefs")); 154%! if (isfolder (tmp_home)) 155%! rmdir (tmp_home); 156%! endif 157%! if (isempty (HOME)) 158%! unsetenv ("HOME"); 159%! else 160%! setenv ("HOME", HOME); 161%! endif 162%! end_unwind_protect 163 164%!error getpref (1,2,3,4) 165%!error <GROUP must be a string> getpref (1) 166%!error <PREF must be a string> getpref ("group1", 1, 2) 167