Skip to content

Commit de4820d

Browse files
jonathfjonathf
committed
Lot of documentation of manual content
1 parent cb83bdb commit de4820d

11 files changed

Lines changed: 1423 additions & 1060 deletions

File tree

‎README.md‎

Lines changed: 60 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,17 @@ Matlab2cpp is a semi-automatic tool for converting code from Matlab to C++.
22

33
Note that it is not meant as a complete tool for creating runnable C++ code.
44
For example, the `eval`-function will not be supported because there is no
5-
general way to implement it in C++.
6-
Instead the program is aimed as support tool, which aims at speed up the
7-
conversion process as much as possible for a user that needs to convert Matlab
8-
programs by hand anyway.
9-
The software does this by converting the basic structures of the
10-
Matlab-program (functions, branches, loops, etc.), adds
11-
variable declarations, and for some lower level code, do a complete
12-
translation.
13-
Any problem the program encounters will be written in a log-file.
14-
15-
Currently, the code will not convert the large library collection
16-
of functions that Matlab currently possesses.
17-
However, there is no reason for the code not to support these features in time.
5+
general way to implement it in C++. Instead the program is aimed as a support
6+
tool, which aims at speed up the conversion process as much as possible for
7+
a user that needs to convert Matlab programs by hand anyway. The software does
8+
this by converting the basic structures of the Matlab-program (functions,
9+
branches, loops, etc.), adds variable declarations, and for some simple code, do
10+
a complete translation. Any problem the program encounters will be written in
11+
a log-file.
12+
13+
Currently, the code will not convert the large library collection of functions
14+
that Matlab currently possesses. However, there is no reason for the code not
15+
to support these features in time.
1816

1917
Installation
2018
------------
@@ -38,17 +36,17 @@ Windows:::
3836
> Python setup.py install
3937

4038
The executable mconvert.py can freely be copied or be added to
41-
environmental variables manually (with or without the `.py` extendtion).
39+
environmental variables manually (with or without the `.py` extension).
4240

4341

4442

4543
Example
4644
-------
4745

48-
Assuming Linux installation and ´mconvert´ available in path.
46+
Assuming Linux installation and `mconvert` available in path.
4947
Code works analogous in Mac and Windows.
5048

51-
Consider the following code snippet in the file ´example.m´: ::
49+
Consider a file `example.m` with the following content: ::
5250

5351
function y=f(x)
5452
y = x+4
@@ -58,14 +56,13 @@ Consider the following code snippet in the file ´example.m´: ::
5856
f(x)
5957
end
6058

61-
Run conversion on the file:
59+
Run conversion on the file: ::
6260

6361
$ mconvert example.m
6462

65-
This will create three files: `example.m.cpp`, `example.m.py` and
66-
`example.m.log`.
63+
This will create two files: `example.m.hpp` and `example.m.py`.
6764

68-
In example.m.cpp, the translated C++ code is placed. It looks as
65+
In example.m.hpp, the translated C++ code is placed. It looks as
6966
follows: ::
7067

7168
#include <armadillo>
@@ -85,10 +82,10 @@ follows: ::
8582
f(x) ;
8683
}
8784

88-
Matlab doesn't declare variables explicitly, so
89-
Matlab2cpp is not able to do a complete translation.
90-
To create a full conversion, the variables must be declared.
91-
Declarations can be done in the file `example.m.py`: ::
85+
Matlab doesn't declare variables explicitly, so Matlab2cpp is unable to complete
86+
the translation. To create a full conversion, the variables must be declared.
87+
Declarations can be done in the file `example.m.py`. After the first run, it
88+
will look as follows: ::
9289

9390
# Supplement file
9491
#
@@ -100,49 +97,56 @@ Declarations can be done in the file `example.m.py`: ::
10097
# umat imat fmat mat cx_mat
10198
# ucube icube fcube cube cx_cube
10299
#
103-
# func_lambda
104-
# char
105-
106-
scope = {}
107-
108-
g = scope["g"] = {}
109-
g["y"] = ""
110-
g["x"] = ""
111-
112-
f = scope["f"] = {}
113-
f["y"] = ""
114-
f["x"] = ""
115-
116-
It is then possible to declare variables by inserting type names
117-
into the respective empty strings.
100+
# char string struct structs func_lambda
101+
102+
functions = {
103+
"g" : {
104+
"x" : "",
105+
},
106+
"g" : {
107+
"y" : "",
108+
"x" : "",
109+
},
110+
}
111+
includes = [
112+
'#include <armadillo>',
113+
'using namespace arma ;',
114+
]
118115

119-
However, some times it is possible to guess some of the variable
120-
types from context.
121-
To use suggestions, run conversion with the `-s` flag:
116+
In addition to defining includes at the bottom, it is possible to declare
117+
variables manually by inserting type names into the respective empty strings.
118+
However, some times it is possible to guess some of the variable types from
119+
context. To let the software try to guess variable types, run conversion with
120+
the `-s` flag: ::
122121

123122
$ mconvert example.m -s
124123

125-
The file `example.m.py` will then automatically be filled with
126-
types from context: ::
124+
The file `example.m.py` will then automatically be populated with data types
125+
from context: ::
127126

128127

129128
# ...
130129

131-
scope = {}
132-
133-
g = scope["g"] = {}
134-
g["x"] = "irowvec"
135-
136-
f = scope["f"] = {}
137-
f["y"] = "irowvec"
138-
f["x"] = "irowvec"
130+
functions = {
131+
"g" : {
132+
"x" : "irowvec",
133+
},
134+
"g" : {
135+
"y" : "irowvec",
136+
"x" : "irowvec",
137+
},
138+
}
139+
includes = [
140+
'#include <armadillo>',
141+
'using namespace arma ;',
142+
]
139143

140144
It will not always be sucsessful and some of the types might in
141145
some cases be wrong. It is therefore also possible to adjust these
142-
values at any time.
146+
values manually at any time.
143147

144148
Having run the conversion with the variables converted, creates a
145-
new output for `example.m.cpp`: ::
149+
new output for `example.m.hpp`: ::
146150

147151
#include <armadillo>
148152
using namespace arma ;
@@ -162,5 +166,5 @@ new output for `example.m.cpp`: ::
162166
f(x) ;
163167
}
164168

165-
The file `example.m.log` will contain a list of errors and warnings
166-
created during conversion.
169+
This is valid and runnable C++ code.
170+
For such a small example, no manual adjustments were necesarry.

‎doc/source/index.rst‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,58 @@
1-
1+
==========
22
Matlab2cpp
33
==========
44

55

6-
76
Introduction
87
============
98

109

1110
.. include:: ../../README.md
1211

1312

14-
1513
User interaction
1614
================
1715

16+
.. automodule:: matlab2cpp.__init__
1817

19-
The simplest way to interact with the `Matlab2cpp`-toolbox is to use the
20-
`mconvert` frontend.
21-
As noted in the introduction, the script automatically creates three files with
22-
extensions `.cpp`, `.py` and `.log`.
23-
In the next subsection, the behavior of `mconvert` will be discussed.
24-
In the sections after, the behavior of the `.py` and the `.log`.
2518

2619
.. autoprogram:: mconvert:parser
2720
:prog: mconvert
2821

29-
30-
The supplement configuration (`.py`-file)
31-
-----------------------------------------
22+
Configuring datatypes
23+
---------------------
3224

3325
.. automodule:: matlab2cpp.supplement
3426

27+
Error log
28+
---------
3529

36-
Translation report (`.log`-file)
37-
--------------------------------
38-
39-
.. automodule:: matlab2cpp.translations._error_log
30+
.. automodule:: matlab2cpp.utils
4031

4132

4233
Application programming interface
4334
=================================
4435

36+
.. automodule:: matlab2cpp.treebuilder
37+
38+
qcpp -- Script translation
39+
~~~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
.. autofunction:: matlab2cpp.qcpp
42+
43+
qhpp -- Headers and module
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~
45+
46+
.. autofunction:: matlab2cpp.qcpp
47+
48+
qpy -- Headers and module
49+
~~~~~~~~~~~~~~~~~~~~~~~~~~
50+
51+
.. autofunction:: matlab2cpp.qpy
4552

4653
Building node-tree
4754
------------------
4855

49-
.. automodule:: matlab2cpp.treebuilder
50-
5156
Treebuilder class
5257
~~~~~~~~~~~~~~~~~
5358
.. autoclass:: matlab2cpp.treebuilder.Treebuilder

‎mconvert.py‎

100644100755
Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,12 @@ def create_parser():
1010
parser = argparse.ArgumentParser(
1111
formatter_class=argparse.RawDescriptionHelpFormatter,
1212
description=dedent("""\
13-
The front end of the Matlab2cpp toolbox is the `mconvert` script.
14-
The script takes the following arguments:
13+
The toolbox frontend of the Matlab2cpp library. Use this to try to do automatic
14+
and semi-automatic translation. The program will create files with the same
15+
name as the input, but with various extra extensions. Scripts will receive the
16+
extension `.cpp`, headers and modules `.hpp`. A file containing data type and
17+
header information will be stored in a `.py` file. Any errors will be stored in
18+
`.log`.
1519
"""))
1620

1721
parser.add_argument("filename",

0 commit comments

Comments
 (0)