gloo-md 1.4 → 1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fabc46f939b1be7b157b2ac465d414d49229dcdfa9a488d975027e72a1b0c77
-  data.tar.gz: eaee04c792674ccdc41fa779940ba8da31e4943f885238521591ccfef1d33775
+  metadata.gz: a096b22407ded192c923fe7a248739abdf91312dfb7c3adbb07971b8d521a8ab
+  data.tar.gz: c9e5db96603db5998f7f5d99c028760ea5d457e8efd531c5cea126491595a3e8
 SHA512:
-  metadata.gz: 4aebf3742809ae3b86e3e17ffbfc308b847083a76a1cda6bac82e2378b01853ac87f4bfec7390b95565e48d95794fad769d6194c08399ec6c52afbdc66d41df0
-  data.tar.gz: 36b30547c2ab17834f42e34b1376248244d2cd1a6bcbc984290f01ee499dea04beac810ac8891f34631a0dba5360546e775703c78070e99d27bd4c36fb587345
+  metadata.gz: 95def51afd4d575cb46bca609e233f8916c94cd40f4811751638b37b6661c9f2c8d84a902c76b64369259d477a57ee7683c0f5f34cbb33f2e8c4cbd03c660b71
+  data.tar.gz: c65726498e76d43dac867a9da4f6f47290e819d873be64eee01b2481d5519439c406d709a43595cc17f4e2c97c03133c8e972b337becfc60563a8f486a569f73

data/lib/markdown_ext.rb

@@ -26,20 +26,27 @@ class MarkdownExt
 
   # 
   # Render gloo markdown extensions.
+  # A block runs from its [!...] line to the next blank line, the next
+  # block, or the end of the data. The engine, when given, is used to
+  # warn about an unknown extension.
   # 
-  def self.render_extensions data
+  def self.render_extensions( data, engine = nil )
     return '' if data.nil?
 
     out_data = ""
     one_ext = ""
     in_ext = false
     data.lines.each_with_index do |line, index|
-      if line.start_with?( '[!' )
+      # A line starting [![ is a Markdown image link (eg. a badge), not a block.
+      if line.start_with?( '[!' ) && !line.start_with?( '[![' )
+        # A new block finishes any block still open; a blank line keeps
+        # the two apart for the Markdown renderer.
+        out_data << render_one_ext( one_ext, engine ) << "\n" if in_ext
         in_ext = true
-        one_ext = line
+        one_ext = line.dup
       elsif in_ext && line.strip.blank?
         in_ext = false
-        out_data << render_one_ext( one_ext )
+        out_data << render_one_ext( one_ext, engine )
         out_data << line
       elsif in_ext
         one_ext << line
@@ -48,6 +55,9 @@ class MarkdownExt
       end
     end
 
+    # A block at the very end has no blank line after it.
+    out_data << render_one_ext( one_ext, engine ) if in_ext
+
     return out_data
   end
 
@@ -58,7 +68,7 @@ class MarkdownExt
   # 
   # Render one markdown extension.
   # 
-  def self.render_one_ext( data )
+  def self.render_one_ext( data, engine = nil )
     if data.start_with?( PANEL )
       return render_panel( data )
     elsif data.start_with?( QUOTE )
@@ -72,9 +82,10 @@ class MarkdownExt
     elsif data.start_with?( IDEA )
       return render_idea( data )
     else
-      # ERROR
-      puts "ERROR: unknown markdown extension: #{data}"
-      return ""
+      # Keep the block as plain text so its content isn't lost.
+      tag = data.lines.first.to_s[ /\A\[![^\]]*\]?/ ]
+      engine&.warn "Unknown markdown extension '#{tag}'; it was shown as plain text."
+      return data
     end
   end
 

data/lib/md.rb

@@ -67,21 +67,26 @@ class Md < Gloo::Core::Obj
 
   #
   # Render the markdown as HTML.
