Coverage for src/pyTRLCConverter/rst/text.py: 100%

1"""reStructuredText text helpers. 

2 Provides reStructuredText escaping and inline reStructuredText string builders. 

3 

4 Author: Gabryel Reyes (gabryel.reyes@newtec.de) 

5""" 

6 

7# pyTRLCConverter - A tool to convert TRLC files to specific formats. 

8# Copyright (c) 2024 - 2026 NewTec GmbH 

9# 

10# This file is part of pyTRLCConverter program. 

11# 

12# The pyTRLCConverter program is free software: you can redistribute it and/or modify it under 

13# the terms of the GNU General Public License as published by the Free Software Foundation, 

14# either version 3 of the License, or (at your option) any later version. 

15# 

16# The pyTRLCConverter program is distributed in the hope that it will be useful, but 

17# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 

18# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 

19# 

20# You should have received a copy of the GNU General Public License along with pyTRLCConverter. 

21# If not, see <https://www.gnu.org/licenses/>. 

22 

23# Imports ********************************************************************** 

24 

25# Variables ******************************************************************** 

26 

27# Classes ********************************************************************** 

28 

29 

30class RstText: 

31 """Utility class providing reStructuredText escaping and inline element builders. 

32 """ 

33 

34 @staticmethod 

35 def escape(text: str) -> str: 

36 # lobster-trace: SwRequirements.sw_req_rst_escape 

37 """ 

38 Escapes the text to be used in a reStructuredText document. 

39 

40 Args: 

41 text (str): Text to escape 

42 

43 Returns: 

44 str: Escaped text 

45 """ 

46 characters = ["\\", "`", "*", "_", "{", "}", "[", "]", "<", ">", "(", ")", "#", "+", "-", ".", "!", "|"] 

47 

48 for character in characters: 

49 text = text.replace(character, "\\" + character) 

50 

51 return text 

52 

53 @staticmethod 

54 def link(text: str, target: str, escape: bool = True) -> str: 

55 # lobster-trace: SwRequirements.sw_req_rst_link 

56 """ 

57 Create a reStructuredText cross-reference. 

58 The text will be automatically escaped for reStructuredText if necessary. 

59 There will be no newline appended at the end. 

60 

61 Args: 

62 text (str): Link text 

63 target (str): Cross-reference target 

64 escape (bool): Escapes text (default: True). 

65 

66 Returns: 

67 str: reStructuredText cross-reference 

68 """ 

69 text_raw = text 

70 

71 if escape is True: 

72 text_raw = RstText.escape(text) 

73 

74 return f":ref:`{text_raw} <{target}>`" 

75 

76 @staticmethod 

77 def role(text: str, role: str, escape: bool = True) -> str: 

78 # lobster-trace: SwRequirements.sw_req_rst_role 

79 """ 

80 Create role text in reStructuredText. 

81 The text will be automatically escaped for reStructuredText if necessary. 

82 There will be no newline appended at the end. 

83 

84 Args: 

85 text (str): Text 

86 role (str): Role 

87 escape (bool): Escapes text (default: True). 

88 

89 Returns: 

90 str: Text with role 

91 """ 

92 text_raw = text 

93 

94 if escape is True: 

95 text_raw = RstText.escape(text) 

96 

97 return f":{role}:`{text_raw}`" 

98 

99# Functions ******************************************************************** 

100 

101# Main *************************************************************************