Skip to content

Commit f744cc2

Browse files
committed
matlab-sections: display message when running sections
Also add help on sections.
1 parent 4607260 commit f744cc2

File tree

5 files changed

+137
-28
lines changed

5 files changed

+137
-28
lines changed

README.org

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,21 +44,13 @@
4444

4545
#+end_example
4646

47-
5. *Code sections* support for MATLAB script files. Script files contain one or more commands, such
48-
as variable assignements, function calls, etc. Script files differ from declaration files such
49-
as those declaring function's or classdef's. You typically focus your efforts on a single part
50-
of your code at a time, working with the code and related text in sections. You demarcate
51-
sections using /"%% description"/ header comments.
47+
5. *Code sections* support for MATLAB script files. See [[file:doc/matlab-code-sections.org][doc/matlab-code-sections.org]].
5248

53-
- After visiting a MATLAB script, you have the *"MATLAB -> Code Sections"* menu and key
54-
bindings which lets you can navigate, run, and move code sections.
49+
- After visiting a MATLAB script, you have a *"MATLAB -> Code Sections"* menu and key bindings
50+
which lets you navigate, run, and move code sections.
5551

5652
- Try out code sections using: [[file:examples/matlab-sections/tryout_matlabsection.m][./examples/matlab-sections/tryout_matlabsection.m]].
5753

58-
- The default keybindings for code sections are ~C-c C-<KEY>~ and ~C-c M-<KEY>~. You can add
59-
super key bindings for code sections. After visiting a file.m, see menu *"MATLAB -> Code
60-
Sections -> Help"*.
61-
6254
6. *Creation of scientific papers, theses, and documents* using MATLAB and [[http://orgmode.org]].
6355

6456
- Org enables [[https://en.wikipedia.org/wiki/Literate_programming][literate programming]] which directly supports reproducible research by allowing

doc/matlab-code-sections.org

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# File: doc/matlab-code-sections.org
2+
3+
#+startup: showall
4+
#+options: toc:nil
5+
6+
# Copyright 2025 Free Software Foundation, Inc.
7+
8+
* MATLAB Code Sections in Script *.m Files
9+
10+
MATLAB script files contain one or more commands, such as variable assignments, function calls, etc.
11+
Script files differ from declaration files such as those declaring function's or classdef's. When
12+
working with script files, you typically focus your efforts on a single part of your code at a time,
13+
working with the code and related text in sections. You demarcate sections using /"%% description"/
14+
header comments.
15+
16+
An example of a script file is ~basic_script.m~:
17+
18+
#+begin_src matlab
19+
%% First section
20+
21+
a = 1;
22+
b = 2;
23+
24+
%% Second section
25+
26+
c = a + b;
27+
disp(['c = ', num2str(c)]);
28+
#+end_src
29+
30+
When you visit a script.m file, you will have a *MATLAB -> Code Sections* menu. Help from within
31+
Emacs is available from *"MATLAB -> Code Sections -> Help"* menu item. You can use the menu or key
32+
bindings to modify or run your script.
33+
34+
#+begin_example
35+
C-c C-SPC Mark/select section.
36+
37+
C-c C-<up> Move point backward to the prior "% section"
38+
C-c C-<down> Move point forward to the next "% section"
39+
C-c C-<left> Move point to the beginning of the current "%% section"
40+
C-c C-<right> Move point to the end of the current "%% section"
41+
42+
C-c M-<up> Move the current "%% section" up
43+
C-c M-<down> Move the current "%% section" down
44+
45+
C-c C-<return> Run the current "%% section"
46+
C-c M-<return> Run all "%% sections" prior to the current section
47+
#+end_example
48+
49+
Sections are run using the =*MATLAB*= shell buffer created using =M-x matlab-shell= on Unix and the
50+
attached MATLAB using the [[file:matlab-netshell-for-windows.org][matlab netshell on Windows]]. When a section is run, you will see in the
51+
MATLAB Command Window:
52+
53+
#+begin_example
54+
emacsrunregion('/path/to/your/script.m', startChar, endChar)
55+
56+
<text displayed by your script.m>
57+
#+end_example
58+
59+
The sections are run asynchronously. After sending the emacsrunregion command to MATLAB, control is
60+
returned to Emacs. In MATLAB, you'll see the ">>" prompt reappear when emacsrunregion is complete.
61+
62+
** Customizations
63+
64+
If you'd like to use super (aka Windows) key bindings instead of the above key bindings, you can
65+
66+
: M-x customize-variable RET matlab-sections-use-super-key RET

matlab-sections.el

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,25 @@ the command `matlab-sections-minor-mode' to turn matlab-sections mode on."
132132

133133
;; Function to obtain range of current code section
134134

135+
(defun matlab-sections--get-heading (&optional range)
136+
"Return the \"%% descrition\" heading or nil if not in a code section.
137+
RANGE is (START-PT . END-PT) of the section or nil. If nil, we'll
138+
determine the RANGE."
139+
(when (not range)
140+
(setq range (matlab-sections-range-function)))
141+
(save-excursion
142+
(save-restriction
143+
(widen)
144+
(goto-char (car range))
145+
(when (not (looking-at "^[[:blank:]]*%%[[:blank:]]*\\(.*\\)$"))
146+
(error "Assert - failed to match section heading at point %S" (point)))
147+
(let ((heading (string-trim (match-string-no-properties 1))))
148+
(when (string= heading "")
149+
(setq heading "Empty section heading"))
150+
(setq heading (concat heading (format " (line %d)"
151+
(line-number-at-pos)))))
152+
)))
153+
135154
(defun matlab-sections-range-function ()
136155
"Return range (START-PT . END-PT) of current MATLAB code section.
137156
nil is returned if there is no code section."
@@ -293,11 +312,14 @@ Return `point'."
293312
"Run the current \"%% section\" in `matlab-shell'."
294313
(interactive)
295314
(let ((rng (matlab-sections-range-function)))
296-
(save-excursion
297-
(save-restriction
298-
(widen)
299-
(save-window-excursion
300-
(matlab-shell-run-region (car rng) (cdr rng)))))))
315+
(if rng
316+
(save-excursion
317+
(save-restriction
318+
(widen)
319+
(save-window-excursion
320+
(message "Running section: %s" (matlab-sections--get-heading rng))
321+
(matlab-shell-run-region (car rng) (cdr rng)))))
322+
(message "Not in a \"%% code section\""))))
301323

302324
(define-obsolete-function-alias 'matlab-sections-run-till-point
303325
#'matlab-sections-run-prior-sections "6.3")
@@ -312,9 +334,14 @@ Does not run the section the point is in."
312334
(let ((current-section-start-point (matlab-sections-beginning-of-section)))
313335
(goto-char (point-min))
314336
(matlab-sections-beginning-of-section)
315-
(when (< (point) current-section-start-point)
316-
(save-window-excursion
317-
(matlab-shell-run-region (point) current-section-start-point)))))))
337+
(if (< (point) current-section-start-point)
338+
(progn
339+
(save-excursion
340+
(goto-char current-section-start-point)
341+
(message "Running sections prior to: %s" (matlab-sections--get-heading)))
342+
(save-window-excursion
343+
(matlab-shell-run-region (point) current-section-start-point)))
344+
(message "No prior \"%% code sections\""))))))
318345

