rspec-usecases 0.0.12

data/hooks/update-version

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# NOTE: you may need change file permissions
+#       chmod +x hooks/update-version
+
+exit 1 if ARGV.empty?
+
+version = ARGV[0]
+version = version[1..-1] # revoke 'v' character, e.g. v0.1.1 becomes 0.1.1
+
+namespaces = %w[Rspec Usecases]
+
+indent = 0
+output = ['# frozen_string_literal: true', '']
+
+namespaces.each do |namespace|
+  output.push "#{'  ' * indent}module #{namespace}"
+  indent += 1
+end
+
+output.push "#{'  ' * indent}VERSION = \'#{version}'"
+indent -= 1
+
+namespaces.each do
+  output.push "#{'  ' * indent}end"
+  indent -= 1
+end
+
+output.push('')
+
+printf "%-25<label>s : %<version>s\n", label: 'GEM VERSION', version: version
+File.open('lib/rspec/usecases/version.rb', 'w+') { |f| f.write(output.join("\n")) }

data/lib/rspec/usecases.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rspec/usecases/version'
+require 'rspec/usecases/usecase'
+require 'rspec/usecases/content'
+require 'rspec/usecases/content_code'
+require 'rspec/usecases/content_outcome'
+
+module Rspec
+  module Usecases
+    # raise Rspec::Usecases::Error, 'Sample message'
+    class Error < StandardError; end
+
+    # Your code goes here...
+  end
+end

data/lib/rspec/usecases/content.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# require 'rspec/usecases/content'
+
+module Rspec
+  module Usecases
+    # Content
+    class Content
+      EXTRACT_CONTENT_REX = /
+        (?<bos>^)                             # beginning of string
+        (?<indent>\s*)                        # find the indent before the method
+        (?<method_type>outcome|code|ruby)\s   # grab the method name from predefined list
+        (?<method_signature>.*?)              # grab the method signature which is every thing up to the first do
+        (?<method_open>do)                    # code comes after the first do
+        (?<content>.*)                        # content is what we want
+        (?<method_closure>end)\z              # the end keyword at the end of string is where the content finishes
+      /xm.freeze
+
+      # title
+      attr_accessor :title
+
+      # :type
+      attr_accessor :type
+
+      # metadata
+      attr_accessor :metadata
+
+      # source
+      attr_accessor :source
+
+      # is_hr
+      attr_accessor :is_hr
+
+      def self.parse(example)
+        return nil if example.description.nil? || example.description.strip.length.zero?
+        return nil if example.metadata[:content_type].nil?
+
+        result = get_instance(example)
+
+        result&.parse_block_source(example)
+
+        result
+      end
+
+      # rubocop:disable Lint/UselessAssignment, Security/Eval
+      def self.get_instance(example)
+        title = example.description
+        type = example.metadata[:content_type].to_s
+        metadata = example.metadata
+
+        klass = "Rspec::Usecases::Content#{type.capitalize}"
+
+        begin
+          content_object = "#{klass}.parse(title, type, metadata)"
+          eval(content_object)
+        rescue NameError
+          # TODO: Logging
+          puts "UNKNOWN CONTENT TYPE: #{metadata[:content_type]}"
+          nil
+        rescue StandardError => e
+          # TODO: Logging
+          puts e
+          nil
+        end
+      end
+      # rubocop:enable Lint/UselessAssignment, Security/Eval
+
+      # rubocop:disable Style/DoubleNegation
+      def initialize(title, type, metadata)
+        @title = title.start_with?('example at .') ? '' : title
+        @type = type
+
+        @is_hr = !!metadata[:hr]
+
+        yield self if block_given?
+      end
+      # rubocop:enable Style/DoubleNegation
+
+      # Have not written a test for this yet
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize
+      def parse_block_source(example)
+        @debug = false
+
+        # Source code for rspec is living on the metadata[:block].source location
+        unless defined?(example.metadata) && defined?(example.metadata[:block]) && defined?(example.metadata[:block].source)
+          @source = ''
+          return
+        end
+
+        unless example.metadata[:source_override].nil?
+          @source = example.metadata[:source_override]
+          return
+        end
+
+        source = example.metadata[:block].source.strip
+
+        segments = source.match(EXTRACT_CONTENT_REX)
+
+        unless defined?(segments) && defined?(segments[:content])
+          @source = ''
+          return
+        end
+        @source = remove_wasted_indentation(segments[:content])
+        @source
+      rescue StandardError => e
+        puts 'Could not parse source'
+        puts example.metadata
+        puts e
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/AbcSize
+
+      def remove_wasted_indentation(content)
+        lines = content.lines
+
+        whitespace = /^\s*/
+
+        # find the small whitespace sequence
+        # at beginning of line that is not \n or blank
+        # and grab the smallest value
+        indent = lines
+                 .map    { |l| l.match(whitespace).to_s }
+                 .reject { |s| ["\n", ''].include?(s) }
+                 .min_by(&:length)
+
+        # remove the smallest indentation from beginning
+        # of all lines, this is the wasted indentation
+        rex_indent = /^#{indent}/
+
+        lines.each { |l| l.gsub!(rex_indent, '') }
+
+        # convert back to a content string
+        lines.join.strip
+      end
+
+      def to_h
+        {
+          title: title,
+          type: type,
+          source: source,
+          options: [
+            is_hr: is_hr
+          ]
+        }
+      end
+
+      def debug
+        puts "title                         : #{title}"
+        puts "type                          : #{type}"
+        puts "metadata                      : #{metadata}"
+        puts "source                        : #{source}"
+        puts "is_hr                         : #{is_hr}"
+      end
+    end
+  end
+end

