singer 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d116f657ac1b8d3b57e540ae37bf0d74c21fe357938fbb6aa33309663b9add5
-  data.tar.gz: 7854c981adfd45a2989647f6302022ff0b40e66b47960c2fc536cd428dc99c93
+  metadata.gz: b91934a916b675cfddecdac26f48673a77e9e2f014ae94a7db7623df0adaac67
+  data.tar.gz: f8a8384bdbba9f096d303e91fbd68a2b1063239d89e5f072d1e8e551cee1b7d2
 SHA512:
-  metadata.gz: 933cc4b306f621d57598f0b1d5f72993fd6c25afea2496aa89f088847b42374b8a01bf68d709a2c3f154455b02b6158f2072677ec23b55ff1b359020c24cfbe5
-  data.tar.gz: 0ed47b046d03641227f28faa499d9ea50cd80901ddf7efa75f5c1da4df07a54b5ad435bb338158047438175862c17b310e92d19ee94ecfafdf135d9810dce468
+  metadata.gz: 5a0d34e3e4ba0b18a55151f796f30d8b0bad715f74a084f37456a4cdebb74d8f66543db90003dc84877a19ef295f0664f1e5ba190cd137d67a670f8819802d01
+  data.tar.gz: d9245c0f2fcbc5671a078daf5bcf71977ba2ec661c1b599e0aedaa2e679948bc4d9ebad738a6302daefe515dae253a5d8d59d6b12b0779b7796b6c9bf52b35d2

data/README.md

@@ -17,6 +17,53 @@ Run `singer --list-templates` to see available templates' names, both shipped wi
 
 For `PROJECT_NAME`, using `snake_case` is best, although an attempt will be made to understand `CamelCase`, too.
 
