Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/prompt_toolkit/contrib/regular_languages/__init__.py: 100%

1r""" 

2Tool for expressing the grammar of an input as a regular language. 

3================================================================== 

4 

5The grammar for the input of many simple command line interfaces can be 

6expressed by a regular language. Examples are PDB (the Python debugger); a 

7simple (bash-like) shell with "pwd", "cd", "cat" and "ls" commands; arguments 

8that you can pass to an executable; etc. It is possible to use regular 

9expressions for validation and parsing of such a grammar. (More about regular 

10languages: http://en.wikipedia.org/wiki/Regular_language) 

11 

12Example 

13------- 

14 

15Let's take the pwd/cd/cat/ls example. We want to have a shell that accepts 

16these three commands. "cd" is followed by a quoted directory name and "cat" is 

17followed by a quoted file name. (We allow quotes inside the filename when 

18they're escaped with a backslash.) We could define the grammar using the 

19following regular expression:: 

20 

21 grammar = \s* ( 

22 pwd | 

23 ls | 

24 (cd \s+ " ([^"]|\.)+ ") | 

25 (cat \s+ " ([^"]|\.)+ ") 

26 ) \s* 

27 

28 

29What can we do with this grammar? 

30--------------------------------- 

31 

32- Syntax highlighting: We could use this for instance to give file names 

33 different color. 

34- Parse the result: .. We can extract the file names and commands by using a 

35 regular expression with named groups. 

36- Input validation: .. Don't accept anything that does not match this grammar. 

37 When combined with a parser, we can also recursively do 

38 filename validation (and accept only existing files.) 

39- Autocompletion: .... Each part of the grammar can have its own autocompleter. 

40 "cat" has to be completed using file names, while "cd" 

41 has to be completed using directory names. 

42 

43How does it work? 

44----------------- 

45 

46As a user of this library, you have to define the grammar of the input as a 

47regular expression. The parts of this grammar where autocompletion, validation 

48or any other processing is required need to be marked using a regex named 

49group. Like ``(?P<varname>...)`` for instance. 

50 

51When the input is processed for validation (for instance), the regex will 

52execute, the named group is captured, and the validator associated with this 

53named group will test the captured string. 

54 

55There is one tricky bit: 

56 

57 Often we operate on incomplete input (this is by definition the case for 

58 autocompletion) and we have to decide for the cursor position in which 

59 possible state the grammar it could be and in which way variables could be 

60 matched up to that point. 

61 

62To solve this problem, the compiler takes the original regular expression and 

63translates it into a set of other regular expressions which each match certain 

64prefixes of the original regular expression. We generate one prefix regular 

65expression for every named variable (with this variable being the end of that 

66expression). 

67 

68 

69TODO: some examples of: 

70 - How to create a highlighter from this grammar. 

71 - How to create a validator from this grammar. 

72 - How to create an autocompleter from this grammar. 

73 - How to create a parser from this grammar. 

74""" 

75from __future__ import annotations 

76 

77from .compiler import compile 

78 

79__all__ = ["compile"]