跳转至

twilight

ArgResult 🔗

Bases: Generic[T], MatchResult[T, ArgumentMatch]

表示 ArgumentMatch 匹配结果

Source code in src/graia/ariadne/message/parser/twilight.py
411
412
413
414
class ArgResult(Generic[T], MatchResult[T, ArgumentMatch]):
    """表示 ArgumentMatch 匹配结果"""

    ...

ArgumentMatch 🔗

Bases: Match, Generic[T]

参数匹配

Source code in src/graia/ariadne/message/parser/twilight.py
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
class ArgumentMatch(Match, Generic[T]):
    """参数匹配"""

    if TYPE_CHECKING:

        @overload
        def __init__(  # type: ignore
            self,
            *pattern: str,
            action: Union[str, Type[Action], Literal[Sentinel]] = Sentinel,
            nargs: Union[int, str, Literal[Sentinel]] = Sentinel,
            const: Union[T, Literal[Sentinel]] = Sentinel,
            default: Union[T, Literal[Sentinel]] = Sentinel,
            type: Union[Callable[[str], T], Literal[Sentinel]] = Sentinel,
            choices: Union[Iterable[T], Literal[Sentinel]] = Sentinel,
            optional: bool = True,
        ):
            """初始化 ArgumentMatch 对象.

            Args:
                *pattern (str): 匹配的参数名.
                action (Union[str, Type[Action]], optional): 参数的动作. Defaults to "store".
                nargs (Union[int, str], optional): 参数的个数.
                const (T, optional): 参数的常量值.
                default (T, optional): 参数的默认值.
                type (Callable[[str], T], optional): 参数的类型.
                choices (Iterable[T], optional): 参数的可选值.
                optional (bool, optional): 参数是否可选. Defaults to True.
            Returns:
                None: 无返回
            """
            ...

    def __init__(self, *pattern: str, **kwargs) -> None:
        """初始化 ArgumentMatch 对象.

        Args:
            *pattern (str): 匹配的参数名.
            action (Union[str, Type[Action]], optional): 参数的动作. Defaults to "store".
            nargs (Union[int, str], optional): 参数的个数.
            const (T, optional): 参数的常量值.
            default (T, optional): 参数的默认值.
            type (Callable[[str], T], optional): 参数的类型.
            choices (Iterable[T], optional): 参数的可选值.
            optional (bool, optional): 参数是否可选. Defaults to True.
        Returns:
            None: 无返回
        """
        super().__init__()
        if not pattern:
            raise ValueError("pattern must not be empty")
        if not all(i.startswith("-") for i in pattern):
            raise ValueError("pattern must start with '-'")
        self.pattern: List[str] = list(pattern)
        self.arg_data: Dict[str, Any] = {"default": Unmatched}
        for k, v in kwargs.items():
            if k == "optional":
                self.arg_data["required"] = not v
            elif k == "type":
                if v is MessageChain:
                    v = MessageChainType()
                elif isinstance(v, Type) and issubclass(v, Element):
                    v = ElementType(v)
                self.arg_data["type"] = v
            else:
                self.arg_data[k] = v

        if "type" not in self.arg_data:
            self.arg_data["type"] = MessageChainType()

    def param(self, target: Union[int, str]) -> Self:
        """标注分派位置

        Args:
            target (Union[int, str]): 分派位置

        Returns:
            Self: 返回自身
        """
        self.arg_data["dest"] = target if isinstance(target, str) else f"_#!{target}!#_"
        super().param(target)
        return self

    def help(self, value: str) -> Self:
        """设置帮助值

        Args:
            value (str): 帮助字符串

        Returns:
            Self: 返回自身
        """
        self.arg_data["help"] = value
        super().help(value)
        return self

    def __repr_args__(self):
        return [(None, self.pattern)]

__init__ 🔗

__init__(*pattern: str, **kwargs: str) -> None

初始化 ArgumentMatch 对象.

Parameters:

  • *pattern (str) –

    匹配的参数名.

  • action (Union[str, Type[Action]]) –

    参数的动作. Defaults to "store".

  • nargs (Union[int, str]) –

    参数的个数.

  • const (T) –

    参数的常量值.

  • default (T) –

    参数的默认值.

  • type (Callable[[str], T]) –

    参数的类型.

  • choices (Iterable[T]) –

    参数的可选值.

  • optional (bool) –

    参数是否可选. Defaults to True.

Returns:

  • None( None ) –

    无返回

Source code in src/graia/ariadne/message/parser/twilight.py
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
def __init__(self, *pattern: str, **kwargs) -> None:
    """初始化 ArgumentMatch 对象.

    Args:
        *pattern (str): 匹配的参数名.
        action (Union[str, Type[Action]], optional): 参数的动作. Defaults to "store".
        nargs (Union[int, str], optional): 参数的个数.
        const (T, optional): 参数的常量值.
        default (T, optional): 参数的默认值.
        type (Callable[[str], T], optional): 参数的类型.
        choices (Iterable[T], optional): 参数的可选值.
        optional (bool, optional): 参数是否可选. Defaults to True.
    Returns:
        None: 无返回
    """
    super().__init__()
    if not pattern:
        raise ValueError("pattern must not be empty")
    if not all(i.startswith("-") for i in pattern):
        raise ValueError("pattern must start with '-'")
    self.pattern: List[str] = list(pattern)
    self.arg_data: Dict[str, Any] = {"default": Unmatched}
    for k, v in kwargs.items():
        if k == "optional":
            self.arg_data["required"] = not v
        elif k == "type":
            if v is MessageChain:
                v = MessageChainType()
            elif isinstance(v, Type) and issubclass(v, Element):
                v = ElementType(v)
            self.arg_data["type"] = v
        else:
            self.arg_data[k] = v

    if "type" not in self.arg_data:
        self.arg_data["type"] = MessageChainType()

help 🔗

help(value: str) -> Self

设置帮助值

Parameters:

  • value (str) –

    帮助字符串

Returns:

  • Self( Self ) –

    返回自身

Source code in src/graia/ariadne/message/parser/twilight.py
394
395
396
397
398
399
400
401
402
403
404
405
def help(self, value: str) -> Self:
    """设置帮助值

    Args:
        value (str): 帮助字符串

    Returns:
        Self: 返回自身
    """
    self.arg_data["help"] = value
    super().help(value)
    return self

param 🔗

param(target: Union[int, str]) -> Self

标注分派位置

Parameters:

Returns:

  • Self( Self ) –

    返回自身

Source code in src/graia/ariadne/message/parser/twilight.py
381
382
383
384
385
386
387
388
389
390
391
392
def param(self, target: Union[int, str]) -> Self:
    """标注分派位置

    Args:
        target (Union[int, str]): 分派位置

    Returns:
        Self: 返回自身
    """
    self.arg_data["dest"] = target if isinstance(target, str) else f"_#!{target}!#_"
    super().param(target)
    return self

