Module: KDoc::BlockProcessor

Includes:
KLog::Logging
Included in:
Container
Defined in:
lib/k_doc/mixins/block_processor.rb

Overview

Provide data load events, dependency and import management

A container acts a base data object for any data that requires tagging such as unique key, type and namespace.

example usage of the container using model as the basis:

KDoc.model do
  init do
    context.some_data = :xmen
  end
  settings do
    name context.some_data
  end
  action
    puts context.some_data
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#action_block ⇒ Object (readonly)

Returns the value of attribute action_block.



28
29
30
 
# File 'lib/k_doc/mixins/block_processor.rb', line 28

def action_block
  @action_block
end

#block ⇒ Object (readonly)

Returns the value of attribute block.



24
25
26
 
# File 'lib/k_doc/mixins/block_processor.rb', line 24

def block
  @block
end

#block_state ⇒ Object (readonly)

Returns the value of attribute block_state.



25
26
27
 
# File 'lib/k_doc/mixins/block_processor.rb', line 25

def block_state
  @block_state
end

#children ⇒ Object (readonly)

Returns the value of attribute children.



29
30
31
 
# File 'lib/k_doc/mixins/block_processor.rb', line 29

def children
  @children
end

#depend_on_tags ⇒ Object (readonly)

TODO: Can dependencies be extracted to their own module?



32
33
34
 
# File 'lib/k_doc/mixins/block_processor.rb', line 32

def depend_on_tags
  @depend_on_tags
end

#dependents ⇒ Object (readonly)

Returns the value of attribute dependents.



33
34
35
 
# File 'lib/k_doc/mixins/block_processor.rb', line 33

def dependents
  @dependents
end

#init_block ⇒ Object (readonly)

Returns the value of attribute init_block.



27
28
29
 
# File 'lib/k_doc/mixins/block_processor.rb', line 27

def init_block
  @init_block
end

Instance Method Details

#action(&block) ⇒ Object

rubocop:enable Metrics/AbcSize



195
196
197
 
# File 'lib/k_doc/mixins/block_processor.rb', line 195

def action(&block)
  @action_block = block
end

#actioned? ⇒ Boolean

The on_action method has been called.

Returns:

  • (Boolean) 


122
123
124
 
# File 'lib/k_doc/mixins/block_processor.rb', line 122

def actioned?
  @block_state == :actioned
end

#add_child(block) ⇒ Object 



160
161
162
 
# File 'lib/k_doc/mixins/block_processor.rb', line 160

def add_child(block)
  @children << block
end

#block_execute ⇒ Object 



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/k_doc/mixins/block_processor.rb', line 84

def block_execute
  return if @block_executed

  # Evaluate the main block of code
  fire_eval # aka primary eval

  return unless dependencies_met?

  # Call the block of code attached to the init method
  fire_init

  # Call the each block in the child array of blocks in the order of creation (FIFO)
  fire_children

  @block_executed = true
end

#children_evaluated? ⇒ Boolean

The block and the data it represents has been evaluated.

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/k_doc/mixins/block_processor.rb', line 117

def children_evaluated?
  @block_state == :children_evaluated || actioned?
end

#debug_block_processor ⇒ Object

rubocop:disable Metrics/AbcSize



216
217
218
219
220
221
222
 
# File 'lib/k_doc/mixins/block_processor.rb', line 216

def debug_block_processor
  log.kv 'block_state'        , block_state         , debug_pad_size
  log.kv 'new'                , new?                , debug_pad_size
  log.kv 'evaluated'          , evaluated?          , debug_pad_size
  log.kv 'children_evaluated' , children_evaluated? , debug_pad_size
  log.kv 'actioned'           , actioned?           , debug_pad_size
end

#depend_on(*document_tags) ⇒ Object 



48
49
50
51
52
 
# File 'lib/k_doc/mixins/block_processor.rb', line 48

def depend_on(*document_tags)
  document_tags.each do |document_tag|
    @depend_on_tags << document_tag
  end
end

#dependencies_met? ⇒ Boolean

Returns:

  • (Boolean) 


75
76
77
 
# File 'lib/k_doc/mixins/block_processor.rb', line 75

