def __init__(self):
super().__init__(COMMAND_LINE_ACTOR)
self._tp = TextParser({
'LINE_COMMENT_MARKER':
formatting.string_constant(LINE_COMMENT_MARKER),
'PROGRAM':
syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name,
'STRING_TRANSFORMER':
syntax_elements.STRING_TRANSFORMER_SYNTAX_ELEMENT.singular_name,
'PATH':
syntax_elements.PATH_SYNTAX_ELEMENT.singular_name,
'path':
types.PATH_TYPE_INFO.name,
'executable_file':
formatting.misc_name_with_formatting(misc_texts.EXECUTABLE_FILE),
'relativity':
formatting.misc_name_with_formatting(misc_texts.RELATIVITY),
'stdout':
misc_texts.STDOUT,
'stdin':
misc_texts.STDIN,
'os_process':
misc_texts.OS_PROCESS_NAME,
'setup_phase':
phase_names.SETUP,
})
def description_rest(self) -> Sequence[ParagraphItem]:
tp = TextParser({
'checked_file':
'checked file',
'program_name':
program_info.PROGRAM_NAME,
'plain_string':
misc_texts.PLAIN_STRING,
'TCDS':
concepts.TCDS_CONCEPT_INFO.acronym,
'symbol':
concepts.SYMBOL_CONCEPT_INFO.name,
'builtin_symbol':
all_entity_types.BUILTIN_SYMBOL_ENTITY_TYPE_NAMES.name,
'hds_act_symbol':
tcds_symbols.SYMBOL_HDS_ACT,
'hds_case_symbol':
tcds_symbols.SYMBOL_HDS_CASE,
'hds_symbol_with_replacement_precedence':
HDS_PATH_WITH_REPLACEMENT_PRECEDENCE,
})
prologue = tp.fnap(_PROLOGUE)
epilogue = tp.fnap(_EPILOGUE)
variables_list = [
docs.simple_header_only_list(
map(directory_variable_name_text,
sorted(tcds_symbols.ALL_REPLACED_SYMBOLS)),
docs.lists.ListType.ITEMIZED_LIST)
]
return prologue + variables_list + epilogue
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 FileInterpreterActorDocumentation(ActorDocumentation):
CL_SYNTAX_RENDERER = cli_program_syntax.CommandLineSyntaxRenderer()
ARG_SYNTAX_RENDERER = cli_program_syntax.ArgumentInArgumentDescriptionRenderer()
def __init__(self):
super().__init__(FILE_INTERPRETER_ACTOR)
self._tp = TextParser({
'shell_syntax_concept': formatting.concept_(concepts.SHELL_SYNTAX_CONCEPT_INFO),
'LINE_COMMENT_MARKER': formatting.string_constant(LINE_COMMENT_MARKER),
})
def act_phase_contents(self) -> doc.SectionContents:
return section_contents(self._tp.fnap(_ACT_PHASE_CONTENTS))
def act_phase_contents_syntax(self) -> doc.SectionContents:
documentation = ActPhaseDocumentationSyntax()
initial_paragraphs = self._tp.fnap(SINGLE_LINE_PROGRAM_ACT_PHASE_CONTENTS_SYNTAX_INITIAL_PARAGRAPH)
sub_sections = []
synopsis_section = doc_utils.synopsis_section(
invokation_variants_content(None,
documentation.invokation_variants(),
documentation.syntax_element_descriptions()))
sub_sections.append(synopsis_section)
return doc.SectionContents(initial_paragraphs, sub_sections)
def _see_also_specific(self) -> List[SeeAlsoTarget]:
return [
concepts.SHELL_SYNTAX_CONCEPT_INFO.cross_reference_target,
]
class SimpleProgressSuiteReporterDocumentation(SuiteReporterDocumentation):
def __init__(self):
super().__init__(PROGRESS_REPORTER)
format_map = {
}
self._parser = TextParser(format_map)
def syntax_of_output(self) -> List[ParagraphItem]:
return self._parser.fnap(_SYNTAX_OF_OUTPUT)
def exit_code_description(self) -> List[ParagraphItem]:
return (self._parser.fnap(_EXIT_CODE_DESCRIPTION_PRELUDE) +
[self._exit_value_table(_exit_values_and_descriptions())])
def _exit_value_table(self, exit_value_and_description_list: list) -> ParagraphItem:
def _row(exit_value: ExitValue, description: str) -> List[TableCell]:
return [
cell(paras(str(exit_value.exit_code))),
cell(paras(exit_value_text(exit_value))),
cell(self._parser.fnap(description)),
]
return first_row_is_header_table(
[
[
cell(paras(misc_texts.EXIT_CODE_TITLE)),
cell(paras(misc_texts.EXIT_IDENTIFIER_TITLE)),
cell(paras('When')),
]] +
[_row(exit_value, description) for exit_value, description in exit_value_and_description_list],
' ')
def __init__(self):
super().__init__(syntax_elements.LIST_SYNTAX_ELEMENT)
self._tp = TextParser({
'list_type': types.LIST_TYPE_INFO.name,
'A_ref_to_symbol_w_string_conversion': types.a_ref_to_a_symbol_w_string_conversion__sentence(),
})
def purpose(self) -> DescriptionWithSubSections:
parse = TextParser({
'phase': phase_names.PHASE_NAME_DICTIONARY,
})
return from_simple_description(
Description(self.single_line_description(),
parse.fnap(WHAT_THE_TIMEOUT_APPLIES_TO)))
class SimpleProgressSuiteReporterDocumentation(SuiteReporterDocumentation):
def __init__(self):
super().__init__(PROGRESS_REPORTER)
format_map = {}
self._parser = TextParser(format_map)
def syntax_of_output(self) -> List[ParagraphItem]:
return self._parser.fnap(_SYNTAX_OF_OUTPUT)
def exit_code_description(self) -> List[ParagraphItem]:
return (self._parser.fnap(_EXIT_CODE_DESCRIPTION_PRELUDE) +
[self._exit_value_table(_exit_values_and_descriptions())])
def _exit_value_table(
self, exit_value_and_description_list: list) -> ParagraphItem:
def _row(exit_value: ExitValue, description: str) -> List[TableCell]:
return [
cell(paras(str(exit_value.exit_code))),
cell(paras(exit_value_text(exit_value))),
cell(self._parser.fnap(description)),
]
return first_row_is_header_table([[
cell(paras(misc_texts.EXIT_CODE_TITLE)),
cell(paras(misc_texts.EXIT_IDENTIFIER_TITLE)),
cell(paras('When')),
]] + [
_row(exit_value, description)
for exit_value, description in exit_value_and_description_list
], ' ')
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 __init__(self):
super().__init__(syntax_elements.PATH_SYNTAX_ELEMENT)
self._file_name = instruction_arguments.FILE_NAME_STRING
self._relativity_name = instruction_arguments.RELATIVITY_ARGUMENT
path_type_symbol = 'MY_PATH_SYMBOL'
self._parser = TextParser({
'Note': headers.NOTE_LINE_HEADER,
'RELATIVITY_OPTION': self._relativity_name.name,
'PATH_STRING': self._file_name.name,
'posix_syntax': documentation_text.POSIX_SYNTAX,
'string_type': formatting.keyword(types.STRING_TYPE_INFO.name.singular),
'string_type_plain': types.STRING_TYPE_INFO.name,
'reserved_word': misc_texts.RESERVED_WORD_NAME,
'reserved_word_list_str': ', '.join([formatting.keyword(x) for x in reserved_words.RESERVED_TOKENS]),
'path_type': formatting.keyword(types.PATH_TYPE_INFO.name.singular),
'string_syntax_element': syntax_elements.STRING_SYNTAX_ELEMENT.singular_name,
'cd': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
'symbol': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO),
'SYMBOL_NAME': syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.argument.name,
'define_symbol': formatting.InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME),
'current_directory': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
'REFERENCED_SYMBOL': path_type_symbol,
'SYMBOL_REFERENCE': symbol_reference_syntax_for_name(path_type_symbol),
'def_of_path_symbol': define_symbol.def_syntax_string(ValueType.PATH, path_type_symbol, '...'),
'ref_of_path_symbol': '... ' + str(PurePosixPath(symbol_reference_syntax_for_name(path_type_symbol)) /
'a' / 'path' / 'relative' / 'to' / path_type_symbol),
})
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]
def __init__(self, name: str):
super().__init__(name)
self._tp = TextParser({
'program_name': program_info.PROGRAM_NAME,
'phase': phase_names.PHASE_NAME_DICTIONARY,
'setup': phase_infos.SETUP.name,
'act': phase_infos.ACT.name,
'action_to_check': concepts.ACTION_TO_CHECK_CONCEPT_INFO.name,
'home_directory': formatting.conf_param_(conf_params.HDS_CASE_DIRECTORY_CONF_PARAM_INFO),
'sandbox': formatting.concept_(concepts.SDS_CONCEPT_INFO),
'result_dir': tc_fs.SDS_RESULT_INFO.identifier,
'actor_option': OPTION_FOR_ACTOR,
'actor': concepts.ACTOR_CONCEPT_INFO.name,
'actor_instruction': formatting.InstructionName(ACTOR_INSTRUCTION_NAME),
'default_actor': actors.DEFAULT_ACTOR_SINGLE_LINE_VALUE,
'null_actor': formatting.entity_(actors.NULL_ACTOR),
'os_process': misc_texts.OS_PROCESS_NAME,
'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name,
'stdin_instruction': InstructionName(instruction_names.CONTENTS_OF_STDIN_INSTRUCTION_NAME),
'env_instruction': InstructionName(instruction_names.ENV_VAR_INSTRUCTION_NAME),
'timeout': concepts.TIMEOUT_CONCEPT_INFO.name,
'timeout_default': concepts.TIMEOUT_CONCEPT_INFO.default,
'timeout_instruction': InstructionName(instruction_names.TIMEOUT_INSTRUCTION_NAME),
'conf_param': concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.name,
'env_var': concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.name,
'PROGRAM': syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name,
'stdin': misc_texts.STDIN,
'directive': concepts.DIRECTIVE_CONCEPT_INFO.name,
'including': formatting.keyword(directives.INCLUDING_DIRECTIVE_INFO.singular_name),
})
class _TypeConcept(ConceptDocumentation):
def __init__(self):
super().__init__(concepts.TYPE_CONCEPT_INFO)
self._parser = TextParser({
'type':
concepts.TYPE_CONCEPT_INFO.name,
'program_name':
formatting.program_name(program_info.PROGRAM_NAME),
'string_type':
types.STRING_TYPE_INFO.name,
'instruction':
concepts.INSTRUCTION_CONCEPT_INFO.name,
})
def purpose(self) -> DescriptionWithSubSections:
rest_paragraphs = self._parser.fnap(_REST__BEFORE_CATEGORY_LIST)
rest_paragraphs.append(_types_categories_list(self._parser))
rest_paragraphs += (self._parser.fnap(_REST__AFTER_CATEGORY_LIST))
sub_sections = [
docs.section(self._parser.text('Summary of {type:s}'),
[_types_list()])
]
return DescriptionWithSubSections(
self.single_line_description(),
SectionContents(rest_paragraphs, sub_sections))
def see_also_targets(self) -> List[SeeAlsoTarget]:
return list(
map(lambda type_doc: type_doc.cross_reference_target(),
all_types.all_types()))
class IndividualActorConstructor(ArticleContentsConstructor):
def __init__(self, actor: ActorDocumentation):
self.actor = actor
self.rendering_environment = None
format_map = {
'actor_concept': formatting.concept_(concepts.ACTOR_CONCEPT_INFO),
'act_phase': phase_names.ACT.emphasis,
}
self._parser = TextParser(format_map)
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents:
self.rendering_environment = environment
initial_paragraphs = self._default_reporter_info()
initial_paragraphs.extend(self.actor.main_description_rest())
sub_sections = []
append_sections_if_contents_is_non_empty(
sub_sections,
[(self._parser.format('{act_phase} phase contents'), self.actor.act_phase_contents()),
(self._parser.format('Syntax of {act_phase} phase contents'), self.actor.act_phase_contents_syntax())])
sub_sections += see_also_sections(self.actor.see_also_targets(), environment)
return doc.ArticleContents(docs.paras(self.actor.single_line_description()),
doc.SectionContents(initial_paragraphs,
sub_sections))
def _default_reporter_info(self) -> List[ParagraphItem]:
from exactly_lib.definitions.entity.actors import DEFAULT_ACTOR
if self.actor.singular_name() == DEFAULT_ACTOR.singular_name:
return self._parser.fnap('This is the default {actor_concept}.')
else:
return []
class IndividualActorConstructor(ArticleContentsConstructor):
def __init__(self, actor: ActorDocumentation):
self.actor = actor
self.rendering_environment = None
format_map = {
'actor_concept': formatting.concept_(concepts.ACTOR_CONCEPT_INFO),
'act_phase': phase_names.ACT.emphasis,
}
self._parser = TextParser(format_map)
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents:
self.rendering_environment = environment
initial_paragraphs = self._default_reporter_info()
initial_paragraphs.extend(self.actor.main_description_rest())
sub_sections = []
append_sections_if_contents_is_non_empty(
sub_sections,
[
(self._parser.format('{act_phase} phase contents'), self.actor.act_phase_contents()),
(self._parser.format('Syntax of {act_phase} phase contents'), self.actor.act_phase_contents_syntax()),
(headers.NOTES__HEADER__CAPITALIZED, self.actor.notes()),
]
)
sub_sections += see_also_sections(self.actor.see_also_targets(), environment)
return doc.ArticleContents(docs.paras(self.actor.single_line_description()),
doc.SectionContents(initial_paragraphs,
sub_sections))
def _default_reporter_info(self) -> List[ParagraphItem]:
from exactly_lib.definitions.entity.actors import DEFAULT_ACTOR
if self.actor.singular_name() == DEFAULT_ACTOR.singular_name:
return self._parser.fnap('This is the default {actor_concept}.')
else:
return []
class CommandLineActorDocumentation(ActorDocumentation):
def __init__(self):
super().__init__(COMMAND_LINE_ACTOR)
self._tp = TextParser({
'phase': phase_names.PHASE_NAME_DICTIONARY,
'LINE_COMMENT_MARKER': formatting.string_constant(LINE_COMMENT_MARKER),
})
def act_phase_contents(self) -> doc.SectionContents:
return doc.SectionContents(self._tp.fnap(_ACT_PHASE_CONTENTS))
def act_phase_contents_syntax(self) -> doc.SectionContents:
documentation = ActPhaseDocumentationSyntax()
initial_paragraphs = self._tp.fnap(SINGLE_LINE_PROGRAM_ACT_PHASE_CONTENTS_SYNTAX_INITIAL_PARAGRAPH)
sub_sections = []
synopsis_section = doc_utils.synopsis_section(
invokation_variants_content(None,
documentation.invokation_variants(),
documentation.syntax_element_descriptions()))
sub_sections.append(synopsis_section)
return doc.SectionContents(initial_paragraphs, sub_sections)
def _see_also_specific(self) -> List[SeeAlsoTarget]:
return cross_reference_id_list([
conf_params.HOME_ACT_DIRECTORY_CONF_PARAM_INFO,
concepts.SHELL_SYNTAX_CONCEPT_INFO,
])
def __init__(self):
super().__init__(actors.NULL_ACTOR)
format_map = {
'null': actors.NULL_ACTOR.singular_name,
'actor': ACTOR_CONCEPT_INFO.name.singular,
}
self._parser = TextParser(format_map)
class _TypeConcept(ConceptDocumentation):
def __init__(self):
super().__init__(concepts.TYPE_CONCEPT_INFO)
self._parser = TextParser({
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'data': type_system.DATA_TYPE_CATEGORY_NAME,
'logic': type_system.LOGIC_TYPE_CATEGORY_NAME,
})
def purpose(self) -> DescriptionWithSubSections:
rest_paragraphs = self._parser.fnap(_REST_DESCRIPTION_1)
rest_paragraphs += [
_categories_list(self._list_header('{data} types'),
self._list_header('{logic} types'))
]
rest_paragraphs += self._parser.fnap(_REST_DESCRIPTION_2)
sub_sections = []
return DescriptionWithSubSections(self.single_line_description(),
SectionContents(rest_paragraphs,
sub_sections))
def _list_header(self, template_string: str) -> str:
return self._parser.format(template_string).capitalize()
def see_also_targets(self) -> List[SeeAlsoTarget]:
return list(map(lambda type_doc: type_doc.cross_reference_target(),
all_types.all_types()))
class _HierarchyGenerator:
def __init__(self, suite_help: TestSuiteHelp):
self._suite_help = suite_help
self._tp = TextParser({
'program_name':
formatting.program_name(program_info.PROGRAM_NAME),
'conf_section':
section_names.CONFIGURATION,
'conf_phase':
phase_names.CONFIGURATION,
})
def generator(self, header: str) -> SectionHierarchyGenerator:
return h.hierarchy(header, paragraphs.constant(
self._tp.fnap(_PRELUDE)
), [
h.child('cases-and-sub-suites',
self._cases_and_sub_suites(CASES_AND_SUB_SUITES_HEADER)),
h.child('common-test-case-contents',
self._common_tc_contents(COMMON_CASE_CONTENTS_HEADER)),
h.child(
'additional-test-case-conf',
h.leaf(
ADDITIONAL_TEST_CASE_CONFIG_HEADER,
sections.constant_contents(
docs.section_contents(
self._tp.fnap(_ADDITIONAL_TEST_CASE_CONFIG))))),
])
def _cases_and_sub_suites(self, header: str) -> SectionHierarchyGenerator:
return h.leaf(
header,
sections.constant_contents(
docs.section_contents(
self._cases_and_sub_suites_paragraphs())))
def _common_tc_contents(self, header: str) -> SectionHierarchyGenerator:
return h.leaf(
header,
sections.constant_contents(
docs.section_contents(self._common_tc_contents_paragraphs())))
def _cases_and_sub_suites_paragraphs(self) -> List[ParagraphItem]:
ret_val = self._tp.fnap(_CASES_AND_SUB_SUITES)
ret_val.append(
sections_short_list(
self._suite_help.test_cases_and_sub_suites_sections,
default_section_name=section_names_plain.DEFAULT_SECTION_NAME,
section_concept_name='section'))
return ret_val
def _common_tc_contents_paragraphs(self) -> List[ParagraphItem]:
ret_val = self._tp.fnap(_COMMON_TC_CONTENTS)
ret_val.append(
sections_short_list(
self._suite_help.test_case_phase_sections,
default_section_name=section_names_plain.DEFAULT_SECTION_NAME,
section_concept_name='section'))
return ret_val
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 purpose(self) -> DescriptionWithSubSections:
tp = TextParser({
'reporter_option': formatting.cli_option(OPTION_FOR_REPORTER),
'default_reporter': formatting.entity(reporters.DEFAULT_REPORTER.singular_name),
})
return from_simple_description(
Description(self.single_line_description(),
tp.fnap(_DESCRIPTION_REST)))
def abs_or_rel_path_of_existing(file_type: str, syntax_element: str,
relativity_root: str) -> List[ParagraphItem]:
tp = TextParser({
'file_type': file_type,
'syntax_element': syntax_element,
'relativity_root': relativity_root
})
return tp.fnap(_PATH_DESCRIPTION) + paths_uses_posix_syntax()
def __init__(self, actor: ActorDocumentation):
self.actor = actor
self.rendering_environment = None
format_map = {
'actor_concept': formatting.concept_(concepts.ACTOR_CONCEPT_INFO),
'act_phase': phase_names.ACT.emphasis,
}
self._parser = TextParser(format_map)
def contents_description(self) -> SectionContents:
tp = TextParser({
'default_suite_file_name':
file_names.DEFAULT_SUITE_FILE,
})
return docs.section_contents(
path_contents_description('suite'),
[docs.section('Default suite file', tp.fnap(_DIR_AS_SUITE))])
def __init__(self, name_of_aliased: str):
target_components = (name_of_aliased,
line_matcher_primitives.CONTENTS_MATCHER_NAME,
sm_matcher_options.MATCHES_ARGUMENT)
self._tp = TextParser({
'grep_shortcut_target':
formatting.keyword(' '.join(target_components)),
})
def __init__(self):
super().__init__(directives.INCLUDING_DIRECTIVE_INFO)
self.file_argument = a.Named(
file_inclusion_directive_parser.FILE_ARGUMENT_NAME)
self._tp = TextParser({
'including_directive': self.info.singular_name,
'FILE': self.file_argument.name,
})
def new_grammar(
concept: grammar.Concept,
model: NameWithGenderWithFormatting,
value_type: ValueType,
simple_expressions: Sequence[NameAndValue[grammar.Primitive[
MatcherSdv[MODEL]]]],
model_freezer: Callable[[MODEL], MODEL],
description: Callable[[], SectionContents] = SectionContents.empty
) -> grammar.Grammar[MatcherSdv[MODEL]]:
tp = TextParser({
'model': model,
})
all_simple_expressions = list(simple_expressions) + [
parse_constant.CONSTANT_PRIMITIVE
]
def mk_reference(symbol_name: str) -> MatcherSdv[MODEL]:
return symbol_reference.MatcherReferenceSdv(symbol_name, value_type)
def mk_conjunction(operands: Sequence[MODEL]) -> MODEL:
return combinator_sdvs.Conjunction(operands, model_freezer)
def mk_disjunction(operands: Sequence[MODEL]) -> MODEL:
return combinator_sdvs.Disjunction(operands, model_freezer)
return grammar.Grammar(
concept,
description=description,
mk_reference=mk_reference,
primitives=all_simple_expressions,
prefix_operators=[
NameAndValue(
logic.NOT_OPERATOR_NAME,
grammar.PrefixOperator(
combinator_sdvs.Negation,
OperatorDescriptionFromFunctions(
tp.fnap__fun(_NOT_SED_DESCRIPTION))))
],
infix_operators_in_order_of_increasing_precedence=(
(NameAndValue(
logic.OR_OPERATOR_NAME,
grammar.InfixOperator(
mk_disjunction,
InfixOperatorDescriptionFromFunctions(
tp.fnap__fun(_OR_SED_DESCRIPTION),
operand_evaluation__lazy__left_to_right=True,
))), ),
(NameAndValue(
logic.AND_OPERATOR_NAME,
grammar.InfixOperator(
mk_conjunction,
InfixOperatorDescriptionFromFunctions(
tp.fnap__fun(_AND_SED_DESCRIPTION),
operand_evaluation__lazy__left_to_right=True,
))), ),
),
)
def _what_outcome_depends_on(tp: TextParser) -> ParagraphItem:
items = [
list_item(tp.text(_OUTCOME_DEPENDENCE__STATUS),
tp.fnap(_OUTCOME_DEFAULT_STATUS)),
list_item(tp.text(_OUTCOME_DEPENDENCE__ASSERT_PHASE)),
]
return lists.HeaderContentList(items,
lists.Format(lists.ListType.ORDERED_LIST,
custom_separations=SEPARATION_OF_HEADER_AND_CONTENTS))
class _EnvironmentVariableConcept(ConceptDocumentation):
def __init__(self):
super().__init__(ENVIRONMENT_VARIABLE_CONCEPT_INFO)
self._tp = TextParser({
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'env_vars__plain': self.name().plural,
'env_instruction': InstructionName(instruction_names.ENV_VAR_INSTRUCTION_NAME),
'tcds_concept': formatting.concept_(concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO),
})
def purpose(self) -> DescriptionWithSubSections:
return DescriptionWithSubSections(
self.single_line_description(),
docs.section_contents(
self._tp.fnap(_INITIAL_PARAGRAPHS),
[
docs.section(self._tp.text('Environment variables set by {program_name}'),
self._tp.fnap(_E_SETS_EXTRA_ENV_VARS),
[
self._variables_from_setup(),
self._variables_from_before_assert(),
])
]))
def see_also_targets(self) -> List[SeeAlsoTarget]:
ret_val = name_and_cross_ref.cross_reference_id_list([
concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO,
conf_params.HOME_CASE_DIRECTORY_CONF_PARAM_INFO,
conf_params.HOME_ACT_DIRECTORY_CONF_PARAM_INFO,
])
ret_val += [
phase_infos.SETUP.instruction_cross_reference_target(instruction_names.ENV_VAR_INSTRUCTION_NAME)
]
return ret_val
def _variables_from_setup(self) -> docs.Section:
return _variables_section(phase_names.SETUP,
_variables_list_paragraphs([
self._item(var_name)
for var_name in map(operator.itemgetter(0),
environment_variables.ENVIRONMENT_VARIABLES_SET_BEFORE_ACT)
]))
def _variables_from_before_assert(self) -> docs.Section:
return _variables_section(phase_names.BEFORE_ASSERT,
_variables_list_paragraphs([
self._item(var_name)
for var_name in map(operator.itemgetter(0),
environment_variables.ENVIRONMENT_VARIABLES_SET_AFTER_ACT)
]))
def _item(self, var_name: str) -> lists.HeaderContentListItem:
return docs.list_item(directory_variable_name_text(var_name),
environment_variables.ENVIRONMENT_VARIABLE_DESCRIPTION.as_description_paragraphs(
var_name))
def description_rest(self) -> Sequence[ParagraphItem]:
tp = TextParser({
'STRING_SOURCE':
formatting.syntax_element_(
syntax_elements.STRING_SOURCE_SYNTAX_ELEMENT),
'model':
matcher_model.TEXT_MODEL,
})
return tp.fnap(_DESCRIPTION)
def cd_instruction_section_on_def_instruction() -> List[ParagraphItem]:
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 tp.fnap(_CD_INSTRUCTION_SECTION_ON_DEF_INSTRUCTION)
def def_instruction_rel_cd_description(path_arg_name: str) -> List[ParagraphItem]:
tp = TextParser({
'current_directory_concept': formatting.concept_(
concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
'path_arg': path_arg_name,
'symbol_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.singular_name),
'symbols_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.plural_name),
})
return tp.fnap(_DEF_INSTRUCTION_REL_CD_DESCRIPTION)
def __init__(self):
super().__init__(SOURCE_INTERPRETER_ACTOR)
format_map = {
'phase': phase_names.PHASE_NAME_DICTIONARY,
'actor_option': formatting.cli_option(common_cli_options.OPTION_FOR_ACTOR),
'actor_instruction': formatting.InstructionName(ACTOR_INSTRUCTION_NAME),
'shell_command': formatting.misc_name_with_formatting(misc_texts.SHELL_COMMAND),
}
self._parser = TextParser(format_map)
def cd_instruction_section_on_def_instruction() -> List[ParagraphItem]:
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,
})
return tp.fnap(_CD_INSTRUCTION_SECTION_ON_DEF_INSTRUCTION)
def abs_or_rel_path_of_existing(file_type: str,
syntax_element: str,
relativity_root: str) -> List[ParagraphItem]:
tp = TextParser({
'file_type': file_type,
'syntax_element': syntax_element,
'relativity_root': relativity_root
})
return tp.fnap(_PATH_DESCRIPTION) + paths_uses_posix_syntax()
def __init__(self):
super().__init__(JUNIT_REPORTER)
format_map = {
'EXIT_CODE': str(junit.UNCONDITIONAL_EXIT_CODE),
'test_suite_element': junit.TEST_SUITE_ELEMENT_NAME,
'test_suites_element': junit.TEST_SUITES_ELEMENT_NAME,
'url': JUNIT_XML_SYNTAX_SEE_ALSO_URL_INFO.url,
}
self._parser = TextParser(format_map)
def __init__(self, name: str, instruction_set: SectionInstructionSet):
super().__init__(name, instruction_set)
self._tp = TextParser({
'phase':
phase_names.PHASE_NAME_DICTIONARY,
'CWD':
formatting.concept_(
concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
})
class _HierarchyGenerator:
def __init__(self, suite_help: TestSuiteHelp):
self._suite_help = suite_help
self._tp = TextParser({
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'conf_section': section_names.CONFIGURATION,
'conf_phase': phase_names.CONFIGURATION,
})
def generator(self, header: str) -> SectionHierarchyGenerator:
return h.hierarchy(
header,
paragraphs.constant(self._tp.fnap(_PRELUDE)),
[
h.child('cases-and-sub-suites',
self._cases_and_sub_suites(CASES_AND_SUB_SUITES_HEADER)
),
h.child('common-test-case-contents',
self._common_tc_contents(COMMON_CASE_CONTENTS_HEADER)
),
h.child('additional-test-case-conf',
h.leaf(
ADDITIONAL_TEST_CASE_CONFIG_HEADER,
sections.constant_contents(
docs.section_contents(self._tp.fnap(_ADDITIONAL_TEST_CASE_CONFIG))
))
),
])
def _cases_and_sub_suites(self, header: str) -> SectionHierarchyGenerator:
return h.leaf(
header,
sections.constant_contents(
docs.section_contents(self._cases_and_sub_suites_paragraphs())
)
)
def _common_tc_contents(self, header: str) -> SectionHierarchyGenerator:
return h.leaf(
header,
sections.constant_contents(
docs.section_contents(self._common_tc_contents_paragraphs())
))
def _cases_and_sub_suites_paragraphs(self) -> List[ParagraphItem]:
ret_val = self._tp.fnap(_CASES_AND_SUB_SUITES)
ret_val.append(sections_short_list(self._suite_help.test_cases_and_sub_suites_sections,
default_section_name=section_names_plain.DEFAULT_SECTION_NAME,
section_concept_name='section'))
return ret_val
def _common_tc_contents_paragraphs(self) -> List[ParagraphItem]:
ret_val = self._tp.fnap(_COMMON_TC_CONTENTS)
ret_val.append(sections_short_list(self._suite_help.test_case_phase_sections,
default_section_name=section_names_plain.DEFAULT_SECTION_NAME,
section_concept_name='section'))
return ret_val
def purpose(self) -> DescriptionWithSubSections:
parse = TextParser({
'directive': concepts.DIRECTIVE_CONCEPT_INFO.name,
'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name,
'symbol': concepts.SYMBOL_CONCEPT_INFO.name,
})
contents = parse.fnap(_DESCRIPTION)
return DescriptionWithSubSections(self.single_line_description(),
docs.section_contents(contents))
class _TcdsConcept(ConceptDocumentation):
def __init__(self):
super().__init__(concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO)
self._tp = TextParser({
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'path_type': formatting.entity_(types.PATH_TYPE_INFO)
})
def purpose(self) -> DescriptionWithSubSections:
rest_paragraphs = []
sub_sections = []
rest_paragraphs += self._tp.fnap(_MAIN_DESCRIPTION_REST)
rest_paragraphs += self._dir_structure_list()
rest_paragraphs += self._tp.fnap(_MAIN_DESCRIPTION_LAST)
return DescriptionWithSubSections(self.single_line_description(),
SectionContents(rest_paragraphs, sub_sections))
def see_also_targets(self) -> List[SeeAlsoTarget]:
return [
concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO.cross_reference_target,
concepts.SANDBOX_CONCEPT_INFO.cross_reference_target,
syntax_elements.PATH_SYNTAX_ELEMENT.cross_reference_target,
]
def _dir_structure_list(self) -> List[docs.ParagraphItem]:
items = [
self._dir_structure_item(concept, tc_dir_infos)
for concept, tc_dir_infos in _DIR_STRUCTURES
]
return [
docs.simple_list_with_space_between_elements_and_content(items, lists.ListType.ITEMIZED_LIST)
]
def _dir_structure_item(self,
dir_structure: SingularAndPluralNameAndCrossReferenceId,
tc_dir_infos: List[TcDirInfo],
) -> lists.HeaderContentListItem:
contents = [
docs.para(dir_structure.single_line_description),
self._dirs_list(tc_dir_infos)
]
return docs.list_item(dir_structure.singular_name.capitalize(),
contents)
def _dirs_list(self, tc_dir_infos: List[TcDirInfo]) -> docs.ParagraphItem:
return docs.first_column_is_header_table([
self._dir_row(tc_dir_info)
for tc_dir_info in tc_dir_infos
])
def _dir_row(self, tc_dir_info: TcDirInfo) -> List[docs.TableCell]:
return [
docs.text_cell(tc_dir_info.informative_name),
docs.text_cell(tc_dir_info.single_line_description_str),
]
def run_program_matcher_description(
exe_env: List[ParagraphItem]) -> List[ParagraphItem]:
tp = TextParser({
'program': types.PROGRAM_TYPE_INFO.name,
'PROGRAM': syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name,
'exit_code': misc_texts.EXIT_CODE,
'Note': headers.NOTE_LINE_HEADER,
})
return (tp.fnap(_HEADER) + exe_env +
tp.fnap(TRANSFORMATION_ARE_IGNORED__TMPL))
def purpose(self) -> DescriptionWithSubSections:
parser = TextParser({
'phase': phase_names.PHASE_NAME_DICTIONARY,
'the_concept': formatting.conf_param_(conf_params.HOME_ACT_DIRECTORY_CONF_PARAM_INFO),
'home_dir_env_var': ENV_VAR_HOME_ACT,
'rel_option': formatting.cli_option(REL_HOME_ACT_OPTION)
})
return from_simple_description(
Description(self.single_line_description(),
parser.fnap(_REST_DESCRIPTION)))
def def_instruction_rel_cd_description(path_arg_name: str) -> List[ParagraphItem]:
tp = TextParser({
'current_directory_concept': formatting.concept_(
concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO),
'path_arg': path_arg_name,
'symbol_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.singular_name),
'symbols_concept': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.plural_name),
'Note': headers.NOTE_LINE_HEADER,
})
return tp.fnap(_DEF_INSTRUCTION_REL_CD_DESCRIPTION)
def description_rest(self) -> Sequence[ParagraphItem]:
tp = TextParser({
'program': types.PROGRAM_TYPE_INFO.name,
'PROGRAM': syntax_elements.PROGRAM_SYNTAX_ELEMENT.singular_name,
'stdin': misc_texts.STDIN,
'stdout': misc_texts.STDOUT,
'model': matcher_model.TEXT_MODEL,
})
return tp.fnap(_DESCRIPTION_REST
) + texts.run_outcome__with_ignored_exit_code_option()
def purpose(self) -> DescriptionWithSubSections:
tp = TextParser({
'the_concept': formatting.concept(self.name().singular),
'preprocessor_option': formatting.cli_option(OPTION_FOR_PREPROCESSOR),
'is_a_shell_cmd': misc_texts.IS_A_SHELL_CMD,
'an_exit_code': misc_texts.EXIT_CODE.singular_determined.capitalize(),
})
return from_simple_description(
Description(self.single_line_description(),
tp.fnap(_DESCRIPTION_REST)))
def purpose(self) -> DescriptionWithSubSections:
tp = TextParser({
'reporter_option':
formatting.cli_option(OPTION_FOR_REPORTER),
'default_reporter':
formatting.entity(reporters.DEFAULT_REPORTER.singular_name),
})
return from_simple_description(
Description(self.single_line_description(),
tp.fnap(_DESCRIPTION_REST)))
def _what_outcome_depends_on(tp: TextParser) -> ParagraphItem:
items = [
list_item(tp.text(_OUTCOME_DEPENDENCE__STATUS),
tp.fnap(_OUTCOME_DEFAULT_STATUS)),
list_item(tp.text(_OUTCOME_DEPENDENCE__ASSERT_PHASE)),
]
return lists.HeaderContentList(
items,
lists.Format(lists.ListType.ORDERED_LIST,
custom_separations=SEPARATION_OF_HEADER_AND_CONTENTS))
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 contents_description(self) -> SectionContents:
tp = TextParser({
'default_suite_file_name': file_names.DEFAULT_SUITE_FILE,
})
return docs.section_contents(
file_ref_contents_description('suite'),
[
docs.section('Default suite file',
tp.fnap(_DIR_AS_SUITE))
]
)
def transformation_syntax_element_description(the_tested_file: str) -> SyntaxElementDescription:
text_parser = TextParser({
'the_tested_file': the_tested_file,
'transformer': syntax_elements.STRING_TRANSFORMER_SYNTAX_ELEMENT.singular_name,
})
return cli_argument_syntax_element_description(
instruction_arguments.STRING_TRANSFORMATION_ARGUMENT,
text_parser.fnap(_TRANSFORMATION_DESCRIPTION),
[
InvokationVariant(cl_syntax.arg_syntax(instruction_arguments.TRANSFORMATION_OPTION)),
]
)
def purpose(self) -> DescriptionWithSubSections:
parser = TextParser({
'action_to_check': concepts.ACTION_TO_CHECK_CONCEPT_INFO.name,
'actor': concepts.ACTOR_CONCEPT_INFO.name,
'ATC': concepts.ACTION_TO_CHECK_CONCEPT_INFO.acronym,
'actor_option': formatting.cli_option(common_cli_options.OPTION_FOR_ACTOR),
'actor_instruction': formatting.InstructionName(ACTOR_INSTRUCTION_NAME),
'act': phase_infos.ACT.name,
'phase': PHASE_NAME_DICTIONARY,
'os_process': misc_texts.OS_PROCESS_NAME,
})
return DescriptionWithSubSections(concepts.ACTION_TO_CHECK_CONCEPT_INFO.single_line_description,
docs.section_contents(parser.fnap(_DESCRIPTION)))
def with_replaced_env_vars_help() -> SectionContents:
text_parser = TextParser({
'checked_file': 'checked file',
'program_name': program_info.PROGRAM_NAME,
'home_act_env_var': environment_variables.ENV_VAR_HOME_ACT,
'home_case_env_var': environment_variables.ENV_VAR_HOME_CASE,
'home_env_var_with_replacement_precedence': HOME_ENV_VAR_WITH_REPLACEMENT_PRECEDENCE,
})
prologue = text_parser.fnap(_WITH_REPLACED_TCDS_PATHS_PROLOGUE)
variables_list = [docs.simple_header_only_list(map(directory_variable_name_text,
sorted(environment_variables.ALL_REPLACED_ENV_VARS)),
docs.lists.ListType.ITEMIZED_LIST)]
return SectionContents(prologue + variables_list)
class FileContentsCheckerHelp:
def __init__(self,
instruction_name: str,
checked_file: str,
initial_args_of_invokation_variants: List[a.ArgumentUsage]):
self._checked_file = checked_file
self.instruction_name = instruction_name
self.initial_args_of_invokation_variants = initial_args_of_invokation_variants
self._tp = TextParser({
'checked_file': checked_file,
'contents_matcher': formatting.syntax_element_(syntax_elements.STRING_MATCHER_SYNTAX_ELEMENT),
'action_to_check': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO),
'program_type': formatting.symbol_type_(types.PROGRAM_TYPE_INFO),
})
def invokation_variants__file(self, actual_file: a.Named) -> List[InvokationVariant]:
actual_file_arg = a.Single(a.Multiplicity.MANDATORY,
actual_file)
return [
invokation_variant_from_args(
[actual_file_arg] + file_contents_checker_arguments__non_program(),
self._tp.fnap(_MAIN_INVOKATION__FILE__SYNTAX_DESCRIPTION)),
]
def invokation_variants__stdout_err(self, program_option: a.OptionName) -> List[InvokationVariant]:
return [
invokation_variant_from_args(
file_contents_checker_arguments__non_program(),
self._tp.fnap(_MAIN_INVOKATION__STDOUT_ERR_ACTION_TO_CHECK__SYNTAX_DESCRIPTION)
),
invokation_variant_from_args(
file_contents_checker_arguments__program(program_option),
self._tp.fnap(_MAIN_INVOKATION__STDOUT_ERR_PROGRAM__SYNTAX_DESCRIPTION)
),
]
@staticmethod
def see_also_targets__file() -> List[SeeAlsoTarget]:
return cross_reference_id_list([
syntax_elements.PATH_SYNTAX_ELEMENT,
syntax_elements.STRING_MATCHER_SYNTAX_ELEMENT,
])
@staticmethod
def see_also_targets__std_out_err() -> List[SeeAlsoTarget]:
return cross_reference_id_list([
syntax_elements.STRING_MATCHER_SYNTAX_ELEMENT,
syntax_elements.PROGRAM_SYNTAX_ELEMENT,
concepts.ACTION_TO_CHECK_CONCEPT_INFO,
])
def purpose(self) -> DescriptionWithSubSections:
parse = TextParser({
'action_to_check': formatting.concept_(concepts.ACTION_TO_CHECK_CONCEPT_INFO),
'actor': self.name(),
'actor_option': formatting.cli_option(common_cli_options.OPTION_FOR_ACTOR),
'actor_instruction': formatting.InstructionName(instruction_names.ACTOR_INSTRUCTION_NAME),
'act': phase_infos.ACT.name,
'default_actor': actors.DEFAULT_ACTOR_SINGLE_LINE_VALUE,
'actor_conf_param': formatting.conf_param_(conf_params.ACTOR_CONF_PARAM_INFO),
'conf_param': concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.name,
})
contents = parse.fnap(_AFTER_SINGLE_LINE_DESCRIPTION)
return DescriptionWithSubSections(self.single_line_description(),
docs.section_contents(contents))
def __init__(self,
name: str,
instruction_set: SectionInstructionSet):
super().__init__(name, instruction_set)
self._tp = TextParser({
'conf_phase': phase_names.CONFIGURATION,
})
def __init__(self):
super().__init__(concepts.TYPE_CONCEPT_INFO)
self._parser = TextParser({
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'data': type_system.DATA_TYPE_CATEGORY_NAME,
'logic': type_system.LOGIC_TYPE_CATEGORY_NAME,
})
def __init__(self):
super().__init__(concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO)
self._tp = TextParser({
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'path_type': formatting.entity_(types.PATH_TYPE_INFO)
})
def _act_examples(tp: TextParser) -> sections.SectionConstructor:
return sections.section(
docs.text('Examples'),
sections.constant_contents(
docs.section_contents(tp.fnap(_ACT_EXAMPLES))
)
)
