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 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 SymbolDescription: def __init__(self): self.text_parser = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'hds_case_directory': formatting.conf_param_( conf_params.HDS_CASE_DIRECTORY_CONF_PARAM_INFO), 'hds_act_directory': formatting.concept_(conf_params.HDS_ACT_DIRECTORY_CONF_PARAM_INFO), 'act_sub_dir': sds.SUB_DIRECTORY__ACT, 'tmp_sub_dir': sds.PATH__TMP_USER, 'result_sub_dir': sds.SUB_DIRECTORY__RESULT, 'sandbox': concepts.SDS_CONCEPT_INFO.name, 'conf_param': concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.name, }) self.all_variables_dict = dict(SYMBOLS_SET_BEFORE_ACT + SYMBOLS_SET_AFTER_ACT) def as_single_line_description_str(self, symbol_name: str) -> str: return self.text_parser.format(self.all_variables_dict[symbol_name])
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 EnvironmentVariableDescription: def __init__(self): self.text_parser = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'case_home_directory': formatting.conf_param_(conf_params.HOME_CASE_DIRECTORY_CONF_PARAM_INFO), 'act_home_directory': formatting.concept_(conf_params.HOME_ACT_DIRECTORY_CONF_PARAM_INFO), 'act_sub_dir': sds.SUB_DIRECTORY__ACT, 'tmp_sub_dir': sds.PATH__TMP_USER, 'result_sub_dir': sds.SUB_DIRECTORY__RESULT, 'sandbox': concepts.SANDBOX_CONCEPT_INFO.name, 'conf_param': concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.name, } ) self.all_variables_dict = dict(ENVIRONMENT_VARIABLES_SET_BEFORE_ACT + ENVIRONMENT_VARIABLES_SET_AFTER_ACT) def as_single_line_description_str(self, environment_variable_name: str) -> str: return self.text_parser.format(self.all_variables_dict[environment_variable_name]) def as_description_paragraphs(self, environment_variable_name: str) -> list: return self.text_parser.paragraph_items(self.all_variables_dict[environment_variable_name])
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, ])
class _HdsConcept(ConceptDocumentation): def __init__(self): super().__init__(concepts.HDS_CONCEPT_INFO) self._tp = TextParser({ 'HDS': concepts.HDS_CONCEPT_INFO.acronym, 'hds_concept': formatting.concept_(concepts.HDS_CONCEPT_INFO), 'phase': phase_names.PHASE_NAME_DICTIONARY, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'symbol': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'symbols': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.plural_name), 'conf_params': formatting.concept( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name), 'PATH': syntax_elements.PATH_SYNTAX_ELEMENT.singular_name, 'Note': headers.NOTE_LINE_HEADER, }) def purpose(self) -> DescriptionWithSubSections: sub_sections = [ self._tp.section( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name. capitalize(), _CONFIGURATION_PARAMETER), self._tp.section('Relative paths', _RELATIVITY), self._tp.section( self._tp.format( BUILTIN_SYMBOL_ENTITY_TYPE_NAMES.name.plural.capitalize()), _BUILTIN_SYMBOL), docs.section('Directories', self._directory_listing()), ] return DescriptionWithSubSections( self.single_line_description(), SectionContents(self._tp.fnap(_MAIN_DESCRIPTION_REST), sub_sections)) def see_also_targets(self) -> List[SeeAlsoTarget]: ret_val = [ concepts.TCDS_CONCEPT_INFO.cross_reference_target, concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO. cross_reference_target, concepts.SYMBOL_CONCEPT_INFO.cross_reference_target, types.PATH_TYPE_INFO.cross_reference_target, ] ret_val += [ dir_info.conf_param.cross_reference_target for dir_info in _ALL_DIRECTORIES ] ret_val += [ phase_infos.CONFIGURATION.instruction_cross_reference_target( dir_info.instruction_name) for dir_info in _ALL_DIRECTORIES ] return ret_val def _directory_listing(self) -> List[docs.ParagraphItem]: items = [self._dir_item(d) for d in _ALL_DIRECTORIES] return [docs.simple_list(items, lists.ListType.VARIABLE_LIST)] def _dir_item(self, x: _DirInfo) -> HeaderContentListItem: def prop_row(header: str, value_str_or_text) -> List[docs.TableCell]: return [ docs.text_cell(header), docs.text_cell(value_str_or_text), ] from exactly_lib.tcfs.relative_path_options import REL_HDS_OPTIONS_MAP properties_table = docs.first_column_is_header_table([ prop_row('Default value', x.default_value_description), prop_row( concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.singular_name. capitalize(), x.conf_param.configuration_parameter_name_text), prop_row('Set by instruction', instruction_name_text(x.instruction_name)), prop_row( BUILTIN_SYMBOL_ENTITY_TYPE_NAMES.name.singular.capitalize(), REL_HDS_OPTIONS_MAP[ x.relativity_option_type].directory_symbol_name_text), prop_row( 'Path relativity option', REL_HDS_OPTIONS_MAP[ x.relativity_option_type].option_name_text), ]) paras = [ docs.para(x.conf_param.single_line_description_str), properties_table, ] return docs.list_item(self._tp.text(x.item_name), paras)
(Files and directories that {phase[setup]:syntax} creates are installed into the {cwd}, if no {instruction} options are used to change this.) """ _RESULT_DIR_DESCRIPTION = """\ This directory is initially empty. It is populated when the {phase[act]} phase is executed with the following files (with obvious contents): """ _USR_TMP_DIR_DESCRIPTION = """\ {program_name} does not touch this directory. The test case can use it as a place where it is safe to put temporary files without the risk of name clashes with files from other program. """ _RESULT_DIR_SYMBOL = """\ The value of this {symbol} is the absolute path of this directory (after the {phase[act]} phase has been executed).""" _THE_VAL_OF_THIS_SYMBOL_IS_THE_ABS_PATH_OF_THE_DIRECTORY = _TP.format( 'The value of this {symbol} is the absolute path of this directory.') _INTERNAL_DIRECTORIES = """\ Root directory for files that are reserved for {program_name}. """
def root(header: str) -> generator.SectionHierarchyGenerator: tp = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'conf_param': formatting.concept_(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO), 'tcds_concept': formatting.concept_(concepts.TCDS_CONCEPT_INFO), 'TCDS': concepts.TCDS_CONCEPT_INFO.acronym, 'SDS': concepts.SDS_CONCEPT_INFO.acronym, 'sds_concept': formatting.concept_(concepts.SDS_CONCEPT_INFO), 'Sds_concept_header': concepts.SDS_CONCEPT_INFO.singular_name.capitalize(), 'sds_single_line_description': concepts.SDS_CONCEPT_INFO.single_line_description_str.capitalize(), 'HDS': concepts.HDS_CONCEPT_INFO.acronym, 'hds_concept': formatting.concept_(concepts.HDS_CONCEPT_INFO), 'Hds_concept_header': concepts.HDS_CONCEPT_INFO.singular_name.capitalize(), 'hds_single_line_description': concepts.HDS_CONCEPT_INFO.single_line_description_str.capitalize(), 'conf_phase': phase_names.CONFIGURATION, 'act_phase': phase_names.ACT, 'act_hds_conf_param': formatting.conf_param(test_case_file_structure.HDS_ACT_INFO.identifier), 'path_type': types.PATH_TYPE_INFO.name, 'symbol_concept': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME), 'os_process': misc_texts.OS_PROCESS_NAME, 'env_var': concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.name, 'timeout': concepts.TIMEOUT_CONCEPT_INFO.name, 'timeout_instruction': InstructionName(instruction_names.TIMEOUT_INSTRUCTION_NAME), 'type': concepts.TYPE_CONCEPT_INFO.name, 'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name, 'relativity': formatting.concept(misc_texts.RELATIVITY.singular), 'relativities': formatting.concept(misc_texts.RELATIVITY.plural), 'cd': formatting.emphasis(instruction_names.CHANGE_DIR_INSTRUCTION_NAME), 'env': formatting.emphasis(instruction_names.ENV_VAR_INSTRUCTION_NAME), 'CD': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), }) def const_paragraphs_child(local_target_name: str, header_: str, paragraphs_: List[ParagraphItem]) -> generator.SectionHierarchyGenerator: return h.child(local_target_name, h.leaf(header_, sections.constant_contents(section_contents(paragraphs_))) ) return h.hierarchy( header, children=[ h.child_hierarchy( 'dir-structure', 'Directory structure and Current directory', paragraphs.constant(tp.fnap(_DS_CD_PREAMBLE)), [ const_paragraphs_child( 'sds', concepts.SDS_CONCEPT_INFO.singular_name.capitalize() + ' and Current directory', tp.fnap(_SDS_AND_CD) ), const_paragraphs_child( 'hds', concepts.HDS_CONCEPT_INFO.singular_name.capitalize(), tp.fnap(_HDS), ), const_paragraphs_child( 'file-ref', 'File references', tp.fnap(_FILE_REFERENCES) ), h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_dir_struct_see_also_targets()) )), ] ), h.child_hierarchy( 'symbols', concepts.SYMBOL_CONCEPT_INFO.plural_name.capitalize(), paragraphs.constant(tp.fnap(_SYMBOLS)), [ h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_symbols_see_also_targets()) )) ] ), h.child_hierarchy( 'os-proc', tp.text(misc_texts.OS_PROCESS_ENVIRONMENT_SECTION_HEADER), paragraphs.constant(tp.fnap(_OS_PROC_INTRO)), [ const_paragraphs_child( 'cd', 'Current directory', tp.fnap(_OS_PROC_CURRENT_DIRECTORY), ), const_paragraphs_child( 'env-vars', tp.format('{env_var:s/u}'), environment_variable.common_description(), ), const_paragraphs_child( 'timeout', 'Timeout', tp.fnap(_OS_PROC_TIMEOUT), ), h.leaf_not_in_toc( see_also.SEE_ALSO_TITLE, see_also.SeeAlsoSectionContentsConstructor( see_also.items_of_targets(_os_process_see_also_targets()) ) ), ], ), ] )
class _HdsConcept(ConceptDocumentation): def __init__(self): super().__init__(concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO) self._tp = TextParser({ 'HDS': formatting.concept_(concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO), 'phase': phase_names.PHASE_NAME_DICTIONARY, 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'symbol': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'symbols': formatting.concept(concepts.SYMBOL_CONCEPT_INFO.plural_name), 'conf_params': formatting.concept(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name), 'PATH': syntax_elements.PATH_SYNTAX_ELEMENT.singular_name, }) def purpose(self) -> DescriptionWithSubSections: rest_paragraphs = [] rest_paragraphs += self._tp.fnap(_MAIN_DESCRIPTION_REST) rest_paragraphs += self._directory_listing() sub_sections = [ self._section(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.singular_name.capitalize(), _CONFIGURATION_PARAMETER), self._section('Relative paths', _RELATIVITY), self._section(self._tp.format('Builtin {symbols} and environment variables'), _BUILTIN_SYMBOL_ENVIRONMENT_VARIABLE), ] return DescriptionWithSubSections(self.single_line_description(), SectionContents(rest_paragraphs, sub_sections)) def _section(self, header: str, text_to_format: str) -> docs.Section: return docs.section(header, self._tp.fnap(text_to_format)) def see_also_targets(self) -> List[SeeAlsoTarget]: ret_val = [ concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO.cross_reference_target, concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.cross_reference_target, types.PATH_TYPE_INFO.cross_reference_target, ] ret_val += [ dir_info.conf_param.cross_reference_target for dir_info in _ALL_DIRECTORIES ] ret_val += [ phase_infos.CONFIGURATION.instruction_cross_reference_target(dir_info.instruction_name) for dir_info in _ALL_DIRECTORIES ] return ret_val def _directory_listing(self) -> List[docs.ParagraphItem]: items = [ self._dir_item(d) for d in _ALL_DIRECTORIES ] return [ docs.simple_list(items, lists.ListType.VARIABLE_LIST) ] def _dir_item(self, x: _DirInfo) -> HeaderContentListItem: def prop_row(header: str, value_str_or_text) -> List[docs.TableCell]: return [docs.text_cell(header), docs.text_cell(value_str_or_text), ] from exactly_lib.test_case_file_structure.relative_path_options import REL_HOME_OPTIONS_MAP properties_table = docs.first_column_is_header_table( [ prop_row('Default value', x.default_value_description), prop_row(concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.singular_name.capitalize(), x.conf_param.configuration_parameter_name_text), prop_row('Set by instruction', instruction_name_text(x.instruction_name)), prop_row('Variable name', REL_HOME_OPTIONS_MAP[x.relativity_option_type].directory_variable_name_text), prop_row('Relativity option', REL_HOME_OPTIONS_MAP[x.relativity_option_type].option_name_text), ] ) paras = [ docs.para(x.conf_param.single_line_description_str), properties_table, ] return docs.list_item(self._tp.text(x.item_name), paras)
class _SandboxConcept(ConceptDocumentation): def __init__(self): super().__init__(concepts.SANDBOX_CONCEPT_INFO) self._tp = TextParser({ 'program_name': formatting.program_name(program_info.PROGRAM_NAME), 'phase': phase_names.PHASE_NAME_DICTIONARY, 'instruction': AnyInstructionNameDictionary(), 'cwd': formatting.concept_(concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO), 'cd_instruction': InstructionName(CHANGE_DIR_INSTRUCTION_NAME), 'keep_sandbox_option': formatting.cli_option(command_line_options.OPTION_FOR_KEEPING_SANDBOX_DIRECTORY), }) def purpose(self) -> DescriptionWithSubSections: rest_paragraphs = [] sub_sections = [] rest_paragraphs += self._tp.fnap(_SANDBOX_PRE_DIRECTORY_TREE) sub_sections.append(directory_structure_list_section(sds.execution_directories)) sub_sections += self._sandbox_directories_info_sections() return DescriptionWithSubSections(self.single_line_description(), SectionContents(rest_paragraphs, sub_sections)) def see_also_targets(self) -> List[SeeAlsoTarget]: return [ concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO.cross_reference_target, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO.cross_reference_target, concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.cross_reference_target, types.PATH_TYPE_INFO.cross_reference_target, phase_infos.SETUP.instruction_cross_reference_target(CHANGE_DIR_INSTRUCTION_NAME), PredefinedHelpContentsPartReference(HelpPredefinedContentsPart.TEST_CASE_CLI), SeeAlsoUrlInfo('Platform dependent location of sandbox', 'https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir') ] def _sandbox_directories_info_sections(self) -> List[docs.SectionItem]: def section(directory_name: str, dir_info: tcds.TcDirInfo, paragraph_items: List[ParagraphItem]) -> Section: return docs.section(dir_name_text(directory_name), docs.paras(dir_info.single_line_description_str + '.') + paragraph_items) return [ section(sds.SUB_DIRECTORY__ACT, tcds.SDS_ACT_INFO, self._act_dir_description_paragraphs()), section(sds.SUB_DIRECTORY__RESULT, tcds.SDS_RESULT_INFO, self._result_dir_description_paragraphs()), section(sds.PATH__TMP_USER, tcds.SDS_TMP_INFO, self._tmp_user_dir_description_paragraphs()), docs.section(dir_name_text(sds.SUB_DIRECTORY__INTERNAL), self._internal_dir_description_paragraphs()) ] def _act_dir_description_paragraphs(self) -> List[ParagraphItem]: rel_opt_info = REL_SDS_OPTIONS_MAP[RelSdsOptionType.REL_ACT] ret_val = [] ret_val += self._tp.fnap(_ACT_DIR_DESCRIPTION) ret_val += _dir_env_variables_and_rel_options(env_var_name=rel_opt_info.directory_variable_name_text, rel_option=rel_opt_info.option_name_text) return ret_val def _result_dir_description_paragraphs(self) -> List[ParagraphItem]: ret_val = [] ret_val += self._tp.fnap(_RESULT_DIR_DESCRIPTION) ret_val.append(docs.simple_header_only_list(map(file_name_text, sds.RESULT_FILE_ALL), lists.ListType.ITEMIZED_LIST)) ret_val += self._result_dir_env_variable_and_rel_option() return ret_val def _tmp_user_dir_description_paragraphs(self) -> List[ParagraphItem]: rel_opt_info = REL_SDS_OPTIONS_MAP[RelSdsOptionType.REL_TMP] ret_val = [] ret_val += self._tp.fnap(_USR_TMP_DIR_DESCRIPTION) ret_val += _dir_env_variables_and_rel_options(env_var_name=rel_opt_info.directory_variable_name_text, rel_option=rel_opt_info.option_name_text) return ret_val def _result_dir_env_variable_and_rel_option(self) -> List[ParagraphItem]: rel_opt_info = REL_SDS_OPTIONS_MAP[RelSdsOptionType.REL_RESULT] return [_dir_info_items_table(rel_opt_info.directory_variable_name_text, rel_opt_info.option_name_text, self._tp.format(_RESULT_DIR_ENV_VARIABLE)) ] def _internal_dir_description_paragraphs(self) -> List[ParagraphItem]: return self._tp.fnap(_INTERNAL_DIRECTORIES)
class _Documentation(SyntaxElementDocumentation): def __init__(self): super().__init__(TypeCategory.DATA, syntax_elements.STRING_SYNTAX_ELEMENT) self._tp = TextParser({ 'string_type': formatting.keyword(types.STRING_TYPE_INFO.name.singular), 'list_type': formatting.keyword(types.LIST_TYPE_INFO.name.singular), 'path_type': formatting.keyword(types.PATH_TYPE_INFO.name.singular), 'symbol': formatting.concept_(concepts.SYMBOL_CONCEPT_INFO), 'CHR': 'CHARACTER', 'SOFT_Q': token.SOFT_QUOTE_CHAR, 'HARD_Q': token.HARD_QUOTE_CHAR, 'soft_quotes': formatting.concept(token.SOFT_QUOTE_NAME.plural), 'hard_quotes': formatting.concept(token.HARD_QUOTE_NAME.plural), 'SYMBOL_REFERENCE_SYNTAX_ELEMENT': syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.singular_name, 'REL_CD_OPTION': file_ref.REL_CWD_OPTION, }) def invokation_variants(self) -> List[InvokationVariant]: return [ InvokationVariant(self._tp.format('{CHR}...'), self._tp.fnap(_DESCRIPTION_OF_NAKED)), InvokationVariant(self._tp.format('{SOFT_Q}{CHR}...{SOFT_Q}'), self._tp.fnap(_DESCRIPTION_OF_SOFT_Q)), InvokationVariant(self._tp.format('{HARD_Q}{CHR}...{HARD_Q}'), self._tp.fnap(_DESCRIPTION_OF_HARD_Q)), ] def syntax_element_descriptions(self) -> list: return [ self._symbol_reference_sed(), ] def main_description_rest_paragraphs(self) -> list: return [] def see_also_targets(self) -> list: info_refs = cross_reference_id_list([ syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT, types.STRING_TYPE_INFO, types.LIST_TYPE_INFO, types.PATH_TYPE_INFO, concepts.SYMBOL_CONCEPT_INFO, ]) plain_refs = [ define_symbol.DEFINE_SYMBOL_INSTRUCTION_CROSS_REFERENCE, ] return info_refs + plain_refs def _symbol_reference_sed(self) -> SyntaxElementDescription: return SyntaxElementDescription(syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.argument.name, self._tp.fnap(_SYMBOL_REFERENCE_DESCRIPTION)) @staticmethod def _cl_arguments() -> list: return [ a.Choice(a.Multiplicity.ZERO_OR_MORE, [ syntax_elements.STRING_SYNTAX_ELEMENT.argument, syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.argument, ]), ]
class _Documentation(SyntaxElementDocumentation): def __init__(self): super().__init__(syntax_elements.STRING_SYNTAX_ELEMENT) the_string_type = 'the ' + types.STRING_TYPE_INFO.singular_name non_str_types_w_str_conversion = value_type.sorted_types( set(value_type.VALUE_TYPES_W_STR_RENDERING) - {value_type.ValueType.STRING}) self._tp = TextParser({ 'symbol': concepts.SYMBOL_CONCEPT_INFO.name, 'symbol_reference': syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.singular_name, 'type': concepts.TYPE_CONCEPT_INFO.name, 'string_type': types.STRING_TYPE_INFO.name, 'string_type_plain': types.STRING_TYPE_INFO.name, 'list_type': types.LIST_TYPE_INFO.name, 'path_type': types.PATH_TYPE_INFO.name, 'A_ref_to_symbol_w_string_conversion': types.a_ref_to_a_symbol_w_string_conversion__sentence(), 'non_str_types_w_str_rendering': types.types__and_list(non_str_types_w_str_conversion), 'soft_quote': syntax_descriptions.SOFT_QUOTE_NAME, 'hard_quote': syntax_descriptions.HARD_QUOTE_NAME, 'SOFT_Q': token.SOFT_QUOTE_CHAR, 'HARD_Q': token.HARD_QUOTE_CHAR, 'CHR': 'CHARACTER', 'whitespace': misc_texts.WHITESPACE, 'reserved_word': misc_texts.RESERVED_WORD_NAME, 'reserved_word_list_str': ', '.join([ formatting.keyword(x) for x in reserved_words.RESERVED_TOKENS ]), 'Sym_refs_are_substituted': syntax_descriptions.symbols_are_substituted_in(the_string_type), 'Sym_refs_are_not_substituted': syntax_descriptions.symbols_are_not_substituted_in( the_string_type), 'REL_CD_OPTION': path.REL_CWD_OPTION, }) def invokation_variants(self) -> List[InvokationVariant]: return [ InvokationVariant(self._tp.format('{CHR}...'), self._tp.fnap(_DESCRIPTION_OF_NAKED)), InvokationVariant(self._tp.format('{SOFT_Q}{CHR}...{SOFT_Q}'), self._tp.fnap(_DESCRIPTION_OF_SOFT_Q)), InvokationVariant(self._tp.format('{HARD_Q}{CHR}...{HARD_Q}'), self._tp.fnap(_DESCRIPTION_OF_HARD_Q)), ] def syntax_element_descriptions(self) -> List[SyntaxElementDescription]: return [ self._symbol_reference_sed(), ] def main_description_rest_paragraphs(self) -> List[ParagraphItem]: return [] def main_description_rest_sub_sections(self) -> List[SectionItem]: return [ self._tp.section( 'Concatenation', _DESCRIPTION__CONCATENATION, ), self._tp.section( misc_texts.RESERVED_WORD_NAME.plural.capitalize(), _RESERVED_WORDS_DESCRIPTION, ), self._tp.section( 'Conversion of {non_str_types_w_str_rendering}', _DESCRIPTION__TYPE_CONVERSION, ), ] def see_also_targets(self) -> List[SeeAlsoTarget]: info_refs = cross_reference_id_list([ syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT, types.STRING_TYPE_INFO, types.LIST_TYPE_INFO, types.PATH_TYPE_INFO, concepts.SYMBOL_CONCEPT_INFO, ]) plain_refs = [ define_symbol.DEFINE_SYMBOL_INSTRUCTION_CROSS_REFERENCE, ] return info_refs + plain_refs def _symbol_reference_sed(self) -> SyntaxElementDescription: return SyntaxElementDescription( syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.argument.name, self._tp.fnap(_SYMBOL_REFERENCE_DESCRIPTION)) @staticmethod def _cl_arguments() -> List[a.ArgumentUsage]: return [ a.Choice.of_single_argument_choices(a.Multiplicity.ZERO_OR_MORE, [ syntax_elements.STRING_SYNTAX_ELEMENT.argument, syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.argument, ]), ]
class _Documentation(SyntaxElementDocumentation): def __init__(self): super().__init__(TypeCategory.DATA, syntax_elements.PATH_SYNTAX_ELEMENT) self._string_name = a.Named(syntax_elements.STRING_SYNTAX_ELEMENT.singular_name) self._relativity_name = instruction_arguments.RELATIVITY_ARGUMENT path_type_symbol = 'MY_PATH_SYMBOL' self._parser = TextParser({ 'RELATIVITY_OPTION': self._relativity_name.name, 'PATH_STRING': self._string_name.name, 'posix_syntax': documentation_text.POSIX_SYNTAX, 'string_type': formatting.keyword(types.STRING_TYPE_INFO.name.singular), '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), }) def invokation_variants(self) -> list: return [ InvokationVariant( cl_syntax.cl_syntax_for_args(self._cl_arguments()) ) ] def syntax_element_descriptions(self) -> List[SyntaxElementDescription]: return [ self._string_sed(), self._relativity_sed(), self._symbol_name_sed(), ] def main_description_rest_paragraphs(self) -> List[ParagraphItem]: return [] def main_description_rest_sub_sections(self) -> List[SectionItem]: return [ docs.section('Relativity', self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY), [docs.section('NOTE', self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY_NOTE))]), path_type_path_rendering() ] def see_also_targets(self) -> List[SeeAlsoTarget]: return cross_reference_id_list([ concepts.TEST_CASE_DIRECTORY_STRUCTURE_CONCEPT_INFO, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO, concepts.SYMBOL_CONCEPT_INFO, syntax_elements.STRING_SYNTAX_ELEMENT, syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT, types.PATH_TYPE_INFO, ]) + [DEFINE_SYMBOL_INSTRUCTION_CROSS_REFERENCE] def _relativity_sed(self) -> SyntaxElementDescription: description_rest = self._parser.fnap(_RELATIVITY_DESCRIPTION_REST) description_rest.append(self._relativity_options_paragraph()) return SyntaxElementDescription(self._relativity_name.name, description_rest) def _string_sed(self) -> SyntaxElementDescription: return SyntaxElementDescription(self._string_name.name, self._parser.fnap(_STRING_DESCRIPTION_REST)) def _symbol_name_sed(self) -> SyntaxElementDescription: return SyntaxElementDescription(syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.singular_name, self._parser.fnap(_SYMBOL_NAME_DESCRIPTION)) def _cl_arguments(self) -> List[a.ArgumentUsage]: return [ a.Single(a.Multiplicity.OPTIONAL, self._relativity_name), a.Single(a.Multiplicity.MANDATORY, self._string_name), ] def _relativity_options_paragraph(self) -> ParagraphItem: return docs.simple_list_with_space_between_elements_and_content([ docs.list_item( self._options_for_directories_in_the(concepts.HOME_DIRECTORY_STRUCTURE_CONCEPT_INFO), self._options_for_directories_in_the_hds(), ), docs.list_item( self._options_for_directories_in_the(concepts.SANDBOX_CONCEPT_INFO), self._options_for_directories_in_the_sds(), ), docs.list_item( self._parser.format('Option for {cd}'), self._options_for_current_directory(), ), docs.list_item( self._parser.format('Option for a path denoted by a {symbol}'), self._options_for_symbol(), ), docs.list_item( self._parser.format('Option for the location of the current source file'), self._options_for_rel_source_file(), ), ], docs.lists.ListType.ITEMIZED_LIST, ) @staticmethod def _options_for_directories_in_the(directory_structure: SingularNameAndCrossReferenceId) -> str: return 'Options for directories in the ' + formatting.concept_(directory_structure) @staticmethod def _options_for_directories_in_the_hds() -> List[ParagraphItem]: return _options_for_directories_in_the_(REL_HOME_OPTIONS_MAP, HDS_DIR_DISPLAY_ORDER) @staticmethod def _options_for_directories_in_the_sds() -> List[ParagraphItem]: return _options_for_directories_in_the_(REL_SDS_OPTIONS_MAP, SDS_DIR_DISPLAY_ORDER) def _options_for_current_directory(self) -> List[ParagraphItem]: return ([ docs.first_row_is_header_table([ [docs.text_cell(REL_CWD_INFO.option_name_text)] ]) ] + self._parser.fnap(_REL_CD_DESCRIPTION) ) def _options_for_symbol(self) -> List[ParagraphItem]: return ([ docs.first_column_is_header_table([ [ docs.text_cell(syntax_text(render_argument(REL_SYMBOL_OPTION))), ] ]) ] + self._parser.fnap(_REL_SYMBOL_DESCRIPTION) ) def _options_for_rel_source_file(self) -> List[ParagraphItem]: return ([ docs.first_column_is_header_table([ [ docs.text_cell(syntax_text(REL_source_file_dir_OPTION)), ] ]) ] + self._parser.fnap(_REL_SOURCE_FILE_DESCRIPTION) )
class _Documentation(SyntaxElementDocumentation): 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), }) def invokation_variants(self) -> list: return [ InvokationVariant( cl_syntax.cl_syntax_for_args(self._cl_arguments()) ) ] def syntax_element_descriptions(self) -> List[SyntaxElementDescription]: return [ self._file_name_string_sed(), self._relativity_sed(), self._symbol_name_sed(), ] def main_description_rest_paragraphs(self) -> List[ParagraphItem]: return [] def main_description_rest_sub_sections(self) -> List[SectionItem]: return [ docs.section(misc_texts.RELATIVITY.singular.capitalize(), self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY), [docs.section(headers.NOTES__HEADER__CAPITALIZED, self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY_NOTE))]), path_type_path_rendering() ] def see_also_targets(self) -> List[SeeAlsoTarget]: return cross_reference_id_list([ concepts.TCDS_CONCEPT_INFO, concepts.CURRENT_WORKING_DIRECTORY_CONCEPT_INFO, concepts.SYMBOL_CONCEPT_INFO, syntax_elements.STRING_SYNTAX_ELEMENT, syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT, types.PATH_TYPE_INFO, ]) + [DEFINE_SYMBOL_INSTRUCTION_CROSS_REFERENCE] def _relativity_sed(self) -> SyntaxElementDescription: description_rest = self._parser.fnap(_RELATIVITY_DESCRIPTION_REST) description_rest.append(self._relativity_options_paragraph()) return SyntaxElementDescription(self._relativity_name.name, description_rest) def _file_name_string_sed(self) -> SyntaxElementDescription: return SyntaxElementDescription( self._file_name.name, (), [invokation_variant_from_args([syntax_elements.STRING_SYNTAX_ELEMENT.single_mandatory])], self._parser.fnap(_STRING_DESCRIPTION_REST)) def _symbol_name_sed(self) -> SyntaxElementDescription: return SyntaxElementDescription(syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.singular_name, self._parser.fnap(_SYMBOL_NAME_DESCRIPTION)) def _cl_arguments(self) -> List[a.ArgumentUsage]: return [ a.Single(a.Multiplicity.OPTIONAL, self._relativity_name), a.Single(a.Multiplicity.MANDATORY, self._file_name), ] def _relativity_options_paragraph(self) -> ParagraphItem: return docs.simple_list_with_space_between_elements_and_content([ docs.list_item( self._options_for_directories_in_the(concepts.HDS_CONCEPT_INFO), self._options_for_directories_in_the_hds(), ), docs.list_item( self._options_for_directories_in_the(concepts.SDS_CONCEPT_INFO), self._options_for_directories_in_the_sds(), ), docs.list_item( self._parser.format('Option for {cd}'), self._options_for_current_directory(), ), docs.list_item( self._parser.format('Option for a path denoted by a {symbol}'), self._options_for_symbol(), ), docs.list_item( self._parser.format('Option for the location of the current source file'), self._options_for_rel_source_file(), ), ], docs.lists.ListType.ITEMIZED_LIST, ) @staticmethod def _options_for_directories_in_the(directory_structure: SingularNameAndCrossReferenceId) -> str: return 'Options for directories in the ' + formatting.concept_(directory_structure) @staticmethod def _options_for_directories_in_the_hds() -> List[ParagraphItem]: return _options_for_directories_in_the_(REL_HDS_OPTIONS_MAP, HDS_DIR_DISPLAY_ORDER) @staticmethod def _options_for_directories_in_the_sds() -> List[ParagraphItem]: return _options_for_directories_in_the_(REL_SDS_OPTIONS_MAP, SDS_DIR_DISPLAY_ORDER) def _options_for_current_directory(self) -> List[ParagraphItem]: return ([ docs.first_row_is_header_table([ [docs.text_cell(REL_CWD_INFO.option_name_text)] ]) ] + self._parser.fnap(_REL_CD_DESCRIPTION) ) def _options_for_symbol(self) -> List[ParagraphItem]: return ([ docs.first_column_is_header_table([ [ docs.text_cell(syntax_text(render_argument(REL_SYMBOL_OPTION))), ] ]) ] + self._parser.fnap(_REL_SYMBOL_DESCRIPTION) ) def _options_for_rel_source_file(self) -> List[ParagraphItem]: return ([ docs.first_column_is_header_table([ [ docs.text_cell(syntax_text(REL_source_file_dir_OPTION)), ] ]) ] + self._parser.fnap(_REL_SOURCE_FILE_DESCRIPTION) )