Implement tab_bar_filter

Useful to manage multiple sessions in a single kitty OS Window.
Add some docs to sessions.rst describing this use case.

Author: kovidgoyal

docs/sessions.rst

@@ -229,6 +229,20 @@ When you run the session file in another kitty instance you will see both
 windows re-created, as expected with the correct working directories and
 running programs.
 
+Managing multi tab sessions in a single OS Window
+----------------------------------------------------
+
+The natural way to organise sessions in kitty is one per :term:`os_window`.
+However, if you prefer to manage multiple sessions in a single OS Window, you
+can configure the kitty tab bar to only show tabs that belong to the currently
+active session. To do so, use :opt:`tab_bar_filter` in :file:`kitty.conf` set::
+
+    tab_bar_filter session:~ or session:^$
+
+This will restrict the tab bar to only showing tabs from the currently active
+session as well tabs that do not belong to any session. Furthermore, when you
+are in a window or tab that does not belong to any session, the tab bar will
+show the tabs from the most recent active session, to maintain context.
 
 Keyword reference
 ---------------------

kitty/boss.py

@@ -129,6 +129,7 @@
     default_save_as_session_opts,
     get_os_window_sizing_data,
     goto_session,
+    most_recent_session,
     save_as_session,
 )
 from .shaders import load_shader_programs
