I'm writing MATLAB functions for use by others. I know how to use nargin, varargin, etc. to create a function with variable number of inputs.
The function I'm currently writing is recursive and I need to pass an argument to handle the recursion, but the user should never pass anything in for that argument (or they should pass in the non-intuitive starting value, but they don't need to be distracted by that). I want to 'hide' this argument from the user, so that when they're writing code to use this function and MATLAB pops up that little yellow window that tells them what arguments the function takes, it just prompts them for the arguments they care about.
To be more explicit, when you type rand(, MATLAB pops up a little help window with
rand()
rand(n)
rand(sz1,...,szN)
...
My function recursively builds a matrix and I've currently defined it this way:
function ret = M(arg1, arg2, HideThisRecursiveArgument)
% code that sets the starting value for HideThisRecursiveArgument when it's not passed
% code that calls M(...) again with a different recursion value
end
When the user types M(, I want MATLAB's little help popup to display the usage as:
M(arg1, arg2)
(arg1 and arg2 are named in a self descriptive manner, so this would be a sufficient 'help page' for my function.)
How can I document this usage so MATLAB's function usage help popup will display this to the user?
If I use varargin, the user might get distracted/confused by trying to figure out what else could be passed in, so that's unsatisfactory. I've tried defining my function with 2 arguments and then looking for a 3rd when it's called, but MATLAB doesn't like that.
Edit
I've found the Add Help for Your Program page, and if the user uses the help command or clicks the More Help... link in that yellow usage popup, I can control what they see there, but this doesn't tell me how to control what appears on the usage popup.
I would opt for two separate interfaces, the function to be called externally and your internal recursive function with the hidden argument:
function z=foo(x,y)
z=internalfoo(x,y,pi);
end
function z=internalfoo(x,y,secret)
if x>y
z=internalfoo(y,x,secret);
else
z=secret*x;
end
end
You can place both in the same file foo.m, only the foo() can be called externally (unless you do nasty stuff). Above example contains a local function. Depending on your task a nested function with shared variables is sometimes practical for recursion.
Regarding the second part of your question, look into functionSignatures.json. This allows you to customize the code suggestions and completions, unfortunately only within the Live Editor.
Examples incl. multiple signatures for the same function can be found in the doc.
Note: I had to restart MATLAB prior to experimenting in the Live Editor
Additionally, if you use R2021a checkout the new arguments syntax for declaring function argument validation, see doc.
Related
A question that pops up quite frequently in different shapes and sizes is: Why do I get the following error message:
"Undefined function 'function_name' for input arguments of type 'double'."
This post attempts to address all the different scenarios where this error message can occur, and propose solutions for how it can be resolved.
If you stumble upon this error message and don't know what it means. Take comfort in this: 90% of us have googled the same phrase.
"Undefined function 'int' for input arguments of type 'double'."
The error message is pretty self-explanatory but may still cause confusion. (I chose 'int' at random, it could just as well be 'train', 'table', 'my_function' or anything else).
There are two main cases where this error occurs:
You are trying to use a function that doesn't exist (yet)
You are trying to access an element in a variable that doesn't exist (yet)
What do you do if you get this error?
First, you might want to try which. This will tell you whether or not the function or variable you're trying to use is defined.
which int
'int' not found.
It's quite obvious, that Matlab can't find any functions or variables named int. Trying to use it is therefore futile. Let's compare it to max:
which max
built-in (C:\Program Files\MATLAB\R2014b\toolbox\matlab\datafun\#logical\max) % logical method
But, you might get the following, even if you get the "Undefined function 'x' ...". If so, see point 3 below.
which x
x is a variable.
1. But the function "int" exists! It is even documented here!?
Yes, int exists, but only if you have the Symbolic Toolbox. Since Toolboxes are additional packages that must be purchased separately (and can be quite expensive), chances are you don't have that package.
If you get the "Undefined function" error, but find the function in the documentation, have a look in the menu to the left, or simply check the address. Standard Matlab functions have addresses such as:
mathworks.com/help/matlab/ref/max.html
^^^^^^
Notice the "matlab" part. If you see this, then you are using a function that is part of the core Matlab.
If however, you see an address such as the one below, then the function you are trying to use is part of the Symbolic Toolbox:
mathworks.com/help/symbolic/int.html
^^^^^^^^
or maybe it's part of the Neural Network Toolbox:
mathworks.com/help/nnet/ref/train.html
^^^^
Solution: Find another function that isn't part of a toolbox you don't have. Chances are you'll find what you are looking for if you are a skilled googler. If you can't find it, ask for help. Explain what you have tried, and show that you have done some effort!
2. But the function is documented here, and is part of core Matlab!?
Even though a function is part of the standard Matlab installation, and is well documented, you may still get this error. The most likely cause for this error is that you are using an older version of Matlab. If you check the documentation you'll see the following at the bottom of the page:
Introduced in R2013b
So, if you are using R2012b then you can't use for instance table.
Solution: Check if the function is defined in your version of Matlab. If it's not yet implemented then you either need to update Matlab or find another way to do it. An alternative to table can for instance be to use cells or structs.
3. But the variable "my_variable" exists! I created it in the line above!
No, you didn't. Chances are you created the variable myvariable, my_Variable, my_Variable or something similar in the line above. It's also possible that you have created it, but have accidentally cleared it.
Solution: Go through the code. Look for typos, places where you have accidentally cleared the variable etc. Inside the Matlab editor you will get the following line at the bottom if you mark a variable: "3 usages of "x" found" if you have defined and used the function. You will also get an orange line underneath unused variables.
4. But I get "y is a variable" when I type which y?
If you get the error above "Undefined function 'y', but which tells you y exists, your error message contains a few more lines:
my_function(x)
Undefined function or variable 'y'.
Error in my_function (line 2)
t = x*y;
>> which y
y is a variable.
What this tells you is that you have a variable called y in your Matlab Workspace (also check this link).
The problem is that functions can't access this workspace:
Functions do not use the base workspace. Every function has its own function workspace.
If you want a function to see and use a variable, you must pass it as an argument. This way the variable will be part of the local workspace for that function. Similarly, if you want variables created inside the function to be accessible outside of the function you must have them as output from the function.
Solution: Pass the variables you want to use as input arguments to the function you use. Make sure the names inside the functions are internally consistent. I.e. it must have the same name throughout the function. Note that there is no connection between the variable names outside and inside the function.
5. But I pass the variable as an input to the function, but I still get the same error message!?
Yes, you probably use the variable as input. However, the variable names are not necessarily the same in different functions (most often they are not).
Suppose you have the function:
function output = my_function(x)
output = 2*y;
end
You'll get the same error as above if you call it from the workspace as in the code below, even though you are using y as input variable, and use y inside the function.
y = 3;
res = my_function(y)
This is because, inside the function my_function, the variable you use as input will be called x, regardless of what it was called outside the function.
Solution: Change the name of the input variable name in the function header, or change the name of the variable throughout the function.
6. But I have created x as a global variable!?
First off: Chances are, if you're reading this post, then you are better off passing variables as arguments rather than using global variables.
It's not enough to declare a variable as global in the Matlab workspace. It must be declared in every function you use it in. So, if you have a global variable x, you need to do global x in every function.
Solution: Rewrite your code and pass variables as arguments instead of using global variables. If this is not an option, add global x in all functions where you're using it.
In addition to this answer, you can refer to the official Matlab FAQ.
I also got
Undefined function '...' for input arguments of type 'double'.
error and I tried the recommendations mentioned above but they could not solve my problem. Then, I realized that there is a special character (*) in my current working directory so I solve the problem when I changed the name of the directory.
Lastly, do not forget to change the current directory after the change operation by using cd argument.
Another way of looking at the problem:
the input arguments should be in an order such that the explanation of the function can read it.
A question that pops up quite frequently in different shapes and sizes is: Why do I get the following error message:
"Undefined function 'function_name' for input arguments of type 'double'."
This post attempts to address all the different scenarios where this error message can occur, and propose solutions for how it can be resolved.
If you stumble upon this error message and don't know what it means. Take comfort in this: 90% of us have googled the same phrase.
"Undefined function 'int' for input arguments of type 'double'."
The error message is pretty self-explanatory but may still cause confusion. (I chose 'int' at random, it could just as well be 'train', 'table', 'my_function' or anything else).
There are two main cases where this error occurs:
You are trying to use a function that doesn't exist (yet)
You are trying to access an element in a variable that doesn't exist (yet)
What do you do if you get this error?
First, you might want to try which. This will tell you whether or not the function or variable you're trying to use is defined.
which int
'int' not found.
It's quite obvious, that Matlab can't find any functions or variables named int. Trying to use it is therefore futile. Let's compare it to max:
which max
built-in (C:\Program Files\MATLAB\R2014b\toolbox\matlab\datafun\#logical\max) % logical method
But, you might get the following, even if you get the "Undefined function 'x' ...". If so, see point 3 below.
which x
x is a variable.
1. But the function "int" exists! It is even documented here!?
Yes, int exists, but only if you have the Symbolic Toolbox. Since Toolboxes are additional packages that must be purchased separately (and can be quite expensive), chances are you don't have that package.
If you get the "Undefined function" error, but find the function in the documentation, have a look in the menu to the left, or simply check the address. Standard Matlab functions have addresses such as:
mathworks.com/help/matlab/ref/max.html
^^^^^^
Notice the "matlab" part. If you see this, then you are using a function that is part of the core Matlab.
If however, you see an address such as the one below, then the function you are trying to use is part of the Symbolic Toolbox:
mathworks.com/help/symbolic/int.html
^^^^^^^^
or maybe it's part of the Neural Network Toolbox:
mathworks.com/help/nnet/ref/train.html
^^^^
Solution: Find another function that isn't part of a toolbox you don't have. Chances are you'll find what you are looking for if you are a skilled googler. If you can't find it, ask for help. Explain what you have tried, and show that you have done some effort!
2. But the function is documented here, and is part of core Matlab!?
Even though a function is part of the standard Matlab installation, and is well documented, you may still get this error. The most likely cause for this error is that you are using an older version of Matlab. If you check the documentation you'll see the following at the bottom of the page:
Introduced in R2013b
So, if you are using R2012b then you can't use for instance table.
Solution: Check if the function is defined in your version of Matlab. If it's not yet implemented then you either need to update Matlab or find another way to do it. An alternative to table can for instance be to use cells or structs.
3. But the variable "my_variable" exists! I created it in the line above!
No, you didn't. Chances are you created the variable myvariable, my_Variable, my_Variable or something similar in the line above. It's also possible that you have created it, but have accidentally cleared it.
Solution: Go through the code. Look for typos, places where you have accidentally cleared the variable etc. Inside the Matlab editor you will get the following line at the bottom if you mark a variable: "3 usages of "x" found" if you have defined and used the function. You will also get an orange line underneath unused variables.
4. But I get "y is a variable" when I type which y?
If you get the error above "Undefined function 'y', but which tells you y exists, your error message contains a few more lines:
my_function(x)
Undefined function or variable 'y'.
Error in my_function (line 2)
t = x*y;
>> which y
y is a variable.
What this tells you is that you have a variable called y in your Matlab Workspace (also check this link).
The problem is that functions can't access this workspace:
Functions do not use the base workspace. Every function has its own function workspace.
If you want a function to see and use a variable, you must pass it as an argument. This way the variable will be part of the local workspace for that function. Similarly, if you want variables created inside the function to be accessible outside of the function you must have them as output from the function.
Solution: Pass the variables you want to use as input arguments to the function you use. Make sure the names inside the functions are internally consistent. I.e. it must have the same name throughout the function. Note that there is no connection between the variable names outside and inside the function.
5. But I pass the variable as an input to the function, but I still get the same error message!?
Yes, you probably use the variable as input. However, the variable names are not necessarily the same in different functions (most often they are not).
Suppose you have the function:
function output = my_function(x)
output = 2*y;
end
You'll get the same error as above if you call it from the workspace as in the code below, even though you are using y as input variable, and use y inside the function.
y = 3;
res = my_function(y)
This is because, inside the function my_function, the variable you use as input will be called x, regardless of what it was called outside the function.
Solution: Change the name of the input variable name in the function header, or change the name of the variable throughout the function.
6. But I have created x as a global variable!?
First off: Chances are, if you're reading this post, then you are better off passing variables as arguments rather than using global variables.
It's not enough to declare a variable as global in the Matlab workspace. It must be declared in every function you use it in. So, if you have a global variable x, you need to do global x in every function.
Solution: Rewrite your code and pass variables as arguments instead of using global variables. If this is not an option, add global x in all functions where you're using it.
In addition to this answer, you can refer to the official Matlab FAQ.
I also got
Undefined function '...' for input arguments of type 'double'.
error and I tried the recommendations mentioned above but they could not solve my problem. Then, I realized that there is a special character (*) in my current working directory so I solve the problem when I changed the name of the directory.
Lastly, do not forget to change the current directory after the change operation by using cd argument.
Another way of looking at the problem:
the input arguments should be in an order such that the explanation of the function can read it.
What do I want?
I am looking for a way to detect all points in my code where a specific function is called.
Why do I want it?
Some examples:
Some output comes out sorted or randomized, and I want to know where this happens
I am considering to change/overload a function and want to know in which part of my code this could have impact
What have I tried?
I tried placing a breakpoint in the file that was called. This only works for non builtin functions which are called from short running code that always executes everything.
I tried 'find files', this way I can easily find direct calls to sort but it is not so easy to find a call to sort invoked by unique for example.
I have tried depfun, it tells me:
whether something will be called
from where non-builtin functions will be called
I thought of overloading the builtin function, but feels like a last resort for me as I am afraid to make a mess. | Edit: Also it probably won't help due to function precedence.
The question
What is the best way to track all potential (in)direct function calls from a specific function to a specific (built-in)function.
I don't exactly understand your use case, but I guess most of the information you want can be obtained using dbstack, which gives you the call-stack of all the parent functions calling a certain function. I think the easiest way is to overload built-in functions something like this (I tried to overload min):
function varargout = min(varargin)
% print info before function call
disp('Wrapped function called with inputs:')
disp(varargin)
[stack,I] = dbstack();
disp('Call stack:')
for i=1:length(stack)
fprintf('level %i: called from line %i in file %s\n', ...
i, stack(i).line, stack(i).file);
end
% call original function
[varargout{1:nargout}] = builtin('min', varargin{:});
% print info after function call
disp('Result of wrapped function:')
disp(varargout)
I tried to test this, but I could not make it work unfortunately, matlab keeps on using the original function, even after playing a lot with addpath. Not sure what I did wrong there, but I hope this gets you started ...
Built-in functions take precedence over functions in local folder or in path. There are two ways you can overload a built-in for direct calls from your own code. By putting your function in a private folder under the same directory where your other MATLAB functions are. This is easier if you are not already using private folder. You can rename your private folder once you are done investigating.
Another way is to use packages and importing them. You put all your override functions in a folder (e.g. +do_not_use). Then in the function where you suspect built-in calls are made add the line "import do_not_use.*;". This will make calls go to the functions in +do_not_use directory first. Once you are done checking you can use "clear import" to clear all imports. This is not easy to use if you have too many functions and do not know in which function you need to add import.
In addition to this, for each of the function you need to follow Bas Swinckels answer for the function body.
Function precedence order.
Those two methods does not work for indirect calls which are not from your own code. For indirect calls I can only think of one way where you create your own class based on built-in type. For example, if you work only on double precision types, you need to create your own class which inherits from double and override the methods you want to detect. Then pass this class as input to your code. Your code should work fine (assuming you are not using class(x) to decide code paths) since the new class should behave like a double data type. This option will not work if your output data is not created from your input data. See subclassing built-in types.
Did you try depfun?
The doc shows results similar to the ones you request.
doc depfun:
...
[list, builtins, classes, prob_files, prob_sym, eval_strings, called_from, java_classes] = depfun('fun') creates additional cell arrays or structure arrays containing information about any problems with the depfun search and about where the functions in list are invoked. The additional outputs are ...
Looks to me you could just filter the results for your function.
Though need to warn you - usually it takes forever to analyze code.
I have been reading someone else's matlab code and I don't know how the code structured. I mean I would like to know the hierarchy of functions, which function uses which function. I am reading the code to figure that out but its taking a lot of time.
So is there any other way I can see this hierarchy without reading the whole thing? To be honest it is starting to get confusing. Maybe MatLab has a built in function for that! I found this:
How can I generate a list of function dependencies in MATLAB?
but this doesn't seem to be helpful!
The MATLAB profiler will show you what functions are called by your code (and much more information to boot) and allow you to click through the hierarchy of function calls. You can either call profile on and then run your code, then call profile off and profile viewer, or you can simply call profile viewer and type a single line of code to run in the edit box at the top.
Use the dependency report provided in MATLAB:
http://www.mathworks.co.uk/help/matlab/matlab_prog/identify-dependencies.html
There are also some tools on the File Exchange, such as fdep.
No idea about a function to show visible or depended-upon functions. However the basic rules are:
1) Only the first function in a .m file (normally has to have the same name as the file itself) is visible outside that file.
2) Any function can see any top level (see 1.) function if the file is in the matlab path. Matlab can show you the path so you know where it's hunting.
3) The order of the path is important, the first instance of a function called foo found in the path will be called. Obviously the current directory is at the top of the path.
3) All functions in a given file can see all other functions in that file.
That's the basics. No doubt there are other rules, and possibly exceptions to this. But that understanding generally serves me well.
Obviously the easiest way to work out which function is being called is to click on it in the editor and open it.
One thing I do is simply place in each function at the beginning fprintf("inside function <name>/n"); and at the end of the function fprintf("leaving function <name>/n"); where <name> is the name of the function.
This will give you a very specific list of which function is being called by which function (based on the order that they appear). Another thing like this would be to place fprintf("function <name1> calling function <name2>/n"); so you can be more explicit about which function is being called by which one.
Let us say that I have a Matlab function and I change its signature (i.e. add parameter). As Matlab does not 'compile' is there an easy way to determine which other functions do not use the right signature (i.e. submits the additional parameter). I do not want to determine this at runtime (i.e. get an error message) or have to do text searches. Hope this makes sense. Any feedback would be very much appreciated. Many thanks.
If I understand you correctly, you want to change a function's signature and find all functions/scripts/classes that call it in the "old" way, and change it to the "new" way.
You also indicated you don't want to do it at runtime, or do text searches, but there is no way to detect "incorrect" calls at "parse-time", so I'm afraid these demands leave no option at all to detect old function calls...
What I would do in that case is temporarily add a few lines to the new function:
function myFunc(param1, param2, newParam) % <-- the NEW signature
if nargin == 2
clc, error('old call detected.'); end
and then run the main script/function/whatever in which this function resides. You'll get one error for each time something calls the function incorrectly, along with the error stack in the Matlab command window.
It is then a matter of clicking on the link in the bottom of the error stack, correct the function call, and repeat from the top until no more errors occur.
Don't forget to remove these lines when you're done, or better, replace the word error with warning just to capture anything that was missed.
Better yet: if you're on linux, a text search would be a matter of
$ grep -l 'myFunc(.*,.*); *.m'
which will list all the files having the "incorrect" call. That's not too difficult I'd say...You can probably do a similar thing with the standard windows search, but I can't test that right now.
This is more or less what the dependency report was invented for. Using that tool, you can find what functions/scripts call your altered function. Then it is just a question of manually inspecting every occurrence.
However, I'd advise to make your changes to the function signature such that backwards compatibility is maintained. You can do so by specifying default values for new parameters and/or issuing a warning in those scenarios. That way, your code will run, and you will get run-time hints of deprecated code (which is more or less a necessary evil in interpreted/dynamic languages).
For many dynamic languages (and MATLAB specifically) it is generally impossible to fully inspect the code without the interpreter executing the code. Just imagine the following piece of code:
x = magic(10);
In general, you'd say that the magic function is called. However, magic could map to a totally different function. This could be done in ways that are invisible to a static analysis tool (such as the dependency report): e.g. eval('magic = 1:100;');.
The only way is to go through your whole code base, either inspecting every occurrence manually (which can be found easily with a text search) or by running a test that fully covers your code base.
edit:
There is however a way to access intermediate outputs of the MATLAB parser. This can be accessed using the undocumented and unsupported mtree function (which can be called like this: t = mtree(file, '-file'); for every file in your code base). Using the resulting structure you might be able to find calls with a certain amount of parameters.