singer 0.4.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23ff6172f3189c234f2b95c1aaee2a67e5b91ffd10c88375c54e37cb4417abb5
-  data.tar.gz: 037ff1bd0e545efd4156ad9ff84cb2934070f0e704e05156acbff1fd7d787cfb
+  metadata.gz: cd871af4e10b86d0362c5bef72223344e86d5f81cb6a2871e901ec588f2d97b8
+  data.tar.gz: 5bbab829554eee4d7da41e43f07fec57784269906da6a7f866a466a73f1a9e92
 SHA512:
-  metadata.gz: 494f03f90b0584d1c0ba3ae4b72454151e8379591082e51fa61cbaae3ad65c50b91463ef52ba56208a7ef6f63d6c8b75f4c4f3c99430a9b367284e337f77cf59
-  data.tar.gz: 55646990590d66996705547ed95ff21b21a6a19609db53231c6f416d91fc37d84f0d1fc1c12189b932ade10a479ebef2f619cd5e1a0c8d3b07eb8a1f58f89d4a
+  metadata.gz: ba2fecb7f5b4a230e5eb26d7e8fef5566e1753fec82952b431779b7720fc3c525beb26a9e9e977c2d328648b11531e1bc4e760c1edbde219f1f025abb0be72d9
+  data.tar.gz: 3f121f9b2383ef48b822e1dac292e5a9f8455ded6cb9816b4fcd79b8139e64d46709c5fd2f9473cb200a1f8fc4808586e16bcfad574d91c86c8892bb67aba96a

data/README.md

@@ -8,7 +8,51 @@ Run `gem install singer`.
 
 ## Usage
 
