merged branch arnaud-lb/line-numbers (PR #353)

Commits
-------

5ec1955 added {% line \d+ %} directive

Discussion
----------

added {% line \d+ %} directive

This directive allows to change the current line number in the tokenizer.

This allows to generate Twig code from some other Twig or partially-Twig script, and still get relevant line numbers in error messages, when the line numbers of the generated Twig script do not match those of the original script.

For example in the following script:

    foo
    {% line 10 %}
    bar
    {{ baz }}

`"foo"` is on line 1, `"bar"` is considered to be on line 10 and `{{ baz }}` is considered to be on line 11.

This is similar to `# line ...` directives in C.

---------------------------------------------------------------------------

by nikic at 2011/06/05 08:51:20 -0700

I don't quite yet understand it's use cases.

---------------------------------------------------------------------------

by arnaud-lb at 2011/06/05 09:17:57 -0700

The `{% line ... %}` directive is not meant to be used by humans, but rather by generators.

The use case is the same as [#line directives in C](http://gcc.gnu.org/onlinedocs/cpp/Line-Control.html): when you generate a C file from a template, you would prefer that the compiler refers to the line number of the template, instead of the line number of the generated file.

In my case, I built a [HAML compiler for php](https://github.com/arnaud-lb/MtHaml) which can target Twig as an output language. I use it as a Twig pre-processor so that it translates HAML scripts to Twig scripts on the fly in a custom Twig_Loader.

So I have scripts like that:

    %p
      test
    %div = foo.bar

which is compiled like that:

    <p>
      test
    </p>
    <div>
       {{ foo.bar }}
    </div>

If an error occurs in the execution of {{ foo.bar }}, Twig will throw an error refering to line 5 in the original script, which is wrong. A simple solution to this is the {% line %} directive:

    <p>
      test
    </p>
    <div>
    {% line 3 %}
       {{ foo.bar }}
    </div>

Now if an error occures in {{ foo.bar }}, the error will refer to line 3.

---------------------------------------------------------------------------

by nikic at 2011/06/05 09:33:26 -0700

Ah, okay, seems reasonable. Though I'm not sure whether it is appropriate to use the comment syntax to accomplish that.

---------------------------------------------------------------------------

by arnaud-lb at 2011/06/05 10:41:03 -0700

You are right, I changed the request to use the block syntax instead.