JACOP 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc06d2415d5d58cd68dae44da601be5e14a7bff1afed2fb29dd3720506ba704e
+  data.tar.gz: 205de8de785654fe05959899cfc4be4f14ab0c6fedb851db7fc5a6dcd1dac5d8
+SHA512:
+  metadata.gz: 15370f5420a1eb3edc5b4ff7e7fadf8b245683088cad3f6cd936f3a394eaa45f5945c2543d3cde2b6f0d4c7f1ebd95666b19da27b0a19f269f2b1b73277ac4b7
+  data.tar.gz: 1b5fc247e1be74fe3e3d37854c7d3af836011fe2bfabb87c810be8f3d969fcd9ee82f328c0cf504cedb81188f5254349934cb1e678678d66a99a251c97ab4107

data/lib/jacop/exception.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module JACOP
+	class Exception < ::StandardError; end
+	class DefinitionError < Exception; end
+	class ParserError < Exception; end
+end

data/lib/jacop/node.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative 'option'
+require_relative 'exception'
+
+module JACOP
+	class Node
+		attr_reader :options
+		attr_reader :name
+		attr_reader :nodes
+		attr_reader :hidden
+
+		def initialize(name:, parent: nil, params:)
+			@name = name
+			@parent = parent
+			@banner = params[:banner]
+			@notes = params[:notes]
+			@version = params[:version]
+			@desc = params[:desc]
+			@call = params[:call]
+			raise DefinitionError, "#{@call} is not call-able" if @call and !@call.respond_to?(:call)
+
+			@hidden = params[:hidden]
+			@options = []
+			@nodes = []
+			params[:options]&.each {|h| @options << Option.new(command: self, option: h[:name], params: h) } || []
+			@nodes = params[:nodes]&.map { |h| Node.new(name: h[:name] , parent: self, params: h)} || []
+
+			# Default 'help' and 'version' options get added automatically
+			@options << Option.new(option: 'help', command: self, params: {short: 'h', desc: "Show help screen", type: :switch})
+			@options << Option.new(option: 'version', command: self, params: {short: 'v', desc: "Show version", type: :switch}) if @version
+		end
+
+		def parse(cmdline)
+			case cmdline
+			when String then
+				cmdline = cmdline.shellsplit
+			when NilClass then
+				cmdline = []
+			end
+
+			usage if cmdline.empty? and @call.nil?
+
+			begin
+				token = cmdline.shift
+				if token && !token.empty? && token !~ /^-{1,2}/ then
+					node = @nodes.find {|n| n.name == token}
+					raise ParserError, "Unknown command '#{token}'" unless node
+
+					node.parse(cmdline)
+				else
+					while token
+						is_short = token.match(/^-[[:alnum:]]/) != nil
+						t = token.sub(/^-{1,2}/, '')
+						opt = @options.find { |o| is_short ? o.short == t : o.option == t }
+						raise ParserError, "Unknown option '#{token}'" unless opt
+						opt.parse(cmdline, @options.select {|o| !o.value.nil?})
+						token = cmdline.shift
+					end
+
+					usage if @options.find {|o| o.option == 'help'}&.value
+					version if @options.find {|o| o.option == 'version'}&.value
+					@options.select {|o| o.required }.each {|o| o.validate_required }
+
+					execute if cmdline.empty?
+				end
+			rescue ParserError => e
+				usage(1, e.message)
+			end
+		end
+
+		def request_short(option, short)
+			noauto = !short.nil?
+			shorts = @options.map {|o| o.short}
+
+			c = option.downcase.scan(/[a-z]/).each
+			short = c.peek unless noauto
+			loop do
+				if shorts.member?(short) then
+					if noauto then
+						short = nil
+						break
+					else
+						begin
+							short = /[a-z]/.match?(short) ? short.upcase : c.next
+						rescue StopIteration
+							short = nil
+							break
+						end
+					end
+				else
+					break
+				end
+			end
+
+			return short
+		end
+
+		def usage_snippet(width)
+			"  %-#{width}.#{width}s%s%s" % [@name + (@nodes.select {|n| !n.hidden}.empty? ? '' : '>'), " " * 8, @desc]
+		end
+
+		def to_s
+			"%s%s%s" % [@parent, @parent ? ' ' : nil, @name]
+		end
+
+		def banner
+			@banner || @parent.banner
+		end
+
+		private
+
+		def execute
+			return unless @call
+
+			options = @options.select {|o| !o.value.nil?}.map { |o| {o.option => o.value} }.reduce(&:merge) || {}
+
+			@call.call(options)
+		end
+
+		def version
+			puts "Version #{@version}"
+			exit(0)
+		end
+
+		def usage(exitcode = 0, misusage = nil)
+			puts misusage if misusage
+
+			if banner then
+				puts banner
+				puts
+			end
+
+			puts @desc if @desc and !@desc.empty?
+			nodes = @nodes.select {|n| !n.hidden }
+
+			usage_str = +'General usage: '
+			usage_str << File.basename($PROGRAM_NAME)
+			usage_str << "#{self}"
+			usage_str << ' <command>' unless nodes.empty?
+			usage_str << ' %s<options>%s' % (@options.any? {|o| o.required } ? [nil, nil] : ['[', ']']) unless @options.empty?
+
+			puts usage_str
+			puts
+
+			width = (nodes.map {|n| n.name.size + 1 } + @options.map {|o| o.usage_str.size}).max
+
+			if !nodes.empty?
+				puts 'Commands:'
+				nodes.each { |m| puts m.usage_snippet(width) }
+				puts
+			end
+
+			options = @options.select {|o| !o.hidden }
+			if !options.empty?
+				puts 'Options:'
+				options.each { |o| puts o.usage_snippet(width) }
+				puts
+			end
+
+			if @notes then
+				puts "Notes:"
+				@notes.each_line {|line| puts "  #{line}"}
+				puts
+			end
+
+			exit(exitcode)
+		end
+	end
+end