ElementMatch 🔗

Bases: RegexMatch

元素类型匹配

Source code in src/graia/ariadne/message/parser/twilight.py
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
class ElementMatch(RegexMatch):
    """元素类型匹配"""

    type: Type[Element]
    """要匹配的元素类型"""

    def __init__(
        self,
        type: Type[Element] = ...,
        optional: bool = False,
    ) -> None:
        """初始化 ElementMatch 对象.

        Args:
            type (Type[Element]): 元素类型.
            optional (bool, optional): 匹配是否可选. Defaults to False.
        """
        super(RegexMatch, self).__init__()
        self.type = type
        self.optional = optional
        self._flags: re.RegexFlag = re.RegexFlag(0)
        self.space_policy: SpacePolicy = SpacePolicy.PRESERVE
        self.help(f"{self.type.__name__} 元素")

    @property
    def _src(self) -> str:
        return f"\x02\\d+_{self.type.__fields__['type'].default}\x03"

    def __repr_args__(self):
        return [(None, self.type), ("space", self.space_policy.name), ("flags", self._flags)]

type instance-attribute 🔗

type: Type[Element] = type

要匹配的元素类型

__init__ 🔗

__init__(type: Type[Element] = ..., optional: bool = False) -> None

初始化 ElementMatch 对象.

Parameters:

  • type (Type[Element]) –

    元素类型.

  • optional (bool) –

    匹配是否可选. Defaults to False.

Source code in src/graia/ariadne/message/parser/twilight.py
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def __init__(
    self,
    type: Type[Element] = ...,
    optional: bool = False,
) -> None:
    """初始化 ElementMatch 对象.

    Args:
        type (Type[Element]): 元素类型.
        optional (bool, optional): 匹配是否可选. Defaults to False.
    """
    super(RegexMatch, self).__init__()
    self.type = type
    self.optional = optional
    self._flags: re.RegexFlag = re.RegexFlag(0)
    self.space_policy: SpacePolicy = SpacePolicy.PRESERVE
    self.help(f"{self.type.__name__} 元素")

ElementResult 🔗

Bases: MatchResult[Element, ElementMatch]

表示 ElementMatch 匹配结果

Source code in src/graia/ariadne/message/parser/twilight.py
423
424
425
426
class ElementResult(MatchResult[Element, ElementMatch]):
    """表示 ElementMatch 匹配结果"""

    ...

ForceResult 🔗

Bases: MatchResult[T, Match]

声明匹配结果一定存在/可通过 matched 判别

Source code in src/graia/ariadne/message/parser/twilight.py
429
430
431
432
433
434
class ForceResult(MatchResult[T, Match]):
    """声明匹配结果一定存在/可通过 matched 判别"""

    result: T
    matched: bool
    ...

FullMatch 🔗

Bases: RegexMatch

全匹配

Source code in src/graia/ariadne/message/parser/twilight.py
212
213
214
215
216
217
class FullMatch(RegexMatch):
    """全匹配"""

    @property
    def _src(self) -> str:
        return re.escape(self.pattern)

Help 🔗

Bases: Decorator, Generic[T]

返回帮助信息的装饰器

Source code in src/graia/ariadne/message/parser/twilight.py
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
class Help(Decorator, Generic[T]):
    """返回帮助信息的装饰器"""

    pre = True

    formatter: Optional[Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]]

    @overload
    def __init__(self) -> None:
        """
        Args:
            formatter (Callable[[str, DecoratorInterface], Union[Awaitable[T], T]], optional): \
                帮助信息格式化函数.
        """
        ...

    @overload
    def __init__(self, formatter: Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]) -> None:
        """
        Args:
            formatter (Callable[[str, DecoratorInterface], Union[Awaitable[T], T]], optional): \
                帮助信息格式化函数.
        """
        ...

    def __init__(
        self, formatter: Optional[Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]] = None
    ) -> None:
        """
        Args:
            formatter (Optional[Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]], optional): \
                帮助信息格式化函数.
        """
        self.formatter = formatter

    async def target(self, i: DecoratorInterface) -> T:
        twilight: Twilight = i.local_storage[f"{__name__}:twilight"]
        help_string: str = twilight.matcher.get_help(**(twilight.help_data or {}))
        if self.formatter:
            coro_or_result = self.formatter(help_string, i)
            if inspect.isawaitable(coro_or_result):
                return await coro_or_result
            else:
                return cast(T, coro_or_result)
        return cast(T, help_string)

__init__ 🔗

__init__(
    formatter: Optional[
        Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]
    ] = None
) -> None

Parameters:

Source code in src/graia/ariadne/message/parser/twilight.py
879
880
881
882
883
884
885
886
887
def __init__(
    self, formatter: Optional[Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]] = None
) -> None:
    """
    Args:
        formatter (Optional[Callable[[str, DecoratorInterface], Union[Awaitable[T], T]]], optional): \
            帮助信息格式化函数.
    """
    self.formatter = formatter

Match 🔗

Bases: abc.ABC, Representation

匹配项抽象基类

Source code in src/graia/ariadne/message/parser/twilight.py
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
class Match(abc.ABC, Representation):
    """匹配项抽象基类"""

    dest: Union[int, str]

    def __init__(self) -> None:
        self._help = ""
        self.dest = ""

    def help(self, value: str) -> Self:
        """设置匹配项的帮助信息."""
        self._help = value
        return self

    def param(self, target: Union[int, str]) -> Self:
        """设置匹配项的分派位置."""
        self.dest = target
        return self

    def __matmul__(self, other: Union[int, str]) -> Self:
        return self.param(other)

    def __rmatmul__(self, other: Union[int, str]) -> Self:
        return self.param(other)

    def __rshift__(self, other: Union[int, str]) -> Self:
        return self.param(other)

    def __rlshift__(self, other: Union[int, str]) -> Self:
        return self.param(other)

help 🔗

help(value: str) -> Self

设置匹配项的帮助信息.

Source code in src/graia/ariadne/message/parser/twilight.py
90
91
92
93
def help(self, value: str) -> Self:
    """设置匹配项的帮助信息."""
    self._help = value
    return self

param 🔗

param(target: Union[int, str]) -> Self

设置匹配项的分派位置.

Source code in src/graia/ariadne/message/parser/twilight.py
95
96
97
98
def param(self, target: Union[int, str]) -> Self:
    """设置匹配项的分派位置."""
    self.dest = target
    return self

MatchResult 🔗

Bases: Generic[T, T_Match], Representation

匹配结果