@@ -546,6 +547,7 @@ def match_windows(self, match: str, self_window: Optional['Window'] = None, all_
         wids = {w.id for w in all_windows}
         window_id_limit = max(wids, default=-1) + 1
         active_session = self.active_session
+        prev_active_session = most_recent_session()
 
         def get_matches(location: str, query: str, candidates: set[int]) -> set[int]:
             if location == 'id' and query.startswith('-'):
@@ -555,7 +557,7 @@ def get_matches(location: str, query: str, candidates: set[int]) -> set[int]:
                     return set()
                 if q < 0:
                     query = str(window_id_limit + q)
-            return {wid for wid in candidates if self.window_id_map[wid].matches_query(location, query, tab, self_window, active_session)}
+            return {wid for wid in candidates if self.window_id_map[wid].matches_query(location, query, tab, self_window, active_session, prev_active_session)}
 
         for wid in search(match, (
             'id', 'title', 'pid', 'cwd', 'cmdline', 'num', 'env', 'var', 'recent', 'state', 'neighbor', 'session',
@@ -574,6 +576,8 @@ def match_tabs(self, match: str, all_tabs: Iterable[Tab] | None = None) -> Itera
         tim = {t.id: t for t in all_tabs}
         tab_id_limit = max(tim, default=-1) + 1
         window_id_limit = max(self.window_id_map, default=-1) + 1
+        active_session = self.active_session
+        prev_active_session = most_recent_session()
 
         def get_matches(location: str, query: str, candidates: set[int]) -> set[int]:
             if location in ('id', 'window_id') and query.startswith('-'):
@@ -584,7 +588,7 @@ def get_matches(location: str, query: str, candidates: set[int]) -> set[int]:
                 if q < 0:
                     limit = tab_id_limit if location == 'id' else window_id_limit
                     query = str(limit + q)
-            return {wid for wid in candidates if tim[wid].matches_query(location, query, tm)}
+            return {wid for wid in candidates if tim[wid].matches_query(location, query, tm, active_session, prev_active_session)}
 
         found = False
         for tid in search(match, (

kitty/options/definition.py

@@ -1386,6 +1386,18 @@
 '''
     )
 
+opt('tab_bar_filter', '', long_text='''
+A :ref:`search expression <search_syntax>`. Only tabs that match this expression
+will be shown in the tab bar. The currently active tab is :italic:`always` shown,
+regardless of whether it matches or not. When using this option, the tab bar may
+be displayed with less tabs than specified in :opt:`tab_bar_min_tabs`, as evaluating
+the filter is expensive and is done only at display time. This is most useful when
+using :ref:`sessions <sessions>`. An expression of :code:`session:~ or session:^$`
+will show only tabs that belong to the current session or no session. The various
+tab navigation actions such as :ac:`goto_tab`, :ac:`next_tab`, :ac:`previous_tab`, etc.
+are automatically restricted to work only on matching tabs.
+''')
+
 opt('tab_bar_align', 'left',
     choices=('left', 'center', 'right'),
     long_text='''

kitty/options/parse.py

@@ -114,7 +114,8 @@ def __call__(self, key: str, opt_name: str | None = None, missing: Any = None) -
 
 The field :code:`session` matches windows that were created in the specified session.
 Use the expression :code:`^$` to match windows that were not created in a session and
-:code:`.` to match the currently active session.
+:code:`.` to match the currently active session and :code:`~` to match either the currently
+active sesison or the last active session when no session is active.
 
 When using the :code:`env` field to match on environment variables, you can specify only the environment variable name
 or a name and value, for example, :code:`env:MY_ENV_VAR=2`.
@@ -160,8 +161,9 @@ def __call__(self, key: str, opt_name: str | None = None, missing: Any = None) -
 active tab, one the previously active tab and so on.
 
 The field :code:`session` matches tabs that were created in the specified session.
-Use the expression :code:`^$` to match tabs that were not created in a session and
-:code:`.` to match the currently active session.
+Use the expression :code:`^$` to match windows that were not created in a session and
+:code:`.` to match the currently active session and :code:`~` to match either the currently
+active sesison or the last active session when no session is active.
 
 When using the :code:`env` field to match on environment variables, you can specify only the environment variable name
 or a name and value, for example, :code:`env:MY_ENV_VAR=2`. Tabs containing any window with the specified environment

kitty/options/types.py

@@ -396,6 +396,10 @@ def append_to_session_history(name: str) -> None:
     goto_session_history.append(name)
 
 
+def most_recent_session() -> str:
+    return goto_session_history[-1] if goto_session_history else ''
+
+
 def switch_to_session(boss: BossType, session_name: str) -> bool:
     w = window_for_session_name(boss, session_name)
     if w is not None:

kitty/rc/base.py

@@ -512,14 +512,27 @@ def draw_tab(
     return draw_tab
 
 
+class CellRange(NamedTuple):
+    start: int
+    end: int
+
+
+class TabExtent(NamedTuple):
+    tab_id: int
+    cell_range: CellRange
+
+    def shifted(self, shift: int) -> 'TabExtent':
+        return TabExtent(self.tab_id, CellRange(self.cell_range.start + shift, self.cell_range.end + shift))
+
+
 class TabBar:
 
     def __init__(self, os_window_id: int):
         self.os_window_id = os_window_id
         self.num_tabs = 1
         self.data_buffer_size = 0
         self.blank_rects: tuple[Border, ...] = ()
-        self.cell_ranges: list[tuple[int, int]] = []
+        self.tab_extents: Sequence[TabExtent] = ()
         self.laid_out_once = False
         self.apply_options()
 
@@ -673,7 +686,7 @@ def update(self, data: Sequence[TabBarData]) -> None:
         last_tab = data[-1] if data else None
         ed = ExtraData()
 
-        def draw_tab(i: int, tab: TabBarData, cell_ranges: list[tuple[int, int]], max_tab_length: int) -> None:
+        def draw_tab(i: int, tab: TabBarData, cell_ranges: list[TabExtent], max_tab_length: int) -> None:
             ed.prev_tab = data[i - 1] if i > 0 else None
             ed.next_tab = data[i + 1] if i + 1 < len(data) else None
             s.cursor.bg = as_rgb(self.draw_data.tab_bg(t))
@@ -682,7 +695,7 @@ def draw_tab(i: int, tab: TabBarData, cell_ranges: list[tuple[int, int]], max_ta
             before = s.cursor.x
             end = self.draw_func(self.draw_data, s, t, before, max_tab_length, i + 1, t is last_tab, ed)
             s.cursor.bg = s.cursor.fg = 0
-            cell_ranges.append((before, end))
+            cell_ranges.append(TabExtent(tab_id=tab.tab_id, cell_range=CellRange(before, end)))
             if not ed.for_layout and t is not last_tab and s.cursor.x > s.columns - max_tab_lengths[i+1]:
                 # Stop if there is no space for next tab
                 s.cursor.x = s.columns - 2
@@ -722,36 +735,36 @@ def draw_tab(i: int, tab: TabBarData, cell_ranges: list[tuple[int, int]], max_ta
 
         s.cursor.x = 0
         s.erase_in_line(2, False)
-        cr: list[tuple[int, int]] = []
+        cr: list[TabExtent] = []
         ed.for_layout = False
         for i, t in enumerate(data):
             try:
                 draw_tab(i, t, cr, max_tab_lengths[i])
             except StopIteration:
                 break
-        self.cell_ranges = cr
+        self.tab_extents = cr
         s.erase_in_line(0, False)  # Ensure no long titles bleed after the last tab
         self.align()
         update_tab_bar_edge_colors(self.os_window_id)
 
     def align_with_factor(self, factor: int = 1) -> None:
-        if not self.cell_ranges:
+        if not self.tab_extents:
             return
-        end = self.cell_ranges[-1][1]
+        end = self.tab_extents[-1].cell_range[1]
         if end < self.screen.columns - 1:
             shift = (self.screen.columns - end) // factor
             self.screen.cursor.x = 0
             self.screen.insert_characters(shift)
-            self.cell_ranges = [(s + shift, e + shift) for (s, e) in self.cell_ranges]
+            self.tab_extents = tuple(te.shifted(shift) for te in self.tab_extents)
 
     def destroy(self) -> None:
         self.screen.reset_callbacks()
         del self.screen
 
-    def tab_at(self, x: int) -> int | None:
+    def tab_id_at(self, x: int) -> int:
         if self.laid_out_once:
             x = (x - self.window_geometry.left) // self.cell_width
-            for i, (a, b) in enumerate(self.cell_ranges):
-                if a <= x <= b:
-                    return i
-        return None
+            for te in self.tab_extents:
+                if te.cell_range.start <= x <= te.cell_range.end:
+                    return te.tab_id
+        return 0