data/lib/jacop/node_builder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'option_builder'
+require_relative 'option'
+require_relative 'exception'
+
+module JACOP
+	##
+	# Internal class, not to be used directly.
+	# The methods of this class are the DSL statements for defining a command.
+	# They become available in a `configure` or `command` block after including the `JACOP` mixin.
+	class NodeBuilder
+		attr_reader :params # :nodoc:
+
+		def initialize(name=nil) # :nodoc:
+			@params = {
+				name: name,
+				nodes: [],
+				options: []
+			}
+		end
+
+		##
+		# Define a new custom data-type for options.
+		# The data-type will be available globally, not just in the blocks where it was defined.
+		def add_type(type:, klass:, &block)
+			raise DefinitionError, "add_type needs a block" unless block_given?
+
+			Option.add_type(type: type, klass: klass, &block)
+		end
+
+		##
+		# Set the banner in the help/usage screen
+		def banner(banner)
+			@params[:banner] = banner
+		end
+
+		##
+		# Set notes shown in the help/usage screen
+		def notes(notes)
+			@params[:notes] = notes
+		end
+
+		##
+		# Set the version.  If set, the `--version` option will be created automatically.
+		def version(version)
+			@params[:version] = version
+		end
+
+		##
+		# Set the description for the command in the help/usage screen
+		def desc(desc)
+			@params[:desc] = desc
+		end
+		alias_method :description, :desc
+
+		##
+		# Define which method or block should be called when this command is invoked.
+		# The given argument will usually be either a `Proc` or `Method` object, or a block.
+		# In any case, it must respond to the `#call` method. The `callable` will receive a
+		# single argument containing a hash of all supplied command-line arguments.
+		def call(callable = nil, &block)
+			@params[:call] = block_given? ? block : callable
+		end
+
+		##
+		# Set the command to be hidden.  It will not be shown in the help/usage screen.
+		def hidden(hidden = true)
+			@params[:hidden] = hidden
+		end
+
+		##
+		# Define a new (sub-) command
+		def command(name, &block)
+			builder = NodeBuilder.new(name)
+			builder.instance_eval(&block)
+			@params[:nodes] << builder.params
+		end
+
+		##
+		# Define a new option for this command
+		def option(name, &block)
+			builder = OptionBuilder.new(name)
+			builder.instance_eval(&block)
+			@params[:options] << builder.params
+		end
+	end
+end

data/lib/jacop/option.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'exception'
+
+module JACOP
+	class Option
+
+		@@valid_types = {
+			switch: { klass: [NilClass, TrueClass, FalseClass], converter: Proc.new {|val| !!val } },
+			string: { klass: String, converter: Proc.new {|val| val.to_s } },
+			int: { klass: Integer, converter: Proc.new {|val| val.to_i } },
+			percent: { klass: Float, converter: Proc.new {|val| val.to_f / 100 } },
+			date: { klass: Date, converter: Proc.new {|val| Date.parse(val) } }
+		}
+
+		def self.valid_types; @@valid_types; end
+
+		def self.add_type(type:, klass:, &block)
+			@@valid_types[type] = { klass: klass, converter: block }
+		end
+
+		attr_reader :option
+		attr_reader :value
+		attr_reader :short
+		attr_reader :required
+		attr_reader :hidden
+
+		def initialize(command:, option:, params:)
+			@option = option
+			@desc = params[:desc]
+			@short = command.request_short(@option, params[:short])
+			@required = params[:required]
+			@conflicts = @required ? [] : params[:conflicts] || []
+			@hidden = params[:hidden]
+			@type = validate_type(params[:type])
+			@multi = params[:multi]
+			@default = validate_value(params[:default], multi: @multi, allow_nil: true)
+			@value = @default
+
+			validate
+		end
+
+		def to_s
+			@option
+		end
+
+		def usage_str
+			s = +"--#{@option}"
+			s << "|-#{@short}" if !(@short.nil? or short.empty?)
+			s << " <%s>%s" % [@type.upcase, @multi ? "[, ...]" : nil] if @type != :switch
+
+			return s
+		end
+
+		def usage_snippet(width)
+			"  %-#{width}.#{width}s%s%s%s" % [usage_str,
+												" " * 8,
+												@desc,
+												@default.nil? ?
+													nil :
+													" (Default: #{@default})"
+											]
+		end
+
+		def conflicts(other)
+			return false if self == other
+
+			@conflicts.member?(other.option)
+		end
+
+		def parse(cmdline, options)
+			if options.any? { |o| conflicts(o) || o.conflicts(self)} then
+				raise ParserError, "Option '#{option}' conflicts with another option"
+			end
+
+			val = []
+			while !cmdline.empty? && cmdline[0] !~ /^-{1,2}/ do
+				raise ParserError, "Option '#{option}' expects a single argument" unless val.empty? or @multi
+				val << (@multi ? cmdline.shift.split(/,/) : cmdline.shift)
+				val.flatten!
+			end
+
+			if @type == :switch then
+				@value = true
+			elsif @multi then
+				@value = val.map { |x| parse_value(x.strip) }
+			else
+				@value = parse_value(val.first)
+			end
+		end
+
+		def validate_required
+			raise ParserError, "Required option '#{@option}' is missing" if @required and !@value
+		end
+
+		private
+
+		def parse_value(value)
+			begin
+				value = @@valid_types.dig(@type, :converter).call(value)
+			rescue => e
+				raise ParserError, "Error while coercing value '#{value}' into type '#{@type}': #{e.message}"
+			end
+
+			return value
+		end
+
+		def validate_type(type)
+			if type then
+				t = type.to_sym
+				return t if @@valid_types.keys.member?(t)
+
+				raise DefinitionError, "Unknown type '#{t}'. Valid types are: #{@@valid_types.keys.join(', ')}"
+			end
+
+			return t
+		end
+
+		def validate
+			raise ParserError, "'short' options are expected to be single characters" if @short and @short.size > 1
+			raise DefinitionError, "Settings 'required' and 'conflicts' for option '#{@option} are mutually exclusive" if @required and !@conflicts.empty?
+
+			if @conflicts && !@conflicts.is_a?(Array) then
+				@conflicts = [@conflicts]
+			end
+		end
+
+		def validate_value(value, multi: @multi, allow_nil: false)
+			return if !value and allow_nil
+
+			if multi then
+				if value.is_a? Array then
+					value.each { |x| validate_value(x, multi: false) }
+				else
+					raise ParserError, "Array expected for option '#{@option}'"
+				end
+			else
+				type_mismatch = value.class != @@valid_types.dig(@type, :klass)
+				raise ParserError, "Value '#{value}' for option '#{@option}' has wrong type, expected '#{@type}'" if type_mismatch
+			end
+
+			return value
+		end
+
+	end
+end

data/lib/jacop/option_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module JACOP
+	##
+	# Internal class, not to be used directly.
+	# The methods of this class are the DSL statements for defining an option for a command.
+	# They become available in an `option` block after including the `JACOP` mixin.
+	class OptionBuilder
+		attr_reader :params # :nodoc:
+
+		def initialize(name) # :nodoc:
+			@params = {
+				name: name
+			}
+		end
+
+		##
+		# Set a description for this option in the help/usage screen.
+		def desc(desc)
+			@params[:desc] = desc
+		end
+		alias_method :description, :desc
+
+		##
+		# Set the alternative single-character option for this option.  If not given, it will be auto-generated.
+		# Auto-generation of the short option can be disabled by setting this to an empty string.
+		def short(short)
+			@params[:short] = short
+		end
+		
+		##
+		# Define this option as being required.
+		# `required` and `conflicts` cannot both be used for the same option.
+		def required(required = true)
+			@params[:required] = required
+		end
+
+		##
+		# Define other options with which this option is mutually exclusive.
+		def conflicts(conflicts)
+			@params[:conflicts] = conflicts
+		end
+
+		##
+		# Set this option to be hidden.  It will not be shown in the help/usage screen.
+		def hidden(hidden = true)
+			@params[:hidden] = hidden
+		end
+
+		##
+		# Set the data-type of this option's argument.  This is a required setting.
+		def type(type)
+			@params[:type] = type
+		end
+
+		##
+		# Set a default value for this option's argument.
+		def default(default)
+			@params[:default] = default
+		end
+
+		##
+		# Define that this option can take multiple arguments, separated by commas.
+		def multi(multi = true)
+			@params[:multi] = multi
+		end
+	end
+end

data/lib/jacop/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module JACOP
+  ##
+  # Version of the `JACOP` gem
+  VERSION = '1.0.1'
+end

data/lib/jacop.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative './jacop/node_builder'
+require_relative './jacop/node'
+require_relative './jacop/exception'
+
+##
+# JACOP is a DSL for building and parsing command-line commands and options.
+# Include this mixin to make use of the DSL.
+module JACOP
+
+	##
+	# Configure the top-level command level
+	def configure(&block)
+		builder = NodeBuilder.new
+		builder.instance_eval(&block)
+		self.root_node = builder.params
+	end
+
+  ##
+	# Parse the provided command-line
+	def parse(cmdline)
+		raise DefinitionError, "#{self.class} has not been configured" if root_node.empty?
+
+		Node.new(name: root_node[:name], params: root_node).parse(cmdline)
+	end
+
+	private
+	def root_node
+		@root_node ||= {}
+	end
+
+	def root_node=(val)
+		@root_node = merge_nodes(root_node, val)
+	end
+
+	def merge_nodes(node1, node2)
+		node1.merge(node2) do |key, this_val, other_val|
+			if this_val.is_a?(Hash) && other_val.is_a?(Hash)
+				merge_nodes(this_val, other_val)
+			elsif this_val.is_a?(Array) && other_val.is_a?(Array)
+				this_val + other_val
+			else
+				this_val
+			end
+		end
+	end
+
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: JACOP
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Oliver Brakmann
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: JACOP is a DSL and command-line parser allowing for regular and Git-style
+  command syntax, featuring type-aware option parsing and automatic help screen generation.
+email:
+- oliver.brakmann@posteo.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/jacop.rb
+- lib/jacop/exception.rb
+- lib/jacop/node.rb
+- lib/jacop/node_builder.rb
+- lib/jacop/option.rb
+- lib/jacop/option_builder.rb
+- lib/jacop/version.rb
+homepage: https://codeberg.org/obrakmann/jacop
+licenses:
+- EUPL-1.2
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Just Another COmmand-line Parser
+test_files: []