319346
(declare-function matlab-mode "matlab.el")
320347

matlab.el

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -602,16 +602,18 @@ point, but it will be restored for them."
602602
("Code Sections"
603603
["Run section" matlab-sections-run-section
604604
:active matlab-sections-minor-mode
605-
:help "Run the current \"%% section\" in `matlab-shell'."]
605+
:help "Run the current \"%% section\" in
606+
matlab-shell (Unix) or matlab-netshell (Windows)"]
606607
["Run prior sections" matlab-sections-run-prior-sections
607608
:active matlab-sections-minor-mode
608-
:help "Run all \"%% sections\" prior to the current section in `matlab-shell'"]
609+
:help "Run all \"%% sections\" prior to the current section in
610+
matlab-shell (Unix) or matlab-netshell (Windows)"]
609611
["Move to beginning" matlab-sections-beginning-of-section
610612
:active matlab-sections-minor-mode
611-
:help "Move `point' to the beginning of the current \"%% section\""]
613+
:help "Move point to the beginning of the current \"%% section\""]
612614
["Move to end" matlab-sections-end-of-section
613615
:active matlab-sections-minor-mode
614-
:help "Move `point' to the end of the current \"%% section\""]
616+
:help "Move point to the end of the current \"%% section\""]
615617
["Backward section" matlab-sections-backward-section
616618
:active matlab-sections-minor-mode
617619
:help "Move point backward to the prior \"%% section\""]

toolbox/emacsrunregion.m

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ function emacsrunregion(file, startchar, endchar)
2525
end
2626

2727
% Now figure out if shortFileName is on the path.
28-
[ fullFilePath, shortFileName ] = fileparts(file);
28+
[fullFilePath, shortFileName, extension] = fileparts(file);
2929
onpath = ~isempty(which(shortFileName));
3030

3131
% If not on the path, temporarily switch to that directory so it and an files it references are
@@ -36,9 +36,31 @@ function emacsrunregion(file, startchar, endchar)
3636
cleanup = onCleanup(@()cd(oldpath));
3737
end
3838

39-
txt = fileread(file);
40-
evalTxt = txt(startchar:min(endchar,length(txt)));
41-
evalin('base',evalTxt);
39+
fileContents = fileread(file);
40+
41+
endchar = min(endchar, length(fileContents));
42+
evalTxt = fileContents(startchar:endchar);
43+
evalin('base', evalTxt);
44+
45+
% See if startchar and endchar are on the first column of a lines and if so display that. Note,
46+
% fileContents can contain POSIX newlines (LF) or be Windows CRFL (13, 10) line endings.
47+
if (startchar == 1 || fileContents(startchar-1) == newline) && ...
48+
regexp(fileContents(endchar), '[\r\n]', 'once')
49+
startLineNum = length(strfind(fileContents(1:startchar), newline)) + 1;
50+
endLineNum = length(strfind(fileContents(1:endchar), newline));
51+
if fileContents(endchar) == 13 || endchar == length(fileContents)
52+
% Looking at CR or end-of-file
53+
endLineNum = endLineNum + 1;
54+
end
55+
56+
regionInfo = sprintf('lines %d to %d', startLineNum, endLineNum);
57+
else
58+
regionInfo = sprintf('chars %d to %d', startchar, endchar);
59+
end
60+
61+
% TODO - enable this display after updating tests to pass on Unix.
62+
% fprintf(1, 'emacsrunregion: finished running %s%s %s\n', ...
63+
% shortFileName, extension, regionInfo);
4264
end
4365

44-
% LocalWords: Ludlam STARTCHAR ENDCHAR
66+
% LocalWords: STARTCHAR ENDCHAR

0 commit comments

Comments
 (0)