gloo-md 1.2 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26d3d6ba34f0daaa4881b63fa84848e8ad01043d34357e67d93aad97d85bfe64
-  data.tar.gz: cd27b868d2846861b17031cbf2076c24b1f1d996238f208d5e2a1760533086d3
+  metadata.gz: 0fabc46f939b1be7b157b2ac465d414d49229dcdfa9a488d975027e72a1b0c77
+  data.tar.gz: eaee04c792674ccdc41fa779940ba8da31e4943f885238521591ccfef1d33775
 SHA512:
-  metadata.gz: 670f1cc4ca37f23fcd67ae241c26bb8c334d9cef5a49de5b5d4b3ac587e629d5f02a3999fdf390c1642c94aeec829b63ccbc4bb6da49a338fb317d81ff0ca2ba
-  data.tar.gz: cc147be4c2af1f0a82e64e504e397d6f76f32cc11e34c38d85645e6ef69324339d67b34f416e5d1a3c948cf9abfa5c37fe48236745031712a487c4c29d77aefd
+  metadata.gz: 4aebf3742809ae3b86e3e17ffbfc308b847083a76a1cda6bac82e2378b01853ac87f4bfec7390b95565e48d95794fad769d6194c08399ec6c52afbdc66d41df0
+  data.tar.gz: 36b30547c2ab17834f42e34b1376248244d2cd1a6bcbc984290f01ee499dea04beac810ac8891f34631a0dba5360546e775703c78070e99d27bd4c36fb587345

data/README.md

@@ -0,0 +1,20 @@
+# gloo-md
+
+A core gloo library for markdown rendering.
+
+## Usage
+
+Load this library in a gloo script:
+
+```gloo
+> load lib md
+```
+
+## Objects
+
+- `markdown` — markdown data in a text string, with rendering support
+- `md_doc` — a markdown file with YAML frontmatter
+
+## Full Reference
+
+Every object's children and messages are documented in-app once the library is loaded — e.g. `help> object markdown`.

data/lib/md.rb

@@ -117,14 +117,45 @@ class Md < Gloo::Core::Obj
   # Redcarpet markdown processor.
   # 
   def self.md_2_html( md )
-    markdown = Redcarpet::Markdown.new( 
-      Redcarpet::Render::HTML, 
-      autolink: true, 
+    markdown = Redcarpet::Markdown.new(
+      Redcarpet::Render::HTML,
+      autolink: true,
       fenced_code_blocks: true,
-      tables: true, 
+      tables: true,
       strikethrough: true )
-      
+
     return markdown.render( md )
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :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.',
+      :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.',
+        '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
+        md [can] :
+          f [file] :
+          on_load [script] :
+            put $.gloo.projects + "/o/data/txt.md" into md.f
+            tell md.f to read (md.data)
+            tell md.data to show
+          data [md] :
+      EXAMPLES
+    }
+  end
+
 end

data/lib/md_doc.rb

@@ -79,7 +79,9 @@ class MdDoc < Gloo::Core::Obj
 
   #
   # Read the file at path, parse frontmatter and body, populate children.
-  # Frontmatter children are created dynamically from whatever keys are present.
+  # 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.
   #
   def msg_read
     path = resolve_path
@@ -96,6 +98,7 @@ class MdDoc < Gloo::Core::Obj
     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
@@ -107,25 +110,35 @@ class MdDoc < Gloo::Core::Obj
 
   #
   # Serialize frontmatter and body children back to the file at path.
-  # Creates the file if it does not exist.
+  # 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.
   #
   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
-    fm_hash = {}
+
+    # Overlay scalar children; updating an existing key preserves its position.
     if fm_can
       fm_can.children.each do |child|
-        fm_hash[ child.name ] = child.value
+        base[ child.name ] = child.value
       end
     end
 
     body = find_child BODY
     body_text = body ? body.value.to_s : ''
 
-    content = build_content( fm_hash, body_text )
-    File.write( File.expand_path( path ), content )
+    File.write( expanded, build_content( base, body_text ) )
   end
 
 
@@ -135,6 +148,15 @@ class MdDoc < Gloo::Core::Obj
 
   private
 
+  #
+  # True for scalar YAML values that can be stored as gloo string children.
+  # Arrays, hashes, and other complex types are skipped on read.
+  #
+  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?
+  end
+
   #
   # Get the expanded path string from the path child.
   #
@@ -175,4 +197,51 @@ class MdDoc < Gloo::Core::Obj
     "---\n#{fm_yaml}---\n#{body_text}"
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  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
+
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: gloo-md
 version: !ruby/object:Gem::Version
-  version: '1.2'
+  version: '1.4'
 platform: ruby
 authors:
 - Eric Crane
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
@@ -31,16 +30,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/gloo-md.rb
 - lib/markdown_ext.rb
 - lib/md.rb
 - lib/md_doc.rb
-homepage: https://gloo.ecrane.us/
+homepage: https://github.com/ecrane/gloo
 licenses:
 - MIT
 metadata:
   gloo.type: core-library
-post_install_message:
+  documentation_uri: https://github.com/ecrane/gloo
 rdoc_options: []
 require_paths:
 - lib
@@ -55,8 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Gloo core library. Markdown support.
 test_files: []