flow-lite 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e984e29ecd1e215ac23dfbc248b5b323236f21ba
-  data.tar.gz: 8105559c7ac2c17840f5efb0e9b0c4fec179bdc1
+  metadata.gz: 1f61f94156b9718eb74e5a99f9e9c1128f067588
+  data.tar.gz: b3da7ea83777db3cbe01609ae431bd4ce043ef1d
 SHA512:
-  metadata.gz: 7e968604c3af2d83da673be18d8db52c0534e6644c29da6925bbfc6319386d52718e02845e9a057d2be7f05c6447a4abadaadd84b909235d6bc84182f6ace123
-  data.tar.gz: c40e200d14aebf20b9d6f67595f5e2571111589efe2f0e852d681f75056b2aa49f640aa2d950b35d7b8d01e6f9720219e035646570ec1a8a5618ac74f64df9d9
+  metadata.gz: 49523aa490c50d6b4602090df7c135899f234b9649c406c6f5ca22967bc976732e3a3c5d6589b6c8ebdd31049651b53d2096a038e611a20a1aa5aa5b85f1565f
+  data.tar.gz: 4321ffd322f70a5288f68d697b4020a8389ac45f273c4f3fd88c7d5e54f104e48e6b1d5be32ee130df158472a69a64e97d0705f2f5380a03e2b474d25132ea37

data/README.md

@@ -10,6 +10,7 @@ flow-lite gem - (yet) another (lite) workflow engine; let's you define your work
 
 
 
+
 ## Usage
 
 
@@ -19,12 +20,12 @@ Define the workflow steps in a Flowfile. Example:
 ``` ruby
 step :first_step do
   puts "first_step"
-  second_step    # note: you can call other steps like methods
+  step :second_step    # note: you can call other steps with step
 end
 
 step :second_step do
   puts "second_step"
-  third_step
+  step :third_step
 end
 
 step :third_step do
@@ -39,7 +40,28 @@ Example:
 $ flow first_step
 ```
 
-Note: By default the `flow` command line tool reads in the `Flowfile`. Use `-f/--flowfile` option to use a different file.
+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
+and use the `-r/--require` 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/git/blob/master/flow-lite/lib/flow-lite.rb) source for the definite always up-to-date list.
 
 
 That's it for now.
@@ -66,14 +88,17 @@ flowfile = Flow::Flowfile.load( <<TXT )
   end
 TXT
 
-flow = flowfile.flow   # (auto-)builds a flow class (see Note 1)
-                       # and constructs/returns an instance
-flow.hello             #=> "Hello, world!"
-flow.hola              #=> "¡Hola, mundo!"
+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( :hello )    #=> "Hello, world!"
-flow.send( :hola  )    #=> "¡Hola, mundo!"
+flow.send( :step_hello )    #=> "Hello, world!"
+flow.send( :step_hola  )    #=> "¡Hola, mundo!"
 # or try
 flow.class.instance_methods.grep( /^step_/ ) #=> [:step_hello, :step_hola]
 # ...
@@ -95,19 +120,40 @@ gets used to (auto-) build (via metaprogramming) a flow class like:
 
 ``` ruby
 class Greeter < Flow::Base
-  def hello
+  def step_hello
     puts "Hello, world!"
   end
-  alias_method :step_hello, :hello
 
-  def hola
+  def step_hola
     puts "¡Hola, mundo!"
   end
-  alias_method :step_hola, :hola
 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**
 
@@ -115,7 +161,7 @@ Auto-include pre-build / pre-defined steps. Use a (regular) Module e.g.:
 
 ``` ruby
 module GitHubActions
-  def setup
+  def step_setup
      # setup ssh
      ssh_key  = ENV['SSH_KEY']
      ssh_path = File.expand_path( '~/.ssh' )
@@ -133,8 +179,6 @@ module GitHubActions
 
      # ...
   end
-  # optional - for auto-discovery add a step alias
-  alias_method :step_setup, :setup
 end
 ```
 
@@ -150,7 +194,54 @@ end
 Flow::Base.include( GitHubActions )
 ```
 
-Now all your flows can (re)use `setup` or any other methods you define.
+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`)
+
 
 
 

data/lib/flow-lite.rb

@@ -44,25 +44,70 @@ end # class Step
 
 
 class Base    ## base class for flow class (auto)-constructed/build from flowfile
-  def self.define_step( step )
-    name = step.names[0]
+  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( name, &step.block )
-    alias_method( :"step_#{name}", name )  ## (auto-)add step_<name> alias
+    define_method( :"step_#{name}", &block )
 
-    alt_names = step.names[1..-1]
+    alt_names = names[1..-1]
     alt_names.each do |alt_name|
       puts "[flow]      adding alias >#{alt_name}< for >#{name}<..."
-      alias_method( alt_name, 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 )
+    name = :"step_#{name}"  ## note: make sure we always use symbols
+    if respond_to?( name )
+       send( name )
+    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:
+  FLOWFILES = ['flowfile',    'Flowfile',
+               'flowfile.rb', 'Flowfile.rb']
+  def self.find_file
+    FLOWFILES.each do |name|
+      return "./#{name}"   if File.exist?( "./#{name}" )
+    end
+
+    STDERR.puts "!! ERROR - no flowfile found, sorry - looking for: #{FLOWFILES.join(', ')} in (#{Dir.pwd})"
+    exit 1
+  end # method self.find_file
+
+
   ## convenience method - use like Flowfile.load_file()
-  def self.load_file( path='./Flowfile' )
+  def self.load_file( path=find_file )
     code = File.open( path, 'r:utf-8' ) { |f| f.read }
     load( code )
   end
@@ -76,9 +121,13 @@ 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
@@ -86,7 +135,7 @@ class Flowfile
     klass = Class.new( Base )
 
     steps.each do |step|
-      klass.define_step( step )
+      klass.define_step( step.names, &step.block )
     end
 
     klass
@@ -106,21 +155,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 = {}
@@ -128,17 +171,41 @@ 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
+    end
+
+
+    path = options[:flowfile] || Flowfile.find_file
+
+
+    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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow-lite
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-25 00:00:00.000000000 Z
+date: 2020-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc