www/users_guide/parserInstructions.rst


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

Instructions to the Parser/Compiler
===================================

(parserInstructions)

#breakpoint
-----------

(parserInstructions.breakpoint)

Syntax:

::

    #breakpoint

{#breakpoint} is a debugging tool that tells the parser to stop
parsing at a specific point. All source code from that point on
will be ignored.

The difference between {#breakpoint} and {#stop} is that {#stop}
occurs in normal templates (e.g., inside an {#if}) but
{#breakpoint} is used only when debugging Cheetah. Another
difference is that {#breakpoint} operates at compile time, while
{#stop} is executed at run time while filling the template.

#compiler-settings
------------------

(parserInstructions.compiler-settings)

Syntax:

::

    #compiler-settings
    key = value    (no quotes)
    #end compiler-settings
    
    #compiler-settings reset

The {#compiler-settings} directive overrides Cheetah's standard
settings, changing how it parses source code and generates Python
code. This makes it possible to change the behaviour of Cheetah's
parser/compiler for a certain template, or within a portion of the
template.

The {reset} argument reverts to the default settings. With {reset},
there's no end tag.

Here are some examples of what you can do:

::

    $myVar
    #compiler-settings
    cheetahVarStartToken = @
    #end compiler-settings
    @myVar
    #compiler-settings reset
    $myVar

::

    ## normal comment
    #compiler-settings
    commentStartToken = //
    #end compiler-settings
    
    // new style of comment
    
    #compiler-settings reset
    
    ## back to normal comments

::

    #slurp
    #compiler-settings
    directiveStartToken = %
    #end compiler-settings
    
    %slurp
    %compiler-settings reset
    
    #slurp

Here's a partial list of the settings you can change:


#. syntax settings

   
   #. cheetahVarStartToken

   #. commentStartToken

   #. multilineCommentStartToken

   #. multilineCommentEndToken

   #. directiveStartToken

   #. directiveEndToken


#. code generation settings

   
   #. commentOffset

   #. outputRowColComments

   #. defDocStrMsg

   #. useNameMapper

   #. useAutocalling

   #. reprShortStrConstants

   #. reprNewlineThreshold


The meaning of these settings and their default values will be
documented in the future.