pragmater 7.1.0 → 8.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f520d4523de27f6ff372f701a852edcd1cd98227c1c86baa5eb3377290be461
-  data.tar.gz: '08e91032f9bb0515d06da796305caf512f248e8488dd7e71f895cd1cc6e6f0c5'
+  metadata.gz: 1d774cddf775dd01454ae0c4e330a26fe1839dbc1425faf320fb48b47c2839e8
+  data.tar.gz: c00d6e9b8697af0dbd01aa4431d73e67506b51a0cdffaa9c60162f2758ca17a9
 SHA512:
-  metadata.gz: ca422a74af731888d2c06c4b7772e1ce09ccf5e9b1e41c22590796f15faea84ba57d296de218ece4627eeb0f636ff592bee4cfa9c2288c48c353fe8513b519c9
-  data.tar.gz: 98b0e252098ac3b158e6abdadb982dd43aed0dbb0763b51adea6b1d6b165279e5ffdaa4feab781dad9045e6be69add27bdb5cad45db27d41ee9e08fc7c536dfe
+  metadata.gz: 97810ad84783a1bab7b7023af8a21778eb5e1a2fff5e956ecf6fa6dd5372df0afc4a6e649bc556a9808bc12ceabf6d68d9dc0d1297e60323c15a69ceabfdd8bf
+  data.tar.gz: 7e1131fddee6223d489df2a8a6eeb02d05269fdf8a584bc74749065619e6b644b699d589895d9fdc7f63f71ef0fc20b944874740d537265a0e90263bc3ef7035

data/LICENSE.adoc

@@ -150,7 +150,7 @@ additional liability.
 
 END OF TERMS AND CONDITIONS
 
-Copyright link:https://www.alchemists.io[Alchemists].
+Copyright 2015 link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
 compliance with the License. You may obtain a link:https://www.apache.org/licenses/LICENSE-2.0[copy]

data/README.adoc

