2.2.3

Added optional {levels} parameter to @uid_fw_trace

Author: quantum-leaps

Spexyfile

@@ -11,15 +11,15 @@ ALIASES += \
 "uid_bw_trace=<tr><td><b>Backward Traceability</b><br>^^" \
 "uid_bw_trace{1}=<tr><td><b>Backward Traceability</b><br>^^" \
 "uid_fw_trace=<tr><td><b>Forward Traceability</b><br>^^" \
-"uid_fw_trace{1}=<tr><td><b>Forward Traceability</b><br>^^" \
+"uid_fw_trace{1}=<tr><td><b>Forward Traceability (truncated to \1 level(s))</b><br>^^" \
 "enduid=</table>" \
 "code_uid{2}=@brief \2^^" \
 "code_alias{2}=@brief <b>\1</b> : \2^^@anchor \1" \
 "code_litem{1}=^^@par \1^^" \
 "code_bw_trace=^^@par Backward Traceability^^" \
 "code_bw_trace{1}=^^@par Backward Traceability^^" \
 "code_fw_trace=^^@par Forward Traceability^^" \
-"code_fw_trace{1}=^^@par Forward Traceability^^" \
+"code_fw_trace{1}=^^@par Forward Traceability (truncated to \1 level(s))^^" \
 "endcode_uid=" \
 "tr{1}=@ref \1 \"\1\"" \
 "precondition{2}=^^@par Precondition `\1:\2`^^" \

doc/DOC_MAN_SPX.pdf

@@ -6,7 +6,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 PROJECT_NAME           = Spexygen
-PROJECT_NUMBER         = 2.2.2
+PROJECT_NUMBER         = 2.2.3
 PROJECT_BRIEF          = "Reference Manual"
 PROJECT_LOGO           = $(SPEXYGEN)/spexygen-awesome/img/logo_spexygen.webp
 PROJECT_ICON           =

doc/Doxyfile

@@ -6,7 +6,7 @@
 # Configuration options related to the LateX output
 #---------------------------------------------------------------------------
 PROJECT_NAME           = Reference Manual
-PROJECT_BRIEF          = For Spexygen 2.2.2
+PROJECT_BRIEF          = For Spexygen 2.2.3
 PROJECT_NUMBER         = Document: DOC_MAN_SPX
 
 #---------------------------------------------------------------------------

doc/Doxyfile-PDF

@@ -222,7 +222,7 @@ __Work artifacts__ (e.g., requirements) are defined by means of the following _S
 <tr><td><b>\@uid_litem{item}</b> <td>adds new line - item in the "work artifact" definition<br>parameter: <b>title</b> -- Title of the line item(e.g., Details)
 <tr><td><b>\@uid_bw_trace{brief}</b> <td>adds the backward trace section in in the "work artifact" definition<br>parameter: <b>brief</b> -- request _Spexygen_ to add the brief item description
 <tr><td><b>\@uid_bw_trace</b> <td>adds the backward trace section in in the "work artifact" definition<br> overloaded version without requesting the brief description
-<tr><td><b>\@uid_fw_trace</b>  <td>adds the forward trace section in in the "work artifact" definition<br> this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "work artifact"
+<tr><td><b>\@uid_fw_trace{levels}</b> <td>adds the forward trace section in in the "work artifact" definition<br> this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "work artifact" <br>optional parameter: <b>levels</b> truncates the displayed recursion levels
 <tr><td><b>\@enduid</b> <td>ends the definition "work artifact" <br> must be placed at the end of "work artifact" definition
 <tr><td><b>\@tr{uid}</b> <td>references the given UID<br> parameter: <b>uid</b>  -- the @ref tr-uid "UID" of the "work artifact"
 </table>
@@ -238,7 +238,7 @@ The following snippet illustrates how a "work artifact" (a requirement) has been
     Longer description of the requirement
 [4] @uid_bw_trace{brief}
 [5] - @tr{SRS_PRJ_Foo_00}
-[6] @uid_fw_trace
+[6] @uid_fw_trace{2}
 [7] @enduid
 @endverbatim
 
@@ -259,7 +259,7 @@ The whole <b>\@uid{}</b> command must be defined in a single line of text and th
 
 `[6]` the "work artifact" can specify forward traceability by means of the <b>\@uid_fw_trace</b> _Spexygen_ command
 @note
