1- # Stable Sort
1+ # Smart Sort
22
33<!-- markdownlint-configure-file
44{
1313  ;
1414[ ![ MIT license] ( https://img.shields.io/badge/license-MIT-lightgray.svg?longCache=true&style=popout )] ( https://github.com/sgryjp/vscode-stable-sort/blob/master/LICENSE.md )
1515
16- Sort CSV-like words or lines in [ VS Code] ( https://code.visualstudio.com ) using stable sort algorithm .
16+ Sort CSV-like words or lines in [ Visual Studio Code] ( https://code.visualstudio.com ) .
1717
18- ## Feature
18+ ## Summary
1919
20- With single shortcut <kbd >Ctrl+Alt+R</kbd > (mac: <kbd >Cmd+Ctrl+R</kbd >),
21- you can:
20+ Smart Sort allows you to:
2221
23- - Sort words separated by
24- - space, comma, tab, pipe (` | ` )
25- - separators recognized automatically
26- - Sort lines by
27- - entire content
28- - selected parts
22+ 1 . Sort words separated by comma, tab, pipe (` | ` ) or space
23+ 2 . Sort lines by comparing selected parts of them, or entire content of them
2924
30- If you want to sort in reversed (descending) order, use
31- <kbd >Ctrl+Alt+Shift+R</kbd > (mac: <kbd >Cmd+Ctrl+Shift+R</kbd >).
25+ Smart Sort chooses how and what to sort according to the selection state
26+ so there are just 2 commands provided: one for sorting ascending order,
27+ one for sorting descending order.
3228
33- Some other key ponits:
29+ Note that Smart Sort recognizes numeric value (e.g.: ` 2 ` comes
30+ before ` 10 ` ).
3431
35- - Words or lines will be sorted as numbers if every one of them starts with a
36- token which looks like a numeric value (e.g.: ` 2 ` comes before ` 10 ` )
37- - Sorting algorithm is
38- [ stable] ( https://en.wikipedia.org/wiki/Sorting_algorithm#Stability )
39- - The order of semantically same (depends on locale) words or lines
40- will be unchanged.
32+ ## Key bindings
4133
42- ### Sorting words
34+ | Command | Shortcut |
35+ | -------------------------- | -------------------------------------------------------------- |
36+ | ` smartSort.SortAscending ` | <kbd >Ctrl+Alt+R</kbd > (mac: <kbd >Cmd+Ctrl+R</kbd >) |
37+ | ` smartSort.SortDescending ` | <kbd >Ctrl+Alt+Shift+R</kbd > (mac: <kbd >Cmd+Ctrl+Shift+R</kbd >) |
4338
44- If there is only one selection range and either start position, end position
45- or both are in the middle of a line, words inside the selection. You can select
46- words across lines; in that case the original indentation and line widths will
47- be kept.
39+ Those key bindings will be enabled by default.
4840
49- Word separators will be recognized automatically. If one of comma (` U+0013 ` ),
50- tab (` U+0009 ` ), or pipe (` U+007C ` ) was found it will be used as word separator.
51- If not found any of them, a space (` U+0020 ` ) will be used.
41+ ## Configuration
5242
53- Note that spaces surrounding word separators will be normalized as below:
43+ - ` smartSort.preferWordSorting `
44+ - When multiple lines are selected by a single selection, setting ` true ` to
45+ this configuration makes Smart Sort to sort words spread over the lines,
46+ instead of sorting the lines. See
47+ [ explanation] ( #sorting-words-spread-over-multiple-lines )
48+ below for detail. (default: ` false ` )
5449
55- - Comma: Zero or one space character following after the first comma will be kept.
56- - Tab: Surrounding spaces are simply ignored.
57- - Pipe: At most one spaces preceding before and/or following after the first
58- pipe character will be kept.
59- - Space: Word separator will always be exactly one space character.
50+ ## Sorting words
6051
61- #### Example animations
52+ To sort words, just select some words and hit <kbd >Ctrl+Alt+R</kbd >
53+ (or <kbd >Cmd+Ctrl+R</kbd > on mac.)
54+
55+ Smart Sort automatically recognizes the word separator. In order of priority,
56+ supported separators are:
57+
58+ 1 . Comma (` U+0013 ` )
59+ 2 . Tab (` U+0009 ` )
60+ 3 . Pipe (` U+007C ` )
61+ 4 . Space (` U+0020 ` )
62+
63+ On sorting words, word separators among them will be normalized. Strictly
64+ writing, whitespace characters surrounding the first word separator will be
65+ treated as part of the separator and they will be used to separate sorted words.
66+
67+ Here are some example animations:
6268
6369- Comma<br >
6470 ![ Sorting words separated by comma] ( images/sort-words-comma.gif )
@@ -69,64 +75,75 @@ Note that spaces surrounding word separators will be normalized as below:
6975- Space<br >
7076 ![ Sorting words separated by space] ( images/sort-words-space.gif )
7177
72- ### Sorting lines
78+ ## Sorting lines
79+
80+ To sort lines, select multiple lines and hit <kbd >Ctrl+Alt+R</kbd >
81+ (or <kbd >Cmd+Ctrl+R</kbd > on mac.)
7382
74- If the condition to sort words are not met, selected lines will be sorted.
83+ If you select portions of lines by using
84+ [ multple selections (multi-cursor)] ( https://code.visualstudio.com/docs/editor/codebasics#_multiple-selections-multicursor ) ,
85+ the lines which are touched by the selection range will be sorted by comparing
86+ the selected parts.
87+ This is useful if you want to sort on arbitrary column of visually aligned text
88+ data such as output of
89+ [ ` ps ` command] ( < https://en.wikipedia.org/wiki/Ps_(Unix) > )
90+ or CSV data.
7591
76- Strictly writing, lines which contains selection range(s) will be sorted using
77- selected part. This means that you can sort lines not only by comparing entire
78- content but also by comparing a portion of them. This is useful if you want to
79- sort on arbitrary column of visually aligned text data such as output of
80- [ ` ps ` command] ( < https://en.wikipedia.org/wiki/Ps_(Unix) > ) or CSV data.
92+ Here are some example animations:
8193
82- #### Example animations
94+ 1 . Sort visually aligned lines by specific "column"<br >
95+ ![ Sorting lines by selected parts] ( images/sort-visually-aligned.gif )
96+ 2 . Sort lines by entire content (CSV colorized with
97+ [ Rainbow CSV] ( https://marketplace.visualstudio.com/items?itemName=mechatroner.rainbow-csv ) )<br >
98+ ![ Sorting lines by entire content] ( images/sort-lines-whole.gif )
99+ 3 . Sort lines by comparing selected parts<br >
100+ ![ Sorting lines by selected parts] ( images/sort-lines-part.gif )
83101
84- - Sort lines by entire content (CSV colorized with
85- [ Rainbow CSV] ( https://marketplace.visualstudio.com/items?itemName=mechatroner.rainbow-csv ) )<br >
86- ![ Sorting lines by entire content] ( images/sort-lines-whole.gif )
87- - Sort lines by selected parts<br >
88- ![ Sorting lines by selected parts] ( images/sort-lines-part.gif )
89- - Sort visually aligned lines by specific "column"<br >
90- ![ Sorting lines by selected parts] ( images/sort-visually-aligned.gif )
102+ ## Sorting words spread over multiple lines
91103
92- ### Sorting words spread over multiple lines
104+ If ` smartSort.preferWordSorting ` is configured as ` true ` , Smart Sort will sort
105+ words instead of lines under the condition shown below:
93106
94- By default you cannot sort words spread over multiple lines. If the selection
95- covers multiple lines, those lines touched by the selection will be sorted.
96- To change this behavior, set ` true ` to ` stableSort.preferWordSorting ` option.
97- Doing so makes this extension sort selected words if start or end of the
98- selection is in the middle of a line. Note that even if this option was enabled
99- you can sort multiple words by placing both start and end of the selection at
100- the beginning of a line (as in the example animation above.)
107+ - there is only one selection range (not using multi-cursor), AND
108+ - both the start and end of the selection range are NOT placed at a beginning
109+ of a line (placed in a middle of a line or at the end of a line).
101110
102- - For example, we can sort import target in Julia language:<br >
111+ In this mode, sorted words will be reflowed. In other words, the original
112+ indentation and line widths will remain unchanged. (for example, the
113+ indentation characters of the second line is kept unchanged in the example
114+ animation below).
115+
116+ Note that if you place both the start and end of the selection range are placed
117+ at a beginning of a line, you can always sort lines even if you set
118+ ` true ` to ` smartSort.preferWordSorting ` .
119+
120+ Here is an example animation:
121+
122+ - Sorting ` import ` target in Julia language:<br >
103123 ![ Sorting words spread over multiple lines] ( images/sort-words-multiline.gif ) <br >
104124 In this example, we don't need to care about where to insert a new target; just
105125 appending one and sorting them will move it to the right place.
106126
107- ## Background
127+ ## Historical Background
108128
109- Stability of sorting is not valuable in most cases except for some.
129+ Previously the name of this extension was "Stable Sort". Here is why I wanted
130+ and created an extension which uses stable sort algorithm.
110131
111- As of VS Code 1.27.2, its algorithm to sort lines are not "stable" so sorting
112- textually "same" words or lines may change those order. This behavior will not
113- be a problem in most cases because those are normally completely identical so
114- swapping those is not a change by all means. But, there are exceptional cases
115- where two textually differrent lines are evaluated as equal. In those cases,
116- sorted result will be different time to time.
132+ Back when Visual Studio Code was version 1.27.2, it have used unstable sort
133+ algorithm. This means that sorting textually identical words or lines may
134+ change those order. This behavior will not be a problem in most cases since
135+ swapping those is not a change by all means.
117136
118- For example, an ASCII digit character and its counter part in
137+ Unfortunately, I encountered an exceptional case. In Japanese locale, an ASCII
138+ digit character and its counter part in
119139[ fullwidth forms] ( https://www.unicode.org/charts/PDF/UFF00.pdf )
120- are treated as equal in Japanese locale so result of sorting words like below
121- (BTW it's "type 2 diabetes" writen in Japanese) may change time to time :
140+ are treated as equal so the order of words like below changed every time I sort
141+ them :
122142
123143 2型糖尿病
124144 ２型糖尿病
125145
126- This behavior is not appreciated for tasks like compositing dictionary data,
127- since you cannot normalize data by simply sorting. This extension solves the
128- problem.
129-
130- (Note that the "unstable" sort algorithm of VS Code (strictly, of Node.js) is
131- used for relatively large number of lines so working with small data might not
132- raise the problem.)
146+ This behavior was very annoying when I was compositing dictionary data since I
147+ cannot normalize entries by simple sorting. Obviously an extension which allows
148+ me to sort entries using stable sort algorithm solves the problem.
149+ So, I created one.
0 commit comments