@@ -6,6 +6,8 @@
 
 [link=http://badge.fury.io/rb/pragmater]
 image::https://badge.fury.io/rb/pragmater.svg[Gem Version]
+[link=https://www.alchemists.io/projects/code_quality]
+image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
 [link=https://circleci.com/gh/bkuhlmann/pragmater]
 image::https://circleci.com/gh/bkuhlmann/pragmater.svg?style=svg[Circle CI Status]
 
@@ -21,14 +23,14 @@ Examples:
 ----
 
 With https://www.ruby-lang.org/en/news/2015/12/25/ruby-2-3-0-released[Ruby 2.3.0], frozen strings
-are supported via a pragma. This gem provides an easy way to add pragmas to single or multiple Ruby
-source files in order to benefit from improved memory and concurrency performance.
+are supported via a pragma. This gem provides an easy way to insert or remove pragmas to single or
+multiple Ruby source files in order to benefit from improved memory and concurrency performance.
 
 toc::[]
 
 == Features
 
-* Supports adding a pragma or multiple pragmas to single or multiple source files.
+* Supports inserting a pragma or multiple pragmas to single or multiple source files.
 * Supports removing pragma(s) from single or multiple source files.
 * Supports file list filtering. Defaults to any file.
 * Ensures duplicate pragmas never exist.
@@ -36,17 +38,15 @@ toc::[]
 
 == Screencasts
 
-[link=https://www.alchemists.io/screencasts/pragmater.html]
-image::https://www.alchemists.io/images/screencasts/pragmater/cover-original.png[Screencast,role=focal_point]
+[link=https://www.alchemists.io/screencasts/pragmater]
+image::https://www.alchemists.io/images/screencasts/pragmater/cover.svg[Screencast,600,240,role=focal_point]
 
 == Requirements
 
-. https://www.ruby-lang.org[Ruby 2.7.x]
+. https://www.ruby-lang.org[Ruby]
 
 == Setup
 
-=== Production
-
 To install, run:
 
 [source,bash]
@@ -54,56 +54,44 @@ To install, run:
 gem install pragmater
 ----
 
-=== Development
-
-To contribute, run:
-
-[source,bash]
-----
-git clone https://github.com/bkuhlmann/pragmater.git
-cd pragmater
-bin/setup
-----
-
-You can also use the IRB console for direct access to all objects:
-
-[source,bash]
-----
-bin/console
-----
-
 == Usage
 
 === Command Line Interface (CLI)
 
-From the command line, type: `+pragmater help+`
+From the command line, type: `pragmater --help`
 
 ....
-pragmater -a, [--add=PATH]      # Add comments to source file(s).
-pragmater -c, [--config]        # Manage gem configuration.
-pragmater -h, [--help=COMMAND]  # Show this message or get help for a command.
-pragmater -r, [--remove=PATH]   # Remove comments from source file(s).
-pragmater -v, [--version]       # Show gem version.
-....
+Pragmater - A command line interface for managing/formatting source file pragma comments.
 
-Both the `+--add+` and `+--remove+` commands support options for specifying pragmas and/or included
-files (viewable by running `+pragmater --help --add+` or `+pragmater --help --remove+`):
+USAGE:
+  -v, --version                            Show gem version.
+  -h, --help                               Show this message.
+  -c, --config [options]                   Manage gem configuration.
+  -i, --insert [PATH]                      Insert pragam comments into files.
+  -r, --remove [options]                   Remove pragam comments from files.
 
-....
--c, [--comments=one two three]  # Define desired comments
--i, [--includes=one two three]  # Include specific files and/or directories
+OPTIONS:
+
+Insert/Remove:
+      --comments a,b,c                     Add pragma comments.
+      --includes a,b,c                     Add console support.
+
+Configuration:
+      --edit                               Edit configuration.
+      --info                               Print configuration.
 ....
 
-Example (same options could be used for the `+--remove+` command too):
+Both the `--insert` and `--remove` commands support the same options for specifying pragmas and/or
+included files. Example:
 
 [source,bash]
 ----
-pragmater --add --comments "# frozen_string_literal: true" --includes "Gemfile" "Guardfile" "Rakefile" ".gemspec" "config.ru" "bin/**/*" "**/*.rake" "**/*.rb"
+pragmater --insert --comments "# frozen_string_literal: true" --includes "Gemfile" "Guardfile" "Rakefile" ".gemspec" "config.ru" "bin/**/*" "**/*.rake" "**/*.rb"
 ----
 
-The `--add` and `--remove` commands default to the current working directory so a path isn’t
-necessary unless you want to run Pragmater on a directory structure _other than_ your current
-working directory.
+The `--insert` and `--remove` commands default to the current working directory so a path isn’t
+necessary unless you want to run Pragmater in a directory structure other than your current working
+directory.
 
 === Customization
 
@@ -116,7 +104,7 @@ The default configuration is as follows:
 
 [source,yaml]
 ----
-:add:
+:insert:
   :comments: []
   :includes: []
 :remove:
@@ -124,15 +112,14 @@ The default configuration is as follows:
   :includes: []
 ----
 
-Feel free to take this default configuration, modify, and save as your own custom
-`configuration.yml`.
+Feel free to take the above configuration, modify, and save as your own custom `configuration.yml`.
 
 The `configuration.yml` file can be configured as follows:
 
-* `add`: Defines global/local comments and/or file include lists when adding pragmas. The `comments`
-  and `includes` options can be either a single string or an array.
+* `insert`: Defines global/local comments and/or file include lists when inserting pragmas. The
+  `comments` and `includes` options can be either a single string or an array of strings.
 * `remove`: Defines global/local comments and/or file include lists when removing pragmas. The
-  `comments` and `includes` options can be either a single string or an array.
+  `comments` and `includes` options can be either a single string or an array of strings.
 
 === Available Pragmas
 
@@ -256,20 +243,46 @@ immutable = -"test"
 mutable = +"test"
 ----
 
-Despite Ruby allowing you to do this, it is _not recommended_ to use the above examples as it leads
-to hard to read code. Instead use the following:
+💡 The use of `+String#-@+`, specifically, was http://bit.ly/2DGAjgG[enhanced in Ruby 2.5.0] to
+_deduplicate_ all instances of the same string thus reducing your memory footprint. This can be
+valuable in situations where you are not using the frozen string comment and need to selectively
+freeze strings.
+
+=== Consistency
+
+As an added bonus, this gem ensures pragmas for all analyzed files are formatted in a consistent
+style. This means there is always a space after the octothorpe (`#`). Here are multiple pragmas
+presented together for a visual comparison:
 
 [source,ruby]
 ----
-immutable = "test".freeze
-mutable = "test"
+#! /usr/bin/env ruby
+# encoding: UTF-8
+# coding: UTF-8
+# frozen_string_literal: true
+# warn_indent: true
 ----
 
-While this requires extra typing, it expresses intent more clearly. There is a slight caveat to this
-rule in which the use of `+String#-@+` was http://bit.ly/2DGAjgG[enhanced in Ruby 2.5.0] to
-_deduplicate_ all instances of the same string thus reducing your memory footprint. This can be
-valuable in situations where you are not using the frozen string comment and need to selectively
-freeze strings.
+One oddity to the above is the use of `# !/usr/bin/env ruby` is not allowed but `#! /usr/bin/env
+ruby` is which is why spacing is slightly different for shell pragmas.
+
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/pragmater.git
+cd pragmater
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
 
 == Tests
 
@@ -307,4 +320,4 @@ Read link:CHANGES.adoc[CHANGES] for details.
 
 == Credits
 
-Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann.html[Brooke Kuhlmann].
+Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/bin/pragmater

@@ -1,9 +1,10 @@
 #! /usr/bin/env ruby
 # frozen_string_literal: true
 
+# TODO: Remove once the Pattern Matching feature is fully supported.
+Warning[:experimental] = false
+
 require "pragmater"
-require "pragmater/cli"
-require "pragmater/identity"
 
 Process.setproctitle Pragmater::Identity::VERSION_LABEL
-Pragmater::CLI.start
+Pragmater::CLI::Shell.new.call ARGV

data/lib/pragmater.rb

@@ -1,8 +1,20 @@
 # frozen_string_literal: true
 
 require "pragmater/identity"
-require "pragmater/formatter"
-require "pragmater/commenter"
-require "pragmater/writer"
+require "pragmater/formatters/general"
+require "pragmater/formatters/shebang"
+require "pragmater/formatters/main"
+require "pragmater/parsers/comments"
+require "pragmater/parsers/file"
+require "pragmater/processors/inserter"
+require "pragmater/processors/remover"
+require "pragmater/processors/handler"
+require "pragmater/context"
 require "pragmater/runner"
-require "pragmater/cli"
+require "pragmater/cli/options/configuration"
+require "pragmater/cli/options/insert_remove"
+require "pragmater/cli/options/core"
+require "pragmater/cli/options/assembler"
+require "pragmater/cli/options/merger"
+require "pragmater/cli/helper"
+require "pragmater/cli/shell"

data/lib/pragmater/cli/helper.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "open3"
+require "logger"
+
+module Pragmater
+  module CLI
+    # A simple delegator for common shell functionality.
+    class Helper
+      extend Forwardable
+
+      LOGGER = Logger.new STDOUT,
+                          formatter: (
+                            proc do |_severity, _datetime, _program_name, message|
+                              "#{message}\n"
+                            end
+                          )
+
+      delegate %i[info error fatal debug unknown] => :logger
+
+      def initialize commander: Open3, logger: LOGGER
+        @commander = commander
+        @logger = logger
+      end
+
+      def run command
+        commander.capture3 command
+      end
+
+      def warn message
+        logger.warn message
+      end
+
+      private
+
+      attr_reader :commander, :logger
+    end
+  end
+end

data/lib/pragmater/cli/options/assembler.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "forwardable"
+
+module Pragmater
+  module CLI
+    module Options
+      # Coalesces all options and arguments into a single hash for further processing.
+      class Assembler
+        extend Forwardable
+
+        PARSER = OptionParser.new nil, 40, "  "
+        SECTIONS = [Core, InsertRemove, Configuration].freeze
+
+        EXCEPTIONS = [
+          OptionParser::InvalidOption,
+          OptionParser::MissingArgument,
+          OptionParser::InvalidArgument
+        ].freeze
+
+        delegate %i[to_s] => :parser
+
+        def initialize sections: SECTIONS, parser: PARSER, exceptions: EXCEPTIONS
+          @sections = sections
+          @parser = parser
+          @options = {}
+          @exceptions = exceptions
+        end
+
+        def call arguments = []
+          sections.each { |section| section.new(options, parser: parser).call }
+          parser.parse! arguments
+          options
+        rescue *EXCEPTIONS
+          {}
+        end
+
+        private
+
+        attr_reader :parser, :sections, :options, :exceptions
+      end
+    end
+  end
+end

data/lib/pragmater/cli/options/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pragmater
+  module CLI
+    module Options
+      # Defines gem configuration options.
+      class Configuration
+        def initialize values, parser: OptionParser.new
+          @parser = parser
+          @values = values
+        end
+
+        def call
+          parser.separator "\nConfiguration:\n"
+          private_methods.grep(/add_/).each { |method| __send__ method }
+          parser
+        end
+
+        private
+
+        attr_reader :parser, :values
+
+        def add_edit
+          parser.on "--edit", "Edit configuration." do
+            values[:edit] = true
+          end
+        end
+
+        def add_info
+          parser.on "--info", "Print configuration." do
+            values[:info] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pragmater/cli/options/core.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Pragmater
+  module CLI
+    module Options
+      # Defines gem primary options.
+      class Core
+        def initialize values, parser: OptionParser.new
+          @values = values
+          @parser = parser
+        end
+
+        def call
+          parser.banner = "#{Identity::LABEL} - #{Identity::SUMMARY}"
+          parser.separator "\nUSAGE:\n"
+          private_methods.grep(/add_/).each { |method| __send__ method }
+          parser
+        end
+
+        private
+
+        attr_reader :values, :parser
+
+        def add_configuration
+          parser.on "-c", "--config [options]", "Manage gem configuration." do
+            values[:config] = true
+          end
+        end
+
+        def add_insert
+          parser.on "-i", "--insert [PATH]", "Insert pragam comments into files." do |path|
+            values[:insert] = path || "."
+          end
+        end
+
+        def add_remove
+          parser.on "-r", "--remove [options]", "Remove pragam comments from files." do |path|
+            values[:remove] = path || "."
+          end
+        end
+
+        def add_version
+          parser.on "-v", "--version", "Show gem version." do
+            values[:version] = Identity::VERSION
+          end
+        end
+
+        def add_help
+          parser.on "-h", "--help", "Show this message." do
+            values[:help] = true
+          end
+        end
+      end
+    end
+  end
+end