data/lib/rspec/usecases/content_code.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rspec/usecases/content'
+
+module Rspec
+  module Usecases
+    # Content Code
+    class ContentCode < Rspec::Usecases::Content
+      # # Source code
+      # attr_accessor :code
+
+      # Type of code, ruby, javascript, css etc.
+      attr_accessor :code_type
+
+      # # Summary
+      # attr_accessor :summary
+
+      def self.parse(title, type, metadata)
+        new(title, type, metadata) do |content|
+          # content.code = metadata[:code].to_s
+          content.code_type = metadata[:code_type].to_s
+          # content.summary = metadata[:summary].to_s
+        end
+      end
+
+      def to_h
+        {
+          # code: code,
+          code_type: code_type
+          # summary: summary
+        }.merge(super.to_h)
+      end
+
+      def debug
+        super
+        puts "code                          : #{code}"
+        puts "code_type                     : #{code_type}"
+        puts "summary                       : #{summary}"
+      end
+    end
+  end
+end

data/lib/rspec/usecases/content_outcome.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rspec/usecases/content'
+
+module Rspec
+  module Usecases
+    # Content Outcome
+    class ContentOutcome < Rspec::Usecases::Content
+      # Summary
+      attr_accessor :summary
+
+      def self.parse(title, type, metadata)
+        new(title, type, metadata) do |content|
+          content.summary = metadata[:summary].to_s
+        end
+      end
+
+      def to_h
+        {
+          summary: summary
+        }.merge(super.to_h)
+      end
+
+      def debug
+        super
+        puts "summary                       : #{summary}"
+      end
+    end
+  end
+end

data/lib/rspec/usecases/usecase.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# require 'rspec/usecases/usecase'
+
+module Rspec
+  module Usecases
+    # Usecase
+    class Usecase
+      # key
+      attr_reader :key
+
+      # title
+      attr_reader :title
+
+      # summary
+      attr_reader :summary
+
+      # Usage contains a sample on how to call some code
+      attr_reader :usage
+
+      # Usage description gives extra details to support the usage example
+      attr_reader :usage_description
+
+      # contents
+      attr_reader :contents
+
+      def initialize(key)
+        @key = key
+        @title = ''
+        @summary = ''
+        @usage = ''
+        @usage_description = ''
+        @contents = []
+      end
+
+      def self.parse(key, data)
+        usecase = Usecase.new(key)
+
+        usecase.build_title(data)
+        usecase.build_attributes(data)
+
+        # Loop through the it blocks
+        data.examples.each do |it|
+          usecase.add_content(it)
+        end
+
+        usecase
+      end
+
+      def to_h
+        {
+          key: key,
+          title: title,
+          summary: summary,
+          usage: usage,
+          usage_description: usage_description,
+          contents: contents.map(&:to_h)
+        }
+      end
+
+      def debug
+        puts "key                           : #{key}"
+        puts "title                         : #{title}"
+        puts "summary                       : #{summary}"
+        puts "usage                         : #{usage}"
+        puts "usage_description             : #{usage_description}"
+        puts "contents                      : #{contents}"
+      end
+
+      def add_content(example)
+        content = Rspec::Usecases::Content.parse(example)
+        @contents << content unless content.nil?
+      end
+
+      def build_attributes(example_group)
+        @summary = example_group.metadata[:summary] if example_group.metadata[:summary]
+
+        @usage = example_group.metadata[:usage] if example_group.metadata[:usage]
+        @usage_description = example_group.metadata[:usage_description] if example_group.metadata[:usage_description]
+      end
+
+      # Build the title from the rspec example_group, aka describe or context
+      #
+      # If title attribute is set then this takes priority.
+      # If not set, then build the title by looking through the parent objects
+      def build_title(example_group)
+        return if title != ''
+
+        if example_group.metadata[:title]
+          @title = example_group.metadata[:title]
+        else
+          example_group.example_group.parent_groups.reverse.each do |group|
+            @title = if @title.length.zero?
+                       group.description
+                     else
+                       "#{@title} #{group.description}"
+                     end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/usecases/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Usecases
+    VERSION = '0.0.12'
+  end
+end

data/rspec-usecases.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/rspec/usecases/version'
+
+Gem::Specification.new do |spec|
+  spec.required_ruby_version  = '>= 2.5'
+  spec.name                   = 'rspec-usecases'
+  spec.version                = Rspec::Usecases::VERSION
+  spec.authors                = ['David Cruwys']
+  spec.email                  = ['david@ideasmen.com.au']
+
+  spec.summary                = 'Rspec Usecases helps to write self-documenting code usage examples that execute as normal unit tests while outputting documentation in varied formats'
+  spec.description            = <<-TEXT
+    Rspec Usecases helps to write self-documenting code usage examples that execute as normal unit tests while outputting documentation in varied formats
+  TEXT
+  spec.homepage               = 'http://appydave.com/gems/rspec-usecases'
+  spec.license                = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.' unless spec.respond_to?(:metadata)
+
+  # spec.metadata['allowed_push_host'] = "Set to 'http://mygemserver.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/klueless-io/rspec-usecases'
+  spec.metadata['changelog_uri'] = 'https://github.com/klueless-io/rspec-usecases/commits/master'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the RubyGem files that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  # spec.extensions    = ['ext/rspec_usecases/extconf.rb']
+
+  # spec.add_dependency 'tty-box',         '~> 0.5.0'
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: rspec-usecases
+version: !ruby/object:Gem::Version
+  version: 0.0.12
+platform: ruby
+authors:
+- David Cruwys
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-01-24 00:00:00.000000000 Z
+dependencies: []
+description: "    Rspec Usecases helps to write self-documenting code usage examples
+  that execute as normal unit tests while outputting documentation in varied formats\n"
+email:
+- david@ideasmen.com.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- STORIES.md
+- USAGE.md
+- bin/console
+- bin/k
+- bin/kgitsync
+- bin/khotfix
+- bin/setup
+- hooks/pre-commit
+- hooks/update-version
+- lib/rspec/usecases.rb
+- lib/rspec/usecases/content.rb
+- lib/rspec/usecases/content_code.rb
+- lib/rspec/usecases/content_outcome.rb
+- lib/rspec/usecases/usecase.rb
+- lib/rspec/usecases/version.rb
+- rspec-usecases.gemspec
+homepage: http://appydave.com/gems/rspec-usecases
+licenses:
+- MIT
+metadata:
+  homepage_uri: http://appydave.com/gems/rspec-usecases
+  source_code_uri: https://github.com/klueless-io/rspec-usecases
+  changelog_uri: https://github.com/klueless-io/rspec-usecases/commits/master
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.5
+signing_key:
+specification_version: 4
+summary: Rspec Usecases helps to write self-documenting code usage examples that execute
+  as normal unit tests while outputting documentation in varied formats
+test_files: []