-TODO: Write usage instructions here
+```bash
+singer [OPTION]... [TEMPLATE_NAME] PROJECT_NAME
+```
+
+Run `singer --help` to see up-to-date list of options.
+Run `singer --list-templates` to see available templates' names, both shipped with the gem and found on current system.
+
+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`.
+
+### 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
 

data/exe/singer

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

data/lib/singer/configuration.rb

@@ -1,4 +1,9 @@
 module Singer
 	# holds settings
-	CONFIGURATION = Struct.new(:template_name, :camelcase_name, :snakecase_name).new
+	CONFIGURATION = Struct.new(
+		:template_name,
+		:project_name_original, :project_name_camelcase, :project_name_snakecase,
+		:template_file_name_original, :template_file_name_actual,
+	).new
+	CONFIGURATION_VARIABLES_FORBIDDEN_IN_PATHS = %w[template_file_name_actual].freeze
 end

data/lib/singer/option_parsing.rb

@@ -0,0 +1,61 @@
+module Singer
+	# extracts what we need from ARGV
+	class OptionParsing
+		DEFAULT_TEMPLATE_NAME = 'tdd'.freeze
+
+		def self.configure(argvies) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+			options = {}
+			OptionParser.new do |parser|
+				parser.banner = <<~USAGE
+					Usage: #{$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
+				parser.on('--show-paths', 'show paths used to load files') do
+					show_paths
+					Kernel.exit
+				end
+				parser.on('--list-variables', 'list all variables available to templates') do
+					list_variables
+					Kernel.exit
+				end
+			end.parse!(argvies, into: options)
+
+			raise NameMissingError, 'Missing mandatory argument PROJECT_NAME' if argvies.empty?
+
+			encase_name(argvies.pop)
+			CONFIGURATION.template_name = argvies.shift || DEFAULT_TEMPLATE_NAME
+		end
+
+		def self.list_all_templates
+			columnize_hash(Template.all.transform_values(&:path))
+		end
+
+		def self.show_paths
+			columnize_hash(%w[singer_config_dir templates_from_user templates_from_gem].to_h{ [_1, Paths.send(_1)] })
+		end
+
+		def self.columnize_hash(hash)
+			first_column_width = hash.keys.map(&:length).max
+			hash.each do |k, v|
+				puts "#{k.to_s.ljust(first_column_width)} #{v}"
+			end
+		end
+
+		def self.list_variables
+			puts CONFIGURATION.members
+		end
+
+		def self.encase_name(name)
+			CONFIGURATION.project_name_original = name
+			CONFIGURATION.project_name_snakecase = name.gsub(/(\w)([A-Z])/){ "#{$1}_#{$2}" }.gsub(/_+/, '_').downcase
+			CONFIGURATION.project_name_camelcase = CONFIGURATION.project_name_snakecase.split('_').map(&:capitalize).join
+		end
+	end
+end

data/lib/singer/paths.rb

@@ -1,6 +1,18 @@
 module Singer
 	# helps find files
 	class Paths
+		def self.xdg_config_dir
+			@xdg_config_dir ||= ENV.fetch('XDG_CONFIG_DIR', File.join(Dir.home, '.config'))
+		end
+
+		def self.singer_config_dir
+			@singer_config_dir ||= File.join(xdg_config_dir, 'singer')
+		end
+
+		def self.templates_from_user
+			@templates_from_user ||= File.join(singer_config_dir, 'templates')
+		end
+
 		def self.templates_from_gem
 			@templates_from_gem ||= File.expand_path('../../templates', __dir__)
 		end
@@ -9,12 +21,16 @@ module Singer
 			File.join(...).gsub(/__([[:alpha:]][[:word:]]+)__/) do |match|
 				potential_config = $1.downcase
 
-				if CONFIGURATION.respond_to?(potential_config)
+				if variable_name_can_be_substituted?(potential_config)
 					CONFIGURATION.send(potential_config)
 				else
 					match
 				end
 			end
 		end
+
+		def self.variable_name_can_be_substituted?(name)
+			CONFIGURATION.respond_to?(name) && !CONFIGURATION_VARIABLES_FORBIDDEN_IN_PATHS.include?(name)
+		end
 	end
 end

data/lib/singer/template.rb

@@ -8,7 +8,13 @@ module Singer
 		end
 
 		def self.load_all
-			Dir[File.join(Paths.templates_from_gem, '*')].to_h do |template_dir|
+			[Paths.templates_from_gem, Paths.templates_from_user]
+				.map{ load_from_directory(_1) }
+				.reduce(&:merge)
+		end
+
+		def self.load_from_directory(dir)
+			Dir[File.join(dir, '*')].to_h do |template_dir|
 				[File.basename(template_dir), new(template_dir)]
 			end
 		end
@@ -25,9 +31,12 @@ module Singer
 
 		def generate(output_path)
 			files.each do |file|
-				source_file = File.join(path, file)
+				CONFIGURATION.template_file_name_original = file
 				target_file = Paths.output_path(output_path, file)
+				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 = '0.4.0'.freeze
+	VERSION = '1.1.0'.freeze
 end

data/lib/singer.rb

@@ -1,29 +1,18 @@
 require_relative 'singer/version'
 require_relative 'singer/configuration'
+require_relative 'singer/option_parsing'
 require_relative 'singer/paths'
 require_relative 'singer/template'
 require_relative 'singer/templating_methods'
 
+require 'optparse'
+
 # Singer, which generates Sinatra apps etc. from templates
 module Singer
 	class Error < StandardError; end
 	class NameMissingError < StandardError; end
 	class TemplateUnknown < StandardError; end
 
-	DEFAULT_TEMPLATE_NAME = 'tdd'.freeze
-
-	def self.configure(argvies)
-		raise NameMissingError, 'Missing mandatory argument NAME' if argvies.empty?
-
-		encase_name(argvies.pop)
-		CONFIGURATION.template_name = argvies.shift || DEFAULT_TEMPLATE_NAME
-	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
-	end
-
 	def self.generate
 		unless Template.all.key?(CONFIGURATION.template_name)
 			raise TemplateUnknown, "Template #{CONFIGURATION.template_name.inspect} not found"

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 $PROGRAM_NAME == __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: 0.4.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Emil Chludziński
 bindir: exe
 cert_chain: []
-date: 2025-01-26 00:00:00.000000000 Z
+date: 2025-02-09 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/option_parsing.rb
 - lib/singer/paths.rb
 - lib/singer/template.rb
 - lib/singer/templating_methods.rb
@@ -47,8 +48,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
@@ -59,8 +60,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

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