gloo-yaml 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26032d41440f6a2857d9a2ce7317d00a9a0940e7b4ada4d237a9928cba6238f1
-  data.tar.gz: 335a5da2eb3bfbf0aacedf4d264faaab1a24f6ab71696a43a8435329da15ecd4
+  metadata.gz: 5c52213b581759c71164627cd649a22d13702a526d695701f6abb7f6469b5bcd
+  data.tar.gz: 947b874647d5e232fd87c32d530fa9bff5d926877b12f3f2cfab50d0e63244ea
 SHA512:
-  metadata.gz: 1e96a78608e74f1301d13b2934f0e9daa7b98ed2f71ab410fadbce09b21e251d6dbc7667aa3bb312de0cdf1d3c080d79510f7e80ebfa94e23a3cb0513fcdb0c9
-  data.tar.gz: f076f137cd4c3f443a65decfbffe573e4dec2f5b956d6c748b3b7e51460f0b597aa67e5baa8a3ca67e2b11d11e74d4217bf46ce2a44d3cb145369dd899173d6a
+  metadata.gz: 87e99e16ef94698cbc6dd471538a31724c61002674063845ccb179b7d4a2f2d2b26e9c88f17ad39c1ce1d5d1af5b56d3412512942a521413d3272efdff0635c8
+  data.tar.gz: 6a8380687d34b2a2e76e5082acbe2c9294c89c2f7d22ac60922df96c72912e2cefbf5b1a67f0fefed01e810c2375ee6f891b27c683c7bbd644ad629c4654a8ca

data/lib/yaml_obj.rb

@@ -5,6 +5,7 @@
 # loading and saving named fields via a container object.
 #
 require 'yaml'
+require 'date'
 
 class YamlObj < Gloo::Core::Obj
 
@@ -48,40 +49,68 @@ class YamlObj < Gloo::Core::Obj
   # Load fields from the YAML file into a container.
   # The param is a path to a container object whose children
   # are matched by name to YAML keys.
+  # It is true when the file was loaded, false if it couldn't be.
   #
   def msg_load
-    return unless @params&.token_count&.positive?
+    container = param_container( 'load' )
+    return @engine.heap.it.set_to( false ) unless container
 
-    container = resolve_container
-    return unless container
+    path = resolve_path
+    return @engine.heap.it.set_to( false ) unless path
 
-    data = read_yaml_file
-    return unless data
+    data = read_yaml_file( path )
+    return @engine.heap.it.set_to( false ) unless data
 
     container.children.each do |child|
       key = child.name
-      child.set_value data[ key ].to_s if data.key?( key )
+      next unless data.key?( key )
+
+      # Nested data is planned for an upcoming release; until then a
+      # nested block or list is skipped, not loaded as Ruby's text for it.
+      if nested?( data[ key ] )
+        warn_nested( key )
+        next
+      end
+
+      child.set_value scalar_text( data[ key ] )
     end
+    @engine.heap.it.set_to true
   end
 
   #
   # Save fields from a container into the YAML file.
   # The param is a path to a container object whose children
-  # are matched by name to YAML keys.
+  # are matched by name to YAML keys. Creates the file if it does
+  # not exist; keys without a matching child are kept.
   #
   def msg_save
-    return unless @params&.token_count&.positive?
-
-    container = resolve_container
+    container = param_container( 'save' )
     return unless container
 
-    data = read_yaml_file || {}
+    path = resolve_path
+    return unless path
+
+    data = {}
+    if File.exist?( path )
+      data = read_yaml_file( path )
+      # The file couldn't be read (reported); don't overwrite it.
+      return unless data
+    end
 
     container.children.each do |child|
-      data[ child.name ] = child.value
+      key = child.name
+
+      # Nested data is planned for an upcoming release; until then a
+      # nested block or list in the file is left as it is.
+      if nested?( data[ key ] )
+        warn_nested( key )
+        next
+      end
+
+      data[ key ] = child.value
     end
 
-    write_yaml_file data
+    file_op( 'write', path ) { File.write( path, data.to_yaml ) }
   end
 
 
@@ -92,31 +121,101 @@ class YamlObj < Gloo::Core::Obj
   private
 
   #
-  # Resolve the container object from the first param.
+  # Resolve the container named by the first param. Reports a syntax
+  # error if there's no param, or an error if the container doesn't
+  # exist, and returns nil.
   #
