cocos 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f34f86372be24c8d19abde781cc66b5d9c6b323e09c7620221f30b9e115b786d
-  data.tar.gz: d025bedc0c96372e74339bd4a0ae7fcd56857d23a1678b35c1b2a8aef2b1be12
+  metadata.gz: e276117f95b89fcfc61f23559b725c3905aa8668eb6b0b7e7175c4fe57eb1a86
+  data.tar.gz: 1b3043bd0de213189a8e531d4fea92ccf7b1262636067a05c914261a66d4338c
 SHA512:
-  metadata.gz: 50b9cc405bb2d5e16900958a55c11fcf02b5854a4410c072cbab51d585c3a656f9a9a8bb4246b51fc7b46d0200d7fefa98ea3bd4d0e95bb455c8e60dc92c6e10
-  data.tar.gz: fc797f93f3f73644b5b6ee6695564ffd4f4f7308aa8412d5d62785baa9301e5cd740ceb017215d7a3417884edcc057044e15c938bea1310c4c217cbb310d188b
+  metadata.gz: ff35b353cde05f6f76e6b6069442abda8769488768edaba6dfd2b411b06ec24aac97d0a10c25bcac08ba5617451e2a9c800861a5bd535e4d347b8e68b17eb747
+  data.tar.gz: '08c86a7e5950818e53c38668b68259e4248be7e0ef5201a52a570349e7dfe803dd6a534af73ca45ca7745fadc9a19022c15d08a38a121c5153fbc7705035e153'

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-### 0.4.0
+### 0.4.2
 ### 0.0.1 / 2022-08-01
 
 * Everything is new. First release.

data/Manifest.txt

@@ -5,4 +5,5 @@ README.md
 Rakefile
 lib/cocos.rb
 lib/cocos/env.rb
+lib/cocos/find_file.rb
 lib/cocos/version.rb

data/README.md

@@ -50,7 +50,7 @@ txt = File.read( "history.txt" )
 # (e.g. on microsoft windows it is ISO Code Page (CP-1252
 # or something - depending on your locale/culture/language)
 
-txt = File.open( "history.txt", "r:utf-8" ) do |f|
+txt = File.open( "history.txt", "r:bom|utf-8" ) do |f|
              f.read
          end
 ```
@@ -61,7 +61,7 @@ and always repeating the same open / read and code block dance
 again and again e.g.:
 
 ``` ruby
-txt  = File.open( "history.json", "r:utf-8" ) do |f|
+txt  = File.open( "history.json", "r:bom|utf-8" ) do |f|
              f.read
          end
 data = JSON.parse( txt )
@@ -94,7 +94,7 @@ _Read / parse convenience short-cut helpers_
 also known as `read_txt`
 
 
-`read_lines( path )`
+`read_lines( path, chomp: true|false )`
 
 
 `read_json( path )` / `parse_json( str )`
@@ -138,5 +138,4 @@ That's it for now.
 ## License
 
 The `cocos` scripts are dedicated to the public domain.
-Use it as you please with no restrictions whatsoever.
-
+Use as you please with no restrictions whatsoever.

data/Rakefile

@@ -12,7 +12,7 @@ Hoe.spec 'cocos' do
   self.urls = { home: 'https://github.com/rubycocos/cocos' }
 
   self.author = 'Gerald Bauer'
-  self.email = 'gerald.bauer@gmail.com'
+  self.email  = 'gerald.bauer@gmail.com'
 
   # switch extension to .markdown for gihub formatting
   self.readme_file  = 'README.md'

data/lib/cocos/env.rb

@@ -2,7 +2,7 @@
 # simple read_env, load_env machinery
 ##   inspired by
 ##      dotenv gem -> https://github.com/bkeepers/dotenv
-##      figaro     -> https://github.com/laserlemon/figaro  
+##      figaro     -> https://github.com/laserlemon/figaro
 ##      and others
 
 
@@ -13,60 +13,65 @@ module EnvParser
     # returns a hash
     #  (compatible structure - works like YAML.load_file)
     #
-    #   change to .read(path) and parse( text) - why? why not?
+    #   change to .read(path) and parse(text) - why? why not?
     def self.load_file( path )
-        text = File.open( path, 'r:utf-8' ) { |f| f.read }
+        text = File.open( path, 'r:bom|utf-8', newline: :lf) { |f| f.read }
         parse( text )
     end
     def self.load( text )   parse( text ); end
- 
-    
+
+
     class Error < StandardError; end
-  
+
     ## todo/check - what is JSON and YAML returning Parser/ParseError something else?
     ##  YAML uses ParseError  and JSON uses ParserError
     class ParseError < Error; end