-The <b>\@uid_fw_trace</b> _Spexygen_ command is just a __placeholder__ for _Spexygen_ to generate the forward traceability links at this place.
+The <b>\@uid_fw_trace</b> _Spexygen_ command is just a __placeholder__ for _Spexygen_ to generate the forward traceability links at this place. The optional parameter truncates the number of recursion levels to the specified value.
 
 `[7]` The artifact definition must end with the _Spexygen_ <b>\@enduid</b> command
 
@@ -277,7 +277,7 @@ __Code artifacts__ (e.g., functions, macros, classes) are naturally handled by D
 <tr><td><b>\@code_litem{item }</b> <td>adds new line-item in the "code artifact" definition<br>parameter: <b>title</b> --Title of the line item(e.g., Details)
 <tr><td><b>\@code_bw_trace{brief}</b> <td>adds the backward trace section in in the "code artifact" definition<br>parameter: <b>brief</b> -- request _Spexygen_ to add the brief item description
 <tr><td><b>\@code_bw_trace</b> <td>adds the backward trace section in in the "code artifact" definition<br> overloaded version without requesting the brief description
-<tr><td><b>\@code_fw_trace</b>  <td>adds the forward trace section in in the "code artifact" definition<br> this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "code artifact"
+<tr><td><b>\@code_fw_trace{levels}</b>  <td>adds the forward trace section in in the "code artifact" definition<br> this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "code artifact"<br>optional parameter: <b>levels</b> truncates the displayed recursion levels
 <tr><td><b>\@endcode_uid</b> <td>ends the definition "code artifact" <br> must be placed at the end of "code artifact" definition
 <tr><td><b>\@tr{uid}</b> <td>references the given UID<br> parameter: <b>uid</b> -- the @ref tr-uid "UID" of the "code artifact"
 </table>
@@ -295,7 +295,7 @@ The following snippet illustrates how a "code artifact" (function `free_fun()`)
 
 [3] @code_bw_trace{brief}
 [4] - @tr{SRS_PRJ_Foo_03}
-[5] @code_fw_trace
+[5] @code_fw_trace{3}
 [6] @endcode_uid
     */
 [7] bool Foo_verify_(Foo const* const me);
@@ -316,7 +316,7 @@ The whole <b>\@code_uid{}</b> command must be defined in a single line of text a
 
 `[5]` the "code artifact" can specify forward traceability by means of the <b>\@code_fw_trace</b> _Spexygen_ command
 @note
-The <b>\@code_fw_trace</b> _Spexygen_ command is just a __placeholder__ for _Spexygen_ to generate the forward traceability links at this place.
+The <b>\@code_fw_trace</b> _Spexygen_ command is just a __placeholder__ for _Spexygen_ to generate the forward traceability links at this place. The optional parameter truncates the number of recursion levels to the specified value.
 
 `[6]` The "code artifact" definition must end with the _Spexygen_ <b>\@endcode_uid</b> command
 

doc/main.dox

@@ -7,7 +7,7 @@
 @endif
 
 @ifnot LATEX
-@nav{gen,srs}
+@nav_next{srs}
 <div style="clear:both"></div>
 @endif
 
@@ -47,6 +47,6 @@ Please note the generated _forward-traceability_ and the _backward-traceability_
 
 @ifnot LATEX
 <p></p>
-@nav{gen,srs}
+@nav_next{srs}
 @endif
 */

example/main.dox

@@ -18,29 +18,29 @@ Definitions of formal requirements specifications with _Spexygen_ commands.
 @uid{SRS_EXA_FF_00,My project shall provide a free function foo().}
 @uid_litem{Description}
 Longer description of the requirement
-@uid_fw_trace
+@uid_fw_trace{1}
 @enduid
 
 @uid{SRS_EXA_Foo_00,My project shall provide a class Foo.}
 @uid_litem{Description}
 Longer description of the requirement
-@uid_fw_trace
+@uid_fw_trace{1}
 @enduid
 
 @uid{SRS_EXA_Foo_01,Class Foo shall provide a public attribute x.}
 @uid_litem{Description}
 Longer description of the requirement
 @uid_bw_trace{brief}
 - @tr{SRS_EXA_Foo_00}
-@uid_fw_trace
+@uid_fw_trace{2}
 @enduid
 
 @uid{SRS_EXA_Foo_02,Class Foo shall provide a constructor.}
 @uid_litem{Description}
 Longer description of the requirement
 @uid_bw_trace{brief}
 - @tr{SRS_EXA_Foo_00}
-@uid_fw_trace
+@uid_fw_trace{2}
 @enduid
 
 @uid{SRS_EXA_Foo_03,Class Foo shall provide a verify operation.}

