Class: Fatty::Pager

Inherits:
Object
  • Object
show all
Includes:
Actionable
Defined in:
lib/fatty/pager.rb

Constant Summary collapse

SCROLL_WHEEL_LINES = 
6

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Actionable

included

Constructor Details

#initialize(output:, viewport: Viewport.new, mode: :paging, lines: nil) ⇒ Pager

Returns a new instance of Pager.



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/fatty/pager.rb', line 12

def initialize(output:, viewport: Viewport.new, mode: :paging, lines: nil)
  @output   = output
  @viewport = viewport
  @lines = lines || -> { @output.lines }
  # @mode can be :paging, or :scrolling
  # - paging: the viewport displays one page worth of output at a time,
  # - scrolling: the viewport displays output continuously as it is produced.
  @mode   = mode
  @paused = false
  @autoscroll = false
  @last_nav_dir = nil
  # Search state (used by SearchSession, but owned here so paging repeats and
  # highlighting survive after the SearchSession closes).
  @isearch_snapshot = nil
  @search_snapshot = nil
  @search = {
    pattern: nil,
    regex: false,
    re: nil,
    original_direction: nil,
    last_direction: nil,
    last: nil, # { line: Integer, from: Integer, to: Integer }
    last_view_top: nil,
    pending_wrap: nil, # :forward/:backward
  }
end

Instance Attribute Details

#mode ⇒ Object (readonly)

Returns the value of attribute mode.



10
11
12
 
# File 'lib/fatty/pager.rb', line 10

def mode
  @mode
end

Instance Method Details

#act_on(action, *args, env:, **kwargs) ⇒ Object

Raises:



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/fatty/pager.rb', line 140

def act_on(action, *args, env:, **kwargs)
  raise Fatty::ActionError, "Unknown action: #{action}" unless action

  if Fatty::Actions.registered?(action)
    Fatty::Actions.call(action, env, *args, **kwargs)
  elsif respond_to?(action)
    public_send(action, *args, **kwargs)
  else
    raise Fatty::ActionError, "Unknown action: #{action}"
  end
end

#active? ⇒ Boolean

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/fatty/pager.rb', line 77

def active?
  paused? || scrolling?
end

#at_bottom? ⇒ Boolean

Returns:

  • (Boolean) 


264
265
266
 
# File 'lib/fatty/pager.rb', line 264

def at_bottom?
  @viewport.top >= max_page_top
end

#at_top? ⇒ Boolean

Returns:

  • (Boolean) 


260
261
262
 
# File 'lib/fatty/pager.rb', line 260

def at_top?
  @viewport.at_top?
end

#autoscroll? ⇒ Boolean

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/fatty/pager.rb', line 85

def autoscroll?
  @autoscroll
end

#autoscroll_step?(max_lines: 200) ⇒ Boolean

Returns:

  • (Boolean) 


323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
 
# File 'lib/fatty/pager.rb', line 323

def autoscroll_step?(max_lines: 200)
  total = lines.length
  moved = false
  if total > 0
    if @viewport.at_bottom?(total)
      @autoscroll = false
    else
      remaining = @viewport.max_top(total) - @viewport.top
      n = [remaining, max_lines].min
      before = @viewport.top
      @viewport.scroll_down(lines, n)
      moved = @viewport.top != before

      if @viewport.at_bottom?(total)
        @autoscroll = false
      end
    end
  end
  moved
end

#begin_command!(anchor:) ⇒ Object 



298
299
300
301
302
303
 
# File 'lib/fatty/pager.rb', line 298

def begin_command!(anchor:)
  @mode = :paging
  @paused = false
  @anchor = anchor
  @autoscroll = false
end

#clamp! ⇒ Object 



286
287
288
289
290
291
292
 
# File 'lib/fatty/pager.rb', line 286

def clamp!
  if paused?
    clamp_to_page!
  else
    @viewport.clamp!(lines)
  end
end

#clamp_to_page! ⇒ Object 



294
295
296
 
# File 'lib/fatty/pager.rb', line 294

def clamp_to_page!
  @viewport.top = @viewport.top.clamp(0, max_page_top)
end

#clear_search! ⇒ Object 



399
400
401
402
403
404
405
406
 
# File 'lib/fatty/pager.rb', line 399

