- Undocumented Matlab - http://undocumentedmatlab.com -

Setting desktop tab completions

Posted By Yair Altman On March 3, 2010 @ 9:03 am In Desktop,Low risk of breaking in future versions,Medium risk of breaking in future versions,Undocumented feature | 34 Comments

This site has lately focused on quite detailed Java-related topics. Next week I will present the promised EDT article, which will dive into even deeper Java territory. So I thought to take a short break and present an entirely pure-Matlab non-Java undocumented feature, which is simple and yet quite useful.

A few months ago, a CSSM reader asked [3] whether it is possible to customize Matlab tab-completion [4] for user-defined functions (see related [5]). A similar question on StackOverflow provided the necessary solution lead [6]:

Apparently, Matlab has a file called TC.xml in its [matlabroot '/toolbox/local/'] folder that contains the definitions of the tab-completable functions and their arguments. In order for a user-defined function’s arguments to support tab-completion, a new entry needs to be added to this XML file.

TC.xml & TC.xsd

The full syntax of the TC.xml file can be found in the TC.xsd file, which is located in the same folder as TC.xml. Here are some sample definitions from my TC.xml file (which might vary across Matlab releases):

<binding name="addpath" ctype="DIR"/>
<binding name="help"    ctype="FUN SUBFUN"/>
<binding name="clear"   ctype="FUN VAR"/>
 
<binding name="whos"    ctype="VAR">
  <arg previous="-file" ctype= "MATFILE"/>
</binding>
 
<binding name="open">
  <arg argn="1" ctype="VAR MATFILE FIGFILE MFILE MDLFILE FILE"/>
</binding>
 
<binding name="openfig">
  <arg argn="1" ctype="FIGFILE"/>
  <arg argn="2" ctype="VAR" value="new visible invisible reuse"/>
</binding>
 
<binding name="mlint"   ctype="FUN">
  <arg argn="2:10" ctype="VAR" value="-struct -string -id"/>
</binding>

The first example defines that an unlimited number of addpath arguments are all of type DIR. Therefore, when completing any argument of this function in the Command-Window, Matlab will present only relevant DIR (=folder) elements in the pop-up window (lexically sorted):

Tab-completion of type DIR

Tab-completion of type DIR

Similarly, help defines all its arguments to be a function or sub-function type, so the popup-up will only be populated with the function names currently visible in the desktop:

Tab-completion of types FUN & SUBFUN

Tab-completion of types FUN & SUBFUN

Similarly, clear defines all its arguments as function names or variables. Note that the list of available functions and variables may change depending on the current execution stack position. The full list of supported types is defined in the TC.xsd file. It is: VAR, FUN, SUBFUN, DIR, FILE, MFILE, MATFILE, FIGFILE and MDLFILE. Addendum: Matlab release 7.10 (R2010a) added the MCOSPCG and MCOSCLASS types; release 7.13 (R2011b) added the MESSAGEID type.

The whos function defines all its arguments as VAR, except the single MATFILE argument that follows a ‘-file’ argument (look at whos‘s help page [7] to understand why).

The open function defines tab completion only for its first argument (with plenty of possible types…). Likewise, openfig defines its first argument as a FIGFILE, and its second as VAR with a few extra special-purpose strings [8] that are added to the popup-up menu.

Finally, the mlint example shows that multiple arguments can be defined using a single XML definition element. In this case, args #2-10 are defined as VAR (with three extra special-purpose strings), while args #1 and #11+ are defined as FUN.

The careful user can edit the TC.xml file using any text editor (I strongly suggest saving a backup first):

edit(fullfile(matlabroot,'toolbox/local/TC.xml'))

User-defined functions can easily be added to TC.xml, and we can even add/modify the built-in Matlab functions that are already defined. Note that changes to TC.xml only take effect after a Matlab restart. From then on, all future Matlab sessions will use the modification, so a really simple one-time edit can improve our workflow for a long time – at least until we upgrade Matlab, when we’ll need to redo our edits…

TabComplete utility

In order to facilitate TC.xml editing, I have created a utility called TabComplete, which is now available on the Matlab File Exchange [9]. The use of this utility is very simple. For example:

tabcomplete test file 'DIR +data -data no_data' VAR

defines a user-defined function test that accepts a FILE argument, followed by a DIR argument with three special-purpose strings, followed by any number of VAR arguments. If I wished to define specific argument types without any default type, I would use:

tabcomplete test file 'DIR +data -data no_data' ''

