[feat] support YAML format, add loadyaml and saveyaml

Author: fangq

loadjd.m

@@ -15,6 +15,7 @@
 %                *.json,.jnii,.jdt,.jmsh,.jnirs,.jbids: JSON/JData based data files, see https://neurojson.org/jdata/draft2
 %                *.bjd,.bnii,.jdb,.bmsh,.bnirs,.pmat: binary JData (BJData) files, see https://neurojson.org/bjdata/draft2
 %                *.ubj: UBJSON-encoded files, see http://ubjson.org
+%                *.yaml: YAML files, see https://yaml.org/
 %                *.msgpack: MessagePack-encoded files, see http://msgpack.org
 %                *.h5,.hdf5,.snirf,.nwb: HDF5 files, see https://www.hdfgroup.org/
 %                *.nii,.nii.gz: NIfTI files, need http://github.com/NeuroJSON/jnifty
@@ -53,6 +54,8 @@
     [varargout{1:nargout}] = loadbj(filename, varargin{:});
 elseif (regexpi(filename, '\.ubj$'))
     [varargout{1:nargout}] = loadubjson(filename, varargin{:});
+elseif (regexpi(filename, '\.yaml$'))
+    [varargout{1:nargout}] = loadyaml(filename, varargin{:});
 elseif (regexpi(filename, '\.msgpack$'))
     [varargout{1:nargout}] = loadmsgpack(filename, varargin{:});
 elseif (regexpi(filename, '\.h5$|\.hdf5$|\.snirf$|\.nwb$'))
@@ -77,6 +80,6 @@
 elseif (regexpi(filename, '\.mat$|\.bvec$|\.bval$'))
     [varargout{1:nargout}] = load(filename, varargin{:});
 else
-    warning('only support parsing .json,.jnii,.jdt,.jmsh,.jnirs,.jbids,.bjd,.bnii,.jdb,.bmsh,.bnirs,.ubj,.msgpack,.h5,.hdf5,.snirf,.pmat,.nwb,.nii,.nii.gz,.tsv,.tsv.gz,.csv,.csv.gz,.mat,.bvec,.bval; load unparsed raw data');
+    warning('only support parsing .json,.jnii,.jdt,.jmsh,.jnirs,.jbids,.bjd,.bnii,.jdb,.bmsh,.bnirs,.ubj,.yaml,.msgpack,.h5,.hdf5,.snirf,.pmat,.nwb,.nii,.nii.gz,.tsv,.tsv.gz,.csv,.csv.gz,.mat,.bvec,.bval; load unparsed raw data');
     [varargout{1:nargout}] = fileread(filename);
 end

loadyaml.m

@@ -0,0 +1,78 @@
+function [data, mmap] = loadyaml(fname, varargin)
+%
+% data=loadyaml(fname,opt)
+%    or
+% [data, mmap]=loadyaml(fname,'param1',value1,'param2',value2,...)
+%
+% parse a YAML (YAML Ain't Markup Language) file or string and return a
+% matlab data structure with optional memory-map (mmap) table
+%
+% authors:Qianqian Fang (q.fang <at> neu.edu)
+% created on 2025/01/01
+%
+% input:
+%      fname: input file name; if fname contains valid YAML syntax,
+%             fname will be interpreted as a YAML string
+%      opt: same options as loadjson (see loadjson help for details)
+%           All loadjson options are supported through yaml2json conversion
+%
+% output:
+%      dat: a cell array or struct converted from YAML
+%      mmap: (optional) memory-mapping table (see loadjson documentation)
+%
+% examples:
+%      dat=loadyaml('name: value')
+%      dat=loadyaml(['examples' filesep 'example.yaml'])
+%      [dat, mmap]=loadyaml('config.yaml','SimplifyCell',0)
+%
+% license:
+%     BSD or GPL version 3, see LICENSE_{BSD,GPLv3}.txt files for details
+%
+% -- this function is part of JSONLab toolbox (http://iso2mesh.sf.net/cgi-bin/index.cgi?jsonlab)
+%
+
+opt = varargin2struct(varargin{:});
+webopt = jsonopt('WebOptions', {}, opt);
+
+% Read YAML input (file, URL, or string)
+if (regexpi(fname, '^\s*(http|https|ftp|file)://'))
+    yamlstring = urlread(fname, webopt{:});
+elseif (exist(fname, 'file'))
+    try
+        encoding = jsonopt('Encoding', '', opt);
+        if (isempty(encoding))
+            yamlstring = fileread(fname);
+        else
+            fid = fopen(fname, 'r', 'n', encoding);
+            yamlstring = fread(fid, '*char')';
+            fclose(fid);
+        end
+    catch
+        try
+            yamlstring = urlread(fname, webopt{:});
+        catch
+            yamlstring = urlread(['file://', fullfile(pwd, fname)]);
+        end
+    end
+else
+    % Assume it's a YAML string
+    yamlstring = fname;
+end
+
+if (jsonopt('Raw', 0, opt))
+    data = yamlstring;
+    if (nargout > 1)
+        mmap = {};
+    end
+    return
+end
+
+% Convert YAML to JSON
+jsonstring = yaml2json(yamlstring);
+
+% Use loadjson to parse the converted JSON
+if (nargout > 1)
+    [data, mmap] = loadjson(jsonstring, varargin{:});
+else
+    data = loadjson(jsonstring, varargin{:});
+end

savejd.m

@@ -23,6 +23,7 @@
 %                *.json,.jnii,.jdt,.jmsh,.jnirs,.jbids: JSON/JData based data files, see https://neurojson.org/jdata/draft2
 %                *.bjd,.bnii,.jdb,.bmsh,.bnirs,.pmat: binary JData (BJData) files, see https://neurojson.org/bjdata/draft2
 %                *.ubj: UBJSON-encoded files, see http://ubjson.org
+%                *.yaml: YAML files, see https://yaml.org/
 %                *.msgpack: MessagePack-encoded files, see http://msgpack.org
 %                *.h5,.hdf5,.snirf: HDF5 files, see https://www.hdfgroup.org/
 %        opt: (optional) for JSON/JData files, these are optional 'param',value pairs
@@ -70,11 +71,13 @@
     [varargout{1:nargout}] = savebj(varargin{:});
 elseif (regexpi(filename, '\.ubj$'))
     [varargout{1:nargout}] = saveubjson(varargin{:});
+elseif (regexpi(filename, '\.yaml$'))
+    [varargout{1:nargout}] = saveyaml(varargin{:});
 elseif (regexpi(filename, '\.msgpack$'))
     [varargout{1:nargout}] = savemsgpack(varargin{:});
 elseif (regexpi(filename, '\.h5$|\.hdf5$|\.snirf$'))
     if (~exist('saveh5', 'file'))
-        error('you must first install EasyH5 from http://github.com/NeuroJSON/easyh5/');
+        error('you must first install EasyH5 from https://github.com/NeuroJSON/easyh5/');
     end
     if (~isfield(opt, 'rootname'))
         if (nargin >= 3 && ischar(varargin{1}))
@@ -85,5 +88,5 @@
     end
     [varargout{1:nargout}] = saveh5(varargin{2}, filename, opt);
 else
-    error('file suffix must be one of .json,.jnii,.jdt,.jmsh,.jnirs,.jbids,.bjd,.bnii,.jdb,.bmsh,.bnirs,.ubj,.msgpack,.h5,.hdf5,.snirf,.pmat');
+    error('file suffix must be one of .json,.jnii,.jdt,.jmsh,.jnirs,.jbids,.bjd,.bnii,.jdb,.bmsh,.bnirs,.ubj,.yaml,.msgpack,.h5,.hdf5,.snirf,.pmat');
 end