+## Writing your own templates
+
+Many features of Singer will become clearer when seeing actual usage - please feel encouraged to examine the templates shipped with the gem (you can find them in `templates_from_gem` shown by the `singer --show-paths`).
+
+### Template location
+
+User-provided templates should be placed in the directory named `templates_from_user` in the `singer --show-paths` output.
+Each template resides in a subdirectory - the subdirectory's name becomes the template's name, and is not included in the generated paths (Singer will only replicate the directory structure _inside_ it).
+
+### Variables available to templates
+
+Templates written in ERB or other templating mechanisms that execute Ruby code will have access to `Singer.configuration` object and its accessors. For example, the following code in a `my_template`'s file:
+```ruby
+class <%= Singer.configuration.project_name_camelcase %>
+```
+will, when Singer is called with `singer my_template foo_bar_baz`, result in this written to output file:
+```ruby
+class FooBarBaz
+```
+
+To see an up-to-date list of available variables, run `singer --list-variables`.
+
+### Using --dashes option
+
+Since Ruby treats the `-` character in snakecased name as corresponding to module nesting in camelcased name, Singer also treats it in a special way. You can control this behavior with the `--dashes` option. This is how different values will affect `project_name_camelcase`:
+
+```bash
+singer foo_bar-baz --dashes modularize # results in FooBar::Baz (default)
+singer foo_bar-baz --dashes preserve   # results in FooBar-baz
+singer foo_bar-baz --dashes delete     # results in FooBarbaz
+```
+
+### Special segments in template paths
+
+Any of the variables above can be also used in paths/filenames of template files, capitalized and surrounded by double underscores.
+So, if `my_template` has a file at this path:
+```
+docs_for___PROJECT_NAME_SNAKECASE__/__PROJECT_NAME_CAMELCASE__ - humble beginnings.txt
+```
+and you run `singer my_template alpha_beta`, a file named like this will be created:
+```
+docs_for_alpha_beta/AlphaBeta - humble beginnings.txt
+```
+
+Tiny caveat for completeness - while `template_file_name_actual` can be used inside template files, the `__TEMPLATE_FILE_NAME_ACTUAL__` will not be substituted in paths.
+"Stack level too deep" and all that ;)
+
 ## Development
 
 ```bash

data/exe/singer

@@ -2,5 +2,4 @@
 
 require 'singer'
 
-Singer::OptionParsing.configure(ARGV)
-Singer.generate
+Singer.configure_and_generate(ARGV)

data/lib/singer/configuration.rb

@@ -1,4 +1,16 @@
+# main module, has `.configuration` reader
 module Singer
 	# holds settings
-	CONFIGURATION = Struct.new(:template_name, :camelcase_name, :snakecase_name).new
+	Configuration = Struct.new(
+		'Configuration',
+		:template_name,
+		:project_name_original, :project_name_camelcase, :project_name_snakecase,
+		:template_file_name_original, :template_file_name_actual,
+		:dashes,
+	)
+	CONFIGURATION_VARIABLES_FORBIDDEN_IN_PATHS = %w[template_file_name_actual].freeze
+
+	def self.configuration
+		@configuration ||= Configuration.new
+	end
 end

data/lib/singer/name_transformation.rb

@@ -0,0 +1,26 @@
+module Singer
+	# transform between snakecase and camelcase, with some special rules
+	class NameTransformation
+		DASHES_OPTIONS = %w[modularize delete preserve].freeze
+
+		def self.encase_name(name)
+			Singer.configuration.project_name_original = name
+			Singer.configuration.project_name_snakecase = name.gsub(/(\w)([A-Z])/){ "#{$1}_#{$2}" }.gsub(/_+/, '_').downcase
+			camelcase = Singer.configuration.project_name_snakecase.split('_').map(&:capitalize).join
+			Singer.configuration.project_name_camelcase = treat_dashes_in_name(camelcase)
+		end
+
+		def self.treat_dashes_in_name(camelcase)
+			case Singer.configuration.dashes
+			when 'modularize'
+				camelcase.gsub(/([[:alnum:]])-+([[:alnum:]])/){ "#{$1}::#{$2.upcase}" }
+			when 'delete'
+				camelcase.delete('-')
+			when 'preserve'
+				camelcase
+			else
+				raise ParameterValueUnsupported, "Unsupported value #{Singer.configuration.dashes.inspect} for --dashes option"
+			end
+		end
+	end
+end

data/lib/singer/option_parsing.rb

@@ -1,40 +1,80 @@
 module Singer
 	# extracts what we need from ARGV
 	class OptionParsing
-		DEFAULT_TEMPLATE_NAME = 'tdd'.freeze
-
 		def self.configure(argvies) # rubocop:disable Metrics/MethodLength
 			options = {}
+			Singer.configuration.dashes = NameTransformation::DASHES_OPTIONS.first
+
 			OptionParser.new do |parser|
+				parser.program_name = 'singer'
+				parser.version = Singer::VERSION
 				parser.banner = <<~USAGE
-					Usage: #{$PROGRAM_NAME} [OPTION]... [TEMPLATE_NAME] PROJECT_NAME
+					Usage: #{parser.program_name} [OPTION]... [TEMPLATE_NAME] PROJECT_NAME
 					Generates a project from a multi-file template.
 					PROJECT_NAME can be in snake_case or CamelCase.
 
 					Options:
 				USAGE
-				parser.on('--list-templates', 'list all available templates') do
-					list_all_templates
-					Kernel.exit
-				end
+				add_options_functional(parser)
+				add_options_listing(parser)
 			end.parse!(argvies, into: options)
+		end
 
-			raise NameMissingError, 'Missing mandatory argument PROJECT_NAME' if argvies.empty?
+		def self.add_options_functional(parser) # rubocop:disable Metrics/MethodLength
+			parser.on(
+				'-t', '--template-path=PATH', 'load a template from a given path - use instead of [TEMPLATE_NAME]',
+			) do |path|
+				Template.load_one_from_path(path)
+			end
+			parser.on('--dashes DASHES', NameTransformation::DASHES_OPTIONS, <<~DESCRIPTION) do |dashes|
+				what to do with "-" in PROJECT_NAME when converting to Singer.configuration.project_name_camelcase:
+						"modularize": convert to "::", following Ruby convention of mapping dashes to module nesting, or
+						"delete": remove entirely, or
+						"preserve": leave as-is
+						(default is "#{Singer.configuration.dashes}" if `--dashes` isn't given)
+				DESCRIPTION
+				Singer.configuration.dashes = dashes
+			end
+		end
 
-			encase_name(argvies.pop)
-			CONFIGURATION.template_name = argvies.shift || DEFAULT_TEMPLATE_NAME
+		def self.add_options_listing(parser) # rubocop:disable Metrics/MethodLength
+			parser.on('--list-templates', 'list all available templates') do
+				list_all_templates
+				Kernel.exit
+			end
+			parser.on('--list-paths', 'list paths used to load files') do
+				list_paths
+				Kernel.exit
+			end
+			parser.on('--list-variables', 'list all variables available to templates and in paths') do
+				list_variables
+				Kernel.exit
+			end
 		end
 
 		def self.list_all_templates
-			name_column_width = Template.all.keys.map(&:length).max
-			Template.all.each do |name, template|
-				puts "#{name.to_s.ljust(name_column_width)} #{template.path}"
-			end
+			columnize_hash(Template.all.transform_values(&:path))
+		end
+
+		def self.list_paths
+			columnize_hash(%w[singer_config_dir templates_from_user templates_from_gem].map{ [_1, Paths.send(_1)] })
 		end
 
-		def self.encase_name(name)
-			CONFIGURATION.snakecase_name = name.gsub(/(\w)([A-Z])/){ "#{$1}_#{$2}" }.gsub(/_+/, '_').downcase
-			CONFIGURATION.camelcase_name = CONFIGURATION.snakecase_name.split('_').map(&:capitalize).join
+		NOT_AVAILABLE = '(not available in paths)'.freeze
+		def self.list_variables
+			columnize_hash(Singer.configuration.members.map do |var|
+				[
+					var,
+					CONFIGURATION_VARIABLES_FORBIDDEN_IN_PATHS.include?(var.to_s) ? NOT_AVAILABLE : "__#{var.upcase}__",
+				]
+			end)
+		end
+
+		def self.columnize_hash(hash_or_array)
+			first_column_width = hash_or_array.map{ |k, _v| k.length }.max
+			hash_or_array.each do |k, v|
+				puts "#{k.to_s.ljust(first_column_width)} #{v}"
+			end
 		end
 	end
 end

data/lib/singer/paths.rb

@@ -21,12 +21,16 @@ module Singer
 			File.join(...).gsub(/__([[:alpha:]][[:word:]]+)__/) do |match|
 				potential_config = $1.downcase
 
-				if CONFIGURATION.respond_to?(potential_config)
-					CONFIGURATION.send(potential_config)
+				if variable_name_can_be_substituted?(potential_config)
+					Singer.configuration.send(potential_config)
 				else
 					match
 				end
 			end
 		end
+
+		def self.variable_name_can_be_substituted?(name)
+			Singer.configuration.respond_to?(name) && !CONFIGURATION_VARIABLES_FORBIDDEN_IN_PATHS.include?(name)
+		end
 	end
 end

data/lib/singer/template.rb

@@ -19,6 +19,11 @@ module Singer
 			end
 		end
 
+		def self.load_one_from_path(path)
+			Singer.configuration.template_name = File.basename(path)
+			all[Singer.configuration.template_name] = new(path)
+		end
+
 		attr_reader :path, :files
 
 		def initialize(path)
@@ -31,9 +36,12 @@ module Singer
 
 		def generate(output_path)
 			files.each do |file|
-				source_file = File.join(path, file)
+				Singer.configuration.template_file_name_original = file
 				target_file = Paths.output_path(output_path, file)
+				Singer.configuration.template_file_name_actual = target_file
+
 				FileUtils.mkdir_p(File.dirname(target_file))
+				source_file = File.join(path, file)
 				TemplatingMethods.send(:erb, source_file, target_file)
 			end
 		end

data/lib/singer/version.rb

@@ -1,3 +1,3 @@
 module Singer
-	VERSION = '1.0.0'.freeze
+	VERSION = '2.0.0'.freeze
 end

data/lib/singer.rb

@@ -1,5 +1,6 @@
 require_relative 'singer/version'
 require_relative 'singer/configuration'
+require_relative 'singer/name_transformation'
 require_relative 'singer/option_parsing'
 require_relative 'singer/paths'
 require_relative 'singer/template'
@@ -10,14 +11,34 @@ require 'optparse'
 # Singer, which generates Sinatra apps etc. from templates
 module Singer
 	class Error < StandardError; end
-	class NameMissingError < StandardError; end
-	class TemplateUnknown < StandardError; end
+	class NameMissingError < Error; end
+	class TemplateUnknown < Error; end
+	class ParameterValueUnsupported < Error; end
 
-	def self.generate
-		unless Template.all.key?(CONFIGURATION.template_name)
-			raise TemplateUnknown, "Template #{CONFIGURATION.template_name.inspect} not found"
-		end
+	def self.configure_and_generate(argvies)
+		Singer::OptionParsing.configure(argvies)
+		configure_project_name(argvies)
+		configure_template(argvies)
+		Singer.generate
+	end
+
+	def self.configure_project_name(argvies)
+		raise NameMissingError, 'Missing mandatory argument PROJECT_NAME' if argvies.empty?
+
+		NameTransformation.encase_name(argvies.pop)
+	end
 
-		Template.all[CONFIGURATION.template_name].generate('.')
+	DEFAULT_TEMPLATE_NAME = 'tdd'.freeze
+	def self.configure_template(argvies)
+		return if configuration.template_name # must have been set via --template-directory
+
+		configuration.template_name = argvies.pop || DEFAULT_TEMPLATE_NAME
+		return if Template.all.key?(configuration.template_name)
+
+		raise TemplateUnknown, "Template #{configuration.template_name.inspect} not found"
+	end
+
+	def self.generate
+		Template.all[configuration.template_name].generate('.')
 	end
 end

data/templates/sinatra_app/config/config.ru

@@ -1,3 +1,3 @@
 require_relative '../lib/zeitwerk_setup'
 
-run <%= Singer::CONFIGURATION.camelcase_name %>::Server
+run <%= Singer.configuration.project_name_camelcase %>::Server

data/templates/sinatra_app/exe/server.rb

@@ -1,3 +1,3 @@
 require 'zeitwerk_setup'
 
-<%= Singer::CONFIGURATION.camelcase_name %>::Server.run!
+<%= Singer.configuration.project_name_camelcase %>::Server.run!

data/templates/sinatra_app/lib/{__SNAKECASE_NAME__ → __PROJECT_NAME_SNAKECASE__}/hello.rb

@@ -1,4 +1,4 @@
-module <%= Singer::CONFIGURATION.camelcase_name %>
+module <%= Singer.configuration.project_name_camelcase %>
 	# demo class - TODO: remove
 	class Hello
 		def self.greet(target)

data/templates/sinatra_app/lib/{__SNAKECASE_NAME__ → __PROJECT_NAME_SNAKECASE__}/server.rb

@@ -3,7 +3,7 @@ require 'haml'
 require 'sassc'
 require 'colorize'
 
-module <%= Singer::CONFIGURATION.camelcase_name %>
+module <%= Singer.configuration.project_name_camelcase %>
 	# Sinatra app with routes
 	class Server < Sinatra::Base
 		set :root, '.' # to make directory structure with views/ work

data/templates/sinatra_app/test/server/test_server.rb

@@ -4,7 +4,7 @@ class TestServer < Minitest::Test
 	include Rack::Test::Methods
 
 	def app
-		<%= Singer::CONFIGURATION.camelcase_name %>::Server
+		<%= Singer.configuration.project_name_camelcase %>::Server
 	end
 
 	def test_top_level_redirects

data/templates/sinatra_app/test/server/test_server_error_dumping.rb

@@ -10,7 +10,7 @@ class TestServerErrorDumping < Minitest::Test
 			refute message.lines.any?{ _1.include?('/vendor/') } # now you don't
 		end
 
-		app = <%= Singer::CONFIGURATION.camelcase_name %>::Server.new! # .new! returns real instance without Sinatra::Wrapper
+		app = <%= Singer.configuration.project_name_camelcase %>::Server.new! # .new! returns real instance without Sinatra::Wrapper
 		app.dump_errors!(exc, log)
 	end
 

data/templates/sinatra_app/test/test_hello.rb

@@ -3,6 +3,6 @@ require 'minitest_helper'
 # TODO: remove
 class TestHello < Minitest::Test
 	def test_greet_with_a_param_generates_a_greeting_string
-		assert_equal 'Hello, stranger.', <%= Singer::CONFIGURATION.camelcase_name %>::Hello.greet(:stranger)
+		assert_equal 'Hello, stranger.', <%= Singer.configuration.project_name_camelcase %>::Hello.greet(:stranger)
 	end
 end

data/templates/sinatra_app/views/layout.haml

@@ -1,7 +1,7 @@
 !!!
 %html
 	%head
-		%title <%= Singer::CONFIGURATION.camelcase_name %>
+		%title <%= Singer.configuration.project_name_camelcase %>
 		%meta{charset: 'UTF-8'}
 		%style!= COMPILED_STYLE
 	%body!= yield

data/templates/tdd/lib/{__SNAKECASE_NAME__.rb → __PROJECT_NAME_SNAKECASE__.rb}

@@ -1,13 +1,13 @@
 require 'colorize'
 # require 'awesome_print'
 
-class <%= Singer::CONFIGURATION.camelcase_name %>
+class <%= Singer.configuration.project_name_camelcase %>
 	def hello(who:)
 		"Hello, #{who}."
 	end
 end
 
 if File.expand_path($PROGRAM_NAME) == File.expand_path(__FILE__)
-	ciastka = <%= Singer::CONFIGURATION.camelcase_name %>.new
+	ciastka = <%= Singer.configuration.project_name_camelcase %>.new
 	puts "Testing testing: #{ciastka.hello(who: :world).green}"
 end

data/templates/tdd/test/test___PROJECT_NAME_SNAKECASE__.rb

@@ -0,0 +1,16 @@
+require 'minitest/rg'
+require 'minitest/autorun' if File.expand_path($PROGRAM_NAME) == File.expand_path(__FILE__)
+
+require_relative '../lib/<%= Singer.configuration.project_name_snakecase %>'
+
+class Test<%= Singer.configuration.project_name_camelcase %> < Minitest::Test
+	# TEST_INPUT = File.read('input_mini.txt').lines(chomp: true)
+
+	def setup
+		@<%= Singer.configuration.project_name_snakecase %> = <%= Singer.configuration.project_name_camelcase %>.new
+	end
+
+	def test_hello_interpolates_into_string
+		assert_equal 'Hello, world.', @<%= Singer.configuration.project_name_snakecase %>.hello(who: :world)
+	end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: singer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Emil Chludziński
 bindir: exe
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: erb
@@ -38,6 +38,7 @@ files:
 - exe/singer
 - lib/singer.rb
 - lib/singer/configuration.rb
+- lib/singer/name_transformation.rb
 - lib/singer/option_parsing.rb
 - lib/singer/paths.rb
 - lib/singer/template.rb
@@ -48,8 +49,8 @@ files:
 - templates/sinatra_app/config/config.ru
 - templates/sinatra_app/config/puma.rb
 - templates/sinatra_app/exe/server.rb
-- templates/sinatra_app/lib/__SNAKECASE_NAME__/hello.rb
-- templates/sinatra_app/lib/__SNAKECASE_NAME__/server.rb
+- templates/sinatra_app/lib/__PROJECT_NAME_SNAKECASE__/hello.rb
+- templates/sinatra_app/lib/__PROJECT_NAME_SNAKECASE__/server.rb
 - templates/sinatra_app/lib/zeitwerk_setup.rb
 - templates/sinatra_app/test/minitest_helper.rb
 - templates/sinatra_app/test/server/test_server.rb
@@ -60,8 +61,8 @@ files:
 - templates/sinatra_app/views/layout.haml
 - templates/sinatra_app/views/style.sass
 - templates/tdd/Gemfile
-- templates/tdd/lib/__SNAKECASE_NAME__.rb
-- templates/tdd/test/test___SNAKECASE_NAME__.rb
+- templates/tdd/lib/__PROJECT_NAME_SNAKECASE__.rb
+- templates/tdd/test/test___PROJECT_NAME_SNAKECASE__.rb
 homepage: https://gitlab.com/tanstaafl/singer/
 licenses:
 - MIT
@@ -83,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Singer generates code (such as Sinatra apps) from templates.
 test_files: []

data/templates/tdd/test/test___SNAKECASE_NAME__.rb

@@ -1,16 +0,0 @@
-require 'minitest/rg'
-require 'minitest/autorun' if $PROGRAM_NAME == __FILE__
-
-require_relative '../lib/<%= Singer::CONFIGURATION.snakecase_name %>'
-
-class Test<%= Singer::CONFIGURATION.camelcase_name %> < Minitest::Test
-	# TEST_INPUT = File.read('input_mini.txt').lines(chomp: true)
-
-	def setup
-		@<%= Singer::CONFIGURATION.snakecase_name %> = <%= Singer::CONFIGURATION.camelcase_name %>.new
-	end
-
-	def test_hello_interpolates_into_string
-		assert_equal 'Hello, world.', @<%= Singer::CONFIGURATION.snakecase_name %>.hello(who: :world)
-	end
-end