flow-lite 0.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4af502cc9764efd28671cbd3e4e498c0cc9dbd87
-  data.tar.gz: af96b08715862f411dfb3cdc7a2b87bc8ac4c8e6
+  metadata.gz: bec58eb7b17f61cd186fa21cf7b57bf3b93a8ee0
+  data.tar.gz: b2c6da0f1440e70133c79b4ab2bdac478c08e8a0
 SHA512:
-  metadata.gz: c2edc964d13234f76c67c52989e4ff9e664164a61ba185f472d6f24a6300d1ee87cdc8ec30eb40a88258fd9beb63e133f95e852249b7f0d5b624e17430a86b31
-  data.tar.gz: 90a4af15059474729db047b8ad658c36cfacbcdfd0db1802ec29423d22893806eea0a9beeb371364a05f848ffbf8b82aa15333b32fbf3cfe630d8a73287e7eee
+  metadata.gz: 6eb5a662ed0393f8a77df8077a7df4c9da69038529fa53ef235d299298e33724aaf764cb4fd3fcbcf9cf53606f5bd22143a1f98d89758ff7905a22b9dd9559ea
+  data.tar.gz: d68c1d0439b921ca86a36e850ecb6837b1e3e5dfbfb1cd411c30466d69d30de6909d8315895b69f8d0db9a4fc1d34578bce789d8d1f36a00137384f697116a2b

data/README.md

@@ -3,16 +3,264 @@
 flow-lite gem - (yet) another (lite) workflow engine; let's you define your workflow steps in Flowfiles; incl. the flow command line tool
 
 
-* 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/flow](https://github.com/rubycoco/flow)
+* bugs  :: [github.com/rubycoco/flow/issues](https://github.com/rubycoco/flow/issues)
 * gem   :: [rubygems.org/gems/flow-lite](https://rubygems.org/gems/flow-lite)
 * rdoc  :: [rubydoc.info/gems/flow-lite](http://rubydoc.info/gems/flow-lite)
 
 
 
+
 ## Usage
 
-To be done
+
+Define the workflow steps in a Flowfile. Example:
+
+
+``` ruby
+step :first_step do
+  puts "first_step"
+  step :second_step    # note: you can call other steps with step
+end
+
+step :second_step do
+  puts "second_step"
+  step :third_step
+end
+
+step :third_step do
+  puts "third_step"
+end
+```
+
+And then use the `flow` command line tool to run a step.
+Example:
+
+```
+$ flow first_step
+```
+
+Note: By default the `flow` command line tool reads in and looks for `flowfile`, `Flowfile`, `flowfile.rb`, `Flowfile.rb`
+in that order.
+Use the `-f/--flowfile` option to use a different file.
+
+
+
+**Prelude / Prolog**
+
+Use the `-r/--require` option to (auto-)require
+some extra libraries or scripts.
+By default for now the "prelude / prolog" that always
+gets auto-required includes:
+
+``` ruby
+require 'pp'
+require 'time'
+require 'date'
+require 'json'
+require 'yaml'
+require 'fileutils'
+
+require 'uri'
+require 'net/http'
+require 'net/https'
+```
+
+Tip: See the [`flow-lite.rb`](https://github.com/rubycoco/flow/blob/master/flow-lite/lib/flow-lite.rb) source for the definite always up-to-date list.
+
+
+That's it for now.
+
+
+
+## Backstage Internals / Inside Flowfiles
+
+
+If you read in a `Flowfile` the flow machinery
+builds a new (regular) class derived from `Flow::Base`
+and every step becomes a (regular) method. Example:
+
+``` ruby
+require 'flow-lite'
+
+flowfile = Flow::Flowfile.load( <<TXT )
+  step :hello do
+    puts "Hello, world!"
+  end
+
+  step :hola do
+    puts "¡Hola, mundo!"
+  end
+TXT
+
+flow = flowfile.flow_class.new   # (auto-)build a flow class (see Note 1)
+                                 # and construct/return a new instance
+flow.step_hello             #=> "Hello, world!"
+flow.step_hola              #=> "¡Hola, mundo!"
+flow.step( :hello )         #=> "Hello, world!"
+flow.step( :hola )          #=> "¡Hola, mundo!"
+flow.class.step_methods     #=> [:hello, :hola]
+
+# or use ruby's (regular) message/metaprogramming machinery
+flow.send( :step_hello )    #=> "Hello, world!"
+flow.send( :step_hola  )    #=> "¡Hola, mundo!"
+# or try
+flow.class.instance_methods.grep( /^step_/ ) #=> [:step_hello, :step_hola]
+# ...
+```
+
+Note 1:  The Flowfile "source / configuration":
+
+``` ruby
+step :hello do
+  puts "Hello, world!"
+end
+
+step :hola do
+  puts "¡Hola, mundo!"
+end
+```
+
+gets used to (auto-) build (via metaprogramming) a flow class like:
+
+``` ruby
+class Greeter < Flow::Base
+  def step_hello
+    puts "Hello, world!"
+  end
+
+  def step_hola
+    puts "¡Hola, mundo!"
+  end
+end
+```
+
+
+Note: Behind the stage the metaprogramming "class macro"
+`define_step( symbol, method )`
+or `define_step( symbol ) { block }` defined in `Flow::Base`
+gets used, thus,
+if you want to create steps in a "hand-coded" class
+use:
+
+
+``` ruby
+class Greeter < Flow::Base
+  define_step :hello do
+    puts "Hello, world!"
+  end
+
+  define_step :hola do
+    puts "¡Hola, mundo!"
+  end
+end
+```
+
+
+
+
+
+**Tips & Tricks**
+
+Auto-include pre-build / pre-defined steps. Use a (regular) Module e.g.:
+
+``` ruby
+module GitHubActions
+  def step_setup
+     # setup ssh
+     ssh_key  = ENV['SSH_KEY']
+     ssh_path = File.expand_path( '~/.ssh' )
+
+     FileUtils.mkdir_p( ssh_path )   # make sure path exists
+     File.open( "#{ssh_path}/id_rsa", 'w' ) { |f| f.write( ssh_key ) }
+     File.chmod( 0600, "#{ssh_path}/id_rsa" )
+
+     # setup git
+     user_name  = ENV['GITHUB_NAME']  || 'you'
+     user_email = ENV['GITHUB_EMAIL'] || 'you@example.com'
+
+     Git.config( 'user.name',  user_name,  global: true )
+     Git.config( 'user.email', user_email, global: true )
+
+     # ...
+  end
+end
+```
+
+and than use (regular) include e.g.:
+
+``` ruby
+class Flow::Base
+  include GitHubActions
+end
+
+#-or-
+
+Flow::Base.include( GitHubActions )
+```
+
+Now all your flows can (re)use `setup` or any other step methods you define.
+
+
+
+
+## Real World Examples
+
+**Collect GitHub Statistics**
+
+Use GitHub Actions to collect
+GitHub Statistics via GitHub API calls
+and update the JSON datasets
+in the `/cache.github` repo at the `yorobot` org(anization):
+
+``` ruby
+step :clone do
+  Mono.clone( '@yorobot/cache.github' )
+end
+
+
+step :update do
+  Hubba.config.data_dir = Mono.real_path( '@yorobot/cache.github' )
+
+  username = 'geraldb'
+  h = Hubba.reposet( username )
+  pp h
+
+  Hubba.update_stats( h )
+  Hubba.update_traffic( h )
+  puts "Done."
+end
+
+
+step :push do
+  msg = "auto-update week #{Date.today.cweek}"
+
+  Mono.open( '@yorobot/cache.github' ) do |proj|
+    if proj.changes?
+      proj.add( "." )
+      proj.commit( msg )
+      proj.push
+    end
+  end
+end
+```
+
+(Sources: [`Flowfile`](https://github.com/yorobot/backup/blob/master/Flowfile.rb), [`workflows/update.yml`](https://github.com/yorobot/backup/blob/master/.github/workflows/update.yml) @ `yorobot/backup`)
+
+
+
+
+
+
+## Installation
+
+Use
+
+    gem install flow-lite
+
+or add to your Gemfile
+
+    gem 'flow-lite'
 
 
 

data/Rakefile

@@ -8,7 +8,7 @@ Hoe.spec 'flow-lite' do
   self.summary = "flow-lite gem - (yet) another (lite) workflow engine; let's you define your workflow steps in Flowfiles; incl. the flow command line tool"
   self.description = summary
 
-  self.urls    = { home: 'https://github.com/rubycoco/git' }
+  self.urls    = { home: 'https://github.com/rubycoco/flow' }
 
   self.author  = 'Gerald Bauer'
   self.email   = 'ruby-talk@ruby-lang.org'
@@ -17,11 +17,7 @@ Hoe.spec 'flow-lite' do
   self.readme_file  = 'README.md'
   self.history_file = 'CHANGELOG.md'
 
-  self.extra_deps = [
-    ['gitti', '>= 0.6.1' ],
-    ['hubba', '>= 1.0.0' ],
-    ['monos', '>= 0.5.0' ],
-  ]
+  self.extra_deps = []
 
   self.licenses = ['Public Domain']
 

data/lib/flow-lite.rb

@@ -1,15 +1,19 @@
+##
+## "prelude / prolog " add some common used stdlibs
+##   add more - why? why not?
 require 'pp'
-require 'optparse'
+require 'time'
+require 'date'
+require 'json'
+require 'yaml'
+require 'fileutils'
 
+require 'uri'
+require 'net/http'
+require 'net/https'
 
 
-####################
-# "prelude/prolog" add some 3rd party libs/gems
-# -- our own
-require 'gitti'
-require 'hubba'  ## todo/fix: rename to gitti-api/gitti-apis
-require 'mono'
-# -- some more ???
+require 'optparse'
 
 
 
@@ -40,12 +44,86 @@ end # class Step
 
 
 class Base    ## base class for flow class (auto)-constructed/build from flowfile
-end
+  def self.define_step( name_or_names, &block )
+    names =  if name_or_names.is_a?( Array )
+               name_or_names
+             else
+               [name_or_names]   ## assume single symbol (name); wrap in array
+             end
+    names = names.map {|name| name.to_sym }   ## make sure we always use symbols
+
+
+    name = names[0]
+    puts "[flow]    adding step  >#{name}<..."
+    define_method( :"step_#{name}", &block )
+
+    alt_names = names[1..-1]
+    alt_names.each do |alt_name|
+      puts "[flow]      adding alias >#{alt_name}< for >#{name}<..."
+      alias_method( :"step_#{alt_name}", :"step_#{name}" )
+    end
+  end  # method self.define_step
+
+
+
+  ## run step by symbol/name (e.g. step :hello - etc.)
+  def step( name )
+    step_name = :"step_#{name}"  ## note: make sure we always use symbols
+    if respond_to?( step_name )
+      #######
+      ## check: track (and report) call stack - why? why not?
+      ## e.g.
+      ##   [flow >(1) first_step)] step >first_step< - starting...
+      ##   [flow >(2) ..first_step > second_step)] step >second_step< - starting...
+      ##   [flow >(3) ....first_step > second_step > third_step)] step >third_step< - starting...
+      @stack ||= []   ## use a call stack of step names
+      @stack.push( name )
+
+      puts "[flow >(#{@stack.size}) #{'..'*(@stack.size-1)}#{@stack.join(' > ')})] step >#{name}< - starting..."
+      start_time = Time.now   ## todo: use Timer? t = Timer.start / stop / diff etc. - why? why not?
+
+      __send__( step_name )
+
+      end_time = Time.now
+      diff_time = end_time - start_time
+      puts "[flow <(#{@stack.size}) #{'..'*(@stack.size-1)}#{@stack.join(' < ')})] step >#{name}< - done in #{diff_time} sec(s)"
+      @stack.pop
+    else
+      puts "!! ERROR: step definition >#{name}< not found; cannot run/execute - known (defined) steps include:"
+      pp self.class.step_methods  #=> e.g. [:hello, ...]
+      exit 1
+    end
+  end  # method step
+
+
+  def self.step_methods
+    names = instance_methods.reduce([]) do |names, name|
+                                          names << $1.to_sym  if name =~ /^step_(.+)/
+                                          names
+                                        end
+    names
+  end
+end  # class Base
+
+
 
 
 class Flowfile
+
+  ## find flowfile path by convention
+  ## check for name by convention in this order:
+  NAMES = ['flowfile',    'Flowfile',
+           'flowfile.rb', 'Flowfile.rb']
+  def self.find_file
+    NAMES.each do |name|
+      return "./#{name}"   if File.exist?( "./#{name}" )
+    end
+    nil
+  end # method self.find_file
+
+
   ## convenience method - use like Flowfile.load_file()
-  def self.load_file( path='./Flowfile' )
+  def self.load_file( path )
     code = File.open( path, 'r:utf-8' ) { |f| f.read }
     load( code )
   end
@@ -59,27 +137,23 @@ class Flowfile
 
 
 
-  def flow  ## build flow class
+  def flow
+    ## todo/check: always return a new instance why? why not?
+    flow_class.new
+  end
+
+  def flow_class
     @flow_class ||= build_flow_class
-    @flow_class.new   ## todo/check: always return a new instance why? why not?
   end
 
   def build_flow_class
-    puts "  building flow class..."
-    flowfile = self
-    klass = Class.new( Base ) do
-      flowfile.steps.each_with_index do |step,i|
-        name = step.names[0]
-        puts "    adding step #{i+1}/#{flowfile.steps.size} >#{name}<..."
-        define_method( name, &step.block )
-
-        alt_names = step.names[1..-1]
-        alt_names.each do |alt_name|
-          puts "      adding alias >#{alt_name}< for >#{name}<..."
-          alias_method( alt_name, name )
-        end
-      end
+    puts "[flow]  building flow class..."
+    klass = Class.new( Base )
+
+    steps.each do |step|
+      klass.define_step( step.names, &step.block )
     end
+
     klass
   end
 
@@ -97,21 +171,15 @@ class Flowfile
     @steps << Step.new( name, block )
   end
 
-
   def run( name )
-    name = name.to_sym  ## make sure we always use symbols
-    if flow.respond_to?( name )
-       flow.send( name )
-    else
-      puts "!! ERROR: step definition >#{name}< not found; cannot run/execute - known steps include:"
-      pp @steps
-      exit 1
-    end
+    ## todo/check: always return/use a new instance why? why not?
+    flow_class.new.step( name )
   end
 end # class Flowfile
 
 
 
+
 class Tool
   def self.main( args=ARGV )
     options = {}
@@ -119,17 +187,56 @@ class Tool
       parser.on( '-f FILENAME', '--flowfile FILENAME' ) do |filename|
         options[:flowfile] = filename
       end
+
+      ## 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
     end.parse!( args )
 
-    path  =  options[:flowfile] || './Flowfile'
+
+    ## check for any (dynamic/auto) requires
+    if options[:requires]
+      names = options[:requires]
+      names.each do |name|
+        ## todo/check: add some error/exception handling here - why? why not?
+        puts "[flow] auto-require >#{name}<..."
+        require( name )
+      end
+    else  ## use/try defaults
+      config_path = "./config.rb"
+      if File.exist?( config_path )
+        puts "[flow] auto-require (default) >#{config_path}<..."
+        require( config_path )
+      end
+    end
+
+
+    path = nil
+    if options[:flowfile]
+      path = options[:flowfile]
+    else
+      path = Flowfile.find_file
+
+      if path.nil?
+        STDERR.puts "!! ERROR - no flowfile found, sorry - looking for: #{Flowfile::NAMES.join(', ')} in (#{Dir.pwd})"
+        exit 1
+      end
+    end
+
+    puts "[flow] loading >#{path}<..."
     flowfile = Flowfile.load_file( path )
 
+
     ## allow multipe steps getting called - why? why not?
     ##   flow setup clone update   etc??
     args.each do |arg|
       flowfile.run( arg )
     end
-  end
+  end # method self.main
 end # class Tool
 
 end # module Flow

data/lib/flow-lite/version.rb

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

metadata

@@ -1,57 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: flow-lite
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-23 00:00:00.000000000 Z
+date: 2020-11-03 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: gitti
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.6.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.6.1
-- !ruby/object:Gem::Dependency
-  name: hubba
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-- !ruby/object:Gem::Dependency
-  name: monos
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.5.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -104,7 +62,7 @@ files:
 - bin/flow
 - lib/flow-lite.rb
 - lib/flow-lite/version.rb
-homepage: https://github.com/rubycoco/git
+homepage: https://github.com/rubycoco/flow
 licenses:
 - Public Domain
 metadata: {}