-  def resolve_container
-    pn = Gloo::Core::Pn.new( @engine, @params.first )
-    pn.resolve
+  def param_container( msg )
+    unless @params&.token_count&.positive?
+      @engine.syntax_err "Missing the container to #{msg}! eg. tell #{name} to #{msg} (data)"
+      return nil
+    end
+
+    container = Gloo::Core::Pn.new( @engine, @params.first ).resolve
+    @engine.err Gloo::Core::NotFound.object( @params.first ) unless container
+    return container
+  end
+
+  #
+  # Get the expanded path of the YAML file (the object's value).
+  # Reports an error and returns nil if there's no path.
+  #
+  def resolve_path
+    if self.value.to_s.strip.empty?
+      @engine.err "yaml '#{name}' has no path; put a file path into #{name} first."
+      return nil
+    end
+
+    return File.expand_path( self.value )
   end
 
   #
-  # Read and parse the YAML file. Returns a hash, or nil on error.
+  # Read and parse the YAML file. Returns a hash of its keys, or nil
+  # after reporting an error: a missing or unreadable file, invalid
+  # YAML, or YAML that isn't key: value pairs. Dates and times are
+  # allowed.
   #
-  def read_yaml_file
-    path = File.expand_path( self.value )
+  def read_yaml_file( path )
     unless File.exist?( path )
-      @engine.log.error "YAML file not found: #{path}"
+      @engine.err Gloo::Core::NotFound.file( path )
       return nil
     end
-    YAML.load_file( path ) || {}
+
+    content = file_op( 'read', path ) { File.read( path ) }
+    return nil unless content
+
+    data = YAML.safe_load( content, permitted_classes: [ Date, Time ] ) || {}
+    return data if data.is_a?( Hash )
+
+    return yaml_err( path, 'it is not a list of key: value pairs' )
+  rescue Psych::SyntaxError => e
+    return yaml_err( path, e.problem )
+  rescue Psych::Exception => e
+    return yaml_err( path, e.message )
+  end
+
+  #
+  # Report YAML that can't be used, and return nil.
+  #
+  def yaml_err( path, reason )
+    @engine.err "Couldn't read the YAML in '#{path}': #{reason}."
+    return nil
+  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
+
+  #
+  # Is the value a nested block or a list (not yet supported)?
+  #
+  def nested?( val )
+    return val.is_a?( Hash ) || val.is_a?( Array )
   end
 
   #
-  # Serialize data hash and write it back to the YAML file.
+  # Warn that a nested block or list was left unchanged.
   #
-  def write_yaml_file( data )
-    path = File.expand_path( self.value )
-    File.write( path, data.to_yaml )
+  def warn_nested( key )
+    @engine.warn "YAML key '#{key}' is a nested block or list, which isn't supported yet; it was left unchanged."
+  end
+
+  #
+  # The text for a simple YAML value. YAML reads a time with no zone
+  # as UTC, so times are shown in UTC rather than converted to local
+  # time (the same as gloo-md's md_doc).
+  #
+  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
 
   # ---------------------------------------------------------------------
@@ -134,11 +233,17 @@ class YamlObj < Gloo::Core::Obj
         'file (as its own value) and supports loading and saving ' \
         'named fields via a container object.',
       :messages => [
-        'load ({container.path}) — Load fields from the YAML file into the given container. Children of the container are matched by name to YAML keys. A parameter is required.',
-        'save ({container.path}) — Save fields from the given container into the YAML file, matching container children by name to YAML keys. A parameter is required.'
+        'load ({container.path}) — Load fields from the YAML file into the given container. Children of the container are matched by name to YAML keys; dates and times load as text. A parameter is required. It is true when the file was loaded, false if it could not be.',
+        'save ({container.path}) — Save fields from the given container into the YAML file, matching container children by name to YAML keys. Creates the file if it does not exist; keys with no matching child are kept. A parameter is required.'
       ],
-      :notes => 'No vault documentation exists for this object type — ' \
-        'this was authored directly from the code.',
+      :notes => 'Errors: no container (a syntax error), a container ' \
+        'that does not exist, an empty path, a file that does not ' \
+        'exist or cannot be read or written, and YAML that is not ' \
+        'valid or is not key: value pairs. load puts false in it on ' \
+        'an error; save does not overwrite a file it could not read. ' \
+        'Nested blocks and lists are not supported yet (planned for ' \
+        'an upcoming release): load skips them with a warning, and ' \
+        'save leaves them in the file as they are.',
       :examples => <<~EXAMPLES.strip
         settings [can] :
           path [yaml] : ~/.my_app/settings.yml

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gloo-yaml
 version: !ruby/object:Gem::Version
-  version: '1.1'
+  version: '1.2'
 platform: ruby
 authors:
 - Eric Crane
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !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