def _for_logic_type(type_info: SingularNameAndCrossReferenceId,
grammar: Grammar) -> SyntaxElementDocumentation:
syntax = Syntax(grammar)
return syntax_element_documentation(TypeCategory.LOGIC,
type_info,
syntax.global_description(),
syntax.invokation_variants(),
[],
syntax.see_also_targets())
def runTest(self):
# ARRANGE #
constructor = SYNTAX_ELEMENT_ENTITY_CONFIGURATION.cli_list_constructor_getter.get_constructor(
[
syntax_element_documentation(
None,
name_and_ref_target('SE1', None,
'single line description of SE1'), [],
(), [], [], []),
syntax_element_documentation(
None,
name_and_ref_target('SE2', None,
'single line description of SE2'), [],
(), [], [], []),
])
# ACT #
actual = constructor.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_section_contents.apply(self, actual)
def documentation() -> SyntaxElementDocumentation:
executable_arg = syntax_elements.PATH_SYNTAX_ELEMENT.single_mandatory
optional_arguments_arg = syntax_elements.PROGRAM_ARGUMENT_SYNTAX_ELEMENT.zero_or_more
invokation_variants = [
invokation_variant_from_args([executable_arg, optional_arguments_arg],
_executable_file_description()),
programs.system_program([optional_arguments_arg]),
programs.python_interpreter([optional_arguments_arg]),
]
return syntax_element_documentation(
None,
syntax_elements.ACT_INTERPRETER_SYNTAX_ELEMENT,
_TEXT_PARSER.fnap(_MAIN__DESCRIPTION),
(),
invokation_variants,
[],
name_and_cross_ref.cross_reference_id_list([
syntax_elements.PATH_SYNTAX_ELEMENT,
syntax_elements.STRING_SYNTAX_ELEMENT,
syntax_elements.PROGRAM_ARGUMENT_SYNTAX_ELEMENT,
]),
)
def documentation() -> SyntaxElementDocumentation:
invokation_variants = [
_string(),
_symbol_reference(),
_existing_path(
pgm_syntax_elements.EXISTING_FILE_OPTION_NAME,
_EXISTING_FILE_DESCRIPTION,
),
_existing_path(
pgm_syntax_elements.EXISTING_DIR_OPTION_NAME,
_EXISTING_DIR_DESCRIPTION,
),
_existing_path(
pgm_syntax_elements.EXISTING_PATH_OPTION_NAME,
_EXISTING_PATH_DESCRIPTION,
),
]
return syntax_element_documentation(
None,
syntax_elements.PROGRAM_ARGUMENT_SYNTAX_ELEMENT,
_TEXT_PARSER.fnap(_MAIN__DESCRIPTION),
(),
invokation_variants,
[
rel_path_doc.path_element_2(
PATH_OF_EXISTING_FILE_OPT_CONFIG,
_TEXT_PARSER.paras(path_syntax.the_path_of_an_existing_file(final_dot=True)))
],
cross_reference_id_list([
syntax_elements.RICH_STRING_SYNTAX_ELEMENT,
syntax_elements.PATH_SYNTAX_ELEMENT,
syntax_elements.LIST_SYNTAX_ELEMENT,
syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT,
]),
)
<<EOF
first line
...
last line
EOF
```
Any single-word string may be used instead of "EOF" as marker.
What matters is that the maker at start and end of input
matches.
Any {SYMBOL_REFERENCE_SYNTAX_ELEMENT} appearing in the text is substituted.
"""
_TEXT_PARSER = TextParser({
'SYMBOL_REFERENCE_SYNTAX_ELEMENT': syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.singular_name
})
DOCUMENTATION = syntax_element_documentation(None,
syntax_elements.HERE_DOCUMENT_SYNTAX_ELEMENT,
_TEXT_PARSER.fnap(_MAIN_DESCRIPTION_REST),
[],
[],
cross_reference_id_list([
STRING_TYPE_INFO,
syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT,
]))
from exactly_lib.common.help.syntax_contents_structure import InvokationVariant
from exactly_lib.definitions.cross_ref.name_and_cross_ref import cross_reference_id_list
from exactly_lib.definitions.entity import syntax_elements, concepts
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.symbol.symbol_syntax import symbol_reference_syntax_for_name
_MAIN_DESCRIPTION_REST = symbol_reference_syntax_for_name(syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.argument.name)
DOCUMENTATION = syntax_element_documentation(
None,
syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT,
[],
[
InvokationVariant(
symbol_reference_syntax_for_name(syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.argument.name)
)
],
[],
cross_reference_id_list([
concepts.SYMBOL_CONCEPT_INFO,
syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT,
]))
lists.ListType.ITEMIZED_LIST)
_DIRECTORY_SPECIFICATIONS = docs.simple_list_with_space_between_elements_and_content([
docs.list_item(syntax_text('**'),
docs.paras('The directory where the pattern is applied, and all subdirectories, recursively.')
),
docs.list_item(syntax_text('/'),
docs.paras('Directory separator.')
),
],
lists.ListType.ITEMIZED_LIST)
DOCUMENTATION = syntax_element_documentation(
None,
syntax_elements.GLOB_PATTERN_SYNTAX_ELEMENT,
_TP.fnap(_HEADER) +
[_PATTERNS] +
_TP.paras(_DIRECTORY_SPECIFICATIONS_HEADER) +
[_DIRECTORY_SPECIFICATIONS] +
_TP.fnap(_FOOTER),
[],
[],
[
SeeAlsoUrlInfo('Python file name matching',
'file:///usr/local/share/doc/python3/library/fnmatch.html'
),
SeeAlsoUrlInfo('Glob patterns on Wikipedia',
'https://en.wikipedia.org/wiki/Glob_(programming)#Unix'
),
])
from exactly_lib.impls.types.regex import parse_regex
from exactly_lib.util.cli_syntax.elements import argument as a
from exactly_lib.util.textformat.textformat_parser import TextParser
_IGNORE_CASE_ARGUMENT = a.Option(parse_regex.IGNORE_CASE_OPTION_NAME)
_CL_ARGUMENTS = [
a.Single(a.Multiplicity.OPTIONAL, _IGNORE_CASE_ARGUMENT),
syntax_elements.RICH_STRING_SYNTAX_ELEMENT.single_mandatory,
]
SEE_ALSO_URL_INFO = SeeAlsoUrlInfo(
'Python regular expressions',
'https://docs.python.org/3/library/re.html#regular-expression-syntax')
_DESCRIPTION_OF_IGNORE_CASE_OPTION = """\
Makes the matching ignore case.
"""
DOCUMENTATION = syntax_element_documentation(
None, syntax_elements.REGEX_SYNTAX_ELEMENT, [], (), [
invokation_variant_from_args(_CL_ARGUMENTS),
], [
cli_argument_syntax_element_description(
_IGNORE_CASE_ARGUMENT,
TextParser().fnap(_DESCRIPTION_OF_IGNORE_CASE_OPTION))
], [
syntax_elements.RICH_STRING_SYNTAX_ELEMENT.cross_reference_target,
SEE_ALSO_URL_INFO,
])
def _here_doc() -> InvokationVariant:
return invokation_variant_from_args([
a.Single(
a.Multiplicity.MANDATORY,
a.Constant(string.HERE_DOCUMENT_MARKER_PREFIX +
_HERE_DOC_SYNTAX_MARKER)),
a.Single(a.Multiplicity.ZERO_OR_MORE, a.Named(_HERE_DOC_LINE)),
a.Single(a.Multiplicity.MANDATORY,
a.Constant(_HERE_DOC_SYNTAX_MARKER)),
], _TEXT_PARSER.fnap(_DESCRIPTION__HERE_DOC))
DOCUMENTATION = syntax_element_documentation(
None,
syntax_elements.RICH_STRING_SYNTAX_ELEMENT,
(),
(),
[
_normal_string(),
string_common.text_until_end_of_line(),
_here_doc(),
],
[],
cross_reference_id_list([
types.STRING_TYPE_INFO,
syntax_elements.STRING_SYNTAX_ELEMENT,
syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT,
]),
)
from exactly_lib.definitions import syntax_descriptions
from exactly_lib.definitions.entity import concepts
from exactly_lib.definitions.entity import syntax_elements
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.util.textformat.parse import normalize_and_parse
_MAIN_DESCRIPTION_REST = syntax_descriptions.SYMBOL_NAME_SYNTAX_DESCRIPTION
DOCUMENTATION = syntax_element_documentation(None,
syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT,
normalize_and_parse(_MAIN_DESCRIPTION_REST),
(),
[],
[],
[concepts.SYMBOL_CONCEPT_INFO.cross_reference_target])
def runTest(self):
for type_category in [None, TypeCategory.DATA]:
nrt = name_and_ref_target('SE1', type_category,
'single line description of SE1')
test_cases = [
('minimal',
syntax_element_documentation(nrt.type_category, nrt, [], (),
[], [], [])),
('with main description rest',
syntax_element_documentation(nrt.type_category, nrt,
[docs.para('a paragraph')], (),
[], [], [])),
('with main description rest sub sections',
syntax_element_documentation(nrt.type_category, nrt, [], [
docs.section('a section header',
docs.paras('section contents'))
], [], [], [])),
('with main description rest, and notes',
syntax_element_documentation(
nrt.type_category,
nrt,
[],
[
docs.section('a section header',
docs.paras('section contents'))
],
[],
[],
[],
docs.section_contents(
docs.paras('notes section contents')),
)),
('with invokation variants',
syntax_element_documentation(nrt.type_category, nrt, [], (),
syntax_parts.INVOKATION_VARIANTS,
[], [])),
('with syntax element descriptions',
syntax_element_documentation(
nrt.type_category, nrt, [], (), [],
syntax_parts.SYNTAX_ELEMENT_DESCRIPTIONS, [])),
('see also',
syntax_element_documentation(
nrt.type_category,
nrt,
[],
(),
[],
[],
[CustomCrossReferenceId('custom-target-name')],
)),
('full',
syntax_element_documentation(
nrt.type_category, nrt, [docs.para('a paragraph')], [
docs.section('a section header',
docs.paras('section contents'))
],
[InvokationVariant('syntax', [docs.para('a paragraph')])],
syntax_parts.SYNTAX_ELEMENT_DESCRIPTIONS,
[CustomCrossReferenceId('custom-target-name')],
docs.section_contents(
docs.paras('notes section contents')))),
]
for test_case_name, documentation in test_cases:
with self.subTest(test_case_name=test_case_name,
type_category=type_category):
# ARRANGE #
renderer = sut.IndividualSyntaxElementConstructor(
documentation)
# ACT #
actual = renderer.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
from exactly_lib.common.help.syntax_contents_structure import InvokationVariant
from exactly_lib.definitions.cross_ref.name_and_cross_ref import cross_reference_id_list
from exactly_lib.definitions.entity import syntax_elements, concepts
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.symbol.symbol_syntax import symbol_reference_syntax_for_name
_MAIN_DESCRIPTION_REST = symbol_reference_syntax_for_name(
syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.argument.name)
DOCUMENTATION = syntax_element_documentation(
None, syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT, [], (), [
InvokationVariant(
symbol_reference_syntax_for_name(
syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT.argument.name))
], [],
cross_reference_id_list([
concepts.SYMBOL_CONCEPT_INFO,
syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT,
]))
from exactly_lib.definitions.entity import syntax_elements, concepts, types
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.util.textformat.textformat_parser import TextParser
_MAIN_DESCRIPTION_REST = """\
A {SYNTAX_ELEMENT} is passed as a single {string_type} to the operating system's shell,
so all features of the shell can be used.
Us of the shell is of course not portable since it
depends on the current operating system environment's shell.
On POSIX, the shell is /bin/sh.
On Windows, the COMSPEC {env_var} specifies the shell.
"""
_TEXT_PARSER = TextParser({
'SYNTAX_ELEMENT':
formatting.syntax_element_(
syntax_elements.SHELL_COMMAND_LINE_SYNTAX_ELEMENT),
'env_var':
concepts.ENVIRONMENT_VARIABLE_CONCEPT_INFO.name,
'string_type':
types.STRING_TYPE_INFO.name,
})
DOCUMENTATION = syntax_element_documentation(
None, syntax_elements.SHELL_COMMAND_LINE_SYNTAX_ELEMENT,
_TEXT_PARSER.fnap(_MAIN_DESCRIPTION_REST), (), [], [], [])
from exactly_lib.definitions import formatting
from exactly_lib.definitions.entity import syntax_elements
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.util.textformat.textformat_parser import TextParser
_MAIN_DESCRIPTION_REST = """\
A {SYNTAX_ELEMENT} is passed as a single string to the operating system's shell,
so all features of the shell can be used.
Us of the shell is of course not portable since it
depends on the current operating system environment's shell.
On POSIX, the shell defaults to /bin/sh.
On Windows, the COMSPEC environment variable specifies the default shell.
"""
_TEXT_PARSER = TextParser({
'SYNTAX_ELEMENT': formatting.syntax_element_(syntax_elements.SHELL_COMMAND_LINE_SYNTAX_ELEMENT)
})
DOCUMENTATION = syntax_element_documentation(None,
syntax_elements.SHELL_COMMAND_LINE_SYNTAX_ELEMENT,
_TEXT_PARSER.fnap(_MAIN_DESCRIPTION_REST),
[],
[],
[])
from exactly_lib.definitions.cross_ref.name_and_cross_ref import cross_reference_id_list
from exactly_lib.definitions.entity import syntax_elements
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.util.textformat.textformat_parser import TextParser
_EXPRESSION_DESCRIPTION = """\
An expression using Python syntax.
The expression must evaluate to an integer (a Python "int").
"""
_TEXT_PARSER = TextParser({
'STRING':
syntax_elements.STRING_SYNTAX_ELEMENT.singular_name,
})
DOCUMENTATION = syntax_element_documentation(
None, syntax_elements.INTEGER_SYNTAX_ELEMENT, (), (), [
invokation_variant_from_args([
syntax_elements.STRING_SYNTAX_ELEMENT.single_mandatory,
])
], [
SyntaxElementDescription(
syntax_elements.STRING_SYNTAX_ELEMENT.singular_name,
_TEXT_PARSER.fnap(_EXPRESSION_DESCRIPTION),
),
], cross_reference_id_list([
syntax_elements.STRING_SYNTAX_ELEMENT,
]))
The actual value that is matched serves as the left hand side in the comparison.
"""
def _operator_syntax_element_description() -> SyntaxElementDescription:
operators_list = ' '.join(sorted(comparators.NAME_2_OPERATOR.keys()))
operator_text = 'One of ' + operators_list
return SyntaxElementDescription(OPERATOR_ARGUMENT.name,
docs.paras(operator_text))
DOCUMENTATION = syntax_element_documentation(
None,
syntax_elements.INTEGER_COMPARISON_SYNTAX_ELEMENT,
[],
invokation_variants=[
InvokationVariant(cl_syntax.cl_syntax_for_args([
_MANDATORY_OPERATOR_ARGUMENT,
syntax_elements.INTEGER_SYNTAX_ELEMENT.single_mandatory,
]),
_TEXT_PARSER.fnap(_DESCRIPTION_OF_COMPARISON_WITH_OPERATOR))
]
,
syntax_element_descriptions=[
_operator_syntax_element_description(),
],
see_also_targets=[
syntax_elements.INTEGER_SYNTAX_ELEMENT.cross_reference_target,
]
)
),
],
lists.ListType.ITEMIZED_LIST)
_DIRECTORY_SPECIFICATIONS = docs.simple_list_with_space_between_elements_and_content([
docs.list_item(syntax_text('/'),
docs.paras('Directory separator.')
),
],
lists.ListType.ITEMIZED_LIST)
DOCUMENTATION = syntax_element_documentation(
None,
syntax_elements.GLOB_PATTERN_SYNTAX_ELEMENT,
_TP.fnap(_HEADER) +
[_PATTERNS] +
_TP.paras(_DIRECTORY_SPECIFICATIONS_HEADER) +
[_DIRECTORY_SPECIFICATIONS] +
_TP.fnap(_FOOTER),
(),
[],
[],
[
SeeAlsoUrlInfo('Python file name matching',
'https://docs.python.org/3/library/fnmatch.html'
),
SeeAlsoUrlInfo('Glob patterns on Wikipedia',
'https://en.wikipedia.org/wiki/Glob_(programming)#Unix'
),
])
from exactly_lib.definitions import syntax_descriptions
from exactly_lib.definitions.entity import concepts
from exactly_lib.definitions.entity import syntax_elements
from exactly_lib.help.entities.syntax_elements.contents_structure import syntax_element_documentation
from exactly_lib.util.textformat.parse import normalize_and_parse
_MAIN_DESCRIPTION_REST = syntax_descriptions.SYMBOL_NAME_SYNTAX_DESCRIPTION
DOCUMENTATION = syntax_element_documentation(None,
syntax_elements.SYMBOL_NAME_SYNTAX_ELEMENT,
normalize_and_parse(_MAIN_DESCRIPTION_REST),
[],
[],
[concepts.SYMBOL_CONCEPT_INFO.cross_reference_target])
'file_matcher': formatting.entity_(types.FILE_MATCHER_TYPE_INFO),
'name': parse_file_matcher.NAME_MATCHER_NAME,
})
SEE_ALSO_URL_INFO = SeeAlsoUrlInfo('Python regular expressions',
'https://docs.python.org/3/library/re.html#regular-expression-syntax')
_DESCRIPTION_OF_IGNORE_CASE_OPTION = """\
Makes the matching ignore case.
"""
DOCUMENTATION = syntax_element_documentation(
None,
syntax_elements.REGEX_SYNTAX_ELEMENT,
[],
[
InvokationVariant(
cl_syntax.cl_syntax_for_args(_CL_ARGUMENTS)
),
],
[
cli_argument_syntax_element_description(_IGNORE_CASE_ARGUMENT,
_TEXT_PARSER.fnap(_DESCRIPTION_OF_IGNORE_CASE_OPTION))
],
[
syntax_elements.STRING_SYNTAX_ELEMENT.cross_reference_target,
syntax_elements.SYMBOL_REFERENCE_SYNTAX_ELEMENT.cross_reference_target,
SEE_ALSO_URL_INFO,
]
)