def dependencies_met?
  depend_on_tags.all? { |tag| dependents[tag] }
end

#evaluated? ⇒ Boolean

The main block has been evaluated, but child blocks are still to be processed

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/k_doc/mixins/block_processor.rb', line 107

def evaluated?
  @block_state == :evaluated || initialized?
end

#execute_block(run_actions: false) ⇒ Object 



79
80
81
82
 
# File 'lib/k_doc/mixins/block_processor.rb', line 79

def execute_block(run_actions: false)
  block_execute
  fire_action if run_actions
end

#fire_action ⇒ Object 



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/k_doc/mixins/block_processor.rb', line 199

def fire_action
  return unless children_evaluated?

  if action_block
    instance_eval(&action_block)
    @block_state = :actioned
  end
rescue StandardError => e
  log.error('Standard error while running actions')
  # puts "key #{unique_key}"
  # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
  log.error(e.message)
  @error = e
  raise
end

#fire_children ⇒ Object

Run blocks associated with the children

A child can follow one of three patterns:

  1. A block that is evaluated immediately against the parent class

  2. A class that has its own custom block evaluation

  3. A class that has a block which will be evaluated immediately against the child class

rubocop:disable Metrics/AbcSize



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/k_doc/mixins/block_processor.rb', line 171

def fire_children
  return unless initialized?

  children.each do |child|
    if child.is_a?(Proc)
      instance_eval(&child)
    elsif child.respond_to?(:fire_eval)
      child.fire_eval
    elsif child.respond_to?(:block)
      child.instance_eval(&child.block)
    end
  end

  @block_state = :children_evaluated
rescue StandardError => e
  log.error('Standard error in document with one of the child blocks')
  # puts "key #{unique_key}"
  # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
  log.error(e.message)
  @error = e
  raise
end

#fire_eval ⇒ Object 



126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/k_doc/mixins/block_processor.rb', line 126

def fire_eval
  return unless new?

  instance_eval(&block) if block

  @block_state = :evaluated
rescue StandardError => e
  log.error('Standard error in document')
  # puts "key #{unique_key}"
  # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
  log.error(e.message)
  @error = e
  raise
end

#fire_init ⇒ Object 



145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/k_doc/mixins/block_processor.rb', line 145

def fire_init
  return unless evaluated?

  instance_eval(&init_block) if init_block

  @block_state = :initialized
rescue StandardError => e
  log.error('Standard error in document on_init')
  # puts "key #{unique_key}"
  # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
  log.error(e.message)
  @error = e
  raise
end

#import(tag) ⇒ Object 



58
59
60
 
# File 'lib/k_doc/mixins/block_processor.rb', line 58

def import(tag)
  @dependents[tag]
end

#import_data(tag, as: :document) ⇒ Object 



62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/k_doc/mixins/block_processor.rb', line 62

def import_data(tag, as: :document)
  doc = import(tag)

  return nil unless doc&.data

  # log.error 'about to import'
  doc.debug(include_header: true)

  return KUtil.data.to_open_struct(doc.data) if %i[open_struct ostruct].include?(as)

  doc.data
end

#init(&block) ⇒ Object 



141
142
143
 
# File 'lib/k_doc/mixins/block_processor.rb', line 141

def init(&block)
  @init_block = block
end

#initialize_block_processor(_opts, &block) ⇒ Object 



35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/k_doc/mixins/block_processor.rb', line 35

def initialize_block_processor(_opts, &block)
  @block = block if block_given?
  @block_state = :new

  @init_block = nil
  @action_block = nil
  @children = []

  @depend_on_tags = []
  @dependents = {}
  @block_executed = false
end

#initialized? ⇒ Boolean

Has the init block been called?

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/k_doc/mixins/block_processor.rb', line 112

def initialized?
  @block_state == :initialized || children_evaluated?
end

#new? ⇒ Boolean

The underlying container is created and in the case of k_manager, registered

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/k_doc/mixins/block_processor.rb', line 102

def new?
  @block_state == :new
end

#resolve_dependency(document) ⇒ Object 



54
55
56
 
# File 'lib/k_doc/mixins/block_processor.rb', line 54

def resolve_dependency(document)
  @dependents[document.tag] = document
end