-
Notifications
You must be signed in to change notification settings - Fork 5
/
MBeautify.txt
82 lines (51 loc) · 5.35 KB
/
MBeautify.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
# MBeautifier
MBeautifier is a lightweight M-Script based Matlab source code formatter usable directly in the Matlab Editor.
Main features
-------------
- Padding operators with white spaces based on the XML configuration file.
- Correction white space padding of keywords
- Correction of indentation using the Smart Indent functionality of the Matlab Editor
- Removal of continuous empty lines (the number can be configured)
- Optionally inserting missing element separators (commas) in matrix and cell array initializations
- Different working modes: format the current page of the Matlab editor, format only a selection in the Matlab Editor or format file(s)
Deployment and Configuration
----------------------------
Add containing directory to the Matlab path, then execute: `MBeautify.setup()`.
This command will create the standard configuration of formatting stored in `MBeautifier\resources\settings\MBeautyConfigurationRules.m`.
This file is used in run-time to gather the configuration rules, therefore when the configuration XML file has been modified, executing this function again will make the rules active.
### Configuration
The configuration can be modified by editing the `MBeautifier\resources\settings\MBeautyConfigurationRules.xml` file.
#### Configuration rules
Currently two types of configuration rules are implemented: `OperatorPaddingRule` and `SpecialRule`.
#### Operator padding rules
Each `OperatorPaddingRule` represents the formatting rules for one single operator and consists of a key, the string that should be replaced and a string that should be used for the replacement.
<OperatorPaddingRule>
<Key>NotEquals</Key>
<ValueFrom>~=</ValueFrom>
<ValueTo> ~= </ValueTo>
</OperatorPaddingRule>
The above example shows the rule for the "not equals" operator. The `ValueFrom` node stores the operator `~=` and the `ValueTo` node stores the expected format: the operator should be preceded and followed by a white-space character.
All of the operator padding rules are collected dynamically, therefore adding a new node to this list then executing the `setup` command will result in that MBeautifier will replace the currently added node also.
#### Special rules
These rules are basically switches for certain functionalities of MBeautifier.
The current list of special rules:
- **MaximalNewLines**: Integer value. MBeautifier will remove continuous empty lines. This rule can be used to specify the maximal number of maximal continuous empty lines.
- **AddCommasToMatrices**: [1|0]. Indicates whether the missing element separator commas in matrices should be inserted. For example: `[1 2 3]` will be formatted as `[1, 2, 3]`.
- **AddCommasToCellArrays**: [1|0]. Indicates whether the missing element separator commas in cell arrays should be inserted. For example: `{1 2 3}` will be formatted as `{1, 2, 3}`.
- **MatrixIndexing_ArithmeticOperatorPadding**: [1|0]. Indicates whether the arithmetic operators should be padded by white spaces (using the operator padding rules), when they are used to index matrices. For example: `matrix(end+1) = 1` can be formatted as `matrix(end+1) = 1` when value is set to 0, or as `matrix(end + 1) = 1` if value is set to 1.
- **CellArrayIndexing_ArithmeticOperatorPadding**: [1|0]. Indicates the same as `MatrixIndexing_ArithmeticOperatorPadding` but for cell arrays.
Usage
-----
Currently there are three approaches supported:
- Perform formatting on the currently active page of Matlab Editor. Command: `MBeautify.formatCurrentEditorPage()`. By default the file is not saved, but it remains opened modified in the editor. Optionally the formatted file can be saved using the `MBeautify.formatCurrentEditorPage(true)` syntax.
- Perform formatting on the currently selected text of the active page of Matlab Editor. Command: `MBeautify.formatEditorSelection()`. An optional saving mechanism as above exists also in this case. Useful in case of large files, but in any case `MBeautify.formatCurrentEditorPage()` is suggested.
- Perform formatting on a file. Command: `MBeautify.formatFile(file)`. Can be used with (1)one argument: the input file is formatted and remains open in the Matlab editor unsaved; (2)two arguments as `MBeautify.formatFile(file, outFile)`: the formatted file is saved to the specified output file if possible. Output can be the same as input.
- Perform formatting on several files in a directory. Command: `MBeautify.formatFiles(directory, fileFilter)`. The first argument is an absolute path to a directory, the second one is a wildcard expression (used for `dir` command) to filter files in the target directory. The files will be formatted in-place (overwritten).
Supported Matlab versions
-------------------------
As MBeautifier uses the built-in Matlab Editor functionality, it supports Matlab versions from R2011a.
Planned future versions
-----------------------
As Matlab does not contain any formatter even in R2017 releases, this project will be maintained until at least R2018 (if that release will contain a formatter).
As it is planned at the moment, the current release is the last one which is M-Script based, and the next release is planned to be implemented in Java with Matlab interface. This is the first step to make MBeautifier also usable in Octave.