Class: MdDoc

Inherits:
Gloo::Core::Obj
  • Object
show all
Defined in:
lib/md_doc.rb

Constant Summary collapse

KEYWORD = 
'md_doc'.freeze
KEYWORD_SHORT = 
'md_doc'.freeze
PATH = 
'path'.freeze
FRONTMATTER = 
'frontmatter'.freeze
BODY = 
'body'.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.doc_data ⇒ Object

Get the object's documentation data.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/md_doc.rb', line 207

def self.doc_data
  {
    :name => KEYWORD,
    :shortcut => KEYWORD_SHORT,
    :description => 'A Markdown file with YAML frontmatter. Holds a ' \
      'path to a .md file and exposes the frontmatter fields as ' \
      'dynamic string children under frontmatter, and the Markdown ' \
      'body as a text child under body. Use read to load a file into ' \
      'the object tree and write to serialize it back. Both ' \
      'frontmatter and body can be modified between a read and a write.',
    :children => [
      'path (file) — Path to the Markdown file.',
      'frontmatter (container) — Container whose children map to YAML frontmatter keys.',
      'body (text) — The Markdown body (everything after the --- closing delimiter).'
    ],
    :messages => [
      'read — Read the file at path, parse the YAML frontmatter and Markdown body. Frontmatter children are created dynamically from whatever keys are present in the file. Populates frontmatter.* children and body.',
      'write — Serialize frontmatter children back to YAML and combine with body. Writes the result to the file at path, creating it if it does not exist. Key order is preserved; quoting style may normalize on first write, but semantic content is unchanged.'
    ],
    :notes => 'If the file has no frontmatter block, frontmatter ' \
      'will have no children and body will contain the full file ' \
      'content. If path is empty or the file does not exist, read ' \
      'logs an error and returns without modifying children. Uses ' \
      "Ruby's built-in psych library for YAML parsing — no " \
      'additional dependencies.',
    :examples => <<~EXAMPLES.strip
      doc [md_doc] :
        path [file] : ~/notes/project.md
        frontmatter [can] :
        body [text] :

      on_load [script] :
        load lib md
        tell doc to read
        show doc.frontmatter.title
        show doc.body
    EXAMPLES
  }
end

.messages ⇒ Object

Get a list of message names that this object receives.



76
77
78
 
# File 'lib/md_doc.rb', line 76

def self.messages
  return super + %w[read write]
end

.short_typename ⇒ Object

The short name of the object type.



34
35
36
 
# File 'lib/md_doc.rb', line 34

def self.short_typename
  return KEYWORD_SHORT
end

.typename ⇒ Object

The name of the object type.



27
28
29
 
# File 'lib/md_doc.rb', line 27

def self.typename
  return KEYWORD
end

Instance Method Details

#add_children_on_create? ⇒ Boolean

Does this object have children to add when an object is created in interactive mode?

Returns:

  • (Boolean) 


54
55
56
 
# File 'lib/md_doc.rb', line 54

def add_children_on_create?
  return true
end

#add_default_children ⇒ Object

Add the default children: path, frontmatter, body.



61
62
63
64
65
66
 
# File 'lib/md_doc.rb', line 61

def add_default_children
  fac = @engine.factory
  fac.create_file PATH, nil, self
  fac.create_can FRONTMATTER, self
  fac.create_text BODY, nil, self
end

#msg_read ⇒ Object

Read the file at path, parse frontmatter and body, populate children. Only scalar frontmatter values become gloo string children; complex values (arrays, nested hashes) are skipped — they are preserved on write by re-reading the file.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/md_doc.rb', line 86

def msg_read
  path = resolve_path
  return unless path

  unless File.exist?( path )
    @engine.log.error "md_doc file not found: #{path}"
    return
  end

  content = File.read( path )
  fm_hash, body_text = parse_frontmatter( content )

  fm_can = find_child FRONTMATTER
  if fm_can && fm_hash
    fm_hash.each do |key, val|
      next unless scalar?( val )
      child = fm_can.find_add_child( key.to_s, 'string' )
      child.set_value val.to_s
    end
  end

  body = find_child BODY
  body.set_value( body_text ) if body
end

#msg_write ⇒ Object

Serialize frontmatter and body children back to the file at path. Re-reads the current file to get the base hash (preserving arrays and other complex values), then overlays the scalar children which may have been modified. Creates the file if it does not exist.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/md_doc.rb', line 117

def msg_write
  path = resolve_path
  return unless path

  expanded = File.expand_path( path )

  # Re-read the file so arrays and nested hashes survive unchanged.
  base = {}
  if File.exist?( expanded )
    base, _ = parse_frontmatter( File.read( expanded ) )
  end

  fm_can = find_child FRONTMATTER

  # Overlay scalar children; updating an existing key preserves its position.
  if fm_can
    fm_can.children.each do |child|
      base[ child.name ] = child.value
    end
  end

  body = find_child BODY
  body_text = body ? body.value.to_s : ''

  File.write( expanded, build_content( base, body_text ) )
end

#set_value(new_value) ⇒ Object

Set the value with any necessary type conversions.



41
42
43
 
# File 'lib/md_doc.rb', line 41

def set_value( new_value )
  self.value = new_value.to_s
end