Using TabComplete for user-defined functions

Using TabComplete for user-defined functions

Addendum: Matlab releases 7.10 (R2010a) through 7.13 (R2011b) have a bug that causes Matlab to enter an endless loop (full CPU load) whenever tab-completion is requested for an argument that has possible values that are not simple terms. In the case above, “+data” and “-data” both cause this abnormal behavior. In such cases, the only remedy is to kill the Matlab process via the OS’s task manager. In Matlab R2010a-R2011b, I therefore suggest to use only simple values. This bug is apparently fixed in R2012a, making non-simple terms safe to use again. I take at least partial credit for this, having reported this bug to Mathworks in August 2011 (1-FCGDEI).

TabComplete can also be used to retrieve the current list of tab-completion definitions:

>> definitions = tabcomplete;
>> definitions(1)
ans = 
    functionName: 'addpath'
     defaultType: 'DIR'
     extraValues: ''
        platform: ''
    functionArgs: []
 
>> definitions(54)
ans = 
    functionName: 'openfig'
     defaultType: ''
     extraValues: ''
        platform: ''
    functionArgs: [1x2 struct]
>> definitions(54).functionArgs(1)
ans = 
    previousArg: ''
        argType: 'FIGFILE'
    extraValues: ''
>> definitions(54).functionArgs(2)
ans = 
    previousArg: ''
        argType: 'VAR'
    extraValues: 'new visible invisible reuse'

TabComplete has a few limitations: it does not support the -previous option described above (you can do this by manually editing TC.xml). There are also some inherent limitations in Matlab’s TC functionality: changes take effect only after a Matlab restart (there might be a way to reload the definitions in the current Matlab session, but I do not know of any); the list of standard types cannot be modified; and the default type does not support extra special-purpose strings as do the numbered arguments.

There is another very annoying limitation: by default, TC.xml only supports lowercase function names. This is stupid, since Matlab has many function names with UPPERCASE characters, and certainly user-defined function names also do. Luckily, this last limitation can easily be overcome by editing the TC.xsd file (note that this is the TC.XSD file, not the TC.XML file). Instead of:

<xsd:simpletype name="tcBindingNameType">
  <xsd:restriction base="xsd:token">
    <xsd:pattern value='[A-Za-z_0-9]+(/[a-z_0-9]+)?'/>
  </xsd:restriction>
</xsd:simpletype>

Change the xsd:pattern definition element to:

    <!-- Yair 21/2/2010: added A-Z -->
    <xsd:pattern value='[A-Za-z_0-9]+(/[A-Za-z_0-9]+)?'/>

(note the way comments can be added to the XSD/XML files)

Addendum: Matlab release 7.11 (R2011a) has fixed this XSD definition; perhaps due to this article :-)

P.S. an entirely different customization, for user-defined class members, was presented by Michal Kutil [10].

Related posts:

  1. setPrompt – Setting the Matlab Desktop prompt [11] The Matlab Desktop's Command-Window prompt can easily be modified using some undocumented features...
  2. Setting the Matlab desktop layout programmatically [12] The Matlab desktop enables saving and switching layouts using the main menu. This post shows how to do so programmatically....
  3. Setting class property types [13] Matlab's class properties have a simple and effective mechanism for setting their type....
  4. Setting status-bar text [14] The Matlab desktop and figure windows have a usable statusbar which can only be set using undocumented methods. This post shows how to set the status-bar text....
  5. Setting system tray icons [15] System-tray icons can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....
  6. Setting system tray popup messages [16] System-tray icons and messages can be programmatically set and controlled from within Matlab, using new functionality available since R2007b....


34 Comments (Open | Close)

34 Comments To "Setting desktop tab completions"

#1 Comment By David On March 3, 2010 @ 10:43 am

Thanks for posting this great utility! Seeing your question dialog and looking through the code, I saw your use of the function “setpref.” I didn’t know about this very useful function, so thanks for that too!

#2 Comment By Michal On March 4, 2010 @ 12:42 pm

Hi, thanks for inspirational blog spot. Have you got any idea if it is possible to save TC.xml to any other location, where the Matlab path is set? It can be useful in case that I have not permission to modify TC.xml in [matlabroot '/toolbox/local/'] folder, or if I distribute own toolbox and can’t modify default TC.xml:).
BTW thank you for link.
Best Michal

#3 Comment By Yair Altman On March 4, 2010 @ 3:00 pm