Source code in src/graia/ariadne/message/parser/twilight.py
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
class MatchResult(Generic[T, T_Match], Representation):
    """匹配结果"""

    __slots__ = ("matched", "result", "origin")

    matched: bool
    """是否匹配成功"""

    result: Optional[T]
    """匹配结果"""

    origin: T_Match
    """原来的 Match 对象"""

    def __init__(self, matched: bool, origin: T_Match, result: T = None) -> None:
        """初始化 MatchResult 对象.

        Args:
            matched (bool): 是否匹配成功
            origin (T_Match): 原来的 Match 对象
            result (T, optional): 匹配结果. Defaults to None.
        """
        self.matched = matched
        self.origin = origin
        self.result = result

matched instance-attribute 🔗

matched: bool = matched

是否匹配成功

origin instance-attribute 🔗

origin: T_Match = origin

原来的 Match 对象

result instance-attribute 🔗

result: Optional[T] = result

匹配结果

__init__ 🔗

__init__(matched: bool, origin: T_Match, result: T = None) -> None

初始化 MatchResult 对象.

Parameters:

  • matched (bool) –

    是否匹配成功

  • origin (T_Match) –

    原来的 Match 对象

  • result (T) –

    匹配结果. Defaults to None.

Source code in src/graia/ariadne/message/parser/twilight.py
130
131
132
133
134
135
136
137
138
139
140
def __init__(self, matched: bool, origin: T_Match, result: T = None) -> None:
    """初始化 MatchResult 对象.

    Args:
        matched (bool): 是否匹配成功
        origin (T_Match): 原来的 Match 对象
        result (T, optional): 匹配结果. Defaults to None.
    """
    self.matched = matched
    self.origin = origin
    self.result = result

ParamMatch 🔗

Bases: RegexMatch

与 WildcardMatch 类似, 但需要至少一个字符. 且仅匹配用空格分开的一段

Source code in src/graia/ariadne/message/parser/twilight.py
284
285
286
287
288
289
290
291
292
293
294
295
class ParamMatch(RegexMatch):
    """与 WildcardMatch 类似, 但需要至少一个字符. 且仅匹配用空格分开的一段"""

    def __init__(self, optional: bool = False) -> None:
        super().__init__(
            r"""(?:").+?(?:")|(?:').+?(?:')|[^ "']+""",
            optional,
        )
        self._help = "参数"

    def __repr_args__(self):
        return [(None, "PARAM"), ("space", self.space_policy.name), ("flags", self._flags)]

RegexMatch 🔗

Bases: Match

正则表达式匹配

Source code in src/graia/ariadne/message/parser/twilight.py
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
class RegexMatch(Match):
    """正则表达式匹配"""

    pattern: str
    """正则表达式字符串"""

    def __init__(self, pattern: str = "", optional: bool = False) -> None:
        """初始化 RegexMatch 对象.

        Args:
            pattern (str, optional): 正则表达式字符串. Defaults to "".
            optional (bool, optional): 是否可选. Defaults to False.
        Returns:
            None: 无返回.
        """
        super().__init__()
        self.pattern: str = pattern
        self._flags: re.RegexFlag = re.RegexFlag(0)
        self.optional: bool = optional
        self.space_policy: SpacePolicy = SpacePolicy.PRESERVE

    def flags(self, flags: re.RegexFlag) -> Self:
        """设置正则表达式的标志.

        Args:
            flags (re.RegexFlag): 正则表达式旗标.

        Returns:
            Self: RegexMatch 自身.
        """
        self._flags = flags
        return self

    def space(self, space: SpacePolicy) -> Self:
        """设置正则表达式的尾随空格策略.

        Args:
            space (SpacePolicy): 尾随空格策略.

        Returns:
            Self: RegexMatch 自身.
        """
        self.space_policy = space
        return self

    @final
    @property
    def _regex_str(self) -> str:
        """生成 RegexMatch 相应的正则表达式."""
        return (
            f"{transform_regex(self._flags, self._src)}"
            f"{'?' if self.optional else ''}{self.space_policy.value}"
        )

    @property
    def _src(self) -> str:
        """正则表达式的来源"""
        return self.pattern

    def __repr_args__(self):
        return [(None, self.pattern), ("space", self.space_policy.name), ("flags", self._flags)]

pattern instance-attribute 🔗

pattern: str = pattern

正则表达式字符串

__init__ 🔗

__init__(pattern: str = '', optional: bool = False) -> None

初始化 RegexMatch 对象.

Parameters:

  • pattern (str) –

    正则表达式字符串. Defaults to "".

  • optional (bool) –

    是否可选. Defaults to False.

Returns:

  • None( None ) –

    无返回.

Source code in src/graia/ariadne/message/parser/twilight.py
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def __init__(self, pattern: str = "", optional: bool = False) -> None:
    """初始化 RegexMatch 对象.

    Args:
        pattern (str, optional): 正则表达式字符串. Defaults to "".
        optional (bool, optional): 是否可选. Defaults to False.
    Returns:
        None: 无返回.
    """
    super().__init__()
    self.pattern: str = pattern
    self._flags: re.RegexFlag = re.RegexFlag(0)
    self.optional: bool = optional
    self.space_policy: SpacePolicy = SpacePolicy.PRESERVE

flags 🔗

flags(flags: re.RegexFlag) -> Self

设置正则表达式的标志.

Parameters:

Returns:

  • Self( Self ) –

    RegexMatch 自身.

Source code in src/graia/ariadne/message/parser/twilight.py
167
168
169
170
171
172
173
174
175
176
177
def flags(self, flags: re.RegexFlag) -> Self:
    """设置正则表达式的标志.

    Args:
        flags (re.RegexFlag): 正则表达式旗标.

    Returns:
        Self: RegexMatch 自身.
    """
    self._flags = flags
    return self

space 🔗

space(space: SpacePolicy) -> Self

设置正则表达式的尾随空格策略.

Parameters:

Returns:

  • Self( Self ) –

    RegexMatch 自身.

Source code in src/graia/ariadne/message/parser/twilight.py
179
180
181
182
183
184
185
186
187
188
189
def space(self, space: SpacePolicy) -> Self:
    """设置正则表达式的尾随空格策略.

    Args:
        space (SpacePolicy): 尾随空格策略.

    Returns:
        Self: RegexMatch 自身.
    """
    self.space_policy = space
    return self

RegexResult 🔗

Bases: MatchResult[MessageChain, RegexMatch]

表示 RegexMatch 匹配结果

Source code in src/graia/ariadne/message/parser/twilight.py
417
418
419
420
class RegexResult(MatchResult[MessageChain, RegexMatch]):
    """表示 RegexMatch 匹配结果"""

    ...

ResultValue 🔗

Bases: Decorator, Derive[MessageChain]

返回 Match 结果值的装饰器

Source code in src/graia/ariadne/message/parser/twilight.py
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
class ResultValue(Decorator, Derive[MessageChain]):
    """返回 Match 结果值的装饰器"""

    pre = True

    async def __call__(self, _: Any, i: DispatcherInterface) -> Any:
        sparkle: Sparkle = i.local_storage[f"{__name__}:result"]
        res = sparkle.res.get(i.name, None)
        if res is not None:
            res = res.result
        if generic_isinstance(res, i.annotation):
            return res
        i.stop()

    @staticmethod
    async def target(i: DecoratorInterface):
        sparkle: Sparkle = i.local_storage[f"{__name__}:result"]
        res = sparkle.res.get(i.name, None)
        if res is not None:
            res = res.result
        if generic_isinstance(res, i.annotation):
            return res
        i.dispatcher_interface.stop()

SpacePolicy 🔗

Bases: str, enum.Enum

指示 RegexMatch 的尾随空格策略.

Source code in src/graia/ariadne/message/parser/twilight.py
58
59
60
61
62
63
64
65
66
67
68
69
70
class SpacePolicy(str, enum.Enum):
    """指示 RegexMatch 的尾随空格策略."""

    value: str

    NOSPACE = ""
    """禁止尾随空格"""

    PRESERVE = "( )?"
    """预留尾随空格"""

    FORCE = "( )"
    """强制尾随空格"""

FORCE class-attribute instance-attribute 🔗

FORCE = '( )'

强制尾随空格

NOSPACE class-attribute instance-attribute 🔗

NOSPACE = ''

禁止尾随空格

PRESERVE class-attribute instance-attribute 🔗

PRESERVE = '( )?'

预留尾随空格

Sparkle 🔗

Bases: Representation

Source code in src/graia/ariadne/message/parser/twilight.py
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
class Sparkle(Representation):
    """Sparkle: Twilight 的匹配容器"""

    __slots__ = ("res",)

    def __init__(self, match_result: Dict[Union[int, str], MatchResult]):
        self.res = match_result

    @overload
    def __getitem__(self, item: Union[int, str]) -> MatchResult:
        ...

    @overload
    def __getitem__(self, item: Type[int]) -> List[MatchResult]:
        ...

    @overload
    def __getitem__(self, item: Type[str]) -> Dict[str, MatchResult]:
        ...

    def __getitem__(self, item: Union[int, str, Type[int], Type[str]]):
        if not isinstance(item, type):
            return self.get(item)
        if item is int:
            return [v for k, v in self.res.items() if isinstance(k, int)]
        elif item is str:
            return {k: v for k, v in self.res.items() if isinstance(k, str)}

    def get(self, item: Union[int, str]) -> MatchResult:
        return self.res[item]

    def __repr_args__(self):
        return [(repr(k), v) for k, v in self.res.items()]

Twilight 🔗

Bases: Generic[T_Sparkle], BaseDispatcher

暮光

Source code in src/graia/ariadne/message/parser/twilight.py
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
class Twilight(Generic[T_Sparkle], BaseDispatcher):
    """暮光"""

    preprocessor: Union[ChainDecorator, AnnotatedType, None] = None

    def __init__(
        self,
        *root: Union[Iterable[Match], Match],
        map_param: Optional[Dict[str, bool]] = None,
        preprocessor: Union[ChainDecorator, AnnotatedType, None, Literal[Sentinel]] = Sentinel,
    ) -> None:
        """本魔法方法用于初始化本实例.

        Args:
            *root (Iterable[Match] | Match): 匹配规则.
            map_param (Dict[str, bool], optional): 控制 MessageChain 转化的参数.
            preprocessor (ChainDecorator, optional): 消息链预处理器. \
            应该来自 `graia.ariadne.message.parser.base` 模块. Defaults to None.
        """
        self.map_param = map_param or {}
        if preprocessor is not Sentinel:
            self.preprocessor = preprocessor
        self.help_data: Optional[_TwilightHelpArgs] = None
        self.help_id: str = TwilightHelpManager.AUTO_ID
        self.help_brief: str = TwilightHelpManager.AUTO_ID
        self.matcher: TwilightMatcher = TwilightMatcher(*root)

    def __repr__(self) -> str:
        return f"<Twilight: {self.matcher}>"

    def generate(self, chain: MessageChain, storage: Optional[Dict[str, Any]] = None) -> T_Sparkle:
        """从消息链生成 Sparkle 实例.

        Args:
            chain (MessageChain): 传入的消息链.

        Returns:
            T_Sparkle: 生成的 Sparkle 对象.
        """
        mapping_str, elem_mapping = chain._to_mapping_str(**self.map_param)
        token = elem_mapping_ctx.set(elem_mapping)
        arguments: List[str] = split(mapping_str, keep_quote=True)
        res, match = self.matcher.match(arguments, elem_mapping)
        if storage:
            storage["__parser_regex_match_obj__"] = match
            storage["__parser_regex_match_map__"] = elem_mapping
        elem_mapping_ctx.reset(token)
        return cast(T_Sparkle, Sparkle(res))

    @classmethod
    def from_command(  # ANCHOR: Sparkle: From command
        cls,
        command: str,
        extra_args: Optional[List[Match]] = None,
    ) -> "Twilight":
        """从 shell 式命令生成 Twilight.

        Args:
            command (str): 命令, 使用 {param} 或 {0} 的形式创建参数占位符. \
                使用 [a|b] 创建选择匹配. 使用 反斜杠 转义.

            extra_args (List[Match], optional): 可选的额外 Match 列表.

        Returns:
            Twilight: 生成的 Twilight.
        """
        extra_args = extra_args or []
        match: List[RegexMatch] = []

        for token in tokenize(command):
            if isinstance(token, TextToken):
                text_list = list(token.choice)
                if len(text_list) == 1:
                    match.append(FullMatch(text_list[0]).space(SpacePolicy.FORCE))
                else:
                    match.append(UnionMatch(text_list).space(SpacePolicy.FORCE))
            elif isinstance(token, ParamToken):
                assert len(token.names) == 1, "Param aliasing is not allowed!"
                match.append(ParamMatch().space(SpacePolicy.FORCE).param(next(iter(token.names))))
            else:
                raise ValueError(f"unexpected token: {token}")

        if match:
            match[-1].space_policy = SpacePolicy.NOSPACE

        return cls(*match, *extra_args)

    def help(
        self,
        usage: str = "",
        description: str = "",
        epilog: str = "",
        dest: bool = True,
        sep: str = " -> ",
        formatter_class: Type[HelpFormatter] = HelpFormatter,
        *,
        brief: Optional[str] = None,
        help_id: str = TwilightHelpManager.AUTO_ID,
        manager: Union[str, TwilightHelpManager] = "global",
    ) -> Self:
        """利用 Match 中的信息生成帮助字符串.

        Args:
            usage (str, optional): 使用方法 (命令格式).
            description (str, optional): 前导描述. Defaults to "".
            epilog (str, optional): 后置总结. Defaults to "".
            dest (bool, optional): 是否显示分派位置. Defaults to True.
            sep (str, optional): 分派位置之间的分隔符. Defaults to " -> ".
            formatter_class (Type[HelpFormatter], optional): 帮助格式化器. Defaults to HelpFormatter.
            help_id (str, optional): 帮助 id. 默认为自动生成 (推荐自行指定).
            brief (str, optional): 简要介绍, 默认与 description 相同.
            manager (str, optional): 帮助信息管理器. 默认 "global" (全局管理器).

        Returns:
            str: 生成的帮助字符串, 被格式化与缩进过了
        """
        self.help_data = {
            "usage": usage,
            "description": description,
            "epilog": epilog,
            "dest": dest,
            "sep": sep,
            "formatter_class": formatter_class,
        }
        self.help_id = help_id
        self.help_brief = brief or description
        help_mgr = TwilightHelpManager.get_help_mgr(manager)
        help_mgr.register(self)
        return self

    def get_help(
        self,
        usage: str = "",
        description: str = "",
        epilog: str = "",
        dest: bool = True,
        sep: str = " -> ",
        formatter_class: Type[HelpFormatter] = HelpFormatter,
    ) -> str:
        """利用 Match 中的信息生成帮助字符串.

        Args:
            usage (str, optional): 使用方法 (命令格式).
            description (str, optional): 前导描述. Defaults to "".
            epilog (str, optional): 后置总结. Defaults to "".
            dest (bool, optional): 是否显示分派位置. Defaults to True.
            sep (str, optional): 分派位置分隔符. Defaults to " -> ".
            formatter_class (Type[HelpFormatter], optional): 帮助格式化器. Defaults to HelpFormatter.

        Returns:
            str: 生成的帮助字符串, 被格式化与缩进过了
        """
        if self.help_data:
            return self.matcher.get_help(**self.help_data)
        return self.matcher.get_help(usage, description, epilog, dest, sep, formatter_class)

    async def beforeExecution(self, interface: DispatcherInterface):
        """检验 MessageChain 并将 Sparkle 存入本地存储

        Args:
            interface (DispatcherInterface): DispatcherInterface, 应该能从中提取 MessageChain

        Raises:
            ExecutionStop: 匹配以任意方式失败
        """
        local_storage = interface.local_storage
        chain: MessageChain
        if isinstance(self.preprocessor, ChainDecorator):
            chain = await interface.lookup_by_directly(
                DecoratorInterface(), "message_chain", MessageChain, self.preprocessor
            )
        elif isinstance(self.preprocessor, AnnotatedType):
            chain = await interface.lookup_by_directly(
                DeriveDispatcher(), "twilight_derive", self.preprocessor, None
            )
        else:
            chain = await interface.lookup_param("message_chain", MessageChain, None)
        with contextlib.suppress(Exception):
            local_storage[f"{__name__}:result"] = self.generate(chain, local_storage)
            local_storage[f"{__name__}:twilight"] = self
            return
        interface.stop()

    async def catch(self, interface: DispatcherInterface):
        local_storage = interface.local_storage
        sparkle: T_Sparkle = local_storage[f"{__name__}:result"]
        if generic_issubclass(Sparkle, interface.annotation):
            return sparkle
        if generic_issubclass(Twilight, interface.annotation):
            return self
        if interface.name in sparkle.res:
            result = sparkle.get(interface.name)
            if generic_isinstance(result.origin, interface.annotation):
                from loguru import logger

                logger.warning(
                    f"Please use {interface.name}: {result.__class__.__qualname__} to get origin attribute!"
                )
                interface.stop()
            if generic_issubclass(get_origin(interface.annotation), MatchResult):
                return result
            if generic_isinstance(result.result, get_origin(interface.annotation)):
                return result.result

