More intuitive default ordering so later built-ins follow earlier

Author: dbarnett

tests/module_tests.py

@@ -5,15 +5,16 @@
 from vimdoc import error
 from vimdoc import module
 
-class TestVimPlugin(unittest.TestCase):
+class TestVimModule(unittest.TestCase):
 
   def test_section(self):
     plugin = module.VimPlugin('myplugin')
     main_module = module.Module('myplugin', plugin)
     intro = Block(vimdoc.SECTION)
     intro.Local(name='Introduction', id='intro')
     main_module.Merge(intro)
-    self.assertEquals(list(main_module.Chunks()), [intro])
+    main_module.Close()
+    self.assertEqual([intro], list(main_module.Chunks()))
 
   def test_duplicate_section(self):
     plugin = module.VimPlugin('myplugin')
@@ -25,4 +26,67 @@ def test_duplicate_section(self):
     intro2.Local(name='Intro', id='intro')
     with self.assertRaises(error.DuplicateSection) as cm:
       main_module.Merge(intro2)
-    self.assertEquals(cm.exception.args, ('Duplicate section intro defined.',))
+    self.assertEqual(('Duplicate section intro defined.',), cm.exception.args)
+
+  def test_default_section_ordering(self):
+    """Sections should be ordered according to documented built-in ordering."""
+    plugin = module.VimPlugin('myplugin')
+    main_module = module.Module('myplugin', plugin)
+    intro = Block(vimdoc.SECTION)
+    intro.Local(name='Introduction', id='intro')
+    commands = Block(vimdoc.SECTION)
+    commands.Local(name='Commands', id='commands')
+    about = Block(vimdoc.SECTION)
+    about.Local(name='About', id='about')
+    # Merge in arbitrary order.
+    main_module.Merge(commands)
+    main_module.Merge(about)
+    main_module.Merge(intro)
+    main_module.Close()
+    self.assertEqual([intro, commands, about], list(main_module.Chunks()))
+
+  def test_manual_section_ordering(self):
+    """Sections should be ordered according to explicitly configured order."""
+    plugin = module.VimPlugin('myplugin')
+    main_module = module.Module('myplugin', plugin)
+    intro = Block(vimdoc.SECTION)
+    intro.Local(name='Introduction', id='intro')
+    # Configure explicit order.
+    intro.Global(order=['commands', 'about', 'intro'])
+    commands = Block(vimdoc.SECTION)
+    commands.Local(name='Commands', id='commands')
+    about = Block(vimdoc.SECTION)
+    about.Local(name='About', id='about')
+    # Merge in arbitrary order.
+    main_module.Merge(commands)
+    main_module.Merge(about)
+    main_module.Merge(intro)
+    main_module.Close()
+    self.assertEqual([commands, about, intro], list(main_module.Chunks()))
+
+  def test_partial_ordering(self):
+    """Always respect explicit order and prefer built-in ordering.
+
+    Undeclared built-in sections will be inserted into explicit order according
+    to default built-in ordering. The about section should come after custom
+    sections unless explicitly ordered."""
+    plugin = module.VimPlugin('myplugin')
+    main_module = module.Module('myplugin', plugin)
+    intro = Block(vimdoc.SECTION)
+    intro.Local(name='Introduction', id='intro')
+    # Configure explicit order.
+    intro.Global(order=['custom1', 'intro', 'custom2'])
+    commands = Block(vimdoc.SECTION)
+    commands.Local(name='Commands', id='commands')
+    about = Block(vimdoc.SECTION)
+    about.Local(name='About', id='about')
+    custom1 = Block(vimdoc.SECTION)
+    custom1.Local(name='Custom1', id='custom1')
+    custom2 = Block(vimdoc.SECTION)
+    custom2.Local(name='Custom2', id='custom2')
+    # Merge in arbitrary order.
+    for section in [commands, custom2, about, intro, custom1]:
+      main_module.Merge(section)
+    main_module.Close()
+    self.assertEqual([custom1, intro, commands, custom2, about],
+        list(main_module.Chunks()))

vimdoc/module.py

@@ -146,35 +146,14 @@ def Close(self):
       config.Local(id='config', name='Configuration')
       self.Merge(config)
 
-    # Use explicit order as partial ordering and merge with default section
-    # ordering. All custom sections must be ordered explicitly.
-    # Custom sections will be ordered after all sections besides 'about'.
-    order = self.order or []
-    builtins_pre = []
-    for builtin in [
-        'intro',
-        'config',
-        'commands',
-        'autocmds',
-        'settings',
-        'dicts',
-        'functions',
-        'exceptions',
-        'mappings']:
-      if builtin in self.sections or builtin in self.backmatters:
-        if builtin not in order:
-          builtins_pre.append(builtin)
-    order = builtins_pre + order
-    for builtin in ['about']:
-      if builtin in self.sections or builtin in self.backmatters:
-        if builtin not in order:
-          order.append(builtin)
-    self.order = order
-
     for backmatter in self.backmatters:
       if backmatter not in self.sections:
         raise error.NoSuchSection(backmatter)
-    known = set(self.sections) | set(self.backmatters)
+    # Use explicit order as partial ordering and merge with default section
+    # ordering. All custom sections must be ordered explicitly.
+    self.order = self._GetSectionOrder(self.order, self.sections)
+
+    known = set(self.sections)
     neglected = sorted(known.difference(self.order))
     if neglected:
       raise error.NeglectedSections(neglected, self.order)
@@ -211,6 +190,46 @@ def Chunks(self):
       if ident in self.backmatters:
         yield self.backmatters[ident]
 
+  @staticmethod
+  def _GetSectionOrder(explicit_order, sections):
+    """Gets final section order from explicit_order and actual sections present.
+
+    Built-in sections with no explicit order come before custom sections, with
+    two exceptions:
+      * The "about" section comes last by default.
+      * If a built-in section is explicitly ordered, it "resets" the ordering so
+        so that subsequent built-in sections come directly after it.
+    This yields the order you would intuitively expect in cases like ordering
+    "intro" after other sections.
+    """
+    order = explicit_order or []
+    default_order = [
+      'intro',
+      'config',
+      'commands',
+      'autocmds',
+      'settings',
+      'dicts',
+      'functions',
+      'exceptions',
+      'mappings']
+    # Add any undeclared sections before custom sections, except 'about' which
+    # comes at the end by default.
+    section_insertion_idx = 0
+    order = order[:]
+    for builtin in default_order:
+      if builtin in order:
+        # Section already present. Skip and continue later sections after it.
+        section_insertion_idx = order.index(builtin) + 1
+        continue
+      else:
+        # If section present, insert into order at logical index.
+        if builtin in sections:
+          order.insert(section_insertion_idx, builtin)
+          section_insertion_idx += 1
+    if 'about' in sections and 'about' not in order:
+      order.append('about')
+    return order
 
 class VimPlugin(object):
   """State for entire plugin (potentially multiple modules)."""