-  # Needs an optional parameter of where to put the rendered html.
-  # The html will be in 'it' as well.
+  # With an optional destination, the HTML goes there and it is true
+  # (false if the destination doesn't exist). With none, the HTML is
+  # put in it.
   #
   def msg_render
-    html = MarkdownExt.render_extensions( value )
+    html = MarkdownExt.render_extensions( value, @engine )
     html = Md.md_2_html( html )
 
-    # Put the HTML in the optional parameter if one is given.
     if @params&.token_count&.positive?
       pn = Gloo::Core::Pn.new( @engine, @params.first )
       o = pn.resolve
+      unless o
+        @engine.err Gloo::Core::NotFound.object( @params.first )
+        return @engine.heap.it.set_to( false )
+      end
+
       o.set_value html
+      return @engine.heap.it.set_to( true )
     end
 
-    # Put the HTML in it, in any case.
     @engine.heap.it.set_to html
   end
 
@@ -140,10 +145,13 @@ class Md < Gloo::Core::Obj
       :shortcut => KEYWORD_SHORT,
       :description => 'Markdown data in a text string. Also supports ' \
         'gloo Markdown extensions (panel, note, quote, idea and check ' \
-        'blocks) rendered via MarkdownExt when the data is rendered.',
+        'blocks) rendered via MarkdownExt when the data is rendered. ' \
+        'A block runs from its [!...] line to the next blank line, the ' \
+        'next block, or the end of the text. An unknown extension is ' \
+        'kept as plain text, with a warning.',
       :messages => [
         'show — Show the markdown data in the terminal.',
-        'render ({dst}) — Convert the markdown to HTML and put it in the {dst} object. The HTML is also put into it either way.',
+        'render ({dst}) — Convert the markdown to HTML. With {dst}, the HTML is put in the {dst} object and it is true (a {dst} that does not exist is an error, and it is false). With no {dst}, the HTML is put in it.',
         'update_asset_path — Update asset paths for all images in the source markdown, so files can refer to images from a path different from the page using them.'
       ],
       :examples => <<~EXAMPLES.strip

data/lib/md_doc.rb

@@ -6,6 +6,7 @@
 # children and the Markdown body as a text child.
 #
 require 'yaml'
+require 'date'
 
 class MdDoc < Gloo::Core::Obj
 
@@ -79,66 +80,75 @@ class MdDoc < Gloo::Core::Obj
 
   #
   # 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.
+  # Only scalar frontmatter values (including dates and times) become gloo
+  # string children; complex values (arrays, nested hashes) are skipped —
+  # they are preserved on write by re-reading the file.
+  # It is true when the file was read, false if it couldn't be.
   #
   def msg_read
     path = resolve_path
-    return unless path
+    return @engine.heap.it.set_to( false ) unless path
 
-    unless File.exist?( path )
-      @engine.log.error "md_doc file not found: #{path}"
-      return
-    end
+    content = read_file( path )
+    return @engine.heap.it.set_to( false ) unless content
 
-    content = File.read( path )
-    fm_hash, body_text = parse_frontmatter( content )
+    fm_hash, body_text = parse_frontmatter( content, path )
+    return @engine.heap.it.set_to( false ) unless fm_hash
 
     fm_can = find_child FRONTMATTER
-    if fm_can && fm_hash
+    # Start from the file's keys only, not ones left from an earlier read.
+    fm_can&.delete_children
+    if fm_can
       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
+        child.set_value scalar_text( val )
       end
     end
 
     body = find_child BODY
     body.set_value( body_text ) if body
+    @engine.heap.it.set_to true
   end
 
   #
   # 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.
+  # complex values), then overlays the scalar children that were changed.
+  # Creates the file if it does not exist.
   #
   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 ) )
+    if File.exist?( path )
+      content = read_file( path )
+      return unless content
+
+      base, _ = parse_frontmatter( content, path )
+      # Invalid frontmatter was reported; don't overwrite the file.
+      return unless base
     end
 
     fm_can = find_child FRONTMATTER
 
