Escaping Mechanisms¶

Upon tinkering with writing blog posts through paxter.author subpackage, we would eventually find out some technical limitations with the command syntax in Paxter language. On this page, we discuss these limitations.

Escaping ‘@’¶

As readers have already noticed that ‘@’ symbol has special meaning in Paxter language: it acts as a switch which turns the subsequence piece of source text into a command. Therefore, if Paxter library users wish to include ‘@’ string literal as-is in the final HTML output, an escape of some sort is required.

… except that the core Paxter language specification actually does not provide a way to escape ‘@’ symbols per se. However, there are a few ways around this.

Method 1: Define Constants For ‘@’¶

We will take advantage of being able to run python code within the source text. Specifically, we will define a variable to store the @ symbol character.

@python##"
at = '@'
"##
This is the @bold{at} symbol: @at.

<p>This is the <b>at</b> symbol: @.</p>

But this method would not work when you wish to write an email address or a twitter handle. For this, additional bar-delimiters surrounding the phrase is needed (see the next section of this page for more information).

@python##"
at = '@'
"##
Email me at @link["mailto:person@example.com"]{person@|at|example.com}
and my twitter handle is @|at|example. Don’t @at me.

<p>Email me at <a href="mailto:person@example.com">person@example.com</a>
   and my twitter handle is @example. Don’t @ me.</p>

Method 2: Using `@verb` Command¶

The pre-defined @verb command (short for verbatim) accepts a string argument and returns it as-is. Here is an example of how to author the same document from the previous example.

Email me at @link["mailto:person@example.com"]{@verb##"person@example.com"##}
and my twitter handle is @verb"@"example. @verb"Don’t @ me".

<p>Email me at <a href="mailto:person@example.com">person@example.com</a>
   and my twitter handle is @example. Don’t @ me.</p>

Method 3: Using Symbol-Only Command¶

Recall the Pre-defined Raw HTML section from a past page. We have the commands @\, @%, @., and @, as shortcuts for some raw HTML strings. In fact, commands under the symbol-only form may represent other kinds of objects as well. Particularly in paxter.author subpackage, we can display the string ‘@’ through the command @@.

Suppose we wish to include an email address in a blog post. Here is an example of the source text:

Email me at @link["mailto:person@example.com"]{person@@example.com}
and my twitter handle is @@example. Don’t @@ me.

The above source text gets transformed into the following HTML output.

<p>Email me at <a href="mailto:person@example.com">person@example.com</a>
   and my twitter handle is @example. Don’t @ me.</p>

What would happen if we forgot to double the @ symbol? Consider the following example source text.

Email me at @link["mailto:person@example.com"]{person@@example.com}
and my twitter handle is @example. Don’t @@ me.

Parsing the above source text would yield the following error. Essentially, the @example command at line 2 column 27 is an unknown command. (The stack trace may be long and scary. It is totally to skim over it.)

Traceback (most recent call last):
  File ".../paxter/src/paxter/evaluate/context.py", line 149, in transform_command
    phrase_value = phrase_eval(token.phrase, self.env)
  File ".../paxter/src/paxter/author/standards.py", line 31, in phrase_unsafe_eval
    return eval(phrase, env)
  File "<string>", line 1, in <module>
NameError: name 'example' is not defined

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File ".../paxter/venv/bin/paxter", line 33, in <module>
    sys.exit(load_entry_point('paxter', 'console_scripts', 'paxter')())
  File ".../paxter/venv/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File ".../paxter/venv/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File ".../paxter/venv/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File ".../paxter/venv/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File ".../paxter/venv/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File ".../paxter/src/paxter/__main__.py", line 99, in run_html
    document = run_document_paxter(src_text, env)
  File ".../paxter/src/paxter/author/preset.py", line 34, in run_document_paxter
    evaluate_context = EvaluateContext(src_text, env, parse_context.tree)
  File "<string>", line 6, in __init__
  File ".../paxter/src/paxter/evaluate/context.py", line 40, in __post_init__
    self.rendered = self.render()
  File ".../paxter/src/paxter/evaluate/context.py", line 43, in render
    return self.transform_fragment_list(self.tree)
  File ".../paxter/src/paxter/evaluate/context.py", line 120, in transform_fragment_list
    result = [
  File ".../paxter/src/paxter/evaluate/context.py", line 120, in <listcomp>
    result = [
  File ".../paxter/src/paxter/evaluate/context.py", line 117, in <genexpr>
    self.transform_fragment(fragment)
  File ".../paxter/src/paxter/evaluate/context.py", line 73, in transform_fragment
    return self.transform_command(fragment)
  File ".../paxter/src/paxter/evaluate/context.py", line 153, in transform_command
    raise PaxterRenderError(
paxter.exceptions.PaxterRenderError: paxter command phrase evaluation error at line 2 col 27: 'example'

Escaping Delimiters: Curly Braces, Quotes, and Bars¶

Under Construction

This section is under construction.