#Reindexing Line Numbers

Now we're really getting into the weeds, but that's exactly what Torchlight is here for.

Sometimes it really matters what the line number is that goes along with your code sample. In the case where you can't get it right, you might be tempted to turn them off altogether.

Torchlight offers a few ways to reindex the lines, using the reindex annotation.

(You can also control the starting line number using the lineNumbersStart option.)

#The Annotation

To reindex a line, you will add the reindex annotation. This annotation is a little bit different than the others, because it accepts an argument in parenthesis.

Here are a few examples:

• reindex(-1): whatever this line number would have been, reduce it by one
• reindex(+1): whatever this line number would have been, increment it by one
• reindex(5): regardless of what number this should be, make it 5
• reindex(null): don't show a line number here.

#Manually Setting a New Number

To just outright set a new number, use the reindex(N) style:

1'a';
2'b';
3'c';
4'x'; // [tl! reindex(24)]
5'y';
6'z';

 1'a';
 2'b';
 3'c';
24'x'; 
25'y';
26'z';

Torchlight will continue with the next number after the one you set.

#No Number At All

If you want a line to have no line number, use the reindex(null) annotation:

1'a';
2'b';
3'c';
4// Lots of letters... [tl! reindex(null)]
5'x'; // [tl! reindex(24)]
6'y';
7'z';

 1'a';
 2'b';
 3'c';
  // Lots of letters... 
24'x'; 
25'y';
26'z';

If you don't immediately reindex, Torchlight just treats that line as if it doesn't exist for numbering purposes.

1'a';
2'b';
3'c';
4// Lots of letters... [tl! reindex(null)]
5'x';
6'y';
7'z';

1'a';
2'b';
3'c';
 // Lots of letters... 
4'x';
5'y';
6'z';

#Relative Changes

Often times it's easiest to think in terms of "increment" or "decrement" instead of thinking in absolutes. Especially as time goes on and your samples may change, it's nice to have the relative numbers always work.

This can be a really nice touch when showing diffs, to keep the numbering legit.

To change the numbers relatively, use the reindex(+N) and reindex(-N) styles.

 1// torchlight! {"diffIndicatorsInPlaceOfLineNumbers": false}
 2return [
 3    'extensions' => [
 4        // Add attributes straight from markdown.
 5        AttributesExtension::class,
 6
 7        // Add Torchlight syntax highlighting.
 8        SomeOtherHighlighter::class, // [tl! remove]
 9        TorchlightExtension::class, // [tl! add reindex(-1)]
10    ]
11]

1 return [
2     'extensions' => [
3         // Add attributes straight from markdown.
4         AttributesExtension::class,
5  
6         // Add Torchlight syntax highlighting.
7-        SomeOtherHighlighter::class, 
7+        TorchlightExtension::class, 
8     ]
9 ]

Of course it doesn't have to just be 1, it could be any number.

 1return [
 2    'extensions' => [
 3        // Add attributes straight from markdown.
 4        AttributesExtension::class,
 5
 6        // Add Torchlight syntax highlighting.
 7        SomeOtherHighlighter::class, // [tl! remove]
 8        TorchlightExtension::class, // [tl! add reindex(+1000)]
 9    ]
10]

   1return [
   2    'extensions' => [
   3        // Add attributes straight from markdown.
   4        AttributesExtension::class,
   5 
   6        // Add Torchlight syntax highlighting.
   -        SomeOtherHighlighter::class, 
   +        TorchlightExtension::class, 
1009    ]
1010]

#Annotation Range Modifiers

The reindex annotation does work with the annotation range modifiers, so you can do some pretty wacky stuff.

If you wanted to reach down several lines and apply a reindex, you totally could!

Here we are going to reach down 6 lines, and apply a +5 reindex to 1 line only.

 1// This is a long bit of text, hard to reindex the middle. [tl! reindex(+5):6,1]
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6
 7deep winter
 8the smell of a crow
 9from the stars
10
11beach to school
12the smell of water
13in the sky
14EOT; // [tl! highlight:-7,3]

 1// This is a long bit of text, hard to reindex the middle. 
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6 
12deep winter
13the smell of a crow
14from the stars
15 
16beach to school
17the smell of water
18in the sky
19EOT;

Or if you wanted to null out the second stanza, you could do that also.

 1// This is a long bit of text, hard to reindex the middle. [tl! reindex(null):5,5]
 2return <<<EOT
 3spring sunshine
 4the smell of waters
 5from the stars
 6
 7deep winter
 8the smell of a crow
 9from the stars
10
11beach to school
12the smell of water
13in the sky
14EOT; // [tl! highlight:-7,3]

1// This is a long bit of text, hard to reindex the middle. 
2return <<<EOT
3spring sunshine
4the smell of waters
5from the stars
  
 deep winter
 the smell of a crow
 from the stars
  
6beach to school
7the smell of water
8in the sky
9EOT;

Why you would ever want to do this, I have no idea. But if you want to, you can!