-    # Overlay scalar children; updating an existing key preserves its position.
+    # Overlay changed children; updating an existing key preserves its
+    # position, and an unchanged one keeps its YAML type (eg. a date).
+    # A changed one keeps its type too when its new text fits it.
     if fm_can
       fm_can.children.each do |child|
-        base[ child.name ] = child.value
+        next if base.key?( child.name ) && scalar_text( base[ child.name ] ) == child.value.to_s
+
+        base[ child.name ] = typed_value( 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 ) )
+    file_op( 'write', path ) { File.write( path, build_content( base, body_text ) ) }
   end
 
 
@@ -154,33 +164,129 @@ class MdDoc < Gloo::Core::Obj
   #
   def scalar?( val )
     val.is_a?( String ) || val.is_a?( Integer ) || val.is_a?( Float ) ||
-      val.is_a?( TrueClass ) || val.is_a?( FalseClass ) || val.nil?
+      val.is_a?( TrueClass ) || val.is_a?( FalseClass ) || val.nil? ||
+      val.is_a?( Date ) || val.is_a?( Time )
+  end
+
+  #
+  # The text for a scalar frontmatter value, as its string child holds it.
+  # YAML reads a time with no zone as UTC, so times are shown in UTC
+  # (eg. 2026-10-01 09:30:00 UTC) rather than converted to local time.
+  #
+  def scalar_text( val )
+    return val.utc.strftime( '%Y-%m-%d %H:%M:%S UTC' ) if val.is_a?( Time )
+
+    return val.to_s
+  end
+
+  #
+  # The kind of a frontmatter value whose type write keeps: :boolean,
+  # :number, :date or :time. Nil for text and anything else.
+  #
+  def value_kind( val )
+    case val
+    when TrueClass, FalseClass then :boolean
+    when Integer, Float then :number
+    when Time then :time
+    when Date then :date
+    end
+  end
+
+  #
+  # The value to write for a changed child. If the old value was a
+  # boolean, number, date or time, and the new text reads as the same
+  # kind of value (and back as the same text), write it as that kind;
+  # otherwise write the text as a string.
+  #
+  def typed_value( old, text )
+    kind = value_kind( old )
+    return text unless kind
+
+    # Read shows times with a UTC suffix, which YAML spells Z.
+    parsed = YAML.safe_load( text.to_s.sub( / UTC\z/, ' Z' ), permitted_classes: [ Date, Time ] )
+    return text unless value_kind( parsed ) == kind
+    # Text that YAML would trim or reinterpret (eg. '3 # note') stays text.
+    return text unless without_zone( scalar_text( parsed ) ) == without_zone( text.to_s )
+
+    return parsed
+  rescue Psych::Exception
+    return text
+  end
+
+  #
+  # A time's text without a trailing UTC or Z zone, for comparing.
+  #
+  def without_zone( text )
+    return text.sub( / (UTC|Z)\z/, '' )
   end
 
   #
   # Get the expanded path string from the path child.
+  # Reports an error and returns nil if there's no path.
   #
   def resolve_path
     o = find_child PATH
-    return nil unless o
-    return nil if o.value.to_s.strip.empty?
+    if o.nil? || o.value.to_s.strip.empty?
+      @engine.err "md_doc '#{name}' has no path; put a file path into #{name}.path first."
+      return nil
+    end
 
     File.expand_path( o.value.to_s )
   end
 
+  #
+  # Read the file at path. Reports an error and returns nil if it's
+  # missing or can't be read.
+  #
+  def read_file( path )
+    unless File.exist?( path )
+      @engine.err Gloo::Core::NotFound.file( path )
+      return nil
+    end
+
+    return file_op( 'read', path ) { File.read( path ) }
+  end
+
+  #
+  # Run a file operation, reporting a failure (eg. no permission, a
+  # missing folder) as an error. Returns nil if it failed.
+  #
+  def file_op( action, path )
+    return yield
+  rescue SystemCallError => e
+    @engine.err "Could not #{action} '#{path}': #{e.message}"
+    return nil
+  end
+
   #
   # Parse YAML frontmatter from file content.
   # Returns [fm_hash, body_text]. If there is no frontmatter block,
   # fm_hash is empty and body_text is the full content.