__init__ 🔗

__init__(
    *root: Union[Iterable[Match], Match],
    map_param: Optional[Dict[str, bool]] = None,
    preprocessor: Union[
        ChainDecorator, AnnotatedType, None, Literal[Sentinel]
    ] = Sentinel
) -> None

本魔法方法用于初始化本实例.

Parameters:

  • *root (Iterable[Match] | Match) –

    匹配规则.

  • map_param (Dict[str, bool]) –

    控制 MessageChain 转化的参数.

  • preprocessor (ChainDecorator) –

    消息链预处理器. 应该来自 graia.ariadne.message.parser.base 模块. Defaults to None.

Source code in src/graia/ariadne/message/parser/twilight.py
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
def __init__(
    self,
    *root: Union[Iterable[Match], Match],
    map_param: Optional[Dict[str, bool]] = None,
    preprocessor: Union[ChainDecorator, AnnotatedType, None, Literal[Sentinel]] = Sentinel,
) -> None:
    """本魔法方法用于初始化本实例.

    Args:
        *root (Iterable[Match] | Match): 匹配规则.
        map_param (Dict[str, bool], optional): 控制 MessageChain 转化的参数.
        preprocessor (ChainDecorator, optional): 消息链预处理器. \
        应该来自 `graia.ariadne.message.parser.base` 模块. Defaults to None.
    """
    self.map_param = map_param or {}
    if preprocessor is not Sentinel:
        self.preprocessor = preprocessor
    self.help_data: Optional[_TwilightHelpArgs] = None
    self.help_id: str = TwilightHelpManager.AUTO_ID
    self.help_brief: str = TwilightHelpManager.AUTO_ID
    self.matcher: TwilightMatcher = TwilightMatcher(*root)

beforeExecution async 🔗

beforeExecution(interface: DispatcherInterface)

检验 MessageChain 并将 Sparkle 存入本地存储

Parameters:

  • interface (DispatcherInterface) –

    DispatcherInterface, 应该能从中提取 MessageChain

Raises:

  • ExecutionStop

    匹配以任意方式失败

Source code in src/graia/ariadne/message/parser/twilight.py
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
async def beforeExecution(self, interface: DispatcherInterface):
    """检验 MessageChain 并将 Sparkle 存入本地存储

    Args:
        interface (DispatcherInterface): DispatcherInterface, 应该能从中提取 MessageChain

    Raises:
        ExecutionStop: 匹配以任意方式失败
    """
    local_storage = interface.local_storage
    chain: MessageChain
    if isinstance(self.preprocessor, ChainDecorator):
        chain = await interface.lookup_by_directly(
            DecoratorInterface(), "message_chain", MessageChain, self.preprocessor
        )
    elif isinstance(self.preprocessor, AnnotatedType):
        chain = await interface.lookup_by_directly(
            DeriveDispatcher(), "twilight_derive", self.preprocessor, None
        )
    else:
        chain = await interface.lookup_param("message_chain", MessageChain, None)
    with contextlib.suppress(Exception):
        local_storage[f"{__name__}:result"] = self.generate(chain, local_storage)
        local_storage[f"{__name__}:twilight"] = self
        return
    interface.stop()

from_command classmethod 🔗

from_command(
    command: str, extra_args: Optional[List[Match]] = None
) -> Twilight

