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)
)
