Add new functionality to the `=` marker in the STL

This new functionality is explained in the documentation.

Also, many tests have been added to the buffer_spec.lua file

5 files changed, 286 insertions, 106 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 105be1cd77..ea0a18c6f3 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6070,7 +6070,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	            feature use `has('tablineat')`.
 	< -   Where to truncate line if too long.  Default is at the start.
 	      No width fields allowed.
-	= -   Separation point between left and right aligned items.
+	= -   Separation point between alignment sections. Each section will
+	      be separated by an equal number of spaces.
 	      No width fields allowed.
 	# -   Set highlight group.  The name must follow and then a # again.
 	      Thus use %#HLname# for highlight group HLname.  The same
diff --git a/src/nvim/buffer.c b/src/nvim/buffer.c
index 71ec20c788..72724b0ffd 100644
--- a/src/nvim/buffer.c
+++ b/src/nvim/buffer.c
@@ -2849,7 +2849,7 @@ typedef enum {
 /// is "curwin".
 ///
 /// Items are drawn interspersed with the text that surrounds it
-/// Specials: %-<wid>(xxx%) => group, %= => middle marker, %< => truncation
+/// Specials: %-<wid>(xxx%) => group, %= => separation marker, %< => truncation
 /// Item: %-<minwid>.<maxwid><itemch> All but <itemch> are optional
 ///
 /// If maxwidth is not zero, the string will be filled at any middle marker
@@ -2893,7 +2893,7 @@ int build_stl_str_hl(
       Normal,
       Empty,
       Group,
-      Middle,
+      Separate,
       Highlight,
       TabPage,
       ClickFunc,
@@ -2994,14 +2994,14 @@ int build_stl_str_hl(
       continue;
     }
 
-    // STL_MIDDLEMARK: Separation place between left and right aligned items.
-    if (*fmt_p == STL_MIDDLEMARK) {
+    // STL_SEPARATE: Separation place between left and right aligned items.
+    if (*fmt_p == STL_SEPARATE) {
       fmt_p++;
       // Ignored when we are inside of a grouping
       if (groupdepth > 0) {
         continue;
       }
-      item[curitem].type = Middle;
+      item[curitem].type = Separate;
       item[curitem++].start = out_p;
       continue;
     }
@@ -3840,27 +3840,53 @@ int build_stl_str_hl(
     width = maxwidth;
 
   // If there is room left in our statusline, and room left in our buffer,
-  // add characters at the middle marker (if there is one) to
+  // add characters at the separate marker (if there is one) to
   // fill up the available space.
   } else if (width < maxwidth
-               && STRLEN(out) + maxwidth - width + 1 < outlen) {
-    for (int item_idx = 0; item_idx < itemcnt; item_idx++) {
-      if (item[item_idx].type == Middle) {
-        // Move the statusline to make room for the middle characters
-        char_u *middle_end = item[item_idx].start + (maxwidth - width);
-        STRMOVE(middle_end, item[item_idx].start);
-
-        // Fill the middle section with our fill character
-        for (char_u *s = item[item_idx].start; s < middle_end; s++)
-          *s = fillchar;
+             && STRLEN(out) + maxwidth - width + 1 < outlen) {
+    // Find how many separators there are, which we will use when
+    // figuring out how many groups there are.
+    int num_separators = 0;
+    for (int i = 0; i < itemcnt; i++) {
+      if (item[i].type == Separate) {
+        num_separators++;
+      }
+    }
 
-        // Adjust the offset of any items after the middle
-        for (item_idx++; item_idx < itemcnt; item_idx++)
-          item[item_idx].start += maxwidth - width;
+    // If we have separated groups, then we deal with it now
+    if (num_separators) {
+      // Create an array of the start location for each
+      // separator mark.
+      int separator_locations[STL_MAX_ITEM];
+      int index = 0;
+      for (int i = 0; i < itemcnt; i++) {
+        if (item[i].type == Separate) {
+          separator_locations[index] = i;
+          index++;
+        }
+      }
 
-        width = maxwidth;
-        break;
+      int standard_spaces = (maxwidth - width) / num_separators;
+      int final_spaces = (maxwidth - width) -
+        standard_spaces * (num_separators - 1);
+
+      for (int i = 0; i < num_separators; i++) {
+        int dislocation = (i == (num_separators - 1)) ?
+          final_spaces : standard_spaces;
+        char_u *sep_loc = item[separator_locations[i]].start + dislocation;
+        STRMOVE(sep_loc, item[separator_locations[i]].start);
+        for (char_u *s = item[separator_locations[i]].start; s < sep_loc; s++) {
+          *s = fillchar;
+        }
+
+        for (int item_idx = separator_locations[i] + 1;
+             item_idx < itemcnt;
+             item_idx++) {
+          item[item_idx].start += dislocation;
+        }
       }
+
+      width = maxwidth;
     }
   }
 
diff --git a/src/nvim/option.c b/src/nvim/option.c
index ac906d82ad..52a1fd8558 100644
--- a/src/nvim/option.c
+++ b/src/nvim/option.c
@@ -3403,9 +3403,10 @@ char_u *check_stl_option(char_u *s)
     if (!*s)
       break;
     s++;
-    if (*s != '%' && *s != ')')
-      ++itemcnt;
-    if (*s == '%' || *s == STL_TRUNCMARK || *s == STL_MIDDLEMARK) {
+    if (*s != '%' && *s != ')') {
+      itemcnt++;
+    }
+    if (*s == '%' || *s == STL_TRUNCMARK || *s == STL_SEPARATE) {
       s++;
       continue;
     }
diff --git a/src/nvim/option_defs.h b/src/nvim/option_defs.h
index 904e97f8ca..b1a2b00bdb 100644
--- a/src/nvim/option_defs.h
+++ b/src/nvim/option_defs.h
@@ -258,7 +258,7 @@ enum {
   STL_ARGLISTSTAT     = 'a',  ///< Argument list status as (x of y).
   STL_PAGENUM         = 'N',  ///< Page number (when printing).
   STL_VIM_EXPR        = '{',  ///< Start of expression to substitute.
-  STL_MIDDLEMARK      = '=',  ///< Separation between left and right.
+  STL_SEPARATE        = '=',  ///< Separation between alignment sections.
   STL_TRUNCMARK       = '<',  ///< Truncation mark if line is too long.
   STL_USER_HL         = '*',  ///< Highlight from (User)1..9 or 0.
   STL_HIGHLIGHT       = '#',  ///< Highlight name.
@@ -274,7 +274,7 @@ enum {
   STL_HELPFLAG, STL_HELPFLAG_ALT, STL_FILETYPE, STL_FILETYPE_ALT, \
   STL_PREVIEWFLAG, STL_PREVIEWFLAG_ALT, STL_MODIFIED, STL_MODIFIED_ALT, \
   STL_QUICKFIX, STL_PERCENTAGE, STL_ALTPERCENT, STL_ARGLISTSTAT, STL_PAGENUM, \
-  STL_VIM_EXPR, STL_MIDDLEMARK, STL_TRUNCMARK, STL_USER_HL, STL_HIGHLIGHT, \
+  STL_VIM_EXPR, STL_SEPARATE, STL_TRUNCMARK, STL_USER_HL, STL_HIGHLIGHT, \
   STL_TABPAGENR, STL_TABCLOSENR, STL_CLICK_FUNC, \
   0, \
 })
diff --git a/test/unit/buffer_spec.lua b/test/unit/buffer_spec.lua
index b7f82064d7..317c9be6e7 100644
--- a/test/unit/buffer_spec.lua
+++ b/test/unit/buffer_spec.lua
@@ -1,10 +1,9 @@
 
-local assert = require("luassert")
 local helpers = require("test.unit.helpers")
 
 local to_cstr = helpers.to_cstr
+local get_str = helpers.ffi.string
 local eq      = helpers.eq
-local neq     = helpers.neq
 local NULL    = helpers.NULL
 
 local globals = helpers.cimport("./src/nvim/globals.h")
@@ -211,93 +210,246 @@ describe('buffer functions', function()
   end)
 
   describe('build_stl_str_hl', function()
+    local buffer_byte_size = 100
+    local STL_MAX_ITEM = 80
+    local output_buffer = ''
+
+    -- This function builds the statusline
+    --
+    -- @param arg Optional arguments are:
+    --    .pat The statusline format string
+    --    .fillchar The fill character used in the statusline
+    --    .maximum_cell_count The number of cells available in the statusline
+    local function build_stl_str_hl(arg)
+      output_buffer = to_cstr(string.rep(" ", buffer_byte_size))
+
+      local pat = arg.pat or ''
+      local fillchar = arg.fillchar or (' '):byte()
+      local maximum_cell_count = arg.maximum_cell_count or buffer_byte_size
 
-    local output_buffer = to_cstr(string.rep(" ", 100))
-
-    local build_stl_str_hl = function(pat)
       return buffer.build_stl_str_hl(globals.curwin,
                                      output_buffer,
-                                     100,
+                                     buffer_byte_size,
                                      to_cstr(pat),
                                      false,
-                                     32,
-                                     80,
+                                     fillchar,
+                                     maximum_cell_count,
                                      NULL,
                                      NULL)
     end
 
-    it('should copy plain text', function()
-      local width = build_stl_str_hl("this is a test")
-
-      eq(14, width)
-      eq("this is a test", helpers.ffi.string(output_buffer, width))
-
-    end)
-
-    it('should print no file name', function()
-      local width = build_stl_str_hl("%f")
-
-      eq(9, width)
-      eq("[No Name]", helpers.ffi.string(output_buffer, width))
-
-    end)
-
-    it('should print the relative file name', function()
-      buffer.setfname(globals.curbuf, to_cstr("Makefile"), NULL, 1)
-      local width = build_stl_str_hl("%f")
-
-      eq(8, width)
-      eq("Makefile", helpers.ffi.string(output_buffer, width))
-
-    end)
-
-    it('should print the full file name', function()
-      buffer.setfname(globals.curbuf, to_cstr("Makefile"), NULL, 1)
-
-      local width = build_stl_str_hl("%F")
-
-      assert.is_true(8 < width)
-      neq(NULL, string.find(helpers.ffi.string(output_buffer, width), "Makefile"))
-
-    end)
-
-    it('should print the tail file name', function()
-      buffer.setfname(globals.curbuf, to_cstr("src/nvim/buffer.c"), NULL, 1)
-
-      local width = build_stl_str_hl("%t")
-
-      eq(8, width)
-      eq("buffer.c", helpers.ffi.string(output_buffer, width))
-
-    end)
-
-    it('should print the buffer number', function()
-      buffer.setfname(globals.curbuf, to_cstr("src/nvim/buffer.c"), NULL, 1)
-
-      local width = build_stl_str_hl("%n")
-
-      eq(1, width)
-      eq("1", helpers.ffi.string(output_buffer, width))
-    end)
-
-    it('should print the current line number in the buffer', function()
-      buffer.setfname(globals.curbuf, to_cstr("test/unit/buffer_spec.lua"), NULL, 1)
-
-      local width = build_stl_str_hl("%l")
-
-      eq(1, width)
-      eq("0", helpers.ffi.string(output_buffer, width))
-
-    end)
-
-    it('should print the number of lines in the buffer', function()
-      buffer.setfname(globals.curbuf, to_cstr("test/unit/buffer_spec.lua"), NULL, 1)
-
-      local width = build_stl_str_hl("%L")
+    -- Use this function to simplify testing the comparison between
+    --  the format string and the resulting statusline.
+    --
+    -- @param description The description of what the test should be doing
+    -- @param statusline_cell_count The number of cells available in the statusline
+    -- @param input_stl The format string for the statusline
+    -- @param expected_stl The expected result string for the statusline
+    --
+    -- @param arg Options can be placed in an optional dictionary as the last parameter
+    --    .expected_cell_count The expected number of cells build_stl_str_hl will return
+    --    .expected_byte_length The expected byte length of the string
+    --    .file_name The name of the file to be tested (useful in %f type tests)
+    --    .fillchar The character that will be used to fill any 'extra' space in the stl
+    local function statusline_test (description,
+                                    statusline_cell_count,
+                                    input_stl,
+                                    expected_stl,
+                                    arg)
+
+      -- arg is the optional parameter
+      -- so we either fill in option with arg or an empty dictionary
+      local option = arg or {}
+
+      local fillchar = option.fillchar or (' '):byte()
+      local expected_cell_count = option.expected_cell_count or statusline_cell_count
+      local expected_byte_length = option.expected_byte_length or expected_cell_count
+
+      it(description, function()
+        if option.file_name then
+          buffer.setfname(globals.curbuf, to_cstr(option.file_name), NULL, 1)
+        else
+          buffer.setfname(globals.curbuf, nil, NULL, 1)
+        end
+
+        local result_cell_count = build_stl_str_hl{pat=input_stl,
+                                                   maximum_cell_count=statusline_cell_count,
+                                                   fillchar=fillchar}
+
+        eq(expected_stl, get_str(output_buffer, expected_byte_length))
+        eq(expected_cell_count, result_cell_count)
+      end)
+    end
 
-      eq(1, width)
-      eq("1", helpers.ffi.string(output_buffer, width))
+    -- file name testing
+    statusline_test('should print no file name', 10,
+      '%f',                  '[No Name]',
+      {expected_cell_count=9})
+    statusline_test('should print the relative file name', 30,
+      '%f',                  'test/unit/buffer_spec.lua',
+      {file_name='test/unit/buffer_spec.lua', expected_cell_count=25})
+    statusline_test('should print the full file name', 40,
+      '%F',                  '/test/unit/buffer_spec.lua',
+      {file_name='/test/unit/buffer_spec.lua', expected_cell_count=26})
+
+    -- fillchar testing
+    statusline_test('should handle `!` as a fillchar', 10,
+      'abcde%=',             'abcde!!!!!',
+      {fillchar=('!'):byte()})
+    statusline_test('should handle `~` as a fillchar', 10,
+      '%=abcde',             '~~~~~abcde',
+      {fillchar=('~'):byte()})
+    statusline_test('should put fillchar `!` in between text', 10,
+      'abc%=def',            'abc!!!!def',
+      {fillchar=('!'):byte()})
+    statusline_test('should put fillchar `~` in between text', 10,
+      'abc%=def',            'abc~~~~def',
+      {fillchar=('~'):byte()})
+    statusline_test('should print the tail file name', 80,
+      '%t',                  'buffer_spec.lua',
+      {file_name='test/unit/buffer_spec.lua', expected_cell_count=15})
+
+    -- standard text testing
+    statusline_test('should copy plain text', 80,
+      'this is a test',      'this is a test',
+      {expected_cell_count=14})
+
+    -- line number testing
+    statusline_test('should print the buffer number', 80,
+      '%n',                  '1',
+      {expected_cell_count=1})
+    statusline_test('should print the current line number in the buffer', 80,
+      '%l',                  '0',
+      {expected_cell_count=1})
+    statusline_test('should print the number of lines in the buffer', 80,
+      '%L',                  '1',
+      {expected_cell_count=1})
+
+    -- truncation testing
+    statusline_test('should truncate when standard text pattern is too long', 10,
+      '0123456789abcde',     '<6789abcde')
+    statusline_test('should truncate when using =', 10,
+      'abcdef%=ghijkl',      'abcdef<jkl')
+    statusline_test('should truncate centered text when using ==', 10,
+      'abcde%=gone%=fghij',  'abcde<ghij')
+    statusline_test('should respect the `<` marker', 10,
+      'abc%<defghijkl',      'abc<ghijkl')
+    statusline_test('should truncate at `<` with one `=`, test 1', 10,
+      'abc%<def%=ghijklmno', 'abc<jklmno')
+    statusline_test('should truncate at `<` with one `=`, test 2', 10,
+      'abcdef%=ghijkl%<mno', 'abcdefghi>')
+    statusline_test('should truncate at `<` with one `=`, test 3', 10,
+      'abc%<def%=ghijklmno', 'abc<jklmno')
+    statusline_test('should truncate at `<` with one `=`, test 4', 10,
+      'abc%<def%=ghij',     'abcdefghij')
+    statusline_test('should truncate at `<` with one `=`, test 4', 10,
+      'abc%<def%=ghijk',     'abc<fghijk')
+
+    statusline_test('should truncate at `<` with many `=`, test 4', 10,
+      'ab%<cdef%=g%=h%=ijk', 'ab<efghijk')
+
+    statusline_test('should truncate at the first `<`', 10,
+      'abc%<def%<ghijklm',   'abc<hijklm')
+
+    -- alignment testing
+    statusline_test('should right align when using =', 20,
+      'neo%=vim',            'neo              vim')
+    statusline_test('should, when possible, center text when using %=text%=', 20,
+      'abc%=neovim%=def',    'abc    neovim    def')
+    statusline_test('should handle uneven spacing in the buffer when using %=text%=', 20,
+      'abc%=neo_vim%=def',   'abc   neo_vim    def')
+    statusline_test('should have equal spaces even with non-equal sides when using =', 20,
+      'foobar%=test%=baz',   'foobar   test    baz')
+    statusline_test('should have equal spaces even with longer right side when using =', 20,
+      'a%=test%=longtext',   'a   test    longtext')
+    statusline_test('should handle an empty left side when using ==', 20,
+      '%=test%=baz',         '      test       baz')
+    statusline_test('should handle an empty right side when using ==', 20,
+      'foobar%=test%=',      'foobar     test     ')
+    statusline_test('should handle consecutive empty ==', 20,
+      '%=%=test%=',          '          test      ')
+    statusline_test('should handle an = alone', 20,
+      '%=',                  '                    ')
+    statusline_test('should right align text when it is alone with =', 20,
+      '%=foo',               '                 foo')
+    statusline_test('should left align text when it is alone with =', 20,
+      'foo%=',               'foo                 ')
+
+    statusline_test('should approximately center text when using %=text%=', 21,
+      'abc%=neovim%=def',    'abc    neovim     def')
+    statusline_test('should completely fill the buffer when using %=text%=', 21,
+      'abc%=neo_vim%=def',   'abc    neo_vim    def')
+    statusline_test('should have equal spaces even with non-equal sides when using =', 21,
+      'foobar%=test%=baz',   'foobar    test    baz')
+    statusline_test('should have equal spaces even with longer right side when using =', 21,
+      'a%=test%=longtext',   'a    test    longtext')
+    statusline_test('should handle an empty left side when using ==', 21,
+      '%=test%=baz',         '       test       baz')
+    statusline_test('should handle an empty right side when using ==', 21,
+      'foobar%=test%=',      'foobar     test      ')
+
+    statusline_test('should quadrant the text when using 3 %=', 40,
+      'abcd%=n%=eovim%=ef',  'abcd         n         eovim          ef')
+    statusline_test('should work well with %t', 40,
+      '%t%=right_aligned',   'buffer_spec.lua            right_aligned',
+      {file_name='test/unit/buffer_spec.lua'})
+    statusline_test('should work well with %t and regular text', 40,
+      'l%=m_l %t m_r%=r',    'l       m_l buffer_spec.lua m_r        r',
+      {file_name='test/unit/buffer_spec.lua'})
+    statusline_test('should work well with %=, %t, %L, and %l', 40,
+      '%t %= %L %= %l',      'buffer_spec.lua           1            0',
+      {file_name='test/unit/buffer_spec.lua'})
+
+    statusline_test('should quadrant the text when using 3 %=', 41,
+      'abcd%=n%=eovim%=ef',  'abcd         n         eovim           ef')
+    statusline_test('should work well with %t', 41,
+      '%t%=right_aligned',   'buffer_spec.lua             right_aligned',
+      {file_name='test/unit/buffer_spec.lua'})
+    statusline_test('should work well with %t and regular text', 41,
+      'l%=m_l %t m_r%=r',    'l        m_l buffer_spec.lua m_r        r',
+      {file_name='test/unit/buffer_spec.lua'})
+    statusline_test('should work well with %=, %t, %L, and %l', 41,
+      '%t %= %L %= %l',      'buffer_spec.lua            1            0',
+      {file_name='test/unit/buffer_spec.lua'})
+
+    statusline_test('should work with 10 %=', 50,
+      'aaaa%=b%=c%=d%=e%=fg%=hi%=jk%=lmnop%=qrstuv%=wxyz',
+      'aaaa  b  c  d  e  fg  hi  jk  lmnop  qrstuv   wxyz')
+
+    -- maximum stl item testing
+    statusline_test('should handle a much larger amount of = than buffer locations', 20,
+      ('%='):rep(STL_MAX_ITEM - 1),
+      '                    ') -- Should be fine, because within limit
+    statusline_test('should handle a much larger amount of = than stl max item', 20,
+      ('%='):rep(STL_MAX_ITEM + 1),
+      '                E541') -- Should show the VIM error
+    statusline_test('should handle many extra characters', 20,
+      'a' .. ('a'):rep(STL_MAX_ITEM * 4),
+      '<aaaaaaaaaaaaaaaaaaa') -- Does not show the error because there are no items
+    statusline_test('should handle almost maximum of characters and flags', 20,
+      'a' .. ('%=a'):rep(STL_MAX_ITEM - 1),
+      'a<aaaaaaaaaaaaaaaaaa') -- Should not show the VIM error
+    statusline_test('should handle many extra characters and flags', 20,
+      'a' .. ('%=a'):rep(STL_MAX_ITEM),
+      'a<aaaaaaaaaaaaa E541') -- Should show the VIM error
+    statusline_test('should handle many extra characters and flags', 20,
+      'a' .. ('%=a'):rep(STL_MAX_ITEM * 2),
+      'a<aaaaaaaaaaaaa E541') -- Should show the VIM error
+    statusline_test('should handle many extra characters and flags with truncation', 20,
+      'aaa%<' .. ('%=a'):rep(STL_MAX_ITEM),
+      'aaa<aaaaaaaaaaa E541') -- Should show the VIM error
+    statusline_test('should handle many characters and flags before and after truncation', 20,
+      'a%=a%=a%<' .. ('%=a'):rep(STL_MAX_ITEM),
+      'aaa<aaaaaaaaaaa E541') -- Should show the VIM error
+
+
+    -- multi-byte testing
+    statusline_test('should handle multibyte characters', 10,
+      'Ĉ%=x',                'Ĉ        x',
+      {expected_byte_length=11})
+    statusline_test('should handle multibyte characters and different fillchars', 10,
+      'Ą%=mid%=end',         'Ą@mid@@end',
+      {fillchar=('@'):byte(), expected_byte_length=11})
 
-    end)
   end)
 end)