+  # Dates and times are allowed. Invalid YAML is reported as an error,
+  # and fm_hash is nil.
   #
-  def parse_frontmatter( content )
+  def parse_frontmatter( content, path )
     if content =~ /\A---\s*\n(.*?\n)---\s*\n?(.*)\z/m
-      fm_hash   = YAML.safe_load( $1 ) || {}
-      body_text = $2
-      return fm_hash, body_text
+      fm_text, body_text = $1, $2
+      fm_hash = YAML.safe_load( fm_text, permitted_classes: [ Date, Time ] ) || {}
+      return fm_hash, body_text if fm_hash.is_a?( Hash )
+
+      return frontmatter_err( path, "it isn't a list of key: value pairs" )
     end
 
     return {}, content
+  rescue Psych::SyntaxError => e
+    return frontmatter_err( path, "it isn't valid YAML (#{e.problem})" )
+  rescue Psych::Exception => e
+    return frontmatter_err( path, "it couldn't be loaded (#{e.message})" )
+  end
+
+  #
+  # Report frontmatter that can't be used, and return no hash or body.
+  #
+  def frontmatter_err( path, reason )
+    @engine.err "Couldn't read the frontmatter in '#{path}': #{reason}."
+    return nil, nil
   end
 
   #
@@ -192,8 +298,15 @@ class MdDoc < Gloo::Core::Obj
       return body_text
     end
 
+    # Write times in UTC, as they were most likely written, not local time.
+    fm_hash = fm_hash.transform_values { |v| v.is_a?( Time ) ? v.utc : v }
+
     # to_yaml emits "---\nkey: val\n"; strip the leading "---\n" and rewrap.
     fm_yaml = fm_hash.to_yaml.sub( /\A---\n/, '' )
+
+    # to_yaml writes a UTC time as 2026-10-01 09:30:00.000000000 Z. A time
+    # with no zone reads as UTC, so dropping the suffix keeps the same time.
+    fm_yaml = fm_yaml.gsub( /(\d{4}-\d\d-\d\d \d\d:\d\d:\d\d)\.0+ Z$/, '\1' )
     "---\n#{fm_yaml}---\n#{body_text}"
   end
 
@@ -220,15 +333,18 @@ class MdDoc < Gloo::Core::Obj
         '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.'
+        'read — Read the file at path, parse the YAML frontmatter and Markdown body. The frontmatter children are replaced with exactly the keys in the file (keys from an earlier read are removed); dates and times become text (times in UTC). Populates frontmatter.* children and body. It is true when the file was read, false if it could not be.',
+        '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. A value keeps its YAML type (a date, time, number or true/false): unchanged values always, and changed values when the new text is that type too (eg. 2026-10-05 for a date); otherwise the new text is written as text.'
       ],
       :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.',
+        'content. These are errors, and read leaves the children as ' \
+        'they were and puts false in it: an empty path, a file that ' \
+        'does not exist or cannot be read, and frontmatter that is not ' \
+        'valid YAML. An empty path or a failed write is also an error ' \
+        'for write; write does not overwrite a file whose frontmatter ' \
+        "is not valid YAML. Uses Ruby's built-in psych library for " \
+        'YAML parsing — no additional dependencies.',
       :examples => <<~EXAMPLES.strip
         doc [md_doc] :
           path [file] : ~/notes/project.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gloo-md
 version: !ruby/object:Gem::Version
-  version: '1.4'
+  version: '1.5'
 platform: ruby
 authors:
 - Eric Crane
@@ -23,6 +23,74 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.6.0
+- !ruby/object:Gem::Dependency
+  name: gloo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
 description: Adds Markdown support to Gloo.
 email:
 - eric.crane@mac.com