branch: externals/matlab-mode
commit 91e9c08e1e843208f5648c25502148073b534c99
Author: John Ciolfi <[email protected]>
Commit: John Ciolfi <[email protected]>
matlab-ts-mode: update doc on indent
---
NEWS.org | 183 +++++++++++++++--------------
README.org | 65 +++++++++-
doc/matlab_code_indent.org | 287 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 449 insertions(+), 86 deletions(-)
diff --git a/NEWS.org b/NEWS.org
index 52c0315b27..6b4c180bd8 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -13,23 +13,43 @@ To indent a MATLAB ~*.m~ file,
: C-x h or M-: (mark-whole-buffer)
: C-M-\ or M-x indent-region
-Electric indent will
+MATLAB indent now:
-1. *Standardize language element spacing*
+1. *Adjusts the indent-level (the whitespace to the left of the code)*
Example:
#+begin_src matlab
- a=b+c *d ;
+ function a = foo(b, c)
+ a = b + ...
+ c;
+ end
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ function a = foo(b, c)
+ a = b + ...
+ c;
+ end
+ #+end_src
+
+2. *Standardizes language element spacing*
+
+ Example:
+
+ #+begin_src matlab
+ a+b * c/ d-1;
#+end_src
Indents to:
#+begin_src matlab
- a = b + c * d;
+ a + b * c / d - 1;
#+end_src
-2. *Align consecutive assignments*
+3. *Aligns consecutive assignments*
Example:
@@ -58,7 +78,7 @@ Electric indent will
c2 = c * 2;
#+end_src
-3. *Align consecutive properties*
+4. *Aligns consecutive properties*
Example:
@@ -84,7 +104,7 @@ Electric indent will
end
#+end_src
-4. *Align consecutive arguments*
+5. *Aligns consecutive arguments*
Example:
@@ -110,7 +130,7 @@ Electric indent will
end
#+end_src
-5. *Align enumeration members*
+6. *Aligns enumeration members*
Example:
@@ -135,8 +155,8 @@ Electric indent will
end
end
#+end_src
-
-6. *Align consecutive trailing comments*
+
+7. *Aligns consecutive trailing comments*
Example:
@@ -156,7 +176,7 @@ Electric indent will
disp(distance1) % Report how far we've gone
#+end_src
-7. *Add missing commas in arrays (matrices and cells)*
+8. *Adds missing commas in arrays (matrices and cells)*
Example:
@@ -170,7 +190,7 @@ Electric indent will
mat1 = [1234, 234, 12234.24];
#+end_src
-8. *Align multi-line matrix columns*
+9. *Aligns multi-line matrix columns*
Example
@@ -186,27 +206,27 @@ Electric indent will
1, 2, 3.41];
#+end_src
-9. *Align fields of multi-line structures*
+10. *Aligns fields of multi-line structures*
- Example:
+ Example:
- #+begin_src matlab
- myStruct = struct( ...
- 'field1', (2+3)*4, ...
- 'longField2',"foo",...
- 'f3',2);
- #+end_src
+ #+begin_src matlab
+ myStruct = struct( ...
+ 'field1', (2+3)*4, ...
+ 'longField2',"foo",...
+ 'f3',2);
+ #+end_src
- Indents to:
+ Indents to:
- #+begin_src matlab
- myStruct = struct( ...
- 'field1' , (2 + 3) * 4, ...
- 'longField2', "foo", ...
- 'f3' , 2);
- #+end_src
-
-10. *Untabify (convert TAB Characters to spaces)*
+ #+begin_src matlab
+ myStruct = struct( ...
+ 'field1' , (2 + 3) * 4, ...
+ 'longField2', "foo", ...
+ 'f3' , 2);
+ #+end_src
+
+11. *Removes tabs (convert TAB Characters to spaces)*
Conversion of tab characters to spaces ensures that code looks the same
when using different
levels of tab stops. For example, UNIX (POSIX) uses tab stops of 8 whereas
Microsoft uses tab
@@ -214,64 +234,57 @@ Electric indent will
** Indent Example
-Given:
-
-#+begin_src matlab
- % Calculate the Golden Ratio (phi)
- phi= ( 1+ sqrt( 5))/ 2 ;
- disp( [ 'Golden Ratio (phi): ', num2str( phi ) ] );
% Display the value
-
- % Plot the exponential function with a Taylor Series Approximation
- x = -2 : 0.1 : 2;
- yExp=exp( x ) ;
- yTaylor = 1+x + x.^ 2 / 2+x.^3 /6; % First few terms
-
- % Plot the approximation
- figure ;% Create a new figure
- plot( x,yExp, 'b-','LineWidth',2); % Plot the actual
exponential
- hold on ;% Keep the current plot
- plot(x, yTaylor, ...
- 'r--',...
- 'LineWidth', 1.5);
- title('Exponential Function & Taylor Approximation');
- xlabel( 'x');
- ylabel('y');
- legend( 'exp(x)', 'Taylor Series' );
- grid on ;
- hold off ;
-#+end_src
-
-Running
+Example:
+
+ #+begin_src matlab
+ function out= indent_example( in1, ...
+ input2)
+ % INDENT_EXAMPLE - an indent example
+ % which illustrates the MATLAB indent engine.
+ arguments
+ in1 = 10
+ input2= 20;
+ end
+
+ mat = [100,2
+ 3 400];
+
+ s = struct( 'f1',1, ...
+ 'otherField', in1+input2);
+
+ if abs(sum(in1)) > 0
+ out=s.f1/input2+ in1;
+ else
+ out = mat+in1 * 2;
+ end
+ end
+ #+end_src
+
+Is indented to the following using ~C-x h~ and then ~C-M-\~:
+
+ #+begin_src matlab
+ function out = indent_example(in1, ...
+ input2)
+ % INDENT_EXAMPLE - an indent example
+ % which illustrates the MATLAB indent engine.
+ arguments
+ in1 = 10
+ input2 = 20;
+ end
-: C-x h or M-: (mark-whole-buffer)
-: C-M-\ or M-x indent-region
+ mat = [100, 2
+ 3, 400];
+
+ s = struct('f1' , 1, ...
+ 'otherField', in1 + input2);
-will produce:
-
-#+begin_src matlab
- % Calculate the Golden Ratio (phi)
- phi = (1 + sqrt(5)) / 2;
- disp(['Golden Ratio (phi): ', num2str(phi)]); % Display the value
-
- % Plot the exponential function with a Taylor Series Approximation
- x = -2 : 0.1 : 2;
- yExp = exp(x);
- yTaylor = 1 + x + x.^2 / 2 + x.^3 / 6; % First few terms
-
- % Plot the approximation
- figure; % Create a new figure
- plot(x, yExp, 'b-', 'LineWidth', 2); % Plot the actual exponential
- hold on; % Keep the current plot
- plot(x, yTaylor, ...
- 'r--', ...
- 'LineWidth', 1.5);
- title('Exponential Function & Taylor Approximation');
- xlabel('x');
- ylabel('y');
- legend('exp(x)', 'Taylor Series');
- grid on;
- hold off;
-#+end_src
+ if abs(sum(in1)) > 0
+ out = s.f1 / input2 + in1;
+ else
+ out = mat + in1 * 2;
+ end
+ end
+ #+end_src
* Release 7.4.1 Nov 26, 2025
diff --git a/README.org b/README.org
index 5adc8a5f9b..1b2c6def64 100644
--- a/README.org
+++ b/README.org
@@ -9,7 +9,8 @@
1. MATLAB mode, *matlab-ts-mode* or *matlab-mode*, for editing ~*.m~ files.
- - Edit MATLAB code with syntax highlighting and smart indentation.
+ - Edit MATLAB code with syntax highlighting, indentation (code formatting),
and semantic
+ movement.
- Lint MATLAB code with fix-it's using the MATLAB Code Analyzer.
The *matlab-ts-mode* is a more capable, performant, and accurate than
*matlab-mode*.
@@ -82,6 +83,68 @@
8. *tlc-mode* for editing ~*.tlc~ files. The Target Language Compiler (TLC) is
part of Simulink®
Coder™.
+* MATLAB Indent (Code Formatting)
+
+With the optional matlab-ts-mode, you have
[[file:doc/matlab_code_indent.org][MATLAB code indentation]] that
+
+ - Adjusts the indent-level (the whitespace to the left of the code), and
+ - Standardizes language element spacing, aligns consecutive statements,
aligns matrices and
+ structs, adds missing commas to matrices.
+
+Example:
+
+ #+begin_src matlab
+ function out= indent_example( in1, ...
+ input2)
+ % INDENT_EXAMPLE - an indent example
+ % which illustrates the MATLAB indent engine.
+ arguments
+ in1 = 10
+ input2= 20;
+ end
+
+ mat = [100,2
+ 3 400];
+
+ s = struct( 'f1',1, ...
+ 'otherField', in1+input2);
+
+ if abs(sum(in1)) > 0
+ out=s.f1/input2+ in1;
+ else
+ out = mat+in1 * 2;
+ end
+ end
+ #+end_src
+
+Is indented to the following using ~C-x h~ and then ~C-M-\~ (or ~Edit ->
Select All~, then ~M-x
+indent-region~):
+
+ #+begin_src matlab
+ function out = indent_example(in1, ...
+ input2)
+ % INDENT_EXAMPLE - an indent example
+ % which illustrates the MATLAB indent engine.
+ arguments
+ in1 = 10
+ input2 = 20;
+ end
+
+ mat = [100, 2
+ 3, 400];
+
+ s = struct('f1' , 1, ...
+ 'otherField', in1 + input2);
+
+ if abs(sum(in1)) > 0
+ out = s.f1 / input2 + in1;
+ else
+ out = mat + in1 * 2;
+ end
+ end
+ #+end_src
+
+
* Installation
1. Install the MATLAB package via [[https://melpa.org][MELPA]] or
[[https://elpa.gnu.org/][ELPA]]. MELPA contains the latest version. To install
from
diff --git a/doc/matlab_code_indent.org b/doc/matlab_code_indent.org
new file mode 100644
index 0000000000..88d5e1c08a
--- /dev/null
+++ b/doc/matlab_code_indent.org
@@ -0,0 +1,287 @@
+# File: doc/code_indent.org
+# Copyright (C) 2025 Free Software Foundation, Inc.
+
+#+startup: showall
+#+startup: logdone
+#+startup: inlineimages
+#+startup: latexpreview
+#+options: ^:{} # a_{b} for subscript, a^{b} for superscript, leave a_b and
a^b as is.
+#+options: toc:2 # toc:nil == no toc, toc:1 == one level, toc:2 == two
levels, etc.
+
+#+latex_header: \usepackage[margin=0.25in]{geometry}
+#+latex_header: \usepackage{parskip}
+#+latex_header: \usepackage{svg}
+#+latex_header: \sloppy
+
+#+title: MATLAB Code Indent (aka Code Format)
+#+author: John Ciolfi
+
+To indent a MATLAB ~*.m~ file,
+
+: C-x h or Menu -> Edit -> Select All
+: C-M-\ or Menu -> Execute Command indent-region
+
+When using matlab-ts-mode (and not matlab-mode) the MATLAB indent engine:
+
+1. *Adjusts the indent-level (the whitespace to the left of the code)*
+
+ Example:
+
+ #+begin_src matlab
+ function a = foo(b, c)
+ a = b + ...
+ c;
+ end
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ function a = foo(b, c)
+ a = b + ...
+ c;
+ end
+ #+end_src
+
+2. *Standardizes language element spacing*
+
+ Example:
+
+ #+begin_src matlab
+ a+b * c/ d-1;
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ a + b * c / d - 1;
+ #+end_src
+
+3. *Aligns consecutive assignments*
+
+ Example:
+
+ #+begin_src matlab
+ rLength =12354 ;
+ rWidth=2;
+ rArea=rLength *rWidth;
+ #+end_src
+
+ Intents to:
+
+ #+begin_src matlab
+ rLength = 12354;
+ rWidth = 2;
+ rArea = rLength * rWidth;
+ #+end_src
+
+ For alignment, the statements must be consecutive. For example, the
following contains two
+ sections of consecutive statement alignment:
+
+ #+begin_src matlab
+ aReallyLongVariable = 10;
+ bShortVar = 5;
+
+ c = aReallyLongVariable + bShortVar;
+ c2 = c * 2;
+ #+end_src
+
+4. *Aligns consecutive properties*
+
+ Example:
+
+ #+begin_src matlab
+ classdef myClass
+ properties
+ p1 ( 1,:) {mustBeNumeric, mustBeReal} = [0, 0, 0];
+ longProperty2 (1, 3) {mustBeNumeric, mustBeReal} = [0, 0, 0];
+ p3(1,2 )
+ end
+ end
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ classdef myClass
+ properties
+ p1 (1,:) {mustBeNumeric, mustBeReal} = [0, 0, 0];
+ longProperty2 (1,3) {mustBeNumeric, mustBeReal} = [0, 0, 0];
+ p3 (1,2)
+ end
+ end
+ #+end_src
+
+5. *Aligns consecutive arguments*
+
+ Example:
+
+ #+begin_src matlab
+ function myFcn(a, longInputVar, c)
+ arguments
+ a{ mustBeNumeric,
mustBeReal}
+ longInputVar { mustBeNumeric,mustBeReal
,mustBeFinite}
+ c{mustBeNumeric}
+ end
+ end
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ function myFcn(a, longInputVar, c)
+ arguments
+ a {mustBeNumeric, mustBeReal}
+ longInputVar {mustBeNumeric, mustBeReal, mustBeFinite}
+ c {mustBeNumeric}
+ end
+ end
+ #+end_src
+
+6. *Aligns enumeration members*
+
+ Example:
+
+ #+begin_src matlab
+ classdef TrafficLightColors < double
+ enumeration
+ red (1)
+ green(2)
+ yellow(3)
+ end
+ end
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ classdef TrafficLightColors < double
+ enumeration
+ red (1)
+ green (2)
+ yellow (3)
+ end
+ end
+ #+end_src
+
+7. *Aligns consecutive trailing comments*
+
+ Example:
+
+ #+begin_src matlab
+ s1 =5 ; % Average speed of the first vehicle in miles
per hour
+ timeH1=2;% Time in hours traveled of first vehicle in hours
+ distance1= s1 * timeH1; % Distance we've traveled in
miles
+ disp(distance1)% Report how far we've
gone
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ s1 = 5; % Average speed of the first vehicle in miles
per hour
+ timeH1 = 2; % Time in hours traveled of first vehicle in
hours
+ distance1 = s1 * timeH1; % Distance we've traveled in miles
+ disp(distance1) % Report how far we've gone
+ #+end_src
+
+8. *Adds missing commas in arrays (matrices and cells)*
+
+ Example:
+
+ #+begin_src matlab
+ mat1 = [1234,234 12234.24];
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ mat1 = [1234, 234, 12234.24];
+ #+end_src
+
+9. *Aligns multi-line matrix columns*
+
+ Example
+
+ #+begin_src matlab
+ mat2 = [1234,234 12234.24
+ 1,2 3.41];
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ mat2 = [1234, 234, 12234.24
+ 1, 2, 3.41];
+ #+end_src
+
+10. *Aligns fields of multi-line structures*
+
+ Example:
+
+ #+begin_src matlab
+ myStruct = struct( ...
+ 'field1', (2+3)*4, ...
+ 'longField2',"foo",...
+ 'f3',2);
+ #+end_src
+
+ Indents to:
+
+ #+begin_src matlab
+ myStruct = struct( ...
+ 'field1' , (2 + 3) * 4, ...
+ 'longField2', "foo", ...
+ 'f3' , 2);
+ #+end_src
+
+11. *Removes tabs (convert TAB Characters to spaces)*
+
+ Conversion of tab characters to spaces ensures that code looks the same
when using different
+ levels of tab stops. For example, UNIX (POSIX) uses tab stops of 8 whereas
Microsoft uses tab
+ stops of 4.
+
+* Indent Engine Design Considerations
+
+When creating the MATLAB indent engine, I leaned on my past experiences.
+
+_Simplicity is good_
+
+The first indent engine I wrote was a c_indent engine that shipped with the
MathWorks Real-Time
+Workshop in 1997 (now called the Simulink Coder). This simple indent engine
worked well. It had no
+options and indented the generated code from Simulink Coder quickly. c_indent
has been updated over
+the years maintaining the goal of simplicity.
+
+_Complexity hurts_
+
+I've helped with the deployment of clang-format and other indent engines on a
large code base. A
+lesson learned is that the flexibility of clang-format causes inconsistencies,
people want different
+options and that creates conflicts. Another lesson learned is that
not-respecting the newlines in
+code causes negative reactions where the formatted code is less readable. The
newlines are put there
+for a reason and removing or adding them changes the readability and meaning
of the code in some
+(rare) cases. clang-format is also complex and we've run into a number of bugs
in it over the
+years. The problem of clang-format making code less-readable also occurs with
other indent
+engines. For example Linus Torvalds vented over "Completely Crazy Rust Format
Checking" [[[https://www.phoronix.com/news/Linus-Torvalds-Rust-Formatting][1]]]
[[[https://www.reddit.com/r/rust/comments/1nwt8nm/linus_torvalds_vents_over_completely_crazy_rust/][2]]].
+
+The benefit of these complex indent engines is significant and outweighs the
drawbacks. Clang-format
+added comment directives ~// clang-format off~ and ~// clang-format on~ which
are liberally used to
+work-around the drawbacks.
+
+_Design_
+
+The design of the MATLAB indent engine is based on simplicity.
+
+- Respect existing newlines,
+- Adjust the indent-level (the whitespace to the left of the code),
+- Standardize language element spacing, aligns consecutive statements, aligns
matrices and
+ structs, adds missing commas to matrices.
+
+A number of people familiar with the MATLAB language came up with a set of
rules for MATLAB
+indent. This includes the indent level is 4 for each condition or scope,
language elements should
+have consistent spacing, matrices should align columns, etc.
+
+We choose to have no indent options and make sure the indents works well in
all cases. This
+eliminates the need for comment directives like ~%#<indent off>~ and ~%<indent
on>~. By having one
+indent standard, people reading code from different projects will see
consistency. Consistency helps
+with understanding and communication.
+
+# LocalWords: showall logdone inlineimages latexpreview usepackage parskip svg