-  
+
 
     ## todo/check - if support for empty values e.g. abc=  is required/possible???
     ##  todo/ addd support for quoted values - why? why not?
     ##  add support for "inline" end of line comments - why? why not?
     ##  add support for escapes and multi-line values - why? why not?
-LINE_RX = /\A(?<key>[A-Za-z][A-Za-z0-9_-]*)
+LINE_RE =  %r{\A
+                 [ ]*
+             (?<key> [A-Za-z][A-Za-z0-9_-]*)
                  [ ]*
                    =
                  [ ]*
                (?<value>.+?)    ## non-greedy
+                 [ ]*
               \z
-             /x
+             }x
 
-  ## use a parser class - why? why not?
-  def self.parse( text )
-   h = {}
+## use a parser class - why? why not?
+def self.parse( text )
+  h = {}
 
-   lineno = 0   
+  lineno = 0
   text.each_line do |line|
     lineno += 1    ## track line numbers for (parse) error reporting
-
     line = line.strip   ## check: use strip (or be more strict) - why? why not?
+
     ## skip empty and comment lines
-    next if line.empty? || line.start_with?( '#' )
+    next   if line.empty? || line.start_with?( '#' )
+    ##  support __END__ marker for inline comments
+    break  if line == '__END__'
 
-    if m=LINE_RX.match(line)
+    if m=LINE_RE.match(line)
       key   = m[:key]
       value = m[:value]
-      
+
       ## todo/check - check/warn about duplicates - why? why not?
       h[key] = value
-   else 
+    else
       raise ParseError,  "line #{lineno} - unknown line type; cannot parse >#{line}<"
-   end
+    end
   end
   h
 end   # methdod self.parse
 end  # module EnvParser
 
-  
+
 
 __END__
 

data/lib/cocos/find_file.rb

@@ -0,0 +1,83 @@
+
+
+##
+## note - use File.file? instead of File.exist?
+##            (checks if file exists AND file is a file NOT a directory)
+##
+##
+##   add  option - raise_on_error: false  - why? why not?
+##     def find_file!  - find_file(  raise_on_error: false )
+##
+##  todo/check
+##    golang  lookup_path or such
+##     always return absolute (expanded) path - why? why not?
+
+
+module Kernel
+
+def find_file!( name, path: )
+    filepath = find_file( name, path: path )
+    raise Errno::ENOENT, "file #{name.inspect} not found; looking in path #{path.inspect}"   if filepath.nil?
+    filepath
+end
+
+##
+##  note - find_file will NOT find directories!!!
+##                          File.file? will only check if a file (not directory) exits!!
+
+##
+## todo/check - expand path and use File.realpath too?
+##           or keep "simple" File.join ?
+
+##
+##  note - always expand path for now and return absolute path!
+##
+##  note - do NOT search path if name passed in is absolute!!!
+def find_file( name, path: )
+    filepath = File.expand_path( name )
+    return filepath   if File.file?( filepath )
+
+##  note - if name starts with root / or c:\
+##          assume it's absolute - handle by Pathname lib for now
+##    do NOT search!!!
+    return nil    if Pathname.new(name).absolute?
+
+    path.each do |basedir|
+        filepath = File.expand_path( name, basedir )
+        return filepath   if File.file?( filepath )
+    end
+
+    nil   ## return nil if not found
+end
+
+
+
+def find_dir( name, path: [] )
+    dirpath = File.expand_path( name )
+    return dirpath   if Dir.exist?( dirpath )
+
+##  note - if name starts with / or \ assume it's absolute!!
+##    do NOT search!!!
+##     note - search still works for
+##               ./austria  or ../austria or such
+##
+##  todo/check/fix-fix-fix
+##     is there a File.absolute? or such method for reuse??
+##
+##  todo/fix-fix-fix add absolute check upstream to find_file too!!!
+   ## return nil    if name.start_with?( %r{[/\\]} )
+   ##  note - Pathname#absolute? is basically !Pathname#relative? !!!
+      return nil    if Pathname.new(name).absolute?
+
+    path.each do |basedir|
+        ## todo/check -  always make sure basedir is an absolute/expanded path - why? why not?
+        dirpath = File.expand_path( name, basedir )
+        return dirpath   if Dir.exist?( dirpath )
+    end
+
+    nil   ## return nil if not found
+end
+
+
+
+end  # module Kernel

data/lib/cocos/version.rb

@@ -2,7 +2,7 @@
 module Cocos
   MAJOR = 0    ## todo: namespace inside version or something - why? why not??
   MINOR = 4