@Michal – unfortunately, I don’t know of any other possible location. As far as I know, Matlab directly opens [matlabroot '/toolbox/local/TC.xml']. We can’t win ‘em all…

In your toolbox, try modifying TC.xml, with a graceful degradation in case this fails. Something like this:

try
   tabcomplete(...);
catch
   oldFname = fullfile(matlabroot, 'toolbox/local/TC.xml');
   newFname = fullfile(pwd,'TC.xml');
   msgbox(['Please ask your sysadmin to replace ' oldFname ' with ' newFname]);
end

#4 Comment By Henrik Toft On March 12, 2010 @ 2:22 am

A related question, which however is not tab completion, but presents informaiton is the same way:

When in the workspace I type e.g. “plot(” or “corrcoef(” and wait a second, I am presented with a context sensitive help showing a number of ways to use the “plot” or “corrcoef” functions. Where is this context sensitive help stored? I have tried to look at different functions to see how the help-section is written, and made a similar setup:

function testHelp(x,varargin)
% TESTHELP   See how context help is defined
%   TESTHELP(X)
%
%   TESTHELP(X,Y)

but it does not present me with a “similar” context sensitive help…

Cheers Henrik

#5 Comment By Yair Altman On March 28, 2010 @ 8:35 am

@Henrik – I believe the syntax help is taken from the “Syntax” section of the relevant function’s doc page (the HTML webpage that is presented as a result of the doc function).

If no doc page is defined, then the help-tooltip popup displays the arguments defined in your function’s declaration. In your example, testHelp is declared as having arguments “x” and “varargin”. “varargin” is always converted to “…”, so your tooltip will say: testHelp(x,…). If you wish to modify this, then specify meaningful argument names (which is always a good thing to do), and/or [17].

#6 Comment By akash garg On March 3, 2012 @ 10:24 am

is it possible to perform autocomplete in matlab without using funtionality just like we type in google search bar

#7 Comment By Yair Altman On March 3, 2012 @ 10:38 am

@Akash – what do you mean “in Matlab”? Do you mean the Command Window? edit boxes in GUI? combo-boxed (pop-up/pop-down menus)? each of them has a different solution

#8 Pingback By Matlab installation take 2 | Undocumented Matlab On September 24, 2012 @ 3:18 am

[...] check the <Tab key narrows completion> option (most useful for the desktop – see related article) [...]

#9 Comment By Marshall On November 28, 2012 @ 2:24 pm

This is only tangentially related… but I’m hoping there is an undocumented way to change the fact that Matlab Tab completes case-insensitively but doesn’t auto-replace the name when it finds the wrong case. This results in tab-completions to functions that error.

#10 Comment By Yair Altman On November 28, 2012 @ 2:28 pm

@Marshall – I fully agree. Indeed a regrettable programming oversight. Unfortunately, I do not know any workaround.

#11 Comment By Oleg On June 6, 2013 @ 1:12 am

I tried to implement on R2013a a custom doc page but couldn’t get the desired result. Even if the section is title ‘Syntax’, I still get the ‘…’ as a hint. If anybody finds a workaround please post it and in the meantime submit a request to TMW for custom syntax hints. Hopefully, with enough requests we will see it in R2013b.

#12 Comment By Yair Altman On June 6, 2013 @ 1:46 am

@Oleg – 13b is too optimistic… The development process is such that releases are finalized months before their official release. At the very earliest you will see it in 14a.

#13 Comment By Marios On June 26, 2013 @ 3:48 pm

Great post as always!

I modified TC.xsd file (r2013a) from:

to

In order to allow full package names to be added on TC.xml

Now the problem is that if I try to call a package level function as a script, somehow Matlab wont let me. In otherwords on the prompt:

myPackage.myFunction('str')

works fine, but:

myPackage.myFunction str

doesn’t. Is there a reason that packaged functions might not be supporting script-like calling?

#14 Comment By Yair Altman On June 27, 2013 @ 12:02 am

@Marios – your comment appears without the code, maybe it was stripped away for some reason. Try reposting without <, > characters

#15 Comment By Marios On June 27, 2013 @ 1:55 pm

Sure, here are the lines again. In TC.xsd I changed:

<xsd:pattern value="[A-Z_a-z_0-9]+(/[A-Z_a-z_0-9]+)?" />

to:

<xsd:pattern value="[A-Z_a-z_0-9_\.]+(/[A-Z_a-z_0-9_\.]+)?" />

So that by adding a packaged function name on the TC.xml such as:

<binding name="myPack.myFun" ctype="FILE FUN MCOSPKG MCOSCLASS"/>

I can have auto-completion on the prompt. So on the prompt, when I type:
>> myP<tab>.myF<tab><space>myF<tab>
I can now autocomplete myF to myFile but some how Matlab doesn’t push the string literal myFile as an argument to myPack.myFun but instead gives an error:

Error: Unexpected MATLAB expression.

Of course if I call myPack.myFun(‘myFile’) it works fine. My conclusion is that command-syntax doesn’t work with packaged functions but of course function syntax does.

I opened a ticket with Mathworks support but they said this functionality is not supported at this point. My general feeling is that packages are pretty half baked at this point. (also Ctrl-D on imported functions doesn’t work etc.)

#16 Comment By Yair Altman On June 27, 2013 @ 2:03 pm

@Marios – interesting. Since the tab-completion thing is internal (as in binary code, not m-code), there’s not much that we can do about this…

#17 Comment By Marios On July 2, 2013 @ 1:12 pm

Right, there is not much we can do according to Mathworks support as well.

My partial solution is to create function aliases on a flat namespace when I absolutely need tab-completions on the desktop.

#18 Comment By Marc On November 14, 2013 @ 12:56 am

Hi very nice. I try to do the same for custom class definitions. For the constructor it’s straight forward but I didn’t find any solutions for methods. I tried something like:

  <binding name="MethodName">
    <arg argn="1" ctype="ClassName"/>
    <arg argn="2" ctype="FILE"/>
  </binding>

(All with a smaller-as sign at the beginning but, if I print those the text is disappearing…)

But all it did is break TC. You mentioned something about a solution for custom classes but the link doesn’t seem to work. Could you elaborate a little bit more how this works?

#19 Comment By Yair Altman On November 14, 2013 @ 4:44 am

@Marc – “ClassName” is not one of the acceptable ctype enumerations, explaining why your TC broke. You need to use “MCOSPKG” and/or “MCOSCLASS” to signify that the first arg needs to be a class object.

<binding name="MethodName">
    <arg argn="1" ctype="MCOSCLASS"/>
    <arg argn="2" ctype="FILE"/>
</binding>

To limit the binding to a specific class, you could try the syntax in Marios’ comment above:

<binding name="ClassName.MethodName" ctype="FILE"/>

(you’d need to modify xsd:pattern to include the . character, as shown in Marios’ comment)

#20 Comment By Magu_ On February 28, 2014 @ 12:47 am

Hi

Great article. Can this method also be used for classes?
For the constructor it’s rather simple following your procedure. But I did fail to do so for class methods. I did post this question also on Stackoverflow ( [18]). Feel free to answer also there if you like and earn your credit.

#21 Comment By Yair Altman On March 2, 2014 @ 10:44 am

@Magu – try to implement hidden methods fieldnames and/or methods in your class. The first is for properties, the second is for methods.

#22 Comment By Magu_ On March 4, 2014 @ 3:07 am

Thank you for your answer.

This is very neat I didn’t know that exist. I did it for the fieldnames but failed for methods so far.

“methods” seems to behave differently depending on nargout. Zero output should not matter in this case single output gives back names in cell’s and double output the same again as well as some meta-data cell matrix which I don’t understand fully (and searching in google for function methods doesn’t really help^^).

That’s my take so far:

classdef test (smaller_as) < handle
    properties
        s
    end
    methods
        function o = test()
        end
    end
    methods (Hidden)
        function out = fieldnames(o)
            out = {'x1'; 'x2'};
        end
        function [names,meta] = methods(o)
            names = {'y1'; 'y2'};
            meta = {'' '' 'test.test' '' []; ...
                    '' '' 'test.asd' '(A,B)' 'C'};
        end
    end
end

#23 Comment By Yannay On June 15, 2014 @ 12:51 pm

Dear Yair,

I have a related, seemingly-trivial question. I was wondering whether there’s any way to disable tab auto-complete altogether outside of a GUI interface.

I often need to work through a shell mode command line on Unix. If I copy-paste blocks of code from my desktop editor, whenever there is a tab in the original code, I get a “no completions found” output, which sometimes renders the output illegible.

I was not able to find any documentation of discussions on how to do that.

Many Thanks,
Yannay

#24 Comment By Yannay On June 15, 2014 @ 12:55 pm

sorry, I meant that I was UNable to find any documentation OR discussions…

#25 Comment By Yair Altman On June 15, 2014 @ 12:58 pm

@Yannay – You can disable command-window tab completion via the main Preferences: Keyboard/Shortcuts group – Tab Completion section – “Enable in Command Window” checkbox.

#26 Comment By Yannay On June 15, 2014 @ 1:16 pm

Thank you for responding so quickly—
Let me make myself clearer: I am on the Unix command line and I am not using a GUI. I am trying to find a way to get the same result outside of the GUI platform. Is there any hope?

#27 Comment By Yair Altman On June 15, 2014 @ 1:30 pm

Yannay – simply add the following line to your matlab.prf file (edit([prefdir,'/matlab.prf'])):

CommandWindowTabCompletion=Bfalse

(remember to restart Matlab in order for the change to take effect)

Discussion: [19]

#28 Comment By Yannay On June 15, 2014 @ 1:33 pm

Thanks! I understand now that you previously were indeed referring to command line preferences control, so you did get me right.
I will follow your advise. If it works it would save me infinite irritations…

#29 Comment By Yannay On June 15, 2014 @ 2:11 pm

Unfortunately it doesn’t do what it should. I changed the matlab.prf file as instructed, restarted Matlab, but the “no completions found” feedback still appears following tabs. Is there anything else to try before giving up?

#30 Comment By Yair Altman On June 15, 2014 @ 3:02 pm

try replacing your tabs with spaces in the editor

#31 Comment By Yannay On June 15, 2014 @ 3:56 pm

Yes, I was aware of this option. I am putting it off right now, and will update here if I find a solution. Many thanks for taking the time and explaining about the off-GUI preferences setting.

#32 Comment By Oleg Komarov On July 9, 2014 @ 9:45 am

Note that tab completion for class properties can also be achieved by subclassing the matlab.System class as I describe in my answer: [20]

#33 Comment By Yair Altman On July 9, 2014 @ 10:09 am

@Oleg – thanks for the cross-reference

#34 Pingback By Class object tab completion & improper field names | Undocumented Matlab On July 17, 2014 @ 11:48 am

[...] I described the hack for desktop tab-completion a few years ago. Unfortunately, that hack only works for functions. [...]


Article printed from Undocumented Matlab: http://undocumentedmatlab.com

URL to article: http://undocumentedmatlab.com/blog/setting-desktop-tab-completions

URLs in this post:

[1] Image: http://undocumentedmatlab.com/feed/

[2] email feed: http://undocumentedmatlab.com/subscribe_email.html

[3] asked: http://www.mathworks.com/matlabcentral/newsreader/view_thread/264550

[4] Matlab tab-completion: http://blogs.mathworks.com/desktop/2007/04/27/tab-completion-will-save-your-fingers/

[5] related: http://blogs.mathworks.com/desktop/2009/08/10/tab-to-narrow-completions/

[6] solution lead: http://stackoverflow.com/questions/1842804/tab-completion-of-filenames-as-arguments-for-matlab-scripts

[7] help page: http://www.mathworks.com/access/helpdesk/help/techdoc/ref/whos.html

[8] special-purpose strings: http://www.mathworks.com/access/helpdesk/help/techdoc/ref/openfig.html

[9] available on the Matlab File Exchange: http://www.mathworks.com/matlabcentral/fileexchange/26830-tabcomplete

[10] presented by Michal Kutil: http://www.tim.cz/en/nfaq/matlab-simulink/tab-completion.php

[11] setPrompt – Setting the Matlab Desktop prompt: http://undocumentedmatlab.com/blog/setprompt-setting-matlab-desktop-prompt

[12] Setting the Matlab desktop layout programmatically: http://undocumentedmatlab.com/blog/setting-the-matlab-desktop-layout-programmatically

[13] Setting class property types: http://undocumentedmatlab.com/blog/setting-class-property-types

[14] Setting status-bar text: http://undocumentedmatlab.com/blog/setting-status-bar-text

[15] Setting system tray icons: http://undocumentedmatlab.com/blog/setting-system-tray-icons

[16] Setting system tray popup messages: http://undocumentedmatlab.com/blog/setting-system-tray-popup-messages

[17] : http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_env/bruby4n-1.html#f3-40511

[18] : http://stackoverflow.com/questions/19931996/tab-completion-of-custom-class-methods-in-matlab

[19] : http://undocumentedmatlab.com/blog/changing-system-preferences-programmatically

[20] : http://www.mathworks.co.uk/matlabcentral/answers/138149#answer_144336

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.