def clear_search!
  @search[:pattern] = nil
  @search[:regex] = false
  @search[:re] = nil
  @search[:last] = nil
  @search[:original_direction] = nil
  @search[:pending_wrap] = nil
end

#finish_command! ⇒ Object 



305
306
307
308
309
310
311
312
313
314
 
# File 'lib/fatty/pager.rb', line 305

def finish_command!
  @anchor = nil
  if @mode == :scrolling && lines.length > page_height
    set_to_paging
    @viewport.top = max_page_top
  elsif @mode == :paging && lines.length > page_height
    @paused = true
    clamp_to_page!
  end
end

#first_term_match(text, from:) ⇒ Object 



585
586
587
588
589
590
591
592
593
594
595
596
597
598
 
# File 'lib/fatty/pager.rb', line 585

def first_term_match(text, from:)
  best = nil

  term_regexps.each do |term_re|
    m = term_re.match(text, from)
    next unless m

    if best.nil? || m.begin(0) < best.begin(0)
      best = m
    end
  end

  best
end

#isearch_accept!(pattern:, direction:) ⇒ Object 



682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
 
# File 'lib/fatty/pager.rb', line 682

def isearch_accept!(pattern:, direction:)
  isearch_begin!

  pattern = pattern.to_s
  if pattern.strip.empty?
    isearch_cancel!
    return { status: :not_found }
  end

  result = isearch_update!(pattern: pattern, direction: direction)
  if result[:status] == :moved
    @search[:original_direction] = direction.to_sym
    @search[:pending_wrap] = nil
    isearch_commit!
  else
    isearch_cancel!
  end

  result
end

#isearch_begin! ⇒ Object 



658
659
660
661
 
# File 'lib/fatty/pager.rb', line 658

def isearch_begin!
  ensure_isearch_snapshot!
  nil
end

#isearch_cancel! ⇒ Object 



673
674
675
676
677
678
679
680
 
# File 'lib/fatty/pager.rb', line 673

def isearch_cancel!
  if @isearch_snapshot
    @viewport.top = @isearch_snapshot[:viewport_top]
    @search = @isearch_snapshot[:search]
    @isearch_snapshot = nil
  end
  nil
end

#isearch_commit! ⇒ Object 



663
664
665
666
 
# File 'lib/fatty/pager.rb', line 663

def isearch_commit!
  @isearch_snapshot = nil
  nil
end

#isearch_step!(direction:) ⇒ Object 



668
669
670
671
 
# File 'lib/fatty/pager.rb', line 668

def isearch_step!(direction:)
  ensure_isearch_snapshot!
  search_step!(direction: direction, initial: false, update_origin: false)
end

#isearch_update!(pattern:, direction:) ⇒ Object

--- ISearch -----------------------------------------------------------



630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
 
# File 'lib/fatty/pager.rb', line 630

def isearch_update!(pattern:, direction:)
  isearch_begin!
  pattern = pattern.to_s

  result =
    if pattern.strip.empty?
      restore_isearch_anchor!
      @search[:re] = nil
      @search[:pattern] = nil
      @search[:last] = nil
      @search[:pending_wrap] = nil
      { status: :not_found }
    else
      re = compile_search_regexp(pattern, regex: false)
      @search[:pattern] = pattern
      @search[:regex] = false
      @search[:re] = re
      @search[:last_direction] = direction.to_sym

      initial = @search[:last].nil?
      search_step!(direction: direction, initial: initial, update_origin: false)
    end

  result
rescue RegexpError => e
  { status: :not_found, message: "Invalid regexp: #{e.message}" }
end

#last_term_match_before(text, limit:) ⇒ Object 



600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/fatty/pager.rb', line 600

def last_term_match_before(text, limit:)
  best = nil

  term_regexps.each do |term_re|
    text.to_enum(:scan, term_re).each do
      m = Regexp.last_match
      break if m.end(0) > limit

      if best.nil? || m.begin(0) >= best.begin(0)
        best = m
      end
    end
  end

  best
end

#max_page_top ⇒ Object 



282
283
284
 
# File 'lib/fatty/pager.rb', line 282

def max_page_top
  [lines.size - page_height, 0].max
end

#merge_highlight_ranges(ranges) ⇒ Object 



