$projectname: $title

Command	Purpose 221 \|
\@uid{uid,brief}	starts the definition of a "work artifact" parameter: uid -- the @ref tr-uid "UID" of the "work artifact" parameter: brief -- brief description of the "work artifact" 222 \|
\@uid_litem{title}	adds new line - item in the "work artifact" definition parameter: title -- Title of the line item(e.g., Details) 223 \|
\@uid_bw_trace{brief}	adds the backward trace section in in the "work artifact" definition parameter: brief -- request _Spexygen_ to add the brief item description 224 \|
\@uid_bw_trace	adds the backward trace section in in the "work artifact" definition overloaded version without requesting the brief description 225 \|
\@uid_fw_trace{levels}	adds the forward trace section in in the "work artifact" definition this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "work artifact" optional parameter: levels truncates the displayed recursion levels 226 \|
\@enduid	ends the definition "work artifact" must be placed at the end of "work artifact" definition 227 \|
\@tr{uid}	references the given UID parameter: uid -- the @ref tr-uid "UID" of the "work artifact" 228 \|

Command

Purpose 221 |

\@uid{uid,brief}

starts the definition of a "work artifact"
parameter: uid -- the @ref tr-uid "UID" of the "work artifact"
parameter: brief -- brief description of the "work artifact" 222 |

\@uid_litem{title}

adds new line - item in the "work artifact" definition
parameter: title -- Title of the line item(e.g., Details) 223 |

\@uid_bw_trace{brief}

adds the backward trace section in in the "work artifact" definition
parameter: brief -- request _Spexygen_ to add the brief item description 224 |

\@uid_bw_trace

adds the backward trace section in in the "work artifact" definition
overloaded version without requesting the brief description 225 |

\@uid_fw_trace{levels}

adds the forward trace section in in the "work artifact" definition
this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "work artifact"
optional parameter: levels truncates the displayed recursion levels 226 |

\@enduid

ends the definition "work artifact"
must be placed at the end of "work artifact" definition 227 |

\@tr{uid}

references the given UID
parameter: uid -- the @ref tr-uid "UID" of the "work artifact" 228 |

Command	Purpose 276 \|
\@code_uid{uid,brief }	starts the definition of a "code artifact" parameter: uid --the @ref tr-uid "UID" of the "code artifact" parameter: brief -- brief description of the "code artifact" 277 \|
\@code_litem{item }	adds new line-item in the "code artifact" definition parameter: title --Title of the line item(e.g., Details) 278 \|
\@code_bw_trace{brief}	adds the backward trace section in in the "code artifact" definition parameter: brief -- request _Spexygen_ to add the brief item description 279 \|
\@code_bw_trace	adds the backward trace section in in the "code artifact" definition overloaded version without requesting the brief description 280 \|
\@code_fw_trace{levels}	adds the forward trace section in in the "code artifact" definition this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "code artifact" optional parameter: levels truncates the displayed recursion levels 281 \|
\@endcode_uid	ends the definition "code artifact" must be placed at the end of "code artifact" definition 282 \|
\@tr{uid}	references the given UID parameter: uid -- the @ref tr-uid "UID" of the "code artifact" 283 \|

Command

Purpose 276 |

\@code_uid{uid,brief }

starts the definition of a "code artifact"
parameter: uid --the @ref tr-uid "UID" of the "code artifact"
parameter: brief -- brief description of the "code artifact" 277 |

\@code_litem{item }

adds new line-item in the "code artifact" definition
parameter: title --Title of the line item(e.g., Details) 278 |

\@code_bw_trace{brief}

adds the backward trace section in in the "code artifact" definition
parameter: brief -- request _Spexygen_ to add the brief item description 279 |

\@code_bw_trace

adds the backward trace section in in the "code artifact" definition
overloaded version without requesting the brief description 280 |

\@code_fw_trace{levels}

adds the forward trace section in in the "code artifact" definition
this is a request to _Spexygen_ to __generate__ the recursive @ref tr-fw "forward traceability" for the "code artifact"
optional parameter: levels truncates the displayed recursion levels 281 |

\@endcode_uid

ends the definition "code artifact"
must be placed at the end of "code artifact" definition 282 |

\@tr{uid}

references the given UID
parameter: uid -- the @ref tr-uid "UID" of the "code artifact" 283 |

You can use this online help in various ways: either sequentially from beginning to end or just by quickly locating the interesting topic. 7 |

31 | 32 | 33 |

34 |