-  PATCH = 0
+  PATCH = 2
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/lib/cocos.rb

@@ -8,6 +8,8 @@ require 'json'
 require 'yaml'
 require 'base64'    ## e.g. Base64.decode64,Base64.encode64,...
 require 'fileutils'
+require 'pathname'  ## used by find_file/find_dir to check for absolute? etc.
+
 
 require 'uri'
 require 'net/http'
@@ -33,13 +35,15 @@ require_relative 'cocos/version'   # note: let version always go first
 require_relative 'cocos/env'       ## e.g. EnvParser
 
 
+require_relative 'cocos/find_file'
+
+
 ###
 ##  read/parse convenience/helper shortcuts
 
 
-module Kernel
-
 
+module Kernel
 
 ################
 #  private helpers - keep along here - why? why not?
@@ -48,6 +52,20 @@ module Kernel
 ## todo:  add symbolize options a la read_json? - why? why not?
 ##         add sep options
 
+  ##
+  ##  todo - add upstream
+  ##            to CsvHash.read
+  ##                    newline option on read/write and
+  ##                     bom    option on read
+  ## note:
+  ##  (i) :newline => :lf option
+  #      Reads text natively; normalizes all incoming newlines to strict LF (\n)
+  ##  (ii) 'bom|' flag
+  ##   The 'bom|' flag instructs Ruby to drop the BOM bytes if they exist
+  ##  File.open( path, 'r:bom|utf-8', newline: :lf) do |f|
+
+
+
 def read_csv( path, sep: nil )
   opts = {}
   opts[:sep] = sep  if sep
@@ -105,6 +123,10 @@ def download_tab( url )
 end
 
 
+##  fix-fix-fix
+##    for json  add new strict: true|false option (default is false!)
+##       add   option for allowing trailing_commas and comments!!!
+##         see JSON.parse  for more
 
 ## todo:  add symbolize options ???
 def read_json( path )
@@ -151,20 +173,19 @@ def download_ini( url )
    parse_ini( download_text( url ))
 end
 
-alias_method :read_conf, :read_ini
-alias_method :parse_conf, :parse_ini
+alias_method :read_conf,     :read_ini
+alias_method :parse_conf,    :parse_ini
 alias_method :download_conf, :download_ini
 
 
 
-
 def read_text( path )
-   ## todo/check: add universal newline mode or such?
-   ##  e.g. will always convert all
-   ##    newline variants (\n|\r|\n\r) to "universal" \n only
-   ##
-   ##  add r:bom  - why? why not?
-    File.open( path, 'r:utf-8' ) do |f|
+  ## note:
+  ##  (i) :newline => :lf option
+  #      Reads text natively; normalizes all incoming newlines to strict LF (\n)
+  ##  (ii) 'bom|' flag
+  ##   The 'bom|' flag instructs Ruby to drop the BOM bytes if they exist
+    File.open( path, 'r:bom|utf-8', newline: :lf) do |f|
         f.read
     end
 end
@@ -199,20 +220,25 @@ end
 ##   add/offer chomp: true/false option or such - why? why not?
 ##    see String.lines in rdoc
 ##
-def read_lines( path )
-  read_text( path ).lines
+##
+##  yes, add chomp: true|false option
+##     note - default is chomp: false (keeping the trailing newline)
+
+def read_lines( path, chomp: false )
+  read_text( path ).lines( chomp: chomp )
 end
 
-def parse_lines( str )
-  str.lines
+def parse_lines( str, chomp: false )
+  str.lines( chomp: chomp )
 end
 
-def download_lines( url )
-  parse_lines( download_text( url ))
+def download_lines( url, chomp: false )
+  parse_lines( download_text( url ), chomp: chomp )
 end
 
 
 
+
 def read_env( path )
    parse_env( read_text( path ))
 end
@@ -222,11 +248,17 @@ def parse_env( str )
 end
 
 
+
+
 ##
 ##  todo/check - change path to *paths=['./.env']
 ##                   and support more files - why? why not?
+##
+##  note - use File.file? instead of File.exist?
+##              will avoid matching directories!
+
 def load_env( path='./.env' )
-  if File.exist?( path )
+  if File.file?( path )
      puts "==> loading .env settings..."
      env = read_env( path )
      puts "    applying .env settings... (merging into ENV)"
@@ -241,6 +273,7 @@ end
 
 
 
+
 ######
 #  add writers
 
@@ -253,7 +286,9 @@ def write_json( path, data )
   FileUtils.mkdir_p( dirname )  unless Dir.exist?( dirname )
 
   ## note: pretty print/reformat json
