class ConfigurationSectionDocumentation(TestSuiteSectionDocumentationForSectionWithInstructions):
def __init__(self,
name: str,
instruction_set: SectionInstructionSet):
super().__init__(name, instruction_set)
self._tp = TextParser({
'conf_phase': phase_names.CONFIGURATION,
})
def instructions_section_header(self) -> docs.Text:
return docs.text('Additional instructions')
def instruction_purpose_description(self) -> List[ParagraphItem]:
return []
def contents_description(self) -> docs.SectionContents:
return self._tp.section_contents(_CONTENTS_DESCRIPTION)
def purpose(self) -> Description:
paragraphs = self._tp.fnap(_PURPOSE_REST_TEXT)
paragraphs += test_case_phase_sections.insertion_position_description(self.section_info.name, True)
return Description(self._tp.text(_PURPOSE_SINGLE_LINE_DESCRIPTION_TEXT),
paragraphs)
@property
def see_also_targets(self) -> List[SeeAlsoTarget]:
return [
phase_infos.CONFIGURATION.cross_reference_target
]
class ConfigurationSectionDocumentation(
TestSuiteSectionDocumentationForSectionWithInstructions):
def __init__(self, name: str, instruction_set: SectionInstructionSet):
super().__init__(name, instruction_set)
self._tp = TextParser({
'conf_phase': phase_names.CONFIGURATION,
})
def instructions_section_header(self) -> docs.Text:
return docs.text('Additional instructions')
def instruction_purpose_description(self) -> List[ParagraphItem]:
return []
def contents_description(self) -> docs.SectionContents:
return self._tp.section_contents(_CONTENTS_DESCRIPTION)
def purpose(self) -> Description:
paragraphs = self._tp.fnap(_PURPOSE_REST_TEXT)
paragraphs += test_case_phase_sections.insertion_position_description(
self.section_info.name, True)
return Description(
self._tp.text(_PURPOSE_SINGLE_LINE_DESCRIPTION_TEXT), paragraphs)
@property
def see_also_targets(self) -> List[SeeAlsoTarget]:
return [phase_infos.CONFIGURATION.cross_reference_target]
class _SectionThatIsIdenticalToTestCasePhase(TestSuiteSectionDocumentationBaseForSectionWithoutInstructions):
def __init__(self,
phase_name: str,
contents_is_inserted_before_case_contents: bool):
super().__init__(phase_name)
self._contents_is_inserted_before_case_contents = contents_is_inserted_before_case_contents
self._tp = TextParser({
'phase': self.section_info.name,
})
def contents_description(self) -> SectionContents:
return self._tp.section_contents(_CONTENTS_DESCRIPTION)
def purpose(self) -> Description:
paragraphs = self._tp.fnap(_CORRESPONDENCE_DESCRIPTION)
paragraphs += insertion_position_description(self.section_info.name,
self._contents_is_inserted_before_case_contents)
return Description(self._tp.text(_SINGLE_LINE_DESCRIPTION),
paragraphs)
@property
def see_also_targets(self) -> List[SeeAlsoTarget]:
return [
TestCasePhaseCrossReference(self.name.plain)
]
def path_type_path_rendering() -> SectionItem:
tp = TextParser({
'current_directory_concept': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME),
'symbol_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.singular_name),
'rel_cd_option': formatting.cli_option(file_ref.REL_CWD_OPTION),
'path_type': formatting.keyword(types.PATH_TYPE_INFO.name.singular),
})
return Section(tp.text(_PATH_TYPE_PATH_RENDERING_DESCRIPTION_HEADER),
tp.section_contents(_PATH_TYPE_PATH_RENDERING_DESCRIPTION))
def outcome(
checked_file: str,
expected_file_type: FileType,
) -> SectionContents:
tp = TextParser({
'HARD_ERROR': exit_values.EXECUTION__HARD_ERROR.exit_identifier,
'checked_file': checked_file,
'file_type': TYPE_INFO[expected_file_type].name,
})
return tp.section_contents(_ERROR_WHEN_INVALID_FILE__OUTCOME)
def notes_on_when_to_use_run_instruction() -> SectionContents:
tp = TextParser({
'stdin':
misc_texts.STDIN,
'exit_code':
misc_texts.EXIT_CODE,
'run_program':
formatting.InstructionName(instruction_names.RUN_INSTRUCTION_NAME),
'instruction':
concepts.INSTRUCTION_CONCEPT_INFO.singular_name,
})
return tp.section_contents(_WHEN_TO_USE_RUN)
def path_type_path_rendering() -> SectionItem:
tp = TextParser({
'current_directory_concept': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME),
'symbol_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.singular_name),
'rel_cd_option': formatting.cli_option(path.REL_CWD_OPTION),
'path_type': types.PATH_TYPE_INFO.name,
'external_program': misc_texts.EXTERNAL_PROGRAM,
'os_process': misc_texts.OS_PROCESS_NAME,
'Note': headers.NOTE_LINE_HEADER,
})
return Section(tp.text(_PATH_TYPE_PATH_RENDERING_DESCRIPTION_HEADER),
tp.section_contents(_PATH_TYPE_PATH_RENDERING_DESCRIPTION))
def _builtin(symbol_name: str, relativity: RelOptionType) -> BuiltinSymbol:
tp = TextParser({
'relativity_option':
formatting.cli_argument_option_string(
option_syntax.option_syntax(
relative_path_options.REL_OPTIONS_MAP[relativity]._option_name)
)
})
return BuiltinSymbol(
symbol_name,
ValueType.PATH,
__sdv_of(relativity),
CustomSymbolDocumentation(
SYMBOL_DESCRIPTION.as_single_line_description_str(symbol_name),
tp.section_contents(_DESCRIPTION),
),
)
class TheInstructionDocumentation(InstructionDocumentationWithTextParserBase):
def __init__(self, name: str):
super().__init__(name, {})
self._tp = TextParser({
'stdin':
misc_texts.STDIN,
'atc':
formatting.concept(concepts.ACTION_TO_CHECK_NAME.singular),
'PROGRAM':
syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name,
'run_program_actor':
formatting.entity_(actors.COMMAND_LINE_ACTOR),
'actor':
formatting.concept_(concepts.ACTOR_CONCEPT_INFO),
})
def single_line_description(self) -> str:
return self._tp.format('Sets the contents of {stdin} for the {atc}')
def invokation_variants(self) -> Sequence[InvokationVariant]:
return [
invokation_variant_from_args([
a.Single(a.Multiplicity.MANDATORY,
a.Constant(
instruction_arguments.ASSIGNMENT_OPERATOR)),
syntax_elements.STRING_SOURCE_SYNTAX_ELEMENT.single_mandatory,
]),
]
def notes(self) -> SectionContents:
return self._tp.section_contents(_NOTES)
def see_also_targets(self) -> List[SeeAlsoTarget]:
return cross_reference_id_list([
phase_infos.ACT,
concepts.ACTION_TO_CHECK_CONCEPT_INFO,
actors.COMMAND_LINE_ACTOR,
syntax_elements.STRING_SOURCE_SYNTAX_ELEMENT,
syntax_elements.PROGRAM_SYNTAX_ELEMENT,
])
and for the {run} instruction, e.g.
"""
_STRING_MAIN_DESCRIPTION_REST = """\
Used for arbitrary {plain_string} values, relative file names etc.
"""
_TEXT_PARSER = TextParser({
'run': InstructionName(instruction_names.RUN_INSTRUCTION_NAME),
'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO),
'plain_string': misc_texts.PLAIN_STRING,
})
STRING_DOCUMENTATION = TypeDocumentation(types.STRING_TYPE_INFO,
syntax_elements.STRING_SYNTAX_ELEMENT,
_TEXT_PARSER.section_contents(_STRING_MAIN_DESCRIPTION_REST)
)
LIST_DOCUMENTATION = TypeDocumentation(types.LIST_TYPE_INFO,
syntax_elements.LIST_SYNTAX_ELEMENT,
_TEXT_PARSER.section_contents(_LIST_MAIN_DESCRIPTION_REST)
)
PATH_DOCUMENTATION = TypeDocumentation(types.PATH_TYPE_INFO,
syntax_elements.PATH_SYNTAX_ELEMENT,
SectionContents([],
[
path_type_path_rendering()
]),
[
concepts.TCDS_CONCEPT_INFO.cross_reference_target,
The line separator is not included in the text contents.
{Line_separator_description}
"""
INTEGER_MATCHER_DOCUMENTATION = TypeDocumentation(
types.INTEGER_MATCHER_TYPE_INFO,
syntax_elements.INTEGER_MATCHER_SYNTAX_ELEMENT,
)
LINE_MATCHER_DOCUMENTATION = TypeDocumentation(
types.LINE_MATCHER_TYPE_INFO,
syntax_elements.LINE_MATCHER_SYNTAX_ELEMENT,
_TP.section_contents(_LINE_MATCHER_DESCRIPTION),
)
FILE_MATCHER_DOCUMENTATION = TypeDocumentation(
types.FILE_MATCHER_TYPE_INFO,
syntax_elements.FILE_MATCHER_SYNTAX_ELEMENT,
)
STRING_TRANSFORMER_DOCUMENTATION = TypeDocumentation(
types.STRING_TRANSFORMER_TYPE_INFO,
syntax_elements.STRING_TRANSFORMER_SYNTAX_ELEMENT,
SectionContents.empty(),
(),
)
STRING_MATCHER_DOCUMENTATION = TypeDocumentation(
Used for arbitrary string values, and relative file names.
When used as a relative file name, {POSIX_SYNTAX} should be used.
"""
_TEXT_PARSER = TextParser({
'run': InstructionName(instruction_names.RUN_INSTRUCTION_NAME),
'POSIX_SYNTAX': POSIX_SYNTAX,
'ATC': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO),
})
STRING_DOCUMENTATION = TypeDocumentation(TypeCategory.DATA,
types.STRING_TYPE_INFO,
syntax_elements.STRING_SYNTAX_ELEMENT,
_TEXT_PARSER.section_contents(_STRING_MAIN_DESCRIPTION_REST)
)
LIST_DOCUMENTATION = TypeDocumentation(TypeCategory.DATA,
types.LIST_TYPE_INFO,
syntax_elements.LIST_SYNTAX_ELEMENT,
_TEXT_PARSER.section_contents(_LIST_MAIN_DESCRIPTION_REST)
)
PATH_DOCUMENTATION = TypeDocumentation(TypeCategory.DATA,
types.PATH_TYPE_INFO,
syntax_elements.PATH_SYNTAX_ELEMENT,
SectionContents([],
[
path_type_path_rendering()
]),