Insert Nums

A Sublime Text plugin, to insert (consecutive) numbers across multiple selections or modifiy selections' contents with expressions using sophisticated expressions syntax.

Installation

Package Control

The easiest way to install is using Package Control. It's listed as Insert Nums.

Open Command Palette using ctrl+shift+P or menu item Tools → Command Palette...
Choose Package Control: Install Package
Find Insert Nums and hit Enter

Manual Setup

Alternatively, you can clone this repository into Sublime Text's Packages folder.

[!NOTE]

To find Packages folder call Menu > Preferences > Browse Packages..

OSX

#!/usr/bin/env bash
cd ~/Library/Application\ Support/Sublime\ Text/Packages/
git clone https://github.com/SublimeText/InsertNums "Insert Nums"

Linux

cd ~/.config/sublime-text/Packages
git clone https://github.com/SublimeText/InsertNums "Insert Nums"

Windows

cd "%APPDATA%\Sublime Text\Packages"
git clone https://github.com/SublimeText/InsertNums "Insert Nums"

Usage

Windows and Linux: Ctrl+Alt+N
OSX: ⌘+⎇+N

An input panel opens which live-previews your current format string. If you close the panel (e.g. by pressing Esc), the changes will be undone. If you prefer to not have this live preview, you can disable it by also pressing the Shift key.

Insert a string in the format <start>:<step> and press enter. Both can be omitted and default to 1 (meaning 1:1).

For every selected region the inserted number (starting with start) will then be increased by step. But there is more!

Commands

prompt_insert_nums

Opens an input panel with live preview as explained above. The parameter preview can specify if Insert Nums should show a live preview when editing the format string. Defaults to true.
insert_nums

This is the basic command. Call this with a format parameter and bind it to a keyboard shortcut if you find yourself using a query very often.

Usage with numbers

Insert Nums supports both, integers and floating numbers, as start and step values respectively, also negative numbers. This means you can use 1:.4 on 4 selections and get this:

1.0
1.4
1.8
2.2

Furthermore, you can use arbitrary Python expressions to generate your numbers, e.g. for bitflags. An example can be found in the Examples.

See the Advanced usage section for information about using a specific formatting.

Usage with the alphabet

Insert Nums can also insert the alphabet. Just use a as start value, or change a to whatever character you'd like to start from. step only accepts integers because there are obviously no fractions of the characters in the alphabet.

One of the side effects of introducing alpha sequences is that you can generate seemingly (but definitely not) random sequences. For instance, using a:12345 will generate the following across three selections:

a
rfv
ajmq

All that's happening there is that the next letter in the sequence is shunted across by the step amount.

If you'd rather like Insert Nums to wrap when the last character (z) is reached, you can append ~w. Thus, a:12345~w will generate this:

a
v
q

For more options see the following Advanced usage section.

Expression Mode

Other than inserting numbers or alphas this mode takes the value of a selection and allows you to modify it with a Python expression. This will be explained in detail further below.

Advanced usage (insert)

The complete syntax is: <start>:<step>~<format>::<expr>@<stopexpr><reverse>, the corresponding separator is only required if you actually supply the following part. Every part itself is optional (defaulting to 1:1), but if you want the alpha mode you have to supply the alphabetical start value.

Below is an abstract example showing the syntax with all optional parts (indicated by []):

numbers: [<start>][:<step>][~<format>][::<expr>][@<stopexpr>][!]
alpha:   <start>[:<step>][~<format>][@<stopexpr>][!]

Detailed syntax definition: format_syntax.txt