557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
 
# File 'lib/fatty/pager.rb', line 557

def merge_highlight_ranges(ranges)
  return [] if ranges.empty?

  merged = [ranges.first.dup]

  ranges.drop(1).each do |from, to, role|
    prev = merged[-1]
    _, prev_to, prev_role = prev

    if from <= prev_to
      prev[1] = [prev_to, to].max
      prev[2] = :primary if prev_role == :primary || role == :primary
    else
      merged << [from, to, role]
    end
  end

  merged
end

#nav_arrow ⇒ Object 



268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/fatty/pager.rb', line 268

def nav_arrow
  if at_top?
    "⇓"
  elsif at_bottom?
    "⇑"
  elsif @last_nav_dir == :up
    "⇑"
  elsif @last_nav_dir == :down
    "⇓"
  else
    ""
  end
end

#on_append(ntrim:) ⇒ Object

Called by OutputSession after new text is appended.



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/fatty/pager.rb', line 99

def on_append(ntrim:)
  @viewport.adjust_for_trim(ntrim)
  current_lines = lines
  total = current_lines.size
  case @mode
  when :scrolling
    # In scrolling mode, the viewport is allowed to move continuously.
    # Autoscroll animation (after switching from paging -> scrolling) is
    # driven by #autoscroll_step? in ShellSession#tick, not by incremental
    # scroll deltas during append.
    @viewport.clamp!(current_lines)
  when :paging
    if @anchor
      produced = total - @anchor
      return if produced <= 0

      # While producing the first page, keep the viewport pinned to the anchor.
      @viewport.top = @anchor
      clamp_to_page!
      if produced >= page_height
        @paused = true
        clamp_to_page!
      end
      return
    end
    if @paused
      clamp_to_page!
      return
    end

    # No anchor and not yet paused: once the output exceeds a single page,
    # pause and show the first page.
    if total > page_height
      @paused = true
      @viewport.page_top
    end
    # Otherwise user is not at bottom; don't force movement.
    @viewport.clamp!(current_lines)
  end
end

#page_bottom! ⇒ Object 



703
704
705
 
# File 'lib/fatty/pager.rb', line 703

def page_bottom!
  @viewport.top = max_page_top
end

#page_height ⇒ Object

The pager sometimes reserves a row for a status/minibuffer line. When it does, paging calculations must use a reduced page height so that the pause threshold and page-step size match what is actually rendered.



92
93
94
95
96
 
# File 'lib/fatty/pager.rb', line 92

def page_height
  h = @viewport.height
  h -= 1 if reserve_prompt_row?
  [h, 1].max
end

#page_top! ⇒ Object 



707
708
709
 
# File 'lib/fatty/pager.rb', line 707

def page_top!
  @viewport.top = 0
end

#paused? ⇒ Boolean

Returns:

  • (Boolean) 


46
47
48
 
# File 'lib/fatty/pager.rb', line 46

def paused?
  @mode == :paging && @paused
end

#plain_search? ⇒ Boolean

Returns:

  • (Boolean) 


577
578
579
 
# File 'lib/fatty/pager.rb', line 577

def plain_search?
  @search[:re] && !@search[:regex]
end

#preserve_after_resize!(was_at_bottom:) ⇒ Object 



711
712
713
714
715
716
717
 
# File 'lib/fatty/pager.rb', line 711

def preserve_after_resize!(was_at_bottom:)
  if @mode == :paging && lines.any? && was_at_bottom
    page_bottom!
  else
    clamp!
  end
end

#quit ⇒ Object 



39
40
41
42
43
44
 
# File 'lib/fatty/pager.rb', line 39

def quit
  @paused = false
  @mode = :paging
  @anchor = nil
  @autoscroll = false
end

#reserve_prompt_row? ⇒ Boolean

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/fatty/pager.rb', line 81

def reserve_prompt_row?
  paused?
end

#reset!(total_lines: 0, mode: :paging) ⇒ Object 



316
317
318
319
320
321
 
# File 'lib/fatty/pager.rb', line 316

def reset!(total_lines: 0, mode: :paging)
  @mode = mode
  @paused = false
  @autoscroll = false
  @anchor = nil
end

#scrolling? ⇒ Boolean

Returns:

  • (Boolean) 


50
51
52
 
# File 'lib/fatty/pager.rb', line 50

def scrolling?
  @mode == :scrolling
end

#search_active? ⇒ Boolean

--- Search -----------------------------------------------------------

Returns:

  • (Boolean) 


346
347
348
 
# File 'lib/fatty/pager.rb', line 346

def search_active?
  !@search[:re].nil?
end

#search_begin! ⇒ Object 



350
351
352
353
 
# File 'lib/fatty/pager.rb', line 350

def search_begin!
  ensure_search_snapshot!
  nil
end

#search_cancel! ⇒ Object 



355
356
357
358
359
360
361
362
 
# File 'lib/fatty/pager.rb', line 355

def search_cancel!
  if @search_snapshot
    @viewport.top = @search_snapshot[:viewport_top]
    @search = @search_snapshot[:search]
    @search_snapshot = nil
  end
  nil
end

#search_commit! ⇒ Object 



364
365
366
367
 
# File 'lib/fatty/pager.rb', line 364

def search_commit!
  @search_snapshot = nil
  nil
end

#search_label ⇒ Object 



617
618
619
620
621
622
623
624
625
626
 
# File 'lib/fatty/pager.rb', line 617

def search_label
  return unless @search[:re]

  # Keep showing the direction of the most recent movement (nice UX),
  # while repeat semantics depend on original_direction.
  arrow = (@search[:last_direction] == :backward ? "↑" : "↓")
  prefix = @search[:regex] ? "re:" : ""
  pat = @search[:pattern].to_s
  "#{arrow} #{prefix}#{pat}"
end

#search_last_match ⇒ Object

Exposes the last match for render-layer highlighting. (We only highlight the last match for now; later we can highlight all visible matches.)



472
473
474
 
# File 'lib/fatty/pager.rb', line 472

def search_last_match
  @search[:last]
end

#search_pattern ⇒ Object 



476
477
478
 
# File 'lib/fatty/pager.rb', line 476

def search_pattern
  @search[:pattern].to_s
end

#search_repeat_next! ⇒ Object

Vim/less semantics:

  • n repeats in the original direction (set by / ? C-s C-r)
  • N repeats in the opposite direction


458
459
460
461
 
# File 'lib/fatty/pager.rb', line 458

def search_repeat_next!
  dir = (@search[:original_direction] || :forward).to_sym
  search_step!(direction: dir, update_origin: false)
end

#search_repeat_prev! ⇒ Object 



463
464
465
466
467
 
# File 'lib/fatty/pager.rb', line 463

def search_repeat_prev!
  origin = (@search[:original_direction] || :forward).to_sym
  dir = (origin == :forward ? :backward : :forward)
  search_step!(direction: dir, update_origin: false)
end

#search_set!(pattern:, regex:, direction:) ⇒ Object

Sets the search pattern and moves the viewport to the next match. Returns a result hash:

{ status: :moved }
{ status: :not_found }

The initial search includes the currently visible page:

  • forward starts at viewport.top
  • backward starts at viewport.bottom_index(total)


377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/fatty/pager.rb', line 377

def search_set!(pattern:, regex:, direction:)
  pattern = pattern.to_s
  if pattern.strip.empty?
    clear_search!
    return { status: :not_found }
  end

  re = compile_search_regexp(pattern, regex: regex)
  @search[:pattern] = pattern
  @search[:regex] = !!regex
  @search[:re] = re
  @search[:last_direction] = direction.to_sym
  @search[:original_direction] = direction.to_sym
  @search[:last] = nil
  @search[:pending_wrap] = nil

  search_step!(direction: direction, initial: true)
rescue RegexpError => e
  clear_search!
  { status: :not_found, message: "Invalid regexp: #{e.message}" }
end

#search_step!(direction:, initial: false, update_origin: true) ⇒ Object

Steps to the next match in direction. If no match exists without wrapping, returns :boundary and requires a second step in the same direction to wrap. NOTE: Regex search is strictly line-local. Matches never span line boundaries even if '.' would normally match '\n'. This preserves pager navigation, viewport anchoring, and renderer simplicity.



416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
 
# File 'lib/fatty/pager.rb', line 416