从 shell 式命令生成 Twilight.

Parameters:

  • command (str) –

    命令, 使用 {param} 或 {0} 的形式创建参数占位符. 使用 [a|b] 创建选择匹配. 使用 反斜杠 转义.

  • extra_args (List[Match]) –

    可选的额外 Match 列表.

Returns:

  • Twilight( Twilight ) –

    生成的 Twilight.

Source code in src/graia/ariadne/message/parser/twilight.py
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
@classmethod
def from_command(  # ANCHOR: Sparkle: From command
    cls,
    command: str,
    extra_args: Optional[List[Match]] = None,
) -> "Twilight":
    """从 shell 式命令生成 Twilight.

    Args:
        command (str): 命令, 使用 {param} 或 {0} 的形式创建参数占位符. \
            使用 [a|b] 创建选择匹配. 使用 反斜杠 转义.

        extra_args (List[Match], optional): 可选的额外 Match 列表.

    Returns:
        Twilight: 生成的 Twilight.
    """
    extra_args = extra_args or []
    match: List[RegexMatch] = []

    for token in tokenize(command):
        if isinstance(token, TextToken):
            text_list = list(token.choice)
            if len(text_list) == 1:
                match.append(FullMatch(text_list[0]).space(SpacePolicy.FORCE))
            else:
                match.append(UnionMatch(text_list).space(SpacePolicy.FORCE))
        elif isinstance(token, ParamToken):
            assert len(token.names) == 1, "Param aliasing is not allowed!"
            match.append(ParamMatch().space(SpacePolicy.FORCE).param(next(iter(token.names))))
        else:
            raise ValueError(f"unexpected token: {token}")

    if match:
        match[-1].space_policy = SpacePolicy.NOSPACE

    return cls(*match, *extra_args)

generate 🔗

generate(
    chain: MessageChain, storage: Optional[Dict[str, Any]] = None
) -> T_Sparkle

从消息链生成 Sparkle 实例.

Parameters:

Returns:

  • T_Sparkle( T_Sparkle ) –

    生成的 Sparkle 对象.

Source code in src/graia/ariadne/message/parser/twilight.py
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
def generate(self, chain: MessageChain, storage: Optional[Dict[str, Any]] = None) -> T_Sparkle:
    """从消息链生成 Sparkle 实例.

    Args:
        chain (MessageChain): 传入的消息链.

    Returns:
        T_Sparkle: 生成的 Sparkle 对象.
    """
    mapping_str, elem_mapping = chain._to_mapping_str(**self.map_param)
    token = elem_mapping_ctx.set(elem_mapping)
    arguments: List[str] = split(mapping_str, keep_quote=True)
    res, match = self.matcher.match(arguments, elem_mapping)
    if storage:
        storage["__parser_regex_match_obj__"] = match
        storage["__parser_regex_match_map__"] = elem_mapping
    elem_mapping_ctx.reset(token)
    return cast(T_Sparkle, Sparkle(res))

get_help 🔗

get_help(
    usage: str = "",
    description: str = "",
    epilog: str = "",
    dest: bool = True,
    sep: str = " -> ",
    formatter_class: Type[HelpFormatter] = HelpFormatter,
) -> str

利用 Match 中的信息生成帮助字符串.

Parameters:

  • usage (str) –

    使用方法 (命令格式).

  • description (str) –

    前导描述. Defaults to "".

  • epilog (str) –

    后置总结. Defaults to "".

  • dest (bool) –

    是否显示分派位置. Defaults to True.

  • sep (str) –

    分派位置分隔符. Defaults to " -> ".

  • formatter_class (Type[HelpFormatter]) –

    帮助格式化器. Defaults to HelpFormatter.

Returns:

  • str( str ) –

    生成的帮助字符串, 被格式化与缩进过了

Source code in src/graia/ariadne/message/parser/twilight.py
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
def get_help(
    self,
    usage: str = "",
    description: str = "",
    epilog: str = "",
    dest: bool = True,
    sep: str = " -> ",
    formatter_class: Type[HelpFormatter] = HelpFormatter,
) -> str:
    """利用 Match 中的信息生成帮助字符串.

    Args:
        usage (str, optional): 使用方法 (命令格式).
        description (str, optional): 前导描述. Defaults to "".
        epilog (str, optional): 后置总结. Defaults to "".
        dest (bool, optional): 是否显示分派位置. Defaults to True.
        sep (str, optional): 分派位置分隔符. Defaults to " -> ".
        formatter_class (Type[HelpFormatter], optional): 帮助格式化器. Defaults to HelpFormatter.

    Returns:
        str: 生成的帮助字符串, 被格式化与缩进过了
    """
    if self.help_data:
        return self.matcher.get_help(**self.help_data)
    return self.matcher.get_help(usage, description, epilog, dest, sep, formatter_class)

help 🔗

help(
    usage: str = "",
    description: str = "",
    epilog: str = "",
    dest: bool = True,
    sep: str = " -> ",
    formatter_class: Type[HelpFormatter] = HelpFormatter,
    *,
    brief: Optional[str] = None,
    help_id: str = TwilightHelpManager.AUTO_ID,
    manager: Union[str, TwilightHelpManager] = "global"
) -> Self

利用 Match 中的信息生成帮助字符串.

Parameters:

  • usage (str) –

    使用方法 (命令格式).

  • description (str) –

    前导描述. Defaults to "".

  • epilog (str) –

    后置总结. Defaults to "".

  • dest (bool) –

    是否显示分派位置. Defaults to True.

  • sep (str) –

    分派位置之间的分隔符. Defaults to " -> ".

  • formatter_class (Type[HelpFormatter]) –

    帮助格式化器. Defaults to HelpFormatter.

  • help_id (str) –

    帮助 id. 默认为自动生成 (推荐自行指定).

  • brief (str) –

    简要介绍, 默认与 description 相同.

  • manager (str) –

    帮助信息管理器. 默认 "global" (全局管理器).

Returns:

  • str( Self ) –

    生成的帮助字符串, 被格式化与缩进过了