start
- with numbers (optional): A [decimalinteger] or [floatnumber] according to Python's syntax specifications with an optional leading sign (- or +). Default: 1
- with alphabet (required): A sequence of either lower- or uppercase ASCII characters from the alphabet (a to z and A to Z).
step (optional)
- with numbers: A [decimalinteger] or [floatnumber] according to Python's syntax specifications with an optional leading sign (- or +). Default: 1
- with alphabet: A [decimalinteger] with an optional leading sign (- or +).
format (optional)
- with numbers: A format string in Python's Format Specific Mini-Language (with small and unimportant adjustments for allowed types).
- with alphabet: Similar to with numbers but a stripped-down version only for strings. This only includes the [[fill]align][width] syntax and additionally accepts a w character at the end (see above).
expr (optional)
- numbers only: A valid Python expression which modifies the value as you please. If specified, the format string is applied afterwards. Here is a list of available variables:
  - s: The value of step (specified in the format query and defaults to 1)
  - n: The number of selections
  - i: Just an integer holding the counter for the iteration; starts at 0 and is increased by 1 in every loop
  - _: The current value before the expression (start + i * step)
  - p: The result of the previously evaluated value (without formatting); 0 for the first value
  - math, random, re and itertools: Useful modules that are pre-imported for you
  Note: The return value does not have to be a number type, you can also generate strings, tuples or booleans.
stopexpr (optional)

A valid Python expression which returns a value that translates to true or false (in a boolean context). Theoretically this can be any value. You can use the same values as in expr with addition of the following:
- c: The current evaluated value by the expression (without formatting) or just the same as _ if there was no expression specified
This ignores the number of selections which means that you can also have more or less values than selections. Especially useful when generating numbers from a single selection.
- If there is more selections than numbers generated when processing the stop expression, all the remaining selections' text will be deleted.
- If there is more numbers generated than selections, all further numbers are joining by newlines ("\n") and added to the last selection made. This can be the first selection if there is only one.
reverse (optional)

Must be ! and results in the regions being filled in reversed order.

Advanced usage (Expression)

In addition to the insert mode Insert Nums also specifies a way to modify the current selection(s). The syntax is as follows:

[<cast>]|[~<format>::]<expr>[@<stopexpr>][!]

Again, for the detailed syntax specification, see: format_syntax.txt.

The | pipe is used to show the meaning of piping the current selection to the following expression. stopexpr behaves a bit different than in insert mode and the current value _ is adjusted.

cast (optional)

Can be one of s, i, f or b and means that the string in the selection will be converted to the corresponding type, if possible. An error message is shown otherwise.
- s: str or unicode (in ST2) (default)
- i: int
- f: float
- b: bool
format (optional)

Same as in insert mode.
expr

Same as in insert mode, except that _ represents the (converted) value of the current selection.
stopexpr (optional)

Usage is the same as in insert mode and the _ for expression mode, but the effects are a bit different:
- You can not generate more values than there are selections.
- If you generate less values than there are selections, the remaining selections will be untouched. Return "" in the expression if you want to clear them.
reverse (optional)

Must be ! and results in both the selections being parsed and the regions being filled in reversed order.

Examples

Basic insert

1 or
```
1
2
3
4
5
6
```
-10:2~3
```
-10
 -8
 -6
 -4
 -2
  0
  2
  4
```

11:11~+4

 +11
 +22
 +33
 +44
 +55
 +66
 +77
 +88
 +99
+110

Insert with format

0.2:.002~-<5 (see g type (default) in the Python format docs)
```
0.2--
0.202
0.204
0.206
0.208
0.21-
0.212
```

.2:2e-3~6.4f

8:8~#010x!

Expression Insert

0~#06x::1<<_

::i**2
```
1
4
9
16
25
36
```

::list(itertools.product(['a', 'b', 'c'], ['x', 'y', 'z']))[i]

('a', 'x')
('a', 'y')
('a', 'z')
('b', 'x')
('b', 'y')
('b', 'z')
('c', 'x')
('c', 'y')
('c', 'z')

Alpha insert

z:25~w or z:-1~w
```
z
y
x
w
v
u
t
```
aa:10000~ ^6 (here, | represents the cursors to visualize trailing spaces)
```
  aa  |
 nuq  |
 acpg |
 arjw |
 bgem |
 buzc |
 cjts |
```

Stop expressions

Note: Assuming everything in Before has been selected with one selection spanning each line.

Before:
```
1
2
3
4
5
```
@_>3
```
1
2
3
```
Before:
```
1
```
~02@p==10 or ~02@_>10 or ~02@i==10
```
01
02
03
04
05
06
07
08
09
10
```

Expression mode