def search_step!(direction:, initial: false, update_origin: true)
  direction = direction.to_sym
  re = @search[:re]
  @search[:last_direction] = direction.to_sym
  if update_origin
    @search[:original_direction] = direction.to_sym
  end
  return { status: :not_found } unless re

  total = lines.length
  return { status: :not_found } if total.zero?

  start = search_start_position(direction: direction, total: total, initial: initial)
  found = find_next_match(lines, re, start, direction: direction, wrap: false)

  if valid_search_match?(found)
    apply_search_match(found)
    @search[:pending_wrap] = nil
    return { status: :moved }
  end

  if @search[:pending_wrap] == direction
    # Second invocation in the same direction: wrap.
    wrap_start = wrap_start_position(direction: direction, total: total)
    found = find_next_match(lines, re, wrap_start, direction: direction, wrap: true)
    @search[:pending_wrap] = nil

    if valid_search_match?(found)
      apply_search_match(found)
      return { status: :moved, wrapped: true }
    end

    return { status: :not_found }
  end

  @search[:pending_wrap] = direction
  { status: :boundary, message: boundary_message(direction: direction) }
end

#search_visible_highlights(viewport:) ⇒ Object

Returns highlight ranges for all matches within the given viewport.

Format:

{
abs_line_index => [[from, to, :secondary], [from, to, :secondary], ...,
                  [from, to, :primary]],
...
}

Ranges are in visible text coordinates (ANSI already stripped), matching the renderer’s slice planner / highlighting behavior.



491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/fatty/pager.rb', line 491

def search_visible_highlights(viewport:)
  return unless @search[:re]
  return unless active?

  total = lines.length
  return if total.zero?

  top = viewport.top.to_i
  bottom = viewport.bottom_index(total)
  current = @search[:last]
  out = {}

  if @search[:regex]
    (top..bottom).each do |i|
      text = visible_text(lines[i])
      next if text.nil? || text.empty?

      ranges = []
      text.to_enum(:scan, @search[:re]).each do
        m = Regexp.last_match
        ranges << [m.begin(0), m.end(0), :secondary]
      end
      next if ranges.empty?

      if current && current[:line].to_i == i
        cf = current[:from].to_i
        ct = current[:to].to_i
        ranges.reject! { |a, b, _role| a == cf && b == ct }
        ranges << [cf, ct, :primary]
      end

      ranges.sort_by!(&:first)
      out[i] = merge_highlight_ranges(ranges)
    end
  else
    term_res = Fatty::Search.compile_term_regexps(@search[:pattern])

    (top..bottom).each do |i|
      text = visible_text(lines[i])
      next if text.nil? || text.empty?

      ranges = []

      term_res.each do |term_re|
        text.to_enum(:scan, term_re).each do
          m = Regexp.last_match
          ranges << [m.begin(0), m.end(0), :secondary]
        end
      end

      next if ranges.empty?

      if current && current[:line].to_i == i
        cf = current[:from].to_i
        ct = current[:to].to_i
        ranges.reject! { |a, b, _role| a == cf && b == ct }
        ranges << [cf, ct, :primary]
      end

      ranges.sort_by!(&:first)
      out[i] = merge_highlight_ranges(ranges)
    end
  end
  out.empty? ? nil : out
end

#set_to_paging ⇒ Object 



69
70
71
72
73
74
75
 
# File 'lib/fatty/pager.rb', line 69

def set_to_paging
    @mode = :paging
    @paused = true
    @autoscroll = false
    @anchor = nil
    @viewport.clamp!(lines)
end

#set_to_scrolling ⇒ Object 



63
64
65
66
67
 
# File 'lib/fatty/pager.rb', line 63

def set_to_scrolling
  @mode = :scrolling
  @paused = false
  @autoscroll = true
end

#term_regexps ⇒ Object 



581
582
583
 
# File 'lib/fatty/pager.rb', line 581

def term_regexps
  Fatty::Search.compile_term_regexps(@search[:pattern])
end

#toggle_paging_mode ⇒ Object 



54
55
56
57
58
59
60
61
 
# File 'lib/fatty/pager.rb', line 54

def toggle_paging_mode
  @last_nav_dir = :down
  if @mode == :paging
    set_to_scrolling
  else
    set_to_paging
  end
end