Source code in src/graia/ariadne/message/parser/twilight.py
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
def help(
    self,
    usage: str = "",
    description: str = "",
    epilog: str = "",
    dest: bool = True,
    sep: str = " -> ",
    formatter_class: Type[HelpFormatter] = HelpFormatter,
    *,
    brief: Optional[str] = None,
    help_id: str = TwilightHelpManager.AUTO_ID,
    manager: Union[str, TwilightHelpManager] = "global",
) -> Self:
    """利用 Match 中的信息生成帮助字符串.

    Args:
        usage (str, optional): 使用方法 (命令格式).
        description (str, optional): 前导描述. Defaults to "".
        epilog (str, optional): 后置总结. Defaults to "".
        dest (bool, optional): 是否显示分派位置. Defaults to True.
        sep (str, optional): 分派位置之间的分隔符. Defaults to " -> ".
        formatter_class (Type[HelpFormatter], optional): 帮助格式化器. Defaults to HelpFormatter.
        help_id (str, optional): 帮助 id. 默认为自动生成 (推荐自行指定).
        brief (str, optional): 简要介绍, 默认与 description 相同.
        manager (str, optional): 帮助信息管理器. 默认 "global" (全局管理器).

    Returns:
        str: 生成的帮助字符串, 被格式化与缩进过了
    """
    self.help_data = {
        "usage": usage,
        "description": description,
        "epilog": epilog,
        "dest": dest,
        "sep": sep,
        "formatter_class": formatter_class,
    }
    self.help_id = help_id
    self.help_brief = brief or description
    help_mgr = TwilightHelpManager.get_help_mgr(manager)
    help_mgr.register(self)
    return self

TwilightMatcher 🔗

Twilight 匹配器

Source code in src/graia/ariadne/message/parser/twilight.py
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
class TwilightMatcher:
    """Twilight 匹配器"""

    def __init__(self, *root: Union[Iterable[Match], Match]):
        self.origin_match_list: List[Match] = []
        self._parser = TwilightParser(prog="", add_help=False)
        self._dest_map: Dict[str, ArgumentMatch] = {}
        self._group_map: Dict[int, RegexMatch] = {}
        self.dispatch_ref: Dict[Union[int, str], Match] = {}
        self.match_ref: DefaultDict[Type[Match], List[Match]] = DefaultDict(list)

        regex_str_list: List[str] = []
        regex_group_cnt: int = 0

        for i in root:
            if isinstance(i, Match):
                i = [i]
            self.origin_match_list.extend(i)
            for m in i:
                if isinstance(m, RegexMatch):
                    self.match_ref[RegexMatch].append(m)
                    if m.dest:
                        self._group_map[regex_group_cnt + 1] = m
                    regex_str_list.append(m._regex_str)
                    regex_group_cnt += re.compile(m._regex_str).groups

                elif isinstance(m, ArgumentMatch):
                    self.match_ref[ArgumentMatch].append(m)
                    if (
                        "action" in m.arg_data
                        and "type" in m.arg_data
                        and not self._parser.accept_type(m.arg_data["action"])
                    ):
                        del m.arg_data["type"]
                    action = self._parser.add_argument(*m.pattern, **m.arg_data)
                    if m.dest:
                        self._dest_map[action.dest] = m

                if m.dest:
                    if m.dest in self.dispatch_ref:
                        raise NameError(f"duplicate dispatch name: {m.dest}")
                    self.dispatch_ref[m.dest] = m

        self._regex_pattern: re.Pattern = re.compile("".join(regex_str_list))

    def match(
        self, arguments: List[str], elem_mapping: Dict[str, Element]
    ) -> Tuple[Dict[Union[int, str], MatchResult], re.Match]:
        """匹配参数
        Args:
            arguments (List[str]): 参数列表
            elem_mapping (Dict[str, Element]): 元素映射

        Returns:
            Dict[Union[int, str], MatchResult]: 匹配结果
        """
        result: Dict[Union[int, str], MatchResult] = {}
        if self._dest_map:
            namespace, arguments = self._parser.parse_known_args(arguments)
            nbsp_dict: Dict[str, Any] = namespace.__dict__
            for k, v in self._dest_map.items():
                res = nbsp_dict.get(k, Unmatched)
                result[v.dest] = MatchResult(res is not Unmatched, v, res)
        if not (total_match := self._regex_pattern.fullmatch(" ".join(arguments))):
            raise ValueError(f"{' '.join(arguments)} not matching {self._regex_pattern.pattern}")
        for index, match in self._group_map.items():
            group: Optional[str] = total_match.group(index)
            if group is None:
                res = None
            else:
                res = (
                    elem_mapping[group[1:-1].split("_")[0]]
                    if isinstance(match, ElementMatch)
                    else MessageChain._from_mapping_string(group, elem_mapping)
                )

            if match.dest:
                if isinstance(match, WildcardMatch):
                    result[match.dest] = MatchResult(bool(res), match, res)
                else:
                    result[match.dest] = MatchResult(group is not None, match, res)
        return result, total_match

    def get_help(
        self,
        usage: str = "",
        description: str = "",
        epilog: str = "",
        dest: bool = True,
        sep: str = " -> ",
        formatter_class: Type[HelpFormatter] = HelpFormatter,
    ) -> str:
        """利用 Match 中的信息生成帮助字符串.

        Args:
            usage (str, optional): 使用方法 (命令格式).
            description (str, optional): 前导描述. Defaults to "".
            epilog (str, optional): 后置总结. Defaults to "".
            dest (bool, optional): 是否显示分派位置. Defaults to True.
            sep (str, optional): 分派位置分隔符. Defaults to " -> ".
            formatter_class (Type[HelpFormatter], optional): 帮助格式化器. Defaults to HelpFormatter.

        Returns:
            str: 生成的帮助字符串, 被格式化与缩进过了
        """
        formatter = formatter_class(prog="")

        if usage:
            formatter.add_usage(None, self._parser._actions, [], prefix=f"{usage} ")

        formatter.add_text(description)

        _, optional, *_ = self._parser._action_groups

        if self.match_ref[RegexMatch]:
            formatter.start_section("匹配项")
            for match in self.match_ref[RegexMatch]:
                if match._help:
                    formatter.add_text(
                        f"""{ f"{match.dest}{sep}" if dest and match.dest else ""}{match._help}"""
                    )
            formatter.end_section()

        if self.match_ref[ArgumentMatch]:
            formatter.start_section("可选参数")
            formatter.add_arguments(optional._group_actions)
            formatter.end_section()

        formatter.add_text(epilog)

        # determine help from format above
        return formatter.format_help()

    def __repr__(self) -> str:
        return f"<Matcher {list(self._group_map.values()) + list(self._dest_map.values())!r}>"  # type: ignore

    def __str__(self) -> str:
        return repr(list(self._group_map.values()) + list(self._dest_map.values()))  # type: ignore

get_help 🔗

get_help(
    usage: str = "",
    description: str = "",
    epilog: str = "",
    dest: bool = True,
    sep: str = " -> ",
    formatter_class: Type[HelpFormatter] = HelpFormatter,
) -> str

利用 Match 中的信息生成帮助字符串.

Parameters:

  • usage (str) –

    使用方法 (命令格式).

  • description (str) –

    前导描述. Defaults to "".

  • epilog (str) –

    后置总结. Defaults to "".

  • dest (bool) –

    是否显示分派位置. Defaults to True.

  • sep (str) –

    分派位置分隔符. Defaults to " -> ".

  • formatter_class (Type[HelpFormatter]) –

    帮助格式化器. Defaults to HelpFormatter.

Returns:

  • str( str ) –

    生成的帮助字符串, 被格式化与缩进过了

Source code in src/graia/ariadne/message/parser/twilight.py
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
def get_help(
    self,
    usage: str = "",
    description: str = "",
    epilog: str = "",
    dest: bool = True,
    sep: str = " -> ",
    formatter_class: Type[HelpFormatter] = HelpFormatter,
) -> str:
    """利用 Match 中的信息生成帮助字符串.

    Args:
        usage (str, optional): 使用方法 (命令格式).
        description (str, optional): 前导描述. Defaults to "".
        epilog (str, optional): 后置总结. Defaults to "".
        dest (bool, optional): 是否显示分派位置. Defaults to True.
        sep (str, optional): 分派位置分隔符. Defaults to " -> ".
        formatter_class (Type[HelpFormatter], optional): 帮助格式化器. Defaults to HelpFormatter.

    Returns:
        str: 生成的帮助字符串, 被格式化与缩进过了
    """
    formatter = formatter_class(prog="")

    if usage:
        formatter.add_usage(None, self._parser._actions, [], prefix=f"{usage} ")

    formatter.add_text(description)

    _, optional, *_ = self._parser._action_groups

    if self.match_ref[RegexMatch]:
        formatter.start_section("匹配项")
        for match in self.match_ref[RegexMatch]:
            if match._help:
                formatter.add_text(
                    f"""{ f"{match.dest}{sep}" if dest and match.dest else ""}{match._help}"""
                )
        formatter.end_section()

    if self.match_ref[ArgumentMatch]:
        formatter.start_section("可选参数")
        formatter.add_arguments(optional._group_actions)
        formatter.end_section()

    formatter.add_text(epilog)

    # determine help from format above
    return formatter.format_help()

match 🔗

match(
    arguments: List[str], elem_mapping: Dict[str, Element]
) -> Tuple[Dict[Union[int, str], MatchResult], re.Match]

匹配参数

Parameters:

Returns:

Source code in src/graia/ariadne/message/parser/twilight.py
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
def match(
    self, arguments: List[str], elem_mapping: Dict[str, Element]
) -> Tuple[Dict[Union[int, str], MatchResult], re.Match]:
    """匹配参数
    Args:
        arguments (List[str]): 参数列表
        elem_mapping (Dict[str, Element]): 元素映射

    Returns:
        Dict[Union[int, str], MatchResult]: 匹配结果
    """
    result: Dict[Union[int, str], MatchResult] = {}
    if self._dest_map:
        namespace, arguments = self._parser.parse_known_args(arguments)
        nbsp_dict: Dict[str, Any] = namespace.__dict__
        for k, v in self._dest_map.items():
            res = nbsp_dict.get(k, Unmatched)
            result[v.dest] = MatchResult(res is not Unmatched, v, res)
    if not (total_match := self._regex_pattern.fullmatch(" ".join(arguments))):
        raise ValueError(f"{' '.join(arguments)} not matching {self._regex_pattern.pattern}")
    for index, match in self._group_map.items():
        group: Optional[str] = total_match.group(index)
        if group is None:
            res = None
        else:
            res = (
                elem_mapping[group[1:-1].split("_")[0]]
                if isinstance(match, ElementMatch)
                else MessageChain._from_mapping_string(group, elem_mapping)
            )

        if match.dest:
            if isinstance(match, WildcardMatch):
                result[match.dest] = MatchResult(bool(res), match, res)
            else:
                result[match.dest] = MatchResult(group is not None, match, res)
    return result, total_match

UnionMatch 🔗

Bases: RegexMatch

多重匹配

Source code in src/graia/ariadne/message/parser/twilight.py
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
class UnionMatch(RegexMatch):
    """多重匹配"""

    pattern: List[str]
    """匹配的选择项"""

    def __init__(
        self,
        *pattern: Union[str, Iterable[str]],
        optional: bool = False,
    ) -> None:
        """初始化 UnionMatch 对象.

        Args:
            *pattern (Union[str, Iterable[str]]): 匹配的选择项.
            optional (bool, optional): 匹配是否可选. Defaults to False.
        """
        super().__init__("", optional)
        self.pattern: List[str] = []
        for p in pattern:
            if isinstance(p, str):
                self.pattern.append(p)
            else:
                self.pattern.extend(p)
        self.optional = optional
        self.help(f"在 {self.pattern} 中选择一项")

    @property
    def _src(self) -> str:
        return f"{'|'.join(re.escape(i) for i in self.pattern)}"

pattern instance-attribute 🔗

pattern: List[str] = []

匹配的选择项

__init__ 🔗

__init__(*pattern: Union[str, Iterable[str]], optional: bool = False) -> None

初始化 UnionMatch 对象.

Parameters:

  • *pattern (Union[str, Iterable[str]]) –

    匹配的选择项.

  • optional (bool) –

    匹配是否可选. Defaults to False.

Source code in src/graia/ariadne/message/parser/twilight.py
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
def __init__(
    self,
    *pattern: Union[str, Iterable[str]],
    optional: bool = False,
) -> None:
    """初始化 UnionMatch 对象.

    Args:
        *pattern (Union[str, Iterable[str]]): 匹配的选择项.
        optional (bool, optional): 匹配是否可选. Defaults to False.
    """
    super().__init__("", optional)
    self.pattern: List[str] = []
    for p in pattern:
        if isinstance(p, str):
            self.pattern.append(p)
        else:
            self.pattern.extend(p)
    self.optional = optional
    self.help(f"在 {self.pattern} 中选择一项")

WildcardMatch 🔗

Bases: RegexMatch

泛匹配

Source code in src/graia/ariadne/message/parser/twilight.py
298
299
300
301
302
303
304
305
306
307
308
class WildcardMatch(RegexMatch):
    """泛匹配"""

    def __init__(self, greed: bool = True, optional: bool = False) -> None:
        """初始化 WildcardMatch 对象.

        Args:
            greed (bool, optional): 是否贪婪匹配. Defaults to True.
            optional (bool, optional): 匹配是否可选. Defaults to False.
        """
        super().__init__(f".*{'' if greed else'?'}", optional)

__init__ 🔗

__init__(greed: bool = True, optional: bool = False) -> None

初始化 WildcardMatch 对象.

Parameters:

  • greed (bool) –

    是否贪婪匹配. Defaults to True.

  • optional (bool) –

    匹配是否可选. Defaults to False.

Source code in src/graia/ariadne/message/parser/twilight.py
301
302
303
304
305
306
307
308
def __init__(self, greed: bool = True, optional: bool = False) -> None:
    """初始化 WildcardMatch 对象.

    Args:
        greed (bool, optional): 是否贪婪匹配. Defaults to True.
        optional (bool, optional): 匹配是否可选. Defaults to False.
    """
    super().__init__(f".*{'' if greed else'?'}", optional)