monofile 0.1.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 460899daff3c93d15ae49ed3163f2c56bb7e15e9
-  data.tar.gz: 7b3e215fe00027e3f4b85e107f30029e048b6e35
+  metadata.gz: dc46a512fd3305af7a7d3949bdfe049de0e1e238
+  data.tar.gz: f152af472841c5145d37ca45f54504fbb48e6f3a
 SHA512:
-  metadata.gz: 6aa5bf5125f770f42d2063d62991779cf7cde8ed06c5752dcd8cd1a3f84556e438b638246884e826951e56219125fafda1e2f00bcb7525fa405f8cc4608996ab
-  data.tar.gz: 4b1452d92bd1e7104fe8f918596978661bdbf3997ab9121327e7ed4527269bdc1ac04d3db4007408582710fdaf74a50691cebda387c645127ac3d9f5f983321c
+  metadata.gz: 83b933f57ceab663f8186d1fd8f99737bebc1f35ecde411b44f4a24d6dc3476b510376d7194f77f68f9d9f5537919e00c7fcf66aedc2a22ce90e37fa75f840ea
+  data.tar.gz: 73acb18f7deb86cc6e4669459c4f531b98cdd7c248c12f36c820577550fcc1ba4eeebc65edbac2ba2fb9f0b697fe73f0b028c828c9f0c420d9c225b3be3b27fa

data/Manifest.txt

@@ -4,4 +4,9 @@ README.md
 Rakefile
 bin/monofile
 lib/monofile.rb
+lib/monofile/monofile.rb
+lib/monofile/mononame.rb
+lib/monofile/tool.rb
 lib/monofile/version.rb
+test/helper.rb
+test/test_names.rb

data/README.md

@@ -1,7 +1,7 @@
-# monofile - read in/ parse mono (source) tree defintions with git (and github) projects, and more
+# monofile - read in / parse monorepo / mono source tree definitions - a list of git (and github) projects, and more
 