35 |

36 |

37 | 38 | 39 |

40 | $projectname 41 | $projectnumber 42 |

43 |

$projectbrief

44 | 45 | 46 | 47 | $searchbox 48 | 49 | 50 |

51 | 52 | 53 | 54 | -------------------------------------------------------------------------------- /spexygen-awesome/spexy-header.tex: -------------------------------------------------------------------------------- 1 | % Latex header for doxygen 1.11.0 2 | % modified by Quantum Leaps on 24-05-17 3 | 4 | % Handle batch mode 5 | $latex_batchmode 6 | 7 | % to overcome problems with too many open files 8 | \let\mypdfximage\pdfximage\def\pdfximage{\immediate\mypdfximage} 9 | 10 | \RequirePackage{iftex} 11 | \ifLuaTeX 12 | \directlua{pdf.setminorversion(7)} 13 | \fi 14 | \ifXeTeX 15 | \special{pdf:minorversion 7} 16 | \fi 17 | \ifPDFTeX 18 | \pdfminorversion=7 19 | \fi 20 | 21 | % Set document class depending on configuration 22 | %%BEGIN COMPACT_LATEX 23 | \documentclass[twoside]{article} 24 | %%END COMPACT_LATEX 25 | %%BEGIN !COMPACT_LATEX 26 | \documentclass[twoside]{book} 27 | %%END !COMPACT_LATEX 28 | 29 | %% moved from doxygen.sty due to workaround for LaTex 2019 version and unmaintained tabu package 30 | \usepackage{ifthen} 31 | \ifx\requestedLaTeXdate\undefined 32 | \usepackage{array} 33 | \else 34 | \usepackage{array}[=2016-10-06] 35 | \fi 36 | %% 37 | \usepackage{geometry} 38 | \usepackage[table]{xcolor} 39 | \usepackage{scrextend} 40 | 41 | % custom colors: 42 | \definecolor{frontbg}{rgb}{0.122, 0.435, 0.698} 43 | \definecolor{frontfg}{rgb}{1, 1, 1} 44 | \definecolor{accent}{rgb}{0.035, 0.411, 0.855} 45 | \definecolor{emph}{rgb}{0.035, 0.411, 0.855} 46 | 47 | % Define your CI: 48 | \newcommand{\copyrightname}{Quantum Leaps, LLC} 49 | \newcommand{\contactdetails}{ 50 | \copyright ~Quantum Leaps, LLC\\ 51 | https://www.state-machine.com\\ 52 | info@state-machine.com\\ 53 | } 54 | 55 | % Packages required by doxygen 56 | \makeatletter 57 | \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion} 58 | % suppress package identification of infwarerr as it contains the word "warning" 59 | \let\@@protected@wlog\protected@wlog 60 | \def\protected@wlog#1{\wlog{package info suppressed}} 61 | \RequirePackage{infwarerr} 62 | \let\protected@wlog\@@protected@wlog 63 | \makeatother 64 | \IfFormatAtLeastTF{2016/01/01}{}{\usepackage{fixltx2e}} % for \textsubscript 65 | \ifPDFTeX 66 | \IfFormatAtLeastTF{2015/01/01}{\pdfsuppresswarningpagegroup=1}{} 67 | \fi 68 | 69 | \usepackage{doxygen} 70 | 71 | $extralatexstylesheet 72 | 73 | \usepackage{graphicx} 74 | \iftutex 75 | \usepackage{fontspec} 76 | \defaultfontfeatures{Ligatures={TeX}} 77 | \usepackage{unicode-math} 78 | \else 79 | \usepackage[utf8]{inputenc} 80 | \fi 81 | \usepackage{makeidx} 82 | \PassOptionsToPackage{warn}{textcomp} 83 | \usepackage{textcomp} 84 | \usepackage[nointegrals]{wasysym} 85 | \usepackage{ifxetex} 86 | 87 | % NLS support packages 88 | $languagesupport 89 | 90 | % Define default fonts 91 | % Font selection 92 | %%BEGIN LATEX_FONTENC 93 | \iftutex 94 | \else 95 | \usepackage[$latexfontenc]{fontenc} 96 | \fi 97 | %%END LATEX_FONTENC 98 | 99 | % set main and monospaced font 100 | $latexfont 101 | 102 | \doxyallsectionsfont{% 103 | \fontseries{bc}\selectfont% 104 | \color{darkgray}% 105 | } 106 | \renewcommand{\DoxyLabelFont}{% 107 | \fontseries{bc}\selectfont% 108 | \color{darkgray}% 109 | } 110 | 111 | % see: https://stackoverflow.com/questions/15230386/howto-disable-hyphenation-for-typewriter-text-in-doxygen 112 | %\newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} 113 | \newcommand{\+}{} 114 | 115 | % Arguments of doxygenemoji: 116 | % 1) '::' form of the emoji, already LaTeX-escaped 117 | % 2) file with the name of the emoji without the .png extension 118 | % in case image exist use this otherwise use the '::' form 119 | \newcommand{\doxygenemoji}[2]{% 120 | \IfFileExists{$latexemojidirectory/#2.png}{\raisebox{-0.1em}{\includegraphics[height=0.9em]{$latexemojidirectory/#2.png}}}{#1}% 121 | } 122 | 123 | % Page & text layout 124 | \usepackage{geometry} 125 | \geometry{% 126 | $papertype,% 127 | top=2.5cm,% 128 | bottom=2.5cm,% 129 | left=2.5cm,% 130 | right=2.5cm% 131 | } 132 | \usepackage{changepage} 133 | 134 | % Allow a bit of overflow to go unnoticed by other means 135 | \tolerance=750 136 | \hfuzz=15pt 137 | \hbadness=750 138 | \setlength{\emergencystretch}{15pt} 139 | \setlength{\parindent}{0cm} 140 | \newcommand{\doxynormalparskip}{\setlength{\parskip}{3ex plus 2ex minus 2ex}} 141 | \newcommand{\doxytocparskip}{\setlength{\parskip}{1ex plus 0ex minus 0ex}} 142 | \doxynormalparskip 143 | % Redefine paragraph/subparagraph environments, using sectsty fonts 144 | \makeatletter 145 | \renewcommand{\paragraph}{% 146 | \@startsection{paragraph}{4}{0ex}{-1.0ex}{1.0ex}{% 147 | \normalfont\normalsize\bfseries\SS@parafont% 148 | }% 149 | } 150 | \renewcommand{\subparagraph}{% 151 | \@startsection{subparagraph}{5}{0ex}{-1.0ex}{1.0ex}{% 152 | \normalfont\normalsize\bfseries\SS@subparafont% 153 | }% 154 | } 155 | \makeatother 156 | 157 | \makeatletter 158 | \newcommand\hrulefilll{\leavevmode\leaders\hrule\hskip 0pt plus 1filll\kern\z@} 159 | \makeatother 160 | 161 | % Headers & footers 162 | \usepackage{fancyhdr} 163 | \pagestyle{fancyplain} 164 | \renewcommand{\footrulewidth}{0.4pt} 165 | 166 | \fancypagestyle{fancyplain}{ 167 | \fancyhf{} 168 | \fancyhead[LE, RO]{\bfseries\thepage} 169 | \fancyhead[LO]{\bfseries\rightmark} 170 | \fancyhead[RE]{\bfseries\leftmark} 171 | \fancyfoot[LO, RE]{\bfseries\thepage} 172 | \fancyfoot[C]{\bfseries\scriptsize $projectnumber} 173 | } 174 | 175 | \fancypagestyle{plain}{ 176 | \fancyhf{} 177 | \fancyfoot[LO, RE]{\bfseries\thepage} 178 | \fancyfoot[C]{\bfseries\scriptsize $projectnumber} 179 | \renewcommand{\headrulewidth}{0pt} 180 | } 181 | 182 | \pagestyle{fancyplain} 183 | 184 | 185 | %%BEGIN !COMPACT_LATEX 186 | \renewcommand{\chaptermark}[1]{% 187 | \markboth{#1}{}% 188 | } 189 | %%END !COMPACT_LATEX 190 | \renewcommand{\sectionmark}[1]{% 191 | \markright{\thesection\ #1}% 192 | } 193 | 194 | % ToC, LoF, LoT, bibliography, and index 195 | % Indices & bibliography 196 | \usepackage{natbib} 197 | \usepackage[titles]{tocloft} 198 | \setcounter{tocdepth}{3} 199 | \setcounter{secnumdepth}{5} 200 | 201 | % creating indexes 202 | $makeindex 203 | 204 | $extralatexpackages 205 | 206 | $latexspecialformulachars 207 | 208 | %%BEGIN FORMULA_MACROFILE 209 | \input{$formulamacrofile} 210 | %%END FORMULA_MACROFILE 211 | 212 | % Hyperlinks 213 | %%BEGIN PDF_HYPERLINKS 214 | % Hyperlinks (required, but should be loaded last) 215 | \ifPDFTeX 216 | \usepackage[pdftex,pagebackref=true]{hyperref} 217 | \else 218 | \ifXeTeX 219 | \usepackage[xetex,pagebackref=true]{hyperref} 220 | \else 221 | \ifLuaTeX 222 | \usepackage[luatex,pagebackref=true]{hyperref} 223 | \else 224 | \usepackage[ps2pdf,pagebackref=true]{hyperref} 225 | \fi 226 | \fi 227 | \fi 228 | \hypersetup{% 229 | colorlinks=true,% 230 | linkcolor=blue,% 231 | citecolor=blue,% 232 | unicode,% 233 | pdftitle={$projectname},% 234 | pdfsubject={$projectnumber}% 235 | } 236 | 237 | %%END PDF_HYPERLINKS 238 | 239 | % Custom commands used by the header 240 | % Custom commands 241 | \newcommand{\clearemptydoublepage}{% 242 | \newpage{\pagestyle{empty}\cleardoublepage}% 243 | } 244 | 245 | % caption style definition 246 | \usepackage{caption} 247 | \captionsetup{labelsep=space,justification=centering,font={bf},singlelinecheck=off,skip=4pt,position=top} 248 | 249 | 250 | % in page table of contents 251 | \IfFormatAtLeastTF{2023/05/01}{\usepackage[deeplevels]{etoc}}{\usepackage[deeplevels]{etoc_doxygen}} 252 | \etocsettocstyle{\doxytocparskip}{\doxynormalparskip} 253 | \etocsetlevel{subsubsubsection}{4} 254 | \etocsetlevel{subsubsubsubsection}{5} 255 | \etocsetlevel{subsubsubsubsubsection}{6} 256 | \etocsetlevel{subsubsubsubsubsubsection}{7} 257 | \etocsetlevel{paragraph}{8} 258 | \etocsetlevel{subparagraph}{9} 259 | 260 | % prevent numbers overlap the titles in toc 261 | \renewcommand{\numberline}[1]{#1~} 262 | 263 | % End of preamble, now comes the document contents 264 | %===== C O N T E N T S ===== 265 | 266 | \begin{document} 267 | \raggedbottom 268 | \raggedright 269 | 270 | $latexdocumentpre 271 | 272 | % Titlepage & ToC 273 | %%BEGIN PDF_HYPERLINKS 274 | %%BEGIN USE_PDFLATEX 275 | % To avoid duplicate page anchors due to reuse of same numbers for 276 | % the index (be it as roman numbers) 277 | \hypersetup{pageanchor=false, 278 | bookmarksnumbered=true, 279 | pdfencoding=unicode 280 | } 281 | %%END USE_PDFLATEX 282 | %%END PDF_HYPERLINKS 283 | \pagenumbering{alph} 284 | \begin{titlepage} 285 | \pagecolor{frontbg} 286 | \color{frontfg} 287 | \vspace*{5cm} 288 | {\fontsize{40}{40} \selectfont $projectname\\} 289 | \vspace*{1cm} 290 | {\fontsize{30}{30} \selectfont $projectbrief\\} 291 | 292 | \line(1,0){800}\\ 293 | \vspace*{0.3cm} 294 | {\fontsize{20}{20} \selectfont $projectnumber\\} 295 | %%BEGIN LATEX_TIMESTAMP 296 | %%END LATEX_TIMESTAMP 297 | \vspace*{7cm} 298 | \begin{addmargin}[30em]{0em} 299 | \fontsize{12}{14} \selectfont \contactdetails 300 | \end{addmargin} 301 | \end{titlepage} 302 | 303 | \pagecolor{white} 304 | \color{black} 305 | %%BEGIN !COMPACT_LATEX 306 | \clearemptydoublepage 307 | %%END !COMPACT_LATEX 308 | \pagenumbering{roman} 309 | 310 | \tableofcontents 311 | %%BEGIN !COMPACT_LATEX 312 | \clearemptydoublepage 313 | %%END !COMPACT_LATEX 314 | \pagenumbering{arabic} 315 | 316 | %%BEGIN PDF_HYPERLINKS 317 | %%BEGIN USE_PDFLATEX 318 | % re-enable anchors again 319 | \hypersetup{pageanchor=true} 320 | %%END USE_PDFLATEX 321 | %%END PDF_HYPERLINKS 322 | 323 | %--- Begin generated contents --- 324 | 325 | -------------------------------------------------------------------------------- /spexygen.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | 3 | #============================================================================= 4 | # _Spexygen_ - Traceable Specifications Based on doxygen 5 | # Copyright (C) 2024 Quantum Leaps, LLC 6 | # 7 | # SPDX-License-Identifier: MIT 8 | # 9 | # Permission is hereby granted, free of charge, to any person obtaining a copy of 10 | # this software and associated documentation files (the "Software"), to deal in 11 | # the Software without restriction, including without limitation the rights to 12 | # use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 13 | # the Software, and to permit persons to whom the Software is furnished to do so, 14 | # subject to the following conditions: 15 | # 16 | # The above copyright notice and this permission notice shall be included in all 17 | # copies or substantial portions of the Software. 18 | # 19 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 21 | # FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 22 | # COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 23 | # IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 24 | # CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 25 | # 26 | # Contact information: 27 | # 28 | # 29 | #============================================================================= 30 | 31 | ''' 32 | Spexygen is a Doxygen extension for creating traceable technical 33 | specifications, such as: 34 | - traceable requirement specifications 35 | - traceable source code 36 | - traceable tests 37 | - traceable specifications of other kind 38 | ''' 39 | 40 | import sys 41 | import os 42 | import json 43 | 44 | class Spexygen: 45 | ''' 46 | Spexygen class that encapsulates tracing and code generation 47 | ''' 48 | 49 | # public class constants 50 | VERSION = 225 51 | 52 | UID_DOC = 1 53 | UID_CODE = 2 54 | LEVELS = ('', ' ', ' ', ' ', ' ') 55 | _debug = False 56 | 57 | def __init__(self): 58 | # private members 59 | self._uid = None # current UID 60 | self._kind = 0 # current UID-kind 61 | self._fname = '' # current file name (for generating output) 62 | self._lnum = 0 # current linie number (for generating output) 63 | self._file = None # current file (for generating output) 64 | self._prefix = '' # prefix for each generated line 65 | self._bw_trace = '' # bw-trace for current uid requested 66 | self._uid_trace_dict = {} # UID dictionary collected during tracing 67 | self._uid_brief_dict = {} # UID-brief dictionary collected during tracing 68 | self._uid_traced_list = [] # UID list built during generation 69 | self._fw_trace_levels = len(Spexygen.LEVELS) - 2 # number of fw-trace levels to generate 70 | 71 | @staticmethod 72 | def debug(*args, **kwargs): 73 | '''debug output (if requesed in command-line parameters) 74 | ''' 75 | if Spexygen._debug: 76 | print(*args, **kwargs) 77 | 78 | 79 | def on_file_pattern(self, fname): 80 | '''return True if file-name is recognizable to Spexygen 81 | ''' 82 | return fname.endswith('.dox') or \ 83 | fname.endswith('.h') or fname.endswith('.c') or \ 84 | fname.endswith('.hpp') or fname.endswith('.cpp') or \ 85 | fname.endswith('.py') or fname.endswith('.lnt') 86 | 87 | def on_gen_fw_trace(self, uid_in, level): 88 | '''recursively generate the forward trace for a "uid" 89 | ''' 90 | self._uid_traced_list.append(uid_in) 91 | Spexygen.debug(" level=", level, "uid=", uid_in, 92 | "self._uid_traced_list:", self._uid_traced_list) 93 | for uid in self._uid_trace_dict.get(uid_in): 94 | if uid not in self._uid_traced_list: 95 | self._file.write("%s%s- @tr{%s}: %s\n" 96 | %(self._prefix, Spexygen.LEVELS[level], 97 | uid, self._uid_brief_dict[uid])) 98 | if level < self._fw_trace_levels: 99 | if uid in self._uid_trace_dict: 100 | self.on_gen_fw_trace(uid, level+1) # recursive! 101 | elif level >= len(Spexygen.LEVELS) - 2: 102 | #self._file.write("%s%s- ...\n" 103 | # %(self._prefix, Spexygen.LEVELS[level+1])) 104 | self._file.write( 105 | f"{self._prefix}{Spexygen.LEVELS[level+1]}- ...\n") 106 | print(f" {self._fname}:{self._lnum} too many"\ 107 | f' forward trace levels for "{uid}"') 108 | 109 | def uid_begin(self, line): 110 | '''set the current uid 'self._uid' and 'self._kind' 111 | if UID found in the given 'line' 112 | ''' 113 | if self._uid != '': 114 | print("Looking for new UID while previous is still active"\ 115 | f" {self._uid}") 116 | kind = Spexygen.UID_DOC 117 | if (i := line.find('@uid{')) >= 0: 118 | l = 5 119 | elif (i := line.find('@code_uid{')) >= 0: 120 | kind = Spexygen.UID_CODE 121 | l = 10 122 | elif (i := line.find('@code_alias{')) >= 0: 123 | kind = Spexygen.UID_CODE 124 | l = 12 125 | else: 126 | return 127 | 128 | j = line.find(',', i + l) 129 | if j < 0: 130 | print("Error: missing ',' in UID definition", 131 | "line", self._lnum, ":", i) 132 | return 133 | 134 | k = line.find('}', j + 1) 135 | if k < 0: 136 | print("Error: missing '}' in UID definition", 137 | "line", self._lnum, ":", i) 138 | return 139 | 140 | self._kind = kind 141 | self._uid = line[i + l:j].strip() 142 | brief = line[j + 1:k].strip() 143 | self._bw_trace = '' 144 | if self._uid not in self._uid_brief_dict: 145 | self._uid_brief_dict[self._uid] = brief 146 | Spexygen.debug(" uid:", self._uid, brief) 147 | 148 | def uid_end(self, line): 149 | '''return True if UID-end was found in the "line" 150 | ''' 151 | if self._uid == '': 152 | print("Looking for UID-end while no UID active") 153 | return False 154 | 155 | if self._kind == Spexygen.UID_DOC: 156 | if line.find('@enduid') >= 0: 157 | Spexygen.debug(" end:", self._uid) 158 | self._uid = '' 159 | self._bw_trace = '' 160 | return True 161 | elif self._kind == Spexygen.UID_CODE: 162 | if line.find('@endcode_uid') >= 0: 163 | Spexygen.debug(" end:", self._uid) 164 | self._uid = '' 165 | self._bw_trace = '' 166 | return True 167 | else: 168 | print(f"Unknown current UID kind={self._kind}") 169 | 170 | return False 171 | 172 | def uid_bw_trace(self, line): 173 | '''return True if bw-trace placeholder found in "line" 174 | ''' 175 | if self._uid == '': 176 | return False 177 | l = 0 178 | i = -1 179 | if self._kind == Spexygen.UID_DOC: 180 | if (i := line.find('@uid_bw_trace')) >= 0: 181 | l = 13 182 | elif self._kind == Spexygen.UID_CODE: 183 | if (i := line.find('@code_bw_trace')) >= 0: 184 | l = 14 185 | else: 186 | print(f"Unknown current UID kind={self._kind}") 187 | return False 188 | 189 | if i < 0: 190 | return False 191 | 192 | if line.find('{', i+l) == i+l: # parameter present? 193 | j = line.find('}', i+l+1) 194 | if j >= 0: 195 | self._bw_trace = line[i+l+1:j] 196 | else: 197 | print("Error: missing '}' for '@uid_bw_trace{' in line", 198 | self._lnum, ":", i+l+1) 199 | return False 200 | else: 201 | self._bw_trace = 'empty' 202 | return True 203 | 204 | def uid_tr(self, line): 205 | '''return list of backward traces found in a given "line" 206 | ''' 207 | tr_list = [] 208 | i = 0 209 | while (i := line.find('@tr{', i)) >= 0: 210 | j = line.find('}', i + 4) 211 | if j >= 0: 212 | tr = line[i + 4:j] 213 | tr_list.append(tr) 214 | i = j 215 | else: 216 | print("Error: missing '}' for '@tr{' in line", 217 | self._lnum, ":", i) 218 | break 219 | return tr_list 220 | 221 | def trace(self, fname): 222 | '''trace a given file and harvest the traces into the 223 | dictionaries: self._uid_brief_dict and self._uid_trace_dict 224 | ''' 225 | try: 226 | f = open(fname, encoding="utf-8") 227 | except OSError: 228 | print("File not found", fname) 229 | return 230 | with f: 231 | lines = f.readlines() 232 | 233 | print("Tracing:", fname) 234 | self._uid = '' 235 | self._lnum = 0 236 | for line in lines: 237 | self._lnum += 1 238 | if self._uid == '': 239 | self.uid_begin(line) 240 | else: 241 | if self.uid_end(line): 242 | pass 243 | elif self.uid_bw_trace(line): 244 | pass 245 | elif self._bw_trace != '': 246 | tr_list = self.uid_tr(line) 247 | for tr in tr_list: 248 | if not self._uid_trace_dict.get(tr): 249 | self._uid_trace_dict[tr] = [] 250 | if self._uid not in self._uid_trace_dict[tr]: 251 | self._uid_trace_dict[tr].append(self._uid) 252 | Spexygen.debug(tr, '<-', self._uid) 253 | 254 | def gen_bw_trace(self, line): 255 | '''find a bw-trace placeholder 256 | as long as bw-trace found 257 | return True if bw-trace placeholder or "@tr{}" found 258 | ''' 259 | if self.uid_bw_trace(line): 260 | self._file.write(line) 261 | return True 262 | 263 | if self._bw_trace != '': 264 | if (i := line.find('@tr{')) >= 0: 265 | j = line.find('}', i + 4) 266 | tr = '' 267 | if j >= 0: 268 | tr = line[i + 4:j] 269 | else: 270 | print("Error: missing '}' for '@tr{' in line", 271 | self._lnum, ":", i) 272 | self._file.write(line) 273 | return True 274 | if tr in self._uid_brief_dict: 275 | if self._bw_trace == 'brief': 276 | self._file.write(line[:j+1]) 277 | self._file.write(f": {self._uid_brief_dict[tr]}") 278 | self._file.write(line[j+1:]) 279 | else: 280 | self._file.write(line) 281 | else: 282 | print(f' {self._fname}:{self._lnum} '\ 283 | f'"{tr}" undefined in backward trace'\ 284 | f' for UID: "{self._uid}"') 285 | self._file.write(line) 286 | return True 287 | return False 288 | 289 | 290 | def gen_fw_trace(self, line): 291 | '''find a fw-trace placeholder and generate fw-trace 292 | return True if the placeholder found 293 | ''' 294 | l = 0 295 | if (i := line.find('@uid_fw_trace')) >= 0: 296 | l = 13 297 | elif (i := line.find('@code_fw_trace')) >= 0: 298 | l = 14 299 | if i < 0: 300 | return False # placeholder not found 301 | 302 | # parse the optional number of levels parameter 303 | levels = len(Spexygen.LEVELS) - 2 304 | if line.find('{', i+l) == i+l: # parameter present? 305 | j = line.find('}', i+l+1) 306 | if j >= 0: 307 | try: 308 | levels = int(line[i+l+1:j]) 309 | if levels >= 1: 310 | levels -= 1 311 | elif levels > len(Spexygen.LEVELS) - 2: 312 | levels = len(Spexygen.LEVELS) - 2 313 | except ValueError: 314 | print("Error: non-numeric parameter in '@uid_fw_trace{}'") 315 | return False 316 | else: 317 | print("Error: missing '}' for '@uid_fw_trace{' in line", 318 | self._lnum, ":", i+l+1) 319 | return False 320 | self._fw_trace_levels = levels 321 | 322 | self._prefix = line[:i] 323 | self._file.write(line) 324 | if self._uid in self._uid_trace_dict: 325 | self._uid_traced_list = [] 326 | self.on_gen_fw_trace(self._uid, 0) 327 | else: 328 | print(f' {self._fname}:{self._lnum} empty forward trace'\ 329 | f' for UID: "{self._uid}"') 330 | 331 | return True 332 | 333 | def gen(self, gendir, fname): 334 | '''generate a given file, replacing the detected placeholdrs 335 | with information from the dictionaries: 336 | self._uid_brief_dict and self._uid_trace_dict 337 | ''' 338 | try: 339 | f = open(fname, encoding="utf-8") 340 | except OSError: 341 | print("File not found", fname) 342 | return 343 | with f: 344 | lines = f.readlines() 345 | 346 | self._fname = os.path.basename(fname) 347 | fname = gendir + '/' + self._fname 348 | try: 349 | self._file = open(fname, 'w', encoding="utf-8") 350 | except OSError: 351 | print("File cannot be written", fname) 352 | return 353 | with self._file: 354 | print("Generating:", fname) 355 | self._lnum = 0 356 | self._uid = '' 357 | self._bw_trace = '' 358 | for line in lines: 359 | self._lnum += 1 360 | if self._uid == '': # no current item 361 | self._file.write(line) 362 | self.uid_begin(line) 363 | else: # have current item 364 | if self.uid_end(line): 365 | self._file.write(line) 366 | elif self.gen_fw_trace(line): 367 | pass 368 | elif self.gen_bw_trace(line): 369 | pass 370 | else: 371 | self._file.write(line) 372 | 373 | def main(self): 374 | '''main entry point to Spexygen 375 | process command-line arguments and run Spexygen 376 | ''' 377 | print(f"Spexygen: traceable technical documentation system "\ 378 | f"{self.VERSION//100}.{(self.VERSION//10) % 10}."\ 379 | f"{self.VERSION % 10}") 380 | print("Copyright (c) 2005-2024 Quantum Leaps, www.state-machine.com\n") 381 | 382 | # defaults 383 | sfname = 'spex.json' 384 | gendir = 'spex' 385 | spexyinp = 'Spexyinput' 386 | 387 | # process command-line arguments... 388 | argv = sys.argv 389 | argc = len(argv) 390 | arg = 1 # skip the 'Spexygen' argument 391 | 392 | if '-h' in argv or '--help' in argv or '?' in argv \ 393 | or '--version' in argv: 394 | print("Usage: python [-d] spexygen.py [spexyfile]", 395 | "\n(deafult spexyfile: 'spexy.json')") 396 | sys.exit(0) 397 | 398 | if '-d' in argv: 399 | Spexygen._debug = True 400 | argv.remove('-d') 401 | argc -= 1 402 | 403 | if arg < argc: 404 | # is the next argument a test script? 405 | sfname = argv[arg] 406 | 407 | # parse the provided spexyfile as json data 408 | try: 409 | sfile = open(sfname, encoding="utf-8") 410 | except OSError: 411 | print("spexyfile not found:", sfname) 412 | sys.exit(-1) 413 | with sfile: 414 | try: 415 | spex = json.load(sfile) 416 | except ValueError as e: 417 | print("Error in spexyfile:", sfname) 418 | print(e) 419 | sys.exit(-1) 420 | 421 | # perform tracing 422 | key = 'trace' 423 | if key not in spex: 424 | key = 'gen' # no 'trace' section means use 'gen' section 425 | if key not in spex: 426 | print("Spexygen: nothing to do") 427 | return 428 | for path in spex[key]: 429 | if os.path.isfile(path): 430 | if self.on_file_pattern(path): 431 | self.trace(path) 432 | elif os.path.isdir(path): 433 | for fname in os.listdir(path): 434 | if self.on_file_pattern(fname): 435 | self.trace(path + '/' + fname) 436 | else: 437 | print("not exist:", path) 438 | Spexygen.debug("\n_uid_trace_dict", self._uid_trace_dict) 439 | Spexygen.debug("\n_uid_brief_dict", self._uid_brief_dict) 440 | 441 | key = 'gen-dir' 442 | if key in spex: 443 | gendir = spex[key] 444 | if gendir == '': 445 | print("No code generation (empty gen directory)") 446 | return 447 | 448 | key = 'gen-inc' 449 | if key in spex: 450 | spexyinp = spex[key] 451 | 452 | key = 'gen' 453 | geninc = None 454 | if key not in spex: 455 | print("Spexygen: nothing to generate") 456 | return 457 | 458 | if not os.path.exists(gendir): 459 | os.mkdir(gendir) 460 | if spexyinp != '': 461 | try: 462 | geninc = open(gendir + '/' + spexyinp, 'w', 463 | encoding="utf-8") 464 | except OSError: 465 | print("spexyinp cannot be written:", spexyinp) 466 | sys.exit(-1) 467 | if geninc: 468 | geninc.write('INPUT +=') 469 | 470 | # generate documentation 471 | for path in spex[key]: 472 | if os.path.isfile(path): 473 | if self.on_file_pattern(path): 474 | self.gen(gendir, path) 475 | if geninc: 476 | geninc.write(' \\\n' + gendir + '/' 477 | + os.path.basename(path)) 478 | elif os.path.isdir(path): 479 | for fname in os.listdir(path): 480 | if self.on_file_pattern(fname): 481 | self.gen(gendir, path + '/' + fname) 482 | if geninc: 483 | geninc.write(' \\\n' + gendir + '/' 484 | + os.path.basename(fname)) 485 | else: 486 | print("not exist:", path) 487 | 488 | if geninc: 489 | geninc.close() 490 | 491 | #============================================================================= 492 | if __name__ == "__main__": 493 | spx = Spexygen() 494 | spx.main() 495 | --------------------------------------------------------------------------------