example/srs.dox

@@ -9,7 +9,7 @@
 
 setup(
     name="spexygen",
-    version="2.2.2",
+    version="2.2.3",
     author="Quantum Leaps",
     author_email="[email protected]",
     description="Traceable specifications based on doxygen",

setup.py

@@ -47,7 +47,7 @@ class Spexygen:
     '''
 
     # public class constants
-    VERSION = 222
+    VERSION = 223
 
     UID_DOC  = 1
     UID_CODE = 2
@@ -66,6 +66,7 @@ def __init__(self):
         self._uid_trace_dict = {}  # UID dictionary collected during tracing
         self._uid_brief_dict = {}  # UID-brief dictionary collected during tracing
         self._uid_traced_list = [] # UID list built during generation
+        self._fw_trace_levels = len(Spexygen.LEVELS) - 2 # number of fw-trace levels to generate
 
     @staticmethod
     def debug(*args, **kwargs):
@@ -76,30 +77,32 @@ def debug(*args, **kwargs):
 
 
     def on_file_pattern(self, fname):
-        '''return True if file-name is acceptable for Spexygen
+        '''return True if file-name is recognizable to Spexygen
         '''
         return fname.endswith('.dox') or \
                fname.endswith('.h') or fname.endswith('.c') or \
                fname.endswith('.hpp') or fname.endswith('.cpp') or \
                fname.endswith('.py') or fname.endswith('.lnt')
 
-    def on_gen_fw_trace(self, uid, level):
+    def on_gen_fw_trace(self, uid_in, level):
         '''recursively generate the forward trace for a "uid"
         '''
-        self._uid_traced_list.append(uid)
-        Spexygen.debug("  level=", level, "uid=", uid,
+        self._uid_traced_list.append(uid_in)
+        Spexygen.debug("  level=", level, "uid=", uid_in,
                        "self._uid_traced_list:", self._uid_traced_list)
-        for uid in self._uid_trace_dict.get(uid):
+        for uid in self._uid_trace_dict.get(uid_in):
             if uid not in self._uid_traced_list:
                 self._file.write("%s%s- @tr{%s}: %s\n"
                     %(self._prefix, Spexygen.LEVELS[level],
                     uid, self._uid_brief_dict[uid]))
-                if level < len(Spexygen.LEVELS) - 2:
+                if level < self._fw_trace_levels:
                     if uid in self._uid_trace_dict:
                         self.on_gen_fw_trace(uid, level+1) # recursive!
-                else:
-                    self._file.write("%s%s- ...\n"
-                        %(self._prefix, Spexygen.LEVELS[level+1]))
+                elif level >= len(Spexygen.LEVELS) - 2:
+                    #self._file.write("%s%s- ...\n"
+                    #    %(self._prefix, Spexygen.LEVELS[level+1]))
+                    self._file.write(
+                        f"{self._prefix}{Spexygen.LEVELS[level+1]}- ...\n")
                     print(f"  {self._fname}:{self._lnum} too many"\
                           f' forward trace levels for "{uid}"')
 
@@ -288,11 +291,34 @@ def gen_fw_trace(self, line):
         '''find a fw-trace placeholder and generate fw-trace
         return True if the placeholder found
         '''
-        if (i := line.find('@uid_fw_trace')) < 0:
-            i = line.find('@code_fw_trace')
+        l = 0
+        if (i := line.find('@uid_fw_trace')) >= 0:
+            l = 13
+        elif (i := line.find('@code_fw_trace')) >= 0:
+            l = 14
         if i < 0:
             return False # placeholder not found
 
+        # parse the optional number of levels parameter
+        levels = len(Spexygen.LEVELS) - 2
+        if line.find('{', i+l) == i+l: # parameter present?
+            j = line.find('}', i+l+1)
+            if j >= 0:
+                try:
+                    levels = int(line[i+l+1:j])
+                    if levels >= 1:
+                        levels -= 1
+                    elif levels > len(Spexygen.LEVELS) - 2:
+                        levels = len(Spexygen.LEVELS) - 2
+                except ValueError:
+                    print("Error: non-numeric parameter in '@uid_fw_trace{}'")
+                    return False
+            else:
+                print("Error: missing '}' for '@uid_fw_trace{' in line",
+                        self._lnum, ":", i+l+1)
+                return False
+        self._fw_trace_levels = levels
+
         self._prefix = line[:i]
         self._file.write(line)
         if self._uid in self._uid_trace_dict: