Our friend Yair recently described on his blog how to use the various functionalities of the Editor by accessing its Java components. I imagine for many MATLAB users, especially those not familiar with Java, this is wading into unfamiliar territory. We don’t write very many APIs in Java intended for our users to access, and we like to abstract away the implementation components so we can be free to refactor behind the scenes. We’ve been spending time on refactoring projects, and so the Java APIs have been changing quite rapidly.
Over the years we’ve had a lot of requests for programmatic access to various desktop components, and we’re working on a MATLAB API for the Editor. In R2009b, this API is hidden in the product (aka undocumented), but we’re planning on bringing it out in a future release fully supported and documented. The api provides methods to manipulate the text, get information about the buffer, as well as close, save, and open editors. With the object provided users can manage the editor state, write scripts that call their favorite diff tool, open files in other programs, open the folder in the OS, etc.
The 9b version isn’t fully vetted or functional; it’s there to satisfy some back-end requirements. This means I’m officially saying not to use it and don’t complain when things don’t work, but… if you’d like to preview it, give it a go. All of the functionality is part of the editorservices package. A single buffer/file in the Editor is represented by the editorservices.EditorDocument class. These objects are constructed by calling the package functions such as editorservices.new(), editorservices.open(), and editorservices.getActive().
Here is a full list of the package function in MATLAB R2009b.
help editorservices
Contents of editorservices:
EditorDocument - Encapsulates all user accessible behavior of the MATLAB Editor
EditorUtils - Static utility methods for editorservices functions
closeGroup - Closes the MATLAB Editor and all open documents.
find - returns an already open EditorDocument for a given file name
getActive - finds the active (topmost) open buffer in the Editor
getAll - Gets all the Editors that are currently open
isOpen - true if the specified file is open in the editor
new - Creates a new buffer, with optional text
open - Opens the MATLAB Editor with the given filename
openAndGoToFunction - open a file in the editor and highlight the indicated function
openAndGoToLine - open a file in the editor and highlight the indicated line
You can try it out now, but keep in mind we’ve already already changed the API, fixed some of the bugs, and enhanced its functionality for its prime-time release, and so any code written with it will likely have to change when we release the documented API.
Please let us know how this new api fits (or doesn’t fit) into your workflows, and what future enhancements you’d like to see and what other Desktop components you’d like to work with programmatically.
By
Michael Katz
Mike is a developer on the MATLAB Desktop team. When not describing himself in the third person, biking, homebrewing, or rooting for the home team, he's busy trying to make the world a better place for programming.
13:04 UTC |
Posted in Editor |
Permalink |
You can follow any responses to this entry through the RSS 2.0 feed.
You can skip to the end and leave a response. Pinging is currently not allowed.
Leave a Reply
Hi,
Is there a way on the desktop to email a mfile that you are editing to someone? I often need to do this.
Thanks!
KE,
We don’t currently have this feature built in to MATLAB. If you’re using a desktop email client on Windows, I can see if I have an old function lying around, though…
We have written some code to help us work with what we call projects - a collection of m-files and, optionally, a project dependent path. We store the project m-file names and the path in a text file. We get the open files using com.mathworks.mlservices.MLEditorServices.builtinGetOpenDocumentNames; we close files using com.mathworks.mlservices.MLEditorServices.closeAll or com.mathworks.mlservices.MLEditorServices.closeDocument. I am glad to see that this type of feature will now be documented. At one time, we were beta testing Matlab’s version of Projects (for the 2007b pre-release). Any plans for that to be released?
@KE -
I have a file that I’ve been too lazy to put on the File Exchange that makes it easy to email files from with MATLAB. Email me and I’ll be happy to send it to you. shirsch@nospamdeleteme.mathworks.com
The API looks something like
>> sendfile myfile myfriend@gmail.com
to send myfile.m which is somewhere on the path. It would be pretty easy to modify it with the API described here to send the current file in the editor instead of the specified file.
@Eric- We don’t have any current plans to release the features from the 7b prerelease as is, though we are folding many of the ideas we used there into existing parts of MATLAB, such as the Current Folder Browser or Deploytool (from the MATLAB Compiler).
It is good to see that these functions will be supported, and I am really excited about having Matlab APIs in general.
A few things I’d like to see, not necessarily related to this API:
- the ability to manipulate the document bar order from the API, and location
- virtual folders in the document bar for organizing groups of files (as well as the ability to manipulate these from the API)
- support for renaming files from the editor (renaming the file on disk)
- support for font formatting (color, bold, italic, underline) in the command window BOTH from a function call and in the description line
Thanks
Currently I’ve ended up grabbing the list of open files via some COM interface I found on the web. The tasks I tend to do are :
1. Run m-lint over the whole set of files to generate a list of whatever MATLAB thinks is potentially dodgy. Since I often have code which violates a warning during development, I find this more effective than trying to navigate through the group of files rechecking all the “colour bar” indicators.
2. Run it the files through an external text searcher like “grep”. What I want here is NOT an interactive search of all files, but a search that throws up the context-line of all the given matches so I can figure out which one I want. (I’ve inhereted a body of MATLAB code with the typical lack of structure so I often need to search for where some variabel is modified within a rats-nest of files.)
3. Getting a list of files currently being modified to commit into source control.
4. Very occasionally I end up applying a text-filter to a set of data-as-code files (like adding a final column) where it’s sometimes more convenient to get the applicable files list from the editor rather than get them from a shell prompt.
The biggest issue I’ve come across is that there’s, AFAIK, no way to present a text string and line number the MATLAB command result text in such a way that you can double click on it to automatically jump to that file/line in the editor. (Maybe I’m just not using the same format as the MATLAB error output; unix tends to use the “file:line” format which definitely doesn’t work.)
Incidentally, one thing that would massively improve the editor for me would be an OPTION (not forcing it on everyone) to keep the files list in the pull-down menu sorted at all times rather than try and cleverly order the files. I waste so much time every day trying to find where the file list has put a file who’s name I know very well.
Actually Dave, look at Urs’ great File Exchange submission GREP, which does exactly what you requested - it searches all specified files (*.m for example), recursively in sub-folders, for a specified regular-expression or search string, returning the context line text, the filename and the linenumber - *which are hyperlinked to the source code* - all this within Matlab and in lightning speed:
http://www.mathworks.com/matlabcentral/fileexchange/9647
Yair
Many thanks to Yair for his pointer. The grep script is very useful. The one thing that I couldn’t see directly from the documentation is a built-in way to specify “run over all the currently open files”, but it’s straightforward to wrap the output of com.mathworks.mlservices.MLEditorServices.builtinGetOpenDocumentNames
into a cell array and pass it in. Very helpful script.
@davetweed
Thank your for describing your workflow. For case #1, you can use the command-line form of mlint, and collector or parse its output. For #2 you can use the utility Yair shared or the !, dos, or system commands to run the command-line grep from the MATLAB Command window.
Hopefully the interface described here can help your #3 and #4 tasks.
As for jumping to a line in the editor, you can use the opentoline command with the full path of the file. For example:
disp('<a href="matlab:opentoline(which(''edit''),30)">edit edit@30</a>')Finally, by the pull-down menu, are you referring to the list of most recently edited files in the File menu?
@Mike,
Thanks for your work improving the overall UI,
For points 1 and 2, I use the mlint command and external grep, the point was that I find it helpful to wrap them in a short script that applies them to all open files rather than needing to manually type out the filename. (Part of the explanation for this is that I’m working in a fully checked out source tree which has “semantically related” things in the same directory and one of our various “programs” is thus a top-level script that uses only SOME of the scripts from a whole slew of directories, so that usage which recursively mlints/searches the directory tree I’m currently in brings up too many results irrelevant to what I’m currently doing. Obviously if there were to be exactly one “program” in a directory tree there’s no difference between the two.) I actually don’t mind calling out to a system utility to do the processing for these (or other things) since the “slower speed” isn’t noticeable in practice. What would make things smoother would being able to go interact with the textual output in the MATLAB command window to jump in the editor. Now I’ve seen the html wrapping I might mess around trying to wrap the incoming results returned from the system function.
By “pull-down menu” I mean the list of windows, including source files, under the Window menu in the command and editor windows. (I don’t have enough screen real estate for the “draggable column of filenames” that seems to be the preferred interface.) It looks like there’s some heuristic in the ordering of the windows that’s supposed to put the files commonly wanted at the top of the list, but for me it just means the list isn’t alphabetically ordered so I have to read all the entries carefully until I find the entry I want.
Hi,
I am very excited about the MATLAB API for editor because right now i am working on a project and i need to open file in editor and make some changes via COM API.
I am using MATLAB R2007b so i want to know is there any way to use these editor options in R2007b??
All i am doing is developing an application in C# which get Calibration data from calibration tool and put that data into MATLAB, do some calculations and put back to calibration tool.
The problem i am facing is that for doing calculations in want to open my m.file having all parameter definitions and calculations, i want to put new values imported from calibration tool to m.file.
At the moment i can only access MATLAB base workspace not m.file for modifications.
Please tell me if there is any way to get handle to this.
Thanks a lot indeed.
Looking forward for fully functional MATLAB API for editor.
Best Regards.
Hi Arsalan,
Unfortunately there is no way to get the new Editor API in older versions of MATLAB.
-Ken