Module: Ast::Merge::BlockDirective

Included in:
FreezeNodeBase
Defined in:
lib/ast/merge/block_directive.rb

Overview

Protocol module for block directive synthetic nodes.

A block directive is an open/close comment pair that wraps content to signal merge or coverage behaviour. Two built-in kinds:

- :freeze  — content between markers is preserved from dest during merge
- :nocov   — content between markers is excluded from coverage reporting

Both kinds share the same structural shape:

- An opening marker line
- Zero or more content lines (comments, code, blank lines)
- A closing marker line

Block directives must form a clean tree:

- They may be nested (a :nocov inside a :freeze, etc.)
- They must NOT offset-overlap (crossing spans are invalid)
- They must open and close at the same syntactic tree level

Examples:

Including in a class

class MyDirective
  include Ast::Merge::BlockDirective
  def kind = :freeze
  def start_line = @start_line
  def end_line = @end_line
  def children = @nodes
  def merge_policy = :destination
end

Instance Method Summary collapse

Instance Method Details

#block_directive? ⇒ Boolean

Returns true to identify this node as a block directive.

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/ast/merge/block_directive.rb', line 79

def block_directive?
  true
end

#children ⇒ Array

This method is abstract.

Returns the child nodes contained between the open and close markers. Must be implemented by including class.

Returns:

  • (Array) —

    Content nodes (AST nodes, comment nodes, blank nodes)

Raises:

  • (NotImplementedError) 


44
45
46
 
# File 'lib/ast/merge/block_directive.rb', line 44

def children
  raise NotImplementedError, "#{self.class} must implement #children"
end

#covers_line?(line) ⇒ Boolean

Returns true if the given line number falls within this directive.

Parameters:

  • line (Integer)

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/ast/merge/block_directive.rb', line 104

def covers_line?(line)
  line_range.cover?(line)
end

#end_line ⇒ Integer

This method is abstract.

Returns the ending line number (the close marker line, 1-based). Must be implemented by including class.

Returns:

  • (Integer)

Raises:

  • (NotImplementedError) 


60
61
62
 
# File 'lib/ast/merge/block_directive.rb', line 60

def end_line
  raise NotImplementedError, "#{self.class} must implement #end_line"
end

#freeze_directive? ⇒ Boolean

Returns true if this is a freeze-kind directive.

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/ast/merge/block_directive.rb', line 85

def freeze_directive?
  kind == :freeze
end

#kind ⇒ Symbol

This method is abstract.

Returns the kind of this directive. Must be implemented by including class.

Returns:

  • (Symbol) —

    :freeze, :nocov, or a custom kind

Raises:

  • (NotImplementedError) 


36
37
38
 
# File 'lib/ast/merge/block_directive.rb', line 36

def kind
  raise NotImplementedError, "#{self.class} must implement #kind"
end

#line_range ⇒ Range

Returns the line span of this directive as a Range.

Returns:

  • (Range) 


97
98
99
 
# File 'lib/ast/merge/block_directive.rb', line 97

def line_range
  (start_line..end_line)
end

#merge_policy ⇒ Symbol?

This method is abstract.

Returns the merge policy for this directive, or nil to follow file preference.

  • :destination — dest wins (e.g., :freeze blocks are user customizations)
  • :template — template wins
  • nil — follow the file's configured preference (no override)

Must be implemented by including class.

Returns:

  • (Symbol, nil)

Raises:

  • (NotImplementedError) 


73
74
75
 
# File 'lib/ast/merge/block_directive.rb', line 73

def merge_policy
  raise NotImplementedError, "#{self.class} must implement #merge_policy"
end

#nocov_directive? ⇒ Boolean

Returns true if this is a nocov-kind directive.

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/ast/merge/block_directive.rb', line 91

def nocov_directive?
  kind == :nocov
end

#start_line ⇒ Integer

This method is abstract.

Returns the starting line number (the open marker line, 1-based). Must be implemented by including class.

Returns:

  • (Integer)

Raises:

  • (NotImplementedError) 


52
53
54
 
# File 'lib/ast/merge/block_directive.rb', line 52

def start_line
  raise NotImplementedError, "#{self.class} must implement #start_line"
end