-* home  :: [github.com/rubycoco/git](https://github.com/rubycoco/git)
-* bugs  :: [github.com/rubycoco/git/issues](https://github.com/rubycoco/git/issues)
+* home  :: [github.com/rubycoco/monos](https://github.com/rubycoco/monos)
+* bugs  :: [github.com/rubycoco/monos/issues](https://github.com/rubycoco/monos/issues)
 * gem   :: [rubygems.org/gems/monofile](https://rubygems.org/gems/monofile)
 * rdoc  :: [rubydoc.info/gems/monofile](http://rubydoc.info/gems/monofile)
 
@@ -9,7 +9,127 @@
 
 ## Usage
 
-To be done
+
+Use `Monofile.read` to read in / parse monorepo / mono source tree definitions - supporting a ruby or a yaml format.
+
+
+Example - `Monofile`:
+``` ruby
+project "@openfootball/england"
+project "@openfootball/world-cup"
+project "@geraldb/austria"
+project "@geraldb/geraldb.github.io"
+
+project "geraldb", "catalog"
+project "openfootball", "europe"
+project "openfootball", "south-america"
+```
+
+or
+
+Example - `monofile.yml`:
+
+``` yaml
+geraldb:
+- austria
+- catalog
+- geraldb.github.io
+
+openfootball:
+- england
+- europe
+- south-america
+- world-cup
+```
+
+
+To read use.
+
+``` ruby
+monofile = Monofile.read( "./Monofile" )
+# -or-
+monofile = Monofile.read( "./monofile.yml" )
+pp monofile.to_a
+#=> ["@openfootball/england",
+#    "@openfootball/world-cup",
+#    "@geraldb/austria",
+#    "@geraldb/geraldb.github.io",
+#    "@geraldb/catalog",
+#    "@openfootball/europe"]
+#    "@openfootball/south-america"]
+
+pp monofile.to_h
+#=> {"openfootball"=>["england", "world-cup", "europe", "south-america"],
+#    "geraldb"     =>["austria", "geraldb.github.io", "catalog"]}
+
+monofile.each do |proj|
+  puts "  #{proj}"
+end
+#=> @openfootball/england
+#   @openfootball/world-cup
+#   @geraldb/austria
+#   @geraldb/geraldb.github.io
+#   @geraldb/catalog
+#   @openfootball/europe
+#   @openfootball/south-america
+
+monofile.size
+#=> 7
+```
+
+and so on.  That's it for now.
+
+
+
+### Troubleshooting / Debugging
+
+Use the `monofile` command line tool to test reading in of
+monorepo / mono source tree definitions.
+Example:
+
+```  shell
+# option 1) try to find default name (e.g. Monofile, Monofile.rb, etc.)
+$ monofile
+
+# option 2) pass in monofiles
+$ monofile ./Monofile
+$ monofile ./monfile.yml
+# ...
+```
+
+Printing the normalized / canonical names of the repo sources. Example.
+
+```
+@openfootball/england
+@openfootball/world-cup
+@geraldb/austria
+@geraldb/geraldb.github.io
+@geraldb/catalog
+@openfootball/europe
+@openfootball/south-america
+```
+
+
+
+
+## Real-World Usage
+
+See the [`monos`](https://github.com/rubycoco/monos/tree/master/monos) package that incl. the `mono` (or short `mo`)
+command line tool lets you run
+git commands on multiple repo(sitories) with a single command.
+
+
+## Installation
+
+Use
+
+    gem install monofile
+
+or add to your Gemfile
+
+    gem 'monofile'
+
+
 
 ## License
 

data/Rakefile

@@ -6,10 +6,10 @@ Hoe.spec 'monofile' do
 
   self.version = Mono::Module::Monofile::VERSION
 
-  self.summary = "monofile - read in/ parse mono (source) tree defintions with git (and github) projects, and more"
+  self.summary = "monofile - read in / parse monorepo / mono source tree definitions - a list of git (and github) projects, and more"
   self.description = summary
 
-  self.urls = { home: 'https://github.com/rubycoco/git' }
+  self.urls = { home: 'https://github.com/rubycoco/monos' }
 
   self.author = 'Gerald Bauer'
   self.email = 'opensport@googlegroups.com'

data/lib/monofile.rb

@@ -13,14 +13,16 @@ require 'net/http'
 require 'net/https'
 
 
-require 'optparse'
+require 'optparse'    ## used by monofile (built-in test/debug) command line tool
 
 
 
 #####################
 # our own code
 require 'monofile/version'   # note: let version always go first
-
+require 'monofile/mononame'
+require 'monofile/monofile'
+require 'monofile/tool'
 
 
 
@@ -46,291 +48,17 @@ module Mono
     ## use expand path to make (assure) absolute path - why? why not?
     @@root = File.expand_path( path )
   end
-
-
-
-  def self.monofile
-    path = Monofile.find
-    Monofile.read( path )
-
-#    if path
-#      GitRepoSet.read( path )
-#    else
-#      puts "!! WARN: no mono configuration file found; looking for #{MONOFILES.join(', ')} in (#{Dir.getwd})"
-#      GitRepoSet.new( {} )  ## return empty set -todo/check: return nil - why? why not?
-#    end
-  end
 end  ## module Mono
 
 
 
 
-
-class Monofile
-  ## holds a list of projects
-
-  ## nested class
-  class Project
-
-    ## use some different names / attributes ??
-    attr_reader :org,    ## todo/check: find a different name (or add alias e.g. login/user/etc.)
-                :name
-
-    ## todo/fix:
-    ##  - use *args  and than split if args==2 or args==1 etc.
-    def initialize( *args )
-      if args.size == 2 && args[0].is_a?(String) && args[1].is_a?(String)
-        ## assume [org, name]
-        @org  = args[0]
-        @name = args[1]
-      elsif args.size == 1 && args[0].is_a?( String )
-        ## todo/fix:  use norm_name parser or such!!!!
-        parts = args[0].split( '/' )
-        @org  = parts[0][1..-1]   ## cut-off leading @ (always assume for now!!)
-        @name = parts[1]
-      else
-        raise ArgumentError, "[Monorepo::Project] one or two string args expected; got: #{args.pretty_inspect}"
-      end
-    end
-
-    def to_s()    "@#{org}/#{name}"; end
-    def to_path() "#{org}/#{name}"; end
-
-    ## add clone_ssh_url  or such too!!!!
-  end  ## (nested) class Project
-
-
-
-  class Builder     ## "clean room" pattern/spell - keep accessible methods to a minimum (by eval in "cleanroom")
-    def initialize( monofile )
-      @monofile = monofile
-    end
-
-    def project( *args )
-      project = Project.new( *args )
-      @monofile.projects << project
-    end
-  end  # (nested) class Builder
-
-
-
-  RUBY_NAMES = ['monofile',
-                'Monofile',
-                'monofile.rb',
-                'Monofile.rb',
-               ]
-
-  TXT_NAMES  = ['monofile.txt',
-                'monotree.txt',  ## keep monotree - why? why not?
-                'monorepo.txt',
-                'repos.txt']
-
-  ## note: yaml always requires an extension
-  YML_NAMES = ['monofile.yml',   'monofile.yaml',
-                'monotree.yml',   'monotree.yaml',  ## keep monotree - why? why not?
-                'monorepo.yml',   'monorepo.yaml',
-                'repos.yml',      'repos.yaml',
-               ]    ## todo/check: add mono.yml too - why? why not?
-
-  NAMES = RUBY_NAMES + TXT_NAMES + YML_NAMES
-
-
-  def self.find
-    RUBY_NAMES.each do |name|
-      return "./#{name}"  if File.exist?( "./#{name}")
-    end
-
-    TXT_NAMES.each do |name|
-      return "./#{name}"  if File.exist?( "./#{name}")
-    end
-
-    YML_NAMES.each do |name|
-      return "./#{name}"  if File.exist?( "./#{name}")
-    end
-
-    nil  ## no monofile found; return nil
-  end
-
-
-  def self.read( path )
-      txt  = File.open( path, 'r:utf-8') { |f| f.read }
-
-      ## check for yml or yaml extension;
-      ##    or for txt extension; otherwise assume ruby
-      extname = File.extname( path ).downcase
-      if ['.yml', '.yaml'].include?( extname )
-        hash = YAML.load( txt )
-        new( hash )
-      elsif ['.txt'].include?( extname )
-        new( txt )
-      else  ## assume ruby code (as text in string)
-        new().load( txt )
-      end
-  end
-
-
-
-  def self.load( code )
-    monofile = new
-    monofile.load( code )
-    monofile
-  end
-
-  def self.load_file( path )  ## keep (or add load_yaml to or such) - why? why not?
-    code  = File.open( path, 'r:utf-8') { |f| f.read }
-    load( code )
-  end
-
-
-  ### attr readers
-  def projects() @projects; end
-  def size()     @projects.size; end
-
-
-  def initialize( obj={} )    ## todo/fix: change default to obj=[]
-    @projects = []
-
-    ## puts "[debug] obj.class=#{obj.class.name}"
-    add( obj )
-  end
-
-  def load( code )  ## note: code is text as a string
-    builder = Builder.new( self )
-    builder.instance_eval( code )
-    self  ## note: for chaining always return self
-  end
-
-
-  def add( obj )
-    ## todo/check: check for proc too! and use load( proc/block ) - possible?
-    if obj.is_a?( String )
-      puts "sorry add String - to be done!!!"
-      exit 1
-    elsif obj.is_a?( Array )
-      puts "sorry add Array- to be done!!!"
-      exit 1
-    elsif obj.is_a?( Hash )
-      add_hash( obj )
-    else  ## assume text (evaluate/parse)
-      puts "sorry add Text - to be done!!!"
-      exit 1
-    end
-    self ## note: return self for chaining
-  end
-
-
-  def add_hash( hash )
-    hash.each do |org_with_counter, names|
-
-      ## remove optional number from key e.g.
-      ##   mrhydescripts (3)    =>  mrhydescripts
-      ##   footballjs (4)       =>  footballjs
-      ##   etc.
-
-      ## todo/check: warn about duplicates or such - why? why not?
-
-      org = org_with_counter.sub( /\([0-9]+\)/, '' ).strip.to_s
-
-      names.each do |name|
-        @projects << Project.new( org, name )
-      end
-    end
-
-    self  ## note: return self for chaining
-  end
-
-
-
-  def each( &block )
-      ## puts "[debug] arity: #{block.arity}"
-
-      ## for backwards compatibility support "old" each with/by org & names
-      ##   add deprecated warnings and use to_h or such - why? why not?
-      if block.arity == 2
-        puts "!! DEPRECATED  - please, use Monofile#to_h or Monofile.each {|proj| ...}"
-        to_h.each do |org, names|
-          block.call( org, names )
-        end
-      else
-        ## assume just regular
-        @projects.each do |project|
-          block.call( project )
-        end
-      end
-  end # method each
-
-  def each_with_index( &block )
-    @projects.each_with_index do |project,i|
-       block.call( project, i )
-    end
-  end
-
-
-
-  ### for backward compat(ibility) add a hash in the form e.g:
-  ##
-  ## geraldb:
-  ## - austria
-  ## - catalog
-  ## - geraldb.github.io
-  ## - logos
-  ## yorobot:
-  ## - auto
-  ## - backup
-  ## - football.json
-  ## - logs
-  ##
-  def to_h
-    h = {}
-    @projects.each do |project|
-      h[ project.org ] ||= []
-      h[ project.org ] << project.name
-    end
-    h
-  end
-
-  def to_a
-    ## todo/check:
-    ##   - sort all entries a-z - why? why not?
-    ##   - always start name with @ marker - why? why not?
-    @projects.map {|project| project.to_s }
-  end
-end # class Monofile
-
-
-
-
-
-class Monofile
-class Tool
-  def self.main( args=ARGV )
-
-    path = Monofile.find
-    if path.nil?
-      puts "!! ERROR: no mono configuration file found; looking for #{Monofile::NAMES.join(', ')} in (#{Dir.getwd})"
-      exit 1
-    end
-
-    ## add check for auto-require (e.g. ./config.rb)
-    config_path = "./config.rb"
-    if File.exist?( config )
-      puts "[monofile] auto-require >#{config_path}<..."
-      require( config_path )
-    end
-
-    puts "[monofile] reading >#{path}<..."
-    monofile=Monofile.read( path )
-    pp monofile
-
-    ## print one project per line
-    puts "---"
-    monofile.each do |proj|
-      puts proj.to_s
-    end
-  end
-end # (nested) class Tool
-end # class Monofile
+###
+## add some convenience alias for alternate spelling (CamelCase)
+MonoName = Mononame
+MonoPath = Monopath
+MonoFile = Monofile
 
 
-Mono::Module::Monofile.banner
+puts Mono::Module::Monofile.banner   ## say hello
 

data/lib/monofile/monofile.rb

@@ -0,0 +1,251 @@
+
+class Monofile
+  ## holds a list of projects
+
+  ## nested class
+  class Project    ## todo/fix: change to Monoproject/MonoProject - why? why not?
+    def initialize( *args )
+      if args.size == 1 && args[0].is_a?( String )
+        @name = Mononame.parse( args[0] )
+      elsif args.size == 2 && args[0].is_a?(String) && args[1].is_a?(String)
+        ## assume [org, name]
+        @name = Mononame.new( *args )
+      else
+        raise ArgumentError, "[MonoProject] one or two string args expected; got: #{args.inspect}"
+      end
+    end
+
+    def org()     @name.org; end
+    def name()    @name.name; end
+
+    def to_path() @name.to_path; end
+    def to_s()    @name.to_s; end
+
+    ## add clone_ssh_url  or such too!!!!
+  end  ## (nested) class Project
+
+
+
+  class Builder     ## "clean room" pattern/spell - keep accessible methods to a minimum (by eval in "cleanroom")
+    def initialize( monofile )
+      @monofile = monofile
+    end
+
+    def project( *args )
+      ## auto-convert symbols to string
+      args = args.map do |arg|
+                        arg.is_a?( Symbol ) ? arg.to_s : arg
+                      end
+
+      project = Project.new( *args )
+      @monofile.projects << project
+    end
+
+    ###
+    ## adding many projects at once (by batch) - keep - why? why not?
+    def projects( *args )
+      ## note: for now only support (list of) hash
+      ##  add more later (nested array or text or such) - why? why not?
+      args.each do |arg|
+        raise ArgumentError, "expected Hash type - got: #{arg.inspect} : #{arg.class.name}"  unless arg.is_a?( Hash )
+      end
+
+      ## pp arg
+      args.each do |arg|
+        arg.each do |org, names|
+          names.each do |name|
+            ## puts "adding #{org} #{name}"
+            project( org, name )
+          end
+        end
+      end
+    end
+  end  # (nested) class Builder
+
+
+
+
+  RUBY_NAMES = ['monofile',
+                'Monofile',
+                'monofile.rb',
+                'Monofile.rb',
+               ]
+
+  TXT_NAMES  = ['monofile.txt',
+                'monotree.txt',  ## keep monotree - why? why not?
+                'monorepo.txt',
+                'repos.txt']
+
+  ## note: yaml always requires an extension
+  YML_NAMES = ['monofile.yml',   'monofile.yaml',
+                'monotree.yml',   'monotree.yaml',  ## keep monotree - why? why not?
+                'monorepo.yml',   'monorepo.yaml',
+                'repos.yml',      'repos.yaml',
+               ]    ## todo/check: add mono.yml too - why? why not?
+
+  NAMES = RUBY_NAMES + TXT_NAMES + YML_NAMES
+
+
+  def self.find
+    RUBY_NAMES.each do |name|
+      return "./#{name}"  if File.exist?( "./#{name}")
+    end
+
+    TXT_NAMES.each do |name|
+      return "./#{name}"  if File.exist?( "./#{name}")
+    end
+
+    YML_NAMES.each do |name|
+      return "./#{name}"  if File.exist?( "./#{name}")
+    end
+
+    nil  ## no monofile found; return nil
+  end
+
+
+  def self.read( path )
+      txt  = File.open( path, 'r:utf-8') { |f| f.read }
+
+      ## check for yml or yaml extension;
+      ##    or for txt extension; otherwise assume ruby
+      extname = File.extname( path ).downcase
+      if ['.yml', '.yaml'].include?( extname )
+        hash = YAML.load( txt )
+        new( hash )
+      elsif ['.txt'].include?( extname )
+        new( txt )
+      else  ## assume ruby code (as text in string)
+        new().load( txt )
+      end
+  end
+
+
+
+  def self.load( code )
+    monofile = new
+    monofile.load( code )
+    monofile
+  end
+
+  def self.load_file( path )  ## keep (or add load_yaml to or such) - why? why not?
+    code  = File.open( path, 'r:utf-8') { |f| f.read }
+    load( code )
+  end
+
+
+  ### attr readers
+  def projects() @projects; end
+  def size()     @projects.size; end
+
+
+  def initialize( obj={} )    ## todo/fix: change default to obj=[]
+    @projects = []
+
+    ## puts "[debug] obj.class=#{obj.class.name}"
+    add( obj )
+  end
+
+  def load( code )  ## note: code is text as a string
+    builder = Builder.new( self )
+    builder.instance_eval( code )
+    self  ## note: for chaining always return self
+  end
+
+
+  def add( obj )
+    ## todo/check: check for proc too! and use load( proc/block ) - possible?
+    if obj.is_a?( String )
+      puts "sorry add String - to be done!!!"
+      exit 1
+    elsif obj.is_a?( Array )
+      puts "sorry add Array- to be done!!!"
+      exit 1
+    elsif obj.is_a?( Hash )
+      add_hash( obj )
+    else  ## assume text (evaluate/parse)
+      puts "sorry add Text - to be done!!!"
+      exit 1
+    end
+    self ## note: return self for chaining
+  end
+
+
+  def add_hash( hash )
+    hash.each do |org_with_counter, names|
+
+      ## remove optional number from key e.g.
+      ##   mrhydescripts (3)    =>  mrhydescripts
+      ##   footballjs (4)       =>  footballjs
+      ##   etc.
+
+      ## todo/check: warn about duplicates or such - why? why not?
+
+      org = org_with_counter.sub( /\([0-9]+\)/, '' ).strip.to_s
+
+      names.each do |name|
+        @projects << Project.new( org, name )
+      end
+    end
+
+    self  ## note: return self for chaining
+  end
+
+
+
+  def each( &block )
+      ## puts "[debug] arity: #{block.arity}"
+
+      ## for backwards compatibility support "old" each with/by org & names
+      ##   add deprecated warnings and use to_h or such - why? why not?
+      if block.arity == 2
+        puts "!! DEPRECATED  - please, use Monofile#to_h or Monofile.each {|proj| ...}"
+        to_h.each do |org, names|
+          block.call( org, names )
+        end
+      else
+        ## assume just regular
+        @projects.each do |project|
+          block.call( project )
+        end
+      end
+  end # method each
+
+  def each_with_index( &block )
+    @projects.each_with_index do |project,i|
+       block.call( project, i )
+    end
+  end
+
+
+
+  ### for backward compat(ibility) add a hash in the form e.g:
+  ##
+  ## geraldb:
+  ## - austria
+  ## - catalog
+  ## - geraldb.github.io
+  ## openfootball:
+  ## - england
+  ## - europe
+  ## - south-america
+  ## - world-cup
+  ##
+  def to_h
+    h = {}
+    @projects.each do |project|
+      h[ project.org ] ||= []
+      h[ project.org ] << project.name
+    end
+    h
+  end
+
+  def to_a
+    ## todo/check:
+    ##   - sort all entries a-z - why? why not?
+    ##   - always start name with @ marker - why? why not?
+    @projects.map {|project| project.to_s }
+  end
+end # class Monofile
+
+
+

data/lib/monofile/mononame.rb

@@ -0,0 +1,176 @@
+#####
+#  mononame (e.g. @org/hello) machinery
+#  turn
+#  - @openfootball/england/2020-21
+#  - 2020-21@openfootball/england
+#  - england/2020-21@openfootball
+#      => into
+#  - openfootball/england/2020-21
+
+
+
+
+module Mono
+  ## shared parse/norm helper (for Name/Path)
+  ##  - find something better - why? why not?
+  def self.parse_name( line )
+    if line.is_a?( String )
+      parts = line.split( '@' )
+      raise ArgumentError, "[Mononame] no @ found BUT required in name; got >#{line}<"               if parts.size == 1
+      raise ArgumentError, "[Mononame] too many @ found (#{parts.size-1}) in name; got >#{line}<"    if parts.size > 2
+
+      ## pass 1) rebuild (normalized) name/path
+      name = String.new('')
+      name << parts[1]  ## add orgs path first - w/o leading @ - gets removed by split :-)
+      if parts[0].length > 0   ## has leading repo name (w/ optional path)
+        name << '/'
+        name << parts[0]
+      end
+
+      ## pass 2) split (normalized) name/path into components (org/name/path)
+      parts = name.split( '/' )
+
+      args = [parts[0], parts[1]]
+
+      more_parts = parts[2..-1]  ## check for any extra (optional) path parts
+      args << more_parts.join( '/' )    if more_parts.size > 0
+
+      args
+    else
+      raise ArgumentError, "[Mononame] string with @ expected; got: #{line.pretty_inspect} of type #{line.class.name}"
+    end
+  end
+end  # module Mono
+
+
+
+class Mononame
+  def self.parse( line )
+    values = Mono.parse_name( line )
+    raise ArgumentError, "[Mononame] expected two parts (org/name); got #{values.pretty_inspect}"   if values.size != 2
+    new( *values )
+  end
+
+  def self.real_path( line )
+    ## add one-time (quick) usage convenience shortcut
+    mononame = parse( line )
+    mononame.real_path
+  end
+
+
+  ## note: org and name for now required
+  ##   - make name optional too - why? why not?!!!
+  ## use some different names / attributes ??
+  attr_reader :org,     ## todo/check: find a different name (or add alias e.g. login/user/etc.)
+              :name
+
+  def initialize( org, name )
+    if org.is_a?(String) && name.is_a?(String)
+      @org  = org
+      @name = name
+    else
+      raise ArgumentError, "[Mononame] expected two strings (org, name); got >#{org}< of type #{org.class.name}, >#{name}< of type #{name.class.name}"
+    end
+  end
+
+  def to_path()   "#{@org}/#{@name}"; end
+  def to_s()      "@#{to_path}"; end
+
+  def real_path() "#{Mono.root}/#{to_path}"; end
+end # class Mononame
+
+
+
+####
+## todo/check:
+##   use as shared Mono/nomen/resource or such
+#   shared base class for Mononame & Monopath - why? why not?
+#
+#  Monoloc  (for location)
+#  Monores  (for resource)
+#  Mono__ ??
+#
+#  name components:
+#    - better name for path?  - use filepath, relpath, ...
+
+
+
+class Monopath
+  def self.parse( line )
+    values = Mono.parse_name( line )
+    raise ArgumentError, "[Monopath] expected three parts (org/name/path); got #{values.pretty_inspect}"   if values.size != 3
+    new( *values )
+  end
+
+  def self.real_path( line )
+    monopath = parse( line )
+    monopath.real_path
+  end
+
+
+  ## note: org and name AND path for now required
+  ##   - make name path optional too - why? why not?!!!
+  attr_reader :org, :name, :path
+
+  def initialize( org, name, path )
+     ## support/check for empty path too - why? why not?
+
+    if org.is_a?(String) && name.is_a?(String) && path.is_a?(String)
+    ## assume [org, name, path?]
+    ##  note: for now assumes proper formatted strings
+    ##   e.g. no leading @ or combined @hello/text in org
+    ##   or name or such
+    ##  - use parse/norm_name here too - why? why not?
+      @org  = org
+      @name = name
+      @path = path
+    else
+      raise ArgumentError, "[Monopath] expected three strings (org, name, path); got >#{org}< of type #{org.class.name}, >#{name}< of type #{name.class.name}, >#{path}< of type #{path.class.name}"
+    end
+  end
+
+  def to_path()   "#{@org}/#{@name}/#{@path}"; end
+  def to_s()      "@#{to_path}"; end
+
+  def real_path() "#{Mono.root}/#{to_path}"; end
+
+
+  ## some File-like convenience helpers
+  ##   e.g. File.exist?   => Monopath.exist?
+  ##        File.open     => Monopath.open( ... ) { block }
+  ##   etc.
+  def self.exist?( line )
+     File.exist?( real_path( line ) )
+  end
+
+
+  ## path always relative to Mono.root
+  ##   todo/fix:  use File.expand_path( path, Mono.root ) - why? why not?
+  ##    or always enfore "absolut" path e.g. do NOT allow ../ or ./ or such
+  def self.open( line, mode='r:utf-8', &block )
+    path = real_path( line )
+    ## make sure path exists if we open for writing/appending - why? why not?
+    if mode[0] == 'w' || mode[0] == 'a'
+      FileUtils.mkdir_p( File.dirname( path ) )  ## make sure path exists
+    end
+
+    File.open( path, mode ) do |file|
+      block.call( file )
+    end
+  end
+
+  def self.read_utf8( line )
+    open( line, 'r:utf-8') { |file| file.read }
+  end
+end  # class Monopath
+## note: use Monopath   - avoid confusion with Monofile (a special file with a list of mono projects)!!!!
+
+
+
+
+
+## todo/check: add a (global) Mono/Mononame converter - why? why not?
+##
+## module Kernel
+##  def Mono( *args ) Mononame.parse( *args ); end
+## end

data/lib/monofile/tool.rb

@@ -0,0 +1,59 @@
+class Monofile
+class Tool
+  def self.main( args=ARGV )
+
+    options = {}
+    OptionParser.new do |parser|
+      ## note:
+      ##  you can add many/multiple modules
+      ##  e.g. -r gitti -r mono etc.
+      parser.on( '-r NAME', '--require NAME') do |name|
+        options[:requires] ||= []
+        options[:requires] << name
+      end
+      ## todo/fix:
+      ##    add --verbose
+      ##    add -d/--debug
+    end.parse!( args )
+
+
+    if args.size == 0   ## auto-add default arg (monofile)
+      monofile_path = Monofile.find
+      if monofile_path.nil?
+        puts "!! ERROR: no mono configuration file found; looking for #{Monofile::NAMES.join(', ')} in (#{Dir.getwd})"
+        exit 1
+      end
+      args << monofile_path
+    end
+
+
+    ## add check for auto-require (e.g. ./config.rb)
+    if options[:requires]  ## use custom (auto-)requires
+      options[:requires].each do |path|
+        puts "[monofile] auto-require >#{path}<..."
+        require( path )
+      end
+    else  ## use/try defaults
+      config_path = "./config.rb"
+      if File.exist?( config_path )
+        puts "[monofile] auto-require (default) >#{config_path}<..."
+        require( config_path )
+      end
+    end
+
+
+    args.each do |path|
+      puts "[monofile] reading >#{path}<..."
+      monofile=Monofile.read( path )
+      pp monofile
+
+      ## print one project per line
+      puts "---"
+      monofile.each do |proj|
+        puts proj.to_s
+      end
+    end
+  end # method self.main
+end # (nested) class Tool
+end # class Monofile
+

data/lib/monofile/version.rb

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

data/test/helper.rb

@@ -0,0 +1,7 @@
+# minitest setup
+require 'minitest/autorun'
+
+
+## our own code
+require 'monofile'
+

data/test/test_names.rb

@@ -0,0 +1,97 @@
+###
+#  to run use
+#     ruby -I ./lib -I ./test test/test_names.rb
+
+
+require 'helper'
+
+
+class TestNames < MiniTest::Test
+
+def test_parse
+  %w[
+    @openfootball/england
+    england@openfootball
+  ].each do |line|
+    mono = Mononame.parse( line )
+
+    assert_equal '@openfootball/england', mono.to_s
+    assert_equal 'openfootball/england',  mono.to_path
+
+    assert_equal 'openfootball',          mono.org
+    assert_equal 'england',               mono.name
+  end
+
+
+  %w[
+    @openfootball/england/2020-21
+    2020-21@openfootball/england
+    england/2020-21@openfootball
+  ].each do |line|
+    mono = Monopath.parse( line )
+
+    assert_equal '@openfootball/england/2020-21', mono.to_s
+    assert_equal 'openfootball/england/2020-21',  mono.to_path
+
+    assert_equal 'openfootball',            mono.org
+    assert_equal 'england',                 mono.name
+    assert_equal '2020-21',                 mono.path
+  end
+
+  %w[
+    @openfootball/england/2020-21/premierleague.txt
+    2020-21/premierleague.txt@openfootball/england
+    england/2020-21/premierleague.txt@openfootball
+  ].each do |line|
+    mono = Monopath.parse( line )
+
+    assert_equal '@openfootball/england/2020-21/premierleague.txt', mono.to_s
+    assert_equal 'openfootball/england/2020-21/premierleague.txt',  mono.to_path
+
+    assert_equal 'openfootball',              mono.org
+    assert_equal 'england',                   mono.name
+    assert_equal '2020-21/premierleague.txt', mono.path
+  end
+end   # method test_parse
+
+
+
+def test_init
+  mono = Mononame.new( 'openfootball','england' )
+
+  assert_equal '@openfootball/england', mono.to_s
+  assert_equal 'openfootball/england',  mono.to_path
+
+  assert_equal 'openfootball',            mono.org
+  assert_equal 'england',              mono.name
+
+
+  mono = Monopath.new( 'openfootball', 'england', '2020-21' )
+
+  assert_equal '@openfootball/england/2020-21', mono.to_s
+  assert_equal 'openfootball/england/2020-21',  mono.to_path
+
+  assert_equal 'openfootball',            mono.org
+  assert_equal 'england',                 mono.name
+  assert_equal '2020-21',                 mono.path
+
+
+  ## !!!!todo/check/fix!!!!!:
+  ##   - support '2020-21', 'premierleague.txt' too (or only) - why? why not?
+  ##
+  ##  todo/check/fix:
+  ##    find a better name for path/path? component / part - why? why not?
+  ##      to_path and path/path? to confusing!!!
+  mono = Monopath.new( 'openfootball', 'england', '2020-21/premierleague.txt' )
+
+  assert_equal '@openfootball/england/2020-21/premierleague.txt', mono.to_s
+  assert_equal 'openfootball/england/2020-21/premierleague.txt',  mono.to_path
+
+  assert_equal 'openfootball',              mono.org
+  assert_equal 'england',                   mono.name
+  assert_equal '2020-21/premierleague.txt', mono.path
+end   # method test_init
+
+
+
+end # class TestNames

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monofile
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.3
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-29 00:00:00.000000000 Z
+date: 2020-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -44,8 +44,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.22'
-description: monofile - read in/ parse mono (source) tree defintions with git (and
-  github) projects, and more
+description: monofile - read in / parse monorepo / mono source tree definitions -
+  a list of git (and github) projects, and more
 email: opensport@googlegroups.com
 executables:
 - monofile
@@ -61,8 +61,13 @@ files:
 - Rakefile
 - bin/monofile
 - lib/monofile.rb
+- lib/monofile/monofile.rb
+- lib/monofile/mononame.rb
+- lib/monofile/tool.rb
 - lib/monofile/version.rb
-homepage: https://github.com/rubycoco/git
+- test/helper.rb
+- test/test_names.rb
+homepage: https://github.com/rubycoco/monos
 licenses:
 - Public Domain
 metadata: {}
@@ -87,6 +92,6 @@ rubyforge_project:
 rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
-summary: monofile - read in/ parse mono (source) tree defintions with git (and github)
-  projects, and more
+summary: monofile - read in / parse monorepo / mono source tree definitions - a list
+  of git (and github) projects, and more
 test_files: []