#86 Allow specification of MATLAB/Octave language

Previously there was a very rough switch --octave. Now there is
a very fine-grained control of the language dialect; but this brings
with it some minor backwards incompatibilities.

In particular:
* the --octave parameter now has a mandatory argument, if you want to
  get to the old behaviour use --octave=latest
* the octave config file entry still works when using "octave: true"
  (but you get a deprecation warning soon). The entry "octave: false"
  is now an error

This should also enable finally fixing #240.

Closes #86
Closes #258

CHANGELOG.md

@@ -20,14 +20,32 @@ Not quite compatible with Octave yet. See #43 [octave support](https://github.co
 
 ### 0.9.35-dev
 
-
+* You can now specify more precise Octave and MATLAB versions. This
+  change is massive, and likely to have subtle bugs. You can now write
+  `octave: "4.4"` or `matlab: "2020b"` in your config files; or specify
+  `--octave=4.4` or `--matlab=2020b` from the command-line. There is
+  also a special `latest` version for both Octave and MATLAB, which is
+  an alias for the latest supported version.
+
+  This is also the first change that introduces backwards
+  incompatibility, specifically:
+  * The command-line option `--octave` no longer works. You need to
+    specify `--octave=latest` to get the same behaviour.
+  * The config setting `octave: true` still works, but is
+    deprecated. It means the same thing as `octave: "latest"`.
+  * The config setting `octave: false` doesn't make sense anymore (and
+    never really did), so it now raises an error.
+
+  As always note that for MATLAB, support should be faily good and
+  accurate. For Octave many things are missing (such as the `end_X`
+  set of keywords). I do plan to improve the situation, but please
+  create tickets for things you need sooner.
 
 ### 0.9.34
 
 * Relaxed docstring recognition: now you can have blank lines (without
   the comment indicator) in your docstring.
 
-
 ### 0.9.33
 
 * Add a new configuration option "indent_function_file_body" for MH

docs/configuration.html

@@ -474,7 +474,7 @@ <h3>STRING</h3>
 
       <h3>INTEGER</h3>
       <div>
-	Grammar: <pre>STRING ::= &lt;non-negative-integer&gt;</pre>
+	Grammar: <pre>INTEGER ::= &lt;non-negative-integer&gt;</pre>
       </div>
     </section>
 
@@ -578,16 +578,32 @@ <h3>Metric configuration</h3>
 
       <h3>Language dialect</h3>
       <div>
-	Grammar: <pre>DIALECT ::= octave ':' BOOLEAN</pre>
+	Grammar:
+<pre>
+DIALECT ::= octave ':' STRING
+          | matlab ':' STRING
+</pre>
       </div>
       <div>
 	This directive controls which language is processed by
-	MISS_HIT. By default we process MATLAB, but if this is set to
-	true we instead process Octave.
+	MISS_HIT. By default we process MATLAB (latest). Note that
+	specifying the dialect option more than once just means the
+	most recent one takes effect, which is the same for any other
+	option.
+      </div>
+      <div>
+        The MATLAB version string can be "latest" or a YEAR[ab]
+        string, such as "2017b". The earliest MATLAB supported is
+        2017b. The latest MATLAB supported is 2022a.
       </div>
       <div>
-	Please note that Octave support is limited right now, but I
-	consider it a medium/long term priority.
+        The OCTAVE version string can be "latest" or a MAJOR.MINOR
+        string, such as "4.4". The earliest Octave supported is
+        4.2. The latest Octave supported is 7.2. Please note that
+        Octave support is extremely limited right now, but I consider
+        it a medium/long term priority. Many features are missing,
+        such as the specific end keywords, the treatment of strings,
+        default arguments, increments, unwind protect, etc.
       </div>
 
       <h3><a name="exclude_dir"></a>Directory exclusion</h3>
@@ -691,7 +707,7 @@ <h4>Future plans</h4>
   </main>
 
   <footer>
-    Content &copy; 2020 Florian Schanda<br>
+    Content &copy; 2020-2022 Florian Schanda<br>
     Style &copy; 2019-2020 Alina Boboc<br>
     MISS_HIT is licensed under the GPLv3
   </footer>

mh_debug_parser

@@ -3,7 +3,7 @@
 ##                                                                          ##
 ##          MATLAB Independent, Small & Safe, High Integrity Tools          ##
 ##                                                                          ##
-##              Copyright (C) 2020, Florian Schanda                         ##
+##              Copyright (C) 2020-2022, Florian Schanda                    ##
 ##                                                                          ##
 ##  This file is part of MISS_HIT.                                          ##
 ##                                                                          ##
@@ -29,6 +29,8 @@
 import os
 import traceback
 
+from miss_hit_core.m_language import (MATLAB_Latest_Language,
+                                      Octave_Latest_Language)
 from miss_hit_core.errors import Message_Handler, Error, ICE
 from miss_hit_core.m_lexer import MATLAB_Lexer, Token_Buffer
 from miss_hit_core.m_parser import MATLAB_Parser
@@ -54,9 +56,11 @@ def sanity_test(mh, filename, show_bt,
     with open(filename, "r") as fd:
         content = fd.read()
     try:
-        lexer = MATLAB_Lexer(mh, content, filename)
         if octave_mode:
-            lexer.set_octave_mode()
+            language = Octave_Latest_Language()
+        else:
+            language = MATLAB_Latest_Language()
+        lexer = MATLAB_Lexer(language, mh, content, filename)
         tbuf = Token_Buffer(lexer, Config())
         parser = MATLAB_Parser(mh,
                                tbuf,

miss_hit/mh_bmc.py

@@ -3,7 +3,7 @@
 ##                                                                          ##
 ##          MATLAB Independent, Small & Safe, High Integrity Tools          ##
 ##                                                                          ##
-##              Copyright (C) 2020, Florian Schanda                         ##
+##              Copyright (C) 2020-2022, Florian Schanda                    ##
 ##                                                                          ##
 ##  This file is part of MISS_HIT.                                          ##
 ##                                                                          ##
@@ -337,12 +337,11 @@ def __init__(self, _):
     @classmethod
     def process_wp(cls, wp):
         # Create lexer
-        lexer = MATLAB_Lexer(wp.mh,
+        lexer = MATLAB_Lexer(wp.cfg.language,
+                             wp.mh,
                              wp.get_content(),
                              wp.filename,
                              wp.blockname)
-        if wp.cfg.octave:
-            lexer.set_octave_mode()
         if not wp.cfg.pragmas:
             lexer.process_pragmas = False
         if len(lexer.text.strip()) == 0:

miss_hit/mh_copyright.py

@@ -3,7 +3,7 @@
 ##                                                                          ##
 ##          MATLAB Independent, Small & Safe, High Integrity Tools          ##
 ##                                                                          ##
-##              Copyright (C) 2021, Florian Schanda                         ##
+##              Copyright (C) 2021-2022, Florian Schanda                    ##
 ##                                                                          ##
 ##  This file is part of MISS_HIT.                                          ##
 ##                                                                          ##
@@ -33,6 +33,7 @@
 from miss_hit_core.m_lexer import MATLAB_Lexer, Token_Buffer
 from miss_hit_core.m_parser import MATLAB_Parser
 from miss_hit_core.m_parse_utils import parse_docstrings
+from miss_hit_core.m_language import Base_Octave_Language
 
 
 def get_primary_entity(options, cfg):
@@ -109,9 +110,11 @@ def process_wp(cls, wp):
         content = wp.get_content()
 
         # Create lexer
-        lexer = MATLAB_Lexer(wp.mh, content, wp.filename, wp.blockname)
-        if wp.cfg.octave:
-            lexer.set_octave_mode()
+        lexer = MATLAB_Lexer(wp.cfg.language,
+                             wp.mh,
+                             content,
+                             wp.filename,
+                             wp.blockname)
         if not wp.cfg.pragmas:  # pragma: no cover
             lexer.process_pragmas = False
 
@@ -284,7 +287,7 @@ def process_wp(cls, wp):
 
                     if wp.options.style == "c_first" or \
                        (wp.options.style == "dynamic" and
-                        not wp.cfg.octave):
+                        not isinstance(wp.cfg.language, Base_Octave_Language)):
                         copy_notice = "(c) Copyright"
                     else:
                         copy_notice = "Copyright (c)"

miss_hit/mh_lint.py

@@ -3,7 +3,7 @@
 ##                                                                          ##
 ##          MATLAB Independent, Small & Safe, High Integrity Tools          ##
 ##                                                                          ##
-##              Copyright (C) 2020-2021, Florian Schanda                    ##
+##              Copyright (C) 2020-2022, Florian Schanda                    ##
 ##                                                                          ##
 ##  This file is part of MISS_HIT.                                          ##
 ##                                                                          ##
@@ -166,12 +166,11 @@ def __init__(self, options):
     @classmethod
     def process_wp(cls, wp):
         # Create lexer
-        lexer = MATLAB_Lexer(wp.mh,
+        lexer = MATLAB_Lexer(wp.cfg.language,
+                             wp.mh,
                              wp.get_content(),
                              wp.filename,
                              wp.blockname)
-        if wp.cfg.octave:
-            lexer.set_octave_mode()
         if not wp.cfg.pragmas:
             lexer.process_pragmas = False
         if len(lexer.text.strip()) == 0:

miss_hit/mh_trace.py

@@ -3,7 +3,7 @@
 ##                                                                          ##
 ##          MATLAB Independent, Small & Safe, High Integrity Tools          ##
 ##                                                                          ##
-##              Copyright (C) 2021, Florian Schanda                         ##
+##              Copyright (C) 2021-2022, Florian Schanda                    ##
 ##                                                                          ##
 ##  This file is part of MISS_HIT.                                          ##
 ##                                                                          ##
@@ -156,12 +156,11 @@ def __init__(self, options):
     @classmethod
     def process_wp(cls, wp):
         # Create lexer
-        lexer = MATLAB_Lexer(wp.mh,
+        lexer = MATLAB_Lexer(wp.cfg.language,
+                             wp.mh,
                              wp.get_content(),
                              wp.filename,
                              wp.blockname)
-        if wp.cfg.octave:
-            lexer.set_octave_mode()
         if not wp.cfg.pragmas:
             lexer.process_pragmas = False
         if len(lexer.text.strip()) == 0:

miss_hit_core/cfg_ast.py

@@ -3,7 +3,7 @@
 ##                                                                          ##
 ##          MATLAB Independent, Small & Safe, High Integrity Tools          ##
 ##                                                                          ##
-##              Copyright (C) 2020-2021, Florian Schanda                    ##
+##              Copyright (C) 2020-2022, Florian Schanda                    ##
 ##                                                                          ##
 ##  This file is part of MISS_HIT.                                          ##
 ##                                                                          ##
@@ -31,6 +31,7 @@
 from abc import ABCMeta, abstractmethod
 
 from miss_hit_core import pathutil
+from miss_hit_core import m_language
 from miss_hit_core.m_ast import MATLAB_Token
 from miss_hit_core.errors import Location, Message_Handler, ICE
 from miss_hit_core.config import (Config,
@@ -251,25 +252,58 @@ def evaluate(self, mh, config):
         raise ICE("logic error - called evaluate() for project_root")
 
 
-class Octave_Mode(Config_Item):
-    # Toggle octave mode. For now this is just on or off, but in the
-    # future it could be a 'both' mode as well.
-    def __init__(self, enabled):
+class Language_Version(Config_Item):
+    # Specify a language
+    def __init__(self, base, major, minor=None):
         super().__init__()
-        assert isinstance(enabled, bool)
-        self.enabled = enabled
+        assert base in ("matlab", "octave")
+        self.base     = base
+
+        if major == "latest":
+            assert minor is None
+        elif base == "matlab":
+            assert isinstance(major, int) and major >= 2000
+            assert minor in ("a", "b")
+        else:
+            assert isinstance(major, int) and major >= 0
+            assert isinstance(minor, int) and minor >= 0
+
+        self.major    = major
+        self.minor    = minor
+        self.language = None
+
+    def assign_language(self, mh, error_location):
+        try:
+            if self.base == "matlab":
+                self.language = m_language.Base_MATLAB_Language.get_version(
+                    self.major,
+                    self.minor)
+            else:
+                self.language = m_language.Base_Octave_Language.get_version(
+                    self.major,
+                    self.minor)
+        except ValueError as verr:
+            mh.error(error_location, verr.args[0])
 
     def dump(self):
-        if self.enabled:
-            print("  Dialect: Octave")
+        if self.base == "matlab":
+            if self.major == "latest":
+                print("  Language: MATLAB (%s)" % self.language.name)
+            else:
+                print("  Language: MATLAB %u%s (%s)" %
+                      (self.major, self.minor, self.language.name))
         else:
-            print("  Dialect: MATLAB")
+            if self.major == "latest":
+                print("  Language: Octave (%s)" % self.language.name)
+            else:
+                print("  Language: Octave %u.%u (%s)" %
+                      (self.major, self.minor, self.language.name))
 
     def evaluate(self, mh, config):
         assert isinstance(mh, Message_Handler)
         assert isinstance(config, Config)
 
-        config.octave = self.enabled
+        config.language = self.language
 
 
 class Path_List: