dsel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07cd134eb19c94b82a1bb7330afe5a0c8a58767e53f42314eb782af6a189d8af
+  data.tar.gz: f368f83eb54221b038a5a3a25f5ba6e4f4791439c7ebe939c10942c142b76f91
+SHA512:
+  metadata.gz: 76d12f31e125b3b643fd2218cbda3b45810ceee941462ae4081cd147f2b316bb1971d2e69e047b73753a3fa43e92cb8ac48b4fc4cdd3acf6cf08f8c4bcbca99c
+  data.tar.gz: 39ca85a0140581511aaa7ae093f2c47a852278dff6e022593b4e2ae715c2daef2c44be21f2bbffdef055743bd5e3611cc7a9dd7e3574b3bd269b27693def400f

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'awesome_print', require: 'ap'
+
+group :docs do
+    gem 'yard'
+    gem 'redcarpet'
+end
+
+group :spec do
+    gem 'rspec'
+end
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,23 @@
+#License
+
+    MIT License
+    
+    Copyright (c) 2018-2021 Tasos Laskos \<tasos.laskos@gmail.com\>.
+    
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+    
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+    
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# DSeL
+
+You can use DSeL (pronounced _Diesel_ -- best I could do) to:
+
+* Safely interact with any object as if you were operating within it.
+    * No need to keep typing `obj.*` to work on `obj`.
+* Unsafely re-open (almost) any object like you re-open a `Class` and mess about it there.
+* Define clean APIs for 3rd party functionality via a DSL.
+    * Documentation can be generated dynamically using API tree data.
+* Access APIs via a DSL.
+    * Allows for scripting etc.
+* Create custom DSLs.
+
+**Currently an unstable work in progress, touch at own risk.**
+
+## Description
+
+It is:
+
+* A generic DSL (`DSeL::DSL::Nodes::Base`) supporting:
+    * Proxy (`DSeL::DSL::Nodes::Proxy`) environments for safe interaction with any given object.
+        * Method calls are forwarded.
+        * Internal state not affected nor accessible.
+    * Direct (`DSeL::DSL::Nodes::Direct`) environments, 
+        where the DSL context is the actual object instance.
+    * Preserved contexts:
+        * Re-entrant.
+        * Re-usable.
+        * Per object instance.
+        * Shared variables across environment nodes.
+        * Tree environment structure, with traversal helpers:
+            * `Root`
+            * `Parent`
+* An API specification framework (`DSeL::API::Node`).
+    * Specify call:
+        * Description 
+        * Type
+        * Object/catch-call
+        * Arguments and &block.
+        * Handler
+    * Tree structure for sections.
+* An API specification language (`DSeL::DSL::APIBuilder`).
+    * `import` external API spec files.
+    * Define and describe sections (children).
+* An API runner.
+    * Providing a specialised DSL (`DSeL::DSL::Nodes::API`) for API nodes (`DSeL::API::Node`).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dsel', github: 'qadron/dsel'
+```
+
+And then execute:
+
+    $ bundle
+
+## Examples
+
+See: [examples/](https://github.com/qadron/dsel/tree/master/examples/)
+
+### API
+
+Include the API specification:
+
+```ruby
+require_relative 'examples/api/my_api'
+```
+
+Use via a DSL script:
+
+```ruby
+MyAPI.run 'examples/api/my_api_dsl.rb'
+```
+
+Use via a Ruby script:
+
+```ruby
+require 'examples/api/my_api_ruby'
+````
+
+See: [examples/api/](https://github.com/qadron/dsel/tree/master/examples/api/)
+
+### DSL
+
+See: [examples/dsl/object.rb](https://github.com/qadron/dsel/tree/master/examples/dsl/object.rb)
+
+#### Proxy
+
+The safe way to get a DSL is to run the object inside a _Proxy_ context and
+just proxy methods, thus allowing the user to interact with the object as if 
+operating within it semantically but without access to non-public methods or its 
+state.
+
+See: [examples/dsl/proxy.rb](https://github.com/qadron/dsel/tree/master/examples/dsl/proxy.rb)
+
+#### Direct
+
+The direct way means not having the object inside the environment, but the 
+environment inside the object, thus allowing you to truly operate within it and 
+make a general mess of things or do some pretty cool stuff.
+
+See: [examples/dsl/direct.rb](https://github.com/qadron/dsel/tree/master/examples/dsl/direct.rb)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/qadron/dsel.
+
+## License
+
+Please see the `LICENSE.md` file.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/dsel.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dsel/version'
+
+Gem::Specification.new do |s|
+    s.name     = 'dsel'
+    s.version  = DSeL::VERSION
+    s.email    = 'tasos.laskos@gmail.com'
+    s.authors  = [ 'Tasos Laskos' ]
+    s.licenses = ['MIT']
+
+    s.summary  = %q{DSL/API generator and runner.}
+    s.homepage = 'https://github.com/qadron/dsel'
+
+    s.require_paths = ['lib']
+    s.files        += Dir.glob( 'lib/**/**' )
+    s.files        += %w(Gemfile Rakefile dsel.gemspec)
+    s.test_files   = Dir.glob( 'spec/**/**' )
+
+    s.extra_rdoc_files  = %w(README.md LICENSE.md CHANGELOG.md)
+end

data/lib/dsel/api/generator.rb

@@ -0,0 +1,285 @@
+require 'singleton'
+require 'securerandom'
+
+module DSeL
+module API
+
+class Generator
+    include Singleton
+
+    # @return   [Hash]
+    #   Data on the last call made.
+    attr_reader :last_call
+
+    def last_call_with_caller?
+        @last_call_with_caller
+    end
+
+    def last_call_without_caller!
+        @last_call_with_caller = false
+    end
+
+    def last_call_with_caller!
+        @last_call_with_caller = true
+    end
+
+    def on_call( &block )
+        fail ArgumentError, 'Missing &block' if !block
+
+        synchronize do
+            @on_call << block
+        end
+
+        self
+    end
+
+    # @note Defaults to `Object#hash` and assumes case-insensitive strings.
+    #
+    # Sets a way to calculate unique routing hashes for call objects.
+    #
+    # @param    [Symbol, #call] hasher
+    #   * `Symbol`: Object method.
+    #   * `#call`: To be passed each object and return an Integer hash.
+    def call_object_hasher=( hasher )
+        if hasher && !(hasher.is_a?( Symbol ) || hasher.respond_to?( :call ))
+            fail ArgumentError,
+                 "Expected Symbol or #call-able hasher, got: #{hasher.inspect}"
+        end
+
+        @call_object_hasher = hasher
+    end
+
+    # @private
+    def initialize
+        reset
+    end
+    
+    # @private
+    def reset
+        @mutex   = Monitor.new
+        @on_call = []
+
+        @last_call_with_caller = false
+        @call_object_hasher    = false
+
+        self
+    end
+
+    # @private
+    def define_definers( node, *types )
+        synchronize do
+            types.each do |type|
+                define_definer( node, type )
+            end
+        end
+
+        nil
+    end
+
+    # @private
+    def define_call_handler( node, type, *possible_object, &block )
+        node.instance_eval do
+            handler = Generator.call_handler_name( type, *possible_object )
+
+            if method_defined?( handler )
+                fail ArgumentError,
+                     'Call handler already exists: ' <<
+                         Generator.handler_to_s( self, type, *possible_object )
+            end
+
+            # We can get the options from here and do stuff...I don't know.
+            push_call_handler( type, handler, *possible_object )
+            define_method handler, &block
+        end
+
+        define_call_router( node, type )
+
+        nil
+    end
+
+    # @private
+    def calling( node, type, handler, args, *possible_object, &block )
+        synchronize do
+            @last_call = {
+                node: node,
+                type: type
+            }
+
+            if !possible_object.empty?
+                @last_call.merge!( object: possible_object.first )
+            end
+
+            @last_call.merge!(
+                handler: handler,
+                args:    args
+            )
+
+            if last_call_with_caller?
+                @last_call[:caller] = caller
+            end
+        end
+
+        t = Time.now
+        r = block.call
+        spent = Time.now - t
+
+        synchronize do
+            @last_call[:time] = spent
+            call_on_call( @last_call )
+        end
+
+        r
+    end
+
+    # @private
+    def definer_name( type )
+        "def_#{type}".to_sym
+    end
+
+    # @private
+    def call_handler_name( type, *possible_object )
+        possible_object.empty? ?
+            call_handler_catch_all_name( type ) :
+            call_handler_with_object_name( type, possible_object.first )
+    end
+
+    # @private
+    def call_handler_with_object_name( type, object )
+        "_#{type}_#{call_object_hash_for( object )}_#{token}".to_sym
+    end
+
+    # @private
+    def call_handler_catch_all_name( type )
+        "_#{type}_catch_all_#{token}".to_sym
+    end
+
+    # @private
+    def handler_to_s( node, type, *possible_object )
+        r = "#{node} #{type}"
+
+        if !possible_object.empty?
+            object = possible_object.first
+            r << ' '
+            r << (object.nil? ? 'nil' : object.to_s)
+        end
+
+        r
+    end
+
+    private
+
+    def call_on_call( *args )
+        @on_call.each do |b|
+            b.call *args
+        end
+    end
+
+    def call_object_hash_for( object )
+        if !@call_object_hasher
+            default_call_object_hash_for( object )
+        elsif @call_object_hasher.is_a?( Symbol )
+            object.send( @call_object_hasher )
+        else
+            @call_object_hasher.call( object )
+        end.tap do |h|
+            next if h.is_a? Integer
+
+            fail ArgumentError,
+                 "Hasher #{@call_object_hasher.inspect} returned non-Integer" <<
+                 " hash #{h.inspect} for object #{object.inspect}."
+        end
+    end
+
+    def default_call_object_hash_for( object )
+        object = object.downcase if object.is_a?( String )
+        object.hash
+    end
+
+    def token
+        @token ||= SecureRandom.hex
+    end
+
+    def define_definer( node, type )
+        definer = Generator.definer_name( type )
+
+        # We can get the options from here and do stuff...I don't know.
+        node.push_definer( type, definer )
+
+        node.class_eval( "undef :#{definer} if defined? #{definer}" )
+        node.define_singleton_method definer do |*possible_object, &block|
+            if possible_object.size > 1
+                fail ArgumentError,  'No more than 1 objects are allowed.'
+            end
+
+            Generator.define_call_handler( self, type, *possible_object, &block )
+        end
+    end
+
+    def define_call_router( node, type )
+        node.instance_eval do
+            return if method_defined?( type )
+
+            # Basically a router, object-based and catch-all.
+            define_method type do |*args, &block|
+                if !args.empty?
+                    object      = args.shift
+                    with_object = Generator.call_handler_with_object_name( __method__, object )
+
+                    if respond_to?( with_object )
+                        r = nil
+                        Generator.calling( self.class, type, with_object, args, object ) do
+                            r = send( with_object, *args, &block )
+                        end
+
+                        return r.nil? ? self : (r == :nil ? nil :r)
+                    end
+
+                    args.unshift object
+                end
+
+                catch_all = Generator.call_handler_catch_all_name( __method__ )
+                if respond_to?( catch_all )
+
+                    r = nil
+                    Generator.calling( self.class, type, catch_all, args ) do
+                        r = send( catch_all, *args, &block )
+                    end
+
+                    return r.nil? ? self : r
+                end
+
+                fail NoMethodError,
+                     "No handler for: #{Generator.handler_to_s( self.class, type, *args )}"
+            end
+        end
+        nil
+    end
+
+    def synchronize( &block )
+        @mutex.synchronize( &block )
+    end
+
+    class <<self
+
+        def method_missing( sym, *args, &block )
+            if instance.respond_to?( sym )
+                instance.send( sym, *args, &block )
+            else
+                super( sym, *args, &block )
+            end
+        end
+
+        def respond_to?( *args )
+            super || instance.respond_to?( *args )
+        end
+
+        # Ruby 2.0 doesn't like my class-level method_missing for some reason.
+        # @private
+        public :allocate
+
+    end
+
+end
+
+end
+end