-  File.open( path, 'w:utf-8' ) do |f|
+  ## note: on windows ruby translates \n to \r\n
+  ##          use newline option to use \n everywhere!!
+  File.open( path, 'w:utf-8', newline: :lf) do |f|
      f.write( JSON.pretty_generate( data ))
   end
 end
@@ -283,7 +318,9 @@ def write_text( path, text )
   dirname = File.dirname( path )
   FileUtils.mkdir_p( dirname )  unless Dir.exist?( dirname )
 
-  File.open( path, 'w:utf-8' ) do |f|
+  ## note: on windows ruby translates \n to \r\n
+  ##          use newline option to use \n everywhere!!
+  File.open( path, 'w:utf-8', newline: :lf) do |f|
     f.write( text )
   end
 end
@@ -291,7 +328,7 @@ alias_method :write_txt,  :write_text
 
 
 
-#
+
 # note:
 #  for now write_csv expects array of string arrays
 #     does NOT support array of hashes for now
@@ -300,22 +337,19 @@ def write_csv( path, recs, headers: nil )
   dirname = File.dirname( path )
   FileUtils.mkdir_p( dirname )  unless Dir.exist?( dirname )
 
-  File.open( path, 'w:utf-8' ) do |f|
-    if headers
-      f.write( headers.join(','))   ## e.g. Date,Team 1,FT,HT,Team 2
+  ## note: on windows ruby translates \n to \r\n
+  ##          use newline option to use \n everywhere!!
+  File.open( path, 'w:utf-8', newline: :lf) do |f|
+    if headers     ## e.g. Date,Team 1,FT,HT,Team 2
+      f.write( headers.map do |header|
+                  _escape_csv( header )
+                end.join(',') )
       f.write( "\n" )
     end
 
     recs.each do |values|
-      ## quote values that incl. a comma
-      ##  todo/fix - add more escape/quote checks - why? why not?
-      ##   check how other csv libs handle value generation
       buf =  values.map do |value|
-               if value.index(',')
-                  %Q{"#{value}"}
-               else
-                  value
-               end
+               _escape_csv( value )
              end.join( ',' )
 
       f.write( buf )
@@ -326,9 +360,61 @@ end
 
 
 
+## quote values that incl. a comma
+##  todo/fix - add more escape/quote checks - why? why not?
+##   check how other csv libs handle value generation
+##
+## If a field contains
+## - a comma  (,)
+## - a double quote (")
+## - a newline  (\r\n)
+##  then wrap the field in quotes
+##  Inside quoted fields, double every double quote (" → "")
+
+
+def _escape_csv(value)
+  ## auto-convert to string or let code fail on nil or such?
+  ##  or use value.to_str - why? why not?
+  value = value.to_s
+
+   ## note - double double quotes (") for now only
+   ##  check
+   ##    -  escape newline (lf) as \n or keep it literal - why? why not?
+   ##            what about  \r carriage return (cr)
+   ##
+   ##  add value.match?(/\A\s|\s\z/) ||
+   ##    to preserve leading/trailing spaces in value ???
+   ##    e.g.   _a_ becomes "_a_" written out
+   ##
+   ##  quote empty strings or keep them empty
+   ##   what about nil - for now empty string too
+   ##    add nil_value option e.g. 'n/a' or such
+   ##     and quote_empty true|false - why? why not?
+  if value.include?(',')  ||
+     value.include?('"')  ||
+     value.include?("\n") ||
+     value.include?("\r")
+    '"' + value.gsub('"', '""') + '"'
+  else
+    value
+  end
+end
+
+
+
+
+
+
+
 ######
 #   world wide web (www) support
 
+##
+##  keep wget/wget! support - why? why not?
+##    check if used outside anywhere
+##    add deprecated warning - why? why not?
+
+
 def wget( url, **opts )
   Webclient.get( url, **opts )
 end
@@ -356,4 +442,3 @@ Coco = Cocos
 
 
 puts Cocos.banner   ## say hello
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocos
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-20 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csvreader
@@ -92,14 +92,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.2'
 description: cocos (code commons) - auto-include quick-starter prelude & prolog
 email: gerald.bauer@gmail.com
 executables: []
@@ -117,6 +117,7 @@ files:
 - Rakefile
 - lib/cocos.rb
 - lib/cocos/env.rb
+- lib/cocos/find_file.rb
 - lib/cocos/version.rb
 homepage: https://github.com/rubycocos/cocos
 licenses:
@@ -139,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: cocos (code commons) - auto-include quick-starter prelude & prolog