indoctrinatr-tools 0.16.0 → 0.17.0

data/lib/indoctrinatr/tools/commands/workflow.rb

@@ -0,0 +1,38 @@
+module Indoctrinatr
+  module Tools
+    module Commands
+      class Workflow < Dry::CLI::Command
+        desc 'Display the suggested workflow.'
+
+        def call(**)
+          puts <<~HEREDOC
+            The workflow for a project (e.g. demo) typically looks like this:
+
+            1. Run in shell: indoctrinatr new demo
+               Creates a new Indoctrinatr Template Pack in the folder demo
+
+            2. Edit demo.tex.erb and configuration.yaml according to needs
+
+            3. Run in shell: indoctrinatr parse demo
+               Parses tex file demo_with_default_values.tex with ERB and default values from configuration.yaml
+
+            4. Run in shell: indoctrinatr pdf demo
+               Compiles PDF from demo_with_default_values.tex
+
+            5. Run in shell: indoctrinatr pdf_with_field_names demo
+               Compiles PDF from demo_with_fieldname_values.tex
+
+            6. Run in shell: indoctrinatr check demo
+               Analyzes your Template Pack for potential errors
+
+            7. Run in shell: indoctrinatr doc demo
+               Creates a technical documentation for the Template Pack
+
+            8. Run in shell: indoctrinatr pack demo
+               Creates demo.zip with all required file for upload to Indoctrinatr server
+          HEREDOC
+        end
+      end
+    end
+  end
+end

data/lib/indoctrinatr/tools/commands/zsh_completions.rb

@@ -0,0 +1,25 @@
+module Indoctrinatr
+  module Tools
+    module Commands
+      class ZshCompletions < Dry::CLI::Command
+        desc 'Print a guide how to add indoctrinatr-tools integration to .zshrc.'
+
+        def call(**)
+          puts <<~HEREDOC
+            Add this to your .zshrc (and open up a new shell):
+
+            if [[ -n ${ZSH_VERSION-} ]]; then
+              autoload -U +X bashcompinit && bashcompinit
+            fi
+            complete -F get_indoctrinatr_commands indoctrinatr
+            function get_indoctrinatr_commands()
+            {
+              local binary="indoctrinatr"
+              COMPREPLY=(`$binary completions`)
+            }
+          HEREDOC
+        end
+      end
+    end
+  end
+end

data/lib/indoctrinatr/tools/commands.rb

@@ -0,0 +1,21 @@
+module Indoctrinatr
+  module Tools
+    module Commands
+      extend Dry::CLI::Registry
+
+      register 'bashcompletion', BashCompletions
+      register 'check', Check
+      register 'commands', CompletionCommands
+      register 'demo', Demo
+      register 'doc', Doc
+      register 'new', Scaffold
+      register 'pack', Pack
+      register 'parse', Parse
+      register 'pdf', Pdf
+      register 'pdf_with_field_names', PdfWithFieldNames
+      register 'version', Version, aliases: %w[v -v --version]
+      register 'workflow', Workflow
+      register 'zshcompletion', ZshCompletions
+    end
+  end
+end

data/lib/indoctrinatr/tools/configuration_extractor.rb

@@ -1,26 +1,24 @@
-require 'indoctrinatr/tools/template_pack_configuration'
+require 'yaml'
 
 module Indoctrinatr
   module Tools
     class ConfigurationExtractor
-      include TemplatePackHelpers
-
       attr_reader :template_pack_name
 
-      def initialize template_pack_name
+      def initialize(template_pack_name)
         @template_pack_name = template_pack_name
       end
 
       def call
-        config_file = YAML.load_file config_file_path
-        configuration = TemplatePackConfiguration.new
-        configuration.template_asset_path = assets_path.to_s
-        configuration.default_file_name = "#{template_pack_name}_with_default_values.pdf"
-        configuration.output_file_name = config_file.fetch('output_file_name', "#{template_pack_name}_with_default_values.pdf")
-        configuration.template_name = config_file.fetch 'template_name'
-        configuration.textual_description = config_file.fetch('textual_description'), ''
-        configuration.attributes_as_hashes_in_array = config_file.fetch 'fields', []
-        configuration
+        config_file = YAML.load_file((Pathname.new(Dir.pwd).join template_pack_name).join('configuration.yaml'))
+        TemplatePackConfiguration.new.tap do |configuration|
+          configuration.template_asset_path = ((Pathname.new(Dir.pwd).join template_pack_name).join 'assets').to_s
+          configuration.default_file_name = "#{template_pack_name}_with_default_values.pdf"
+          configuration.output_file_name = config_file.fetch('output_file_name', "#{template_pack_name}_with_default_values.pdf")
+          configuration.template_name = config_file.fetch 'template_name'
+          configuration.textual_description = config_file.fetch('textual_description'), ''
+          configuration.attributes_as_hashes_in_array = config_file.fetch 'fields', []
+        end
       end
     end
   end

data/lib/indoctrinatr/tools/content_for_tex_files.rb

@@ -5,12 +5,12 @@ module Indoctrinatr
     class ContentForTexFiles
       # a class that DefaultValues, TemplateDocumentationContent, and field_names_as_variables should inherit from
       # or to be precise: When we want use variables in an indoctrinatr tex.erb file, we should use this class
-      def initialize configuration
+      def initialize(configuration)
         @_configuration = configuration
         _build_from_configuration
       end
 
-      def textile2latex textile
+      def textile2latex(textile)
         RedCloth.new(textile).to_latex
       end
 
@@ -19,7 +19,9 @@ module Indoctrinatr
       end
 
       def customized_output_file_name
-        @_customized_output_file_name ||= eval('"' + @_output_file_name + '"') # rubocop:disable Security/Eval, Naming/MemoizedInstanceVariableName
+        return @customized_output_file_name if defined? @customized_output_file_name
+
+        @customized_output_file_name = eval("\"#{@_output_file_name}\"", binding, __FILE__, __LINE__) # rubocop:disable Security/Eval
       end
 
       def template_asset_path

data/lib/indoctrinatr/tools/default_values.rb

@@ -1,5 +1,3 @@
-require 'indoctrinatr/tools/content_for_tex_files'
-
 module Indoctrinatr
   module Tools
     class DefaultValues < ContentForTexFiles
@@ -11,7 +9,7 @@ module Indoctrinatr
         @_default_file_name
       end
 
-      def _use_default_values # rubocop:disable Metrics/AbcSize
+      def _use_default_values
         @_configuration.attributes_as_hashes_in_array.each do |attribute_hash|
           instance_variable_set("@_#{attribute_hash['name']}", attribute_hash['default_value'])
 

data/lib/indoctrinatr/tools/field_name_values.rb

@@ -1,11 +1,9 @@
-require 'indoctrinatr/tools/content_for_tex_files'
-
 module Indoctrinatr
   module Tools
     # This class defines the content for a document that has the field names as content.
     class FieldNameValues < ContentForTexFiles
-      # TODO: extensive list of possibilities
       PICTURE_FILE_ENDINGS = %w[.png .jpeg .jpg .bmp .gif .pdf].freeze
+
       def _field_names_as_values # rubocop:disable Metrics/AbcSize
         @_configuration.attributes_as_hashes_in_array.each do |attribute_hash|
           # Usage of \textless to avoid issues with the < > characters.
@@ -29,7 +27,7 @@ module Indoctrinatr
 
       # The LaTeX compilation would fail if the \includegraphics tries to include a file that does not exist.
       # Because of that it makes sense to simply use the default values again if user sets file names.
-      def overwrite_picture_file_names_output attributes_as_hashes # rubocop:disable Metrics/AbcSize
+      def overwrite_picture_file_names_output(attributes_as_hashes) # rubocop:disable Metrics/AbcSize
         attributes_as_hashes.each do |attribute_hash|
           # search for typical picture file endings
           next unless detect_picture_file_names attribute_hash['default_value']
@@ -48,7 +46,7 @@ module Indoctrinatr
 
       # Indoctrinatr has no picture data type. This means that the only way to check for pictures is to check for
       # file endings. If an user has obscure file type the possibility list would have to get updated.
-      def detect_picture_file_names string_to_check
+      def detect_picture_file_names(string_to_check)
         PICTURE_FILE_ENDINGS.any? do |picture_file_ending|
           string_to_check.downcase.include? picture_file_ending # http://stackoverflow.com/a/3686568
         end

data/lib/indoctrinatr/tools/pdf_generator.rb

@@ -5,7 +5,7 @@ module Indoctrinatr
       # Compiles a PDF from a tex file with XeLaTeX
       # @param tex_file a Pathname that points to the tex file
       # @return false if error, nil if system command unknown
-      def make_pdf tex_file, output_dir = nil, cleanup = true
+      def make_pdf(tex_file, output_dir = nil, cleanup: true)
         args = ['-xelatex',
                 '-shell-escape',
                 '-interaction=batchmode', # more silent output
@@ -15,14 +15,14 @@ module Indoctrinatr
           args.delete_at 3 # Remove argument if no output dir is wished for. This probably could be done better.
         end
         latexmk_successful = system('latexmk', *args) # latexmk instead of running 2.times
-        latex_cleanup output_dir if latexmk_successful == true && cleanup
+        latex_cleanup output_dir if latexmk_successful && cleanup
         latexmk_successful
       end
 
       # Cleans up LaTeX helper files in a specific directory
       # @param working_directory a Pathname that points the directory that should get cleaned up
       # @return false if error, nil if system command unknown
-      def latex_cleanup working_directory
+      def latex_cleanup(working_directory)
         # latexmk -c apparently cannot cleanup a specified subdirectory. So we have to change the working directory,
         # run the cleanup command in it and then change back to the directory that we were in. http://tex.stackexchange.com/q/301366/17834
         current_dir = Dir.getwd

data/lib/{redcloth_latex_formatter_patch/patch.rb → indoctrinatr/tools/redcloth_formatters_latex_patch.rb}

@@ -1,13 +1,22 @@
 require 'redcloth'
 
-module RedCloth
-  module Formatters
-    module LATEX
+module Indoctrinatr
+  module Tools
+    module RedclothFormattersLatexPatch
+      def self.apply
+        const = Kernel.const_get('RedCloth::Formatters::LATEX')
+        const&.prepend(self)
+      rescue NameError => e
+        puts e
+      end
+
       {
         h1: 'chapter',
         h2: 'section',
         h3: 'subsection',
-        h4: 'subsubsection'
+        h4: 'subsubsection',
+        h5: 'subparagraph',
+        h6: 'textbf'
       }.each do |m, tag|
         define_method(m) do |opts|
           case opts[:align]
@@ -23,20 +32,9 @@ module RedCloth
         end
       end
 
-      def del opts
+      def del(opts)
         "\\st{#{opts[:text]}}"
       end
-
-      def table_close _opts
-        output = "\\begin{tabu}{ #{'l ' * @table[0].size}}\n"
-        output << "    #{@table[0].join(' & ')} \\\\\n"
-        output << "    \\tabletoprule\n"
-        @table[1..-1].each do |row|
-          output << "    #{row.join(' & ')} \\\\\n"
-        end
-        output << "    \\tablebottomrule\n\\end{tabu}\n"
-        output
-      end
     end
   end
 end

data/lib/indoctrinatr/tools/template_documentation_content.rb

@@ -1,20 +1,13 @@
-require 'indoctrinatr/tools/content_for_tex_files'
-require 'indoctrinatr/tools/template_pack_configuration'
-require 'indoctrinatr/tools/directory_helpers'
-require 'indoctrinatr/tools/template_documentation_source_file'
-require 'indoctrinatr/tools/default_values'
-
 module Indoctrinatr
   module Tools
     class TemplateDocumentationContent < ContentForTexFiles
-      include DirectoryHelpers
-      include TemplatePackHelpers
-
       attr_accessor :template_pack_name, :list_of_files
 
       # Overwrite the initialize method because the content is built up much more complex than for the other
       # ContentForTexFile children.
-      def initialize template_pack_name, configuration
+      def initialize(template_pack_name, configuration)
+        super(configuration)
+
         @configuration = configuration
         @template_pack_name = template_pack_name
         @list_of_files = print_dirtree_style @template_pack_name
@@ -29,6 +22,9 @@ module Indoctrinatr
 
       def read_template_files_content
         filenames = list_files_of_type template_pack_name
+        path_name = Pathname.new(Dir.pwd).join template_pack_name
+        pack_documentation_dir_path = path_name.join 'doc'
+        pack_documentation_examples_dir_path = pack_documentation_dir_path.join 'examples'
         filenames.reject! { |f| f.include?(pack_documentation_examples_dir_path.relative_path_from(Pathname.new(Dir.pwd)).to_s) }
         filenames.inject [] do |files, filename|
           files.push TemplateDocumentationSourceFile.new filename
@@ -36,27 +32,80 @@ module Indoctrinatr
       end
 
       def default_values_example
-        default_values_compiler = TemplatePackDefaultValuesCompiler.new(template_pack_name)
-        unless default_values_compiler.pdf_exists?
-          TemplatePackDefaultValuesParser.new(template_pack_name).call
-          default_values_compiler.call
+        Indoctrinatr::Tools::Transactions::TemplatePackDefaultValuesParser.new.call(@template_pack_name) do |result|
+          result.success do |message|
+            puts message
+            Indoctrinatr::Tools::Transactions::TemplatePackDefaultValuesCompiler.new.call(template_pack_name:, keep_aux_files: false) do |result2|
+              result2.success do |message2|
+                puts message2
+              end
+              result2.failure do |message2|
+                puts message2
+              end
+            end
+            pdf_with_default_values_file_path
+          end
+          result.failure do |message|
+            puts message
+          end
+        end
+      end
+
+      # get file path for PDF example with default values:
+      def pdf_with_default_values_file_path
+        path_name = Pathname.new(Dir.pwd).join template_pack_name
+        pack_documentation_dir_path = path_name.join 'doc'
+        pack_documentation_examples_dir_path = pack_documentation_dir_path.join 'examples'
+        default_values = DefaultValues.new @configuration
+        # if there is a change in where the pdf command (DefaultValuesCompiler) saves it's output, this logic needs to be updated
+        if default_values.customized_output_file_name == default_values.default_file_name
+          Pathname.new(Dir.pwd).join pack_documentation_examples_dir_path + default_values.customized_output_file_name
+        else
+          Pathname.new(Dir.pwd).join pack_documentation_examples_dir_path + eval("\"#{default_values.output_file_name}\"", binding, __FILE__, __LINE__) # rubocop:disable Security/Eval
+          # usage of eval to execute the interpolation of a custom filename string with interpolation - e.g. a filename with the current date
         end
-        pdf_with_default_values_file_path @configuration
       end
 
       def fieldname_values_example
-        fieldnames_creator = TemplatePackFieldnamesCreator.new(template_pack_name)
         # This gives user the option to customize the FieldNameValues Example that is appended in the documentation
-        return pdf_with_fieldname_values_file_path if fieldnames_creator.pdf_exists?
+        path_name = Pathname.new(Dir.pwd).join template_pack_name
+        fail 'Please specify a template pack name.' if template_pack_name.empty? # rubocop:disable Style/SignalException
+        fail "A folder with name '#{template_pack_name}' does not exist." unless Dir.exist? path_name.to_s # rubocop:disable Style/SignalException
 
-        if fieldnames_creator.call
-          puts 'INFO: Example with field names has been automatically generated for the documentation' # More user information and for testing
-          pdf_with_fieldname_values_file_path
-        else
-          puts 'ERROR: Example with field names could not be created and is not included in documentation'
-          nil
+        pack_documentation_dir_path = path_name.join 'doc'
+        pack_documentation_examples_dir_path = pack_documentation_dir_path.join 'examples'
+        pdf_with_fieldname_values_file_path = "#{pack_documentation_examples_dir_path.join template_pack_name}_with_fieldname_values.pdf"
+
+        return pdf_with_fieldname_values_file_path if File.exist? pdf_with_fieldname_values_file_path
+
+        Indoctrinatr::Tools::Transactions::TemplatePackFieldnamesCreator.new.call(template_pack_name:, keep_aux_files: false) do |result|
+          result.success do
+            puts 'INFO: Example with field names has been automatically generated for the documentation' # More user information and for testing
+            pdf_with_fieldname_values_file_path
+          end
+          result.failure do |message|
+            puts message
+            puts 'ERROR: Example with field names could not be created and is not included in documentation'
+            nil
+          end
         end
       end
+
+      # refractored from directory_helpers.rb author: Luka Lüdicke
+      def print_dirtree_style(directory = '.')
+        Dir.glob("#{directory}/**/*").inject [] do |entries, entry| # list entries recursively
+          nesting = entry.count(File::SEPARATOR) + 1 # nesting starts with 2, because for \dirtree 1 is root
+          name = entry.split(File::SEPARATOR).last
+          entries.push ".#{nesting} #{name}. " # formatting for \dirtree: .<level><space><text-node>.<space>
+        end
+      end
+
+      # refractored from directory_helpers.rb author: Luka Lüdicke
+      # default file types for template docs
+      def list_files_of_type(directory = '.', types = %w[erb rb yaml sty tex])
+        # found and modified from http://stackoverflow.com/a/3504307/1796645
+        Dir.glob("#{directory}/**/*.{#{types.join(',')}}") # recursively list files of type in types array
+      end
     end
   end
 end

data/lib/indoctrinatr/tools/template_documentation_source_file.rb

@@ -3,7 +3,7 @@ module Indoctrinatr
     class TemplateDocumentationSourceFile
       attr_reader :name, :content, :language
 
-      def initialize filename
+      def initialize(filename)
         @name = filename
         @content = File.read filename
         @language = set_programming_language
@@ -12,19 +12,14 @@ module Indoctrinatr
       private
 
       def set_programming_language
-        language =  case File.extname(@name)
-                    when '.tex'
-                      'TeX'
-                    when '.sty'
-                      'TeX'
-                    when '.erb' # .erb files are just supposed to be tex.erb files. TODO: more correct
-                      'TeX'
-                    when '.rb'
-                      'Ruby'
-                    else # probably YAML
-                      'unspecified'
-                    end
-        language
+        case File.extname(@name)
+        when '.tex', '.sty', '.erb'
+          'TeX'
+        when '.rb'
+          'Ruby'
+        else # probably YAML
+          'unspecified'
+        end
       end
     end
   end

data/lib/indoctrinatr/tools/transactions/template_pack_default_values_compiler.rb

@@ -0,0 +1,67 @@
+require 'dry/transaction'
+require 'fileutils'
+
+module Indoctrinatr
+  module Tools
+    module Transactions
+      class TemplatePackDefaultValuesCompiler
+        include PdfGenerator
+        include Dry::Transaction
+
+        step :setup
+        step :check_setup
+        step :compile_tex_file
+        step :rename_if_necessary
+
+        private
+
+        def setup(template_pack_name:, keep_aux_files:)
+          path_name = Pathname.new(Dir.pwd).join template_pack_name
+          pack_documentation_dir_path = path_name.join 'doc'
+          pack_documentation_examples_dir_path = pack_documentation_dir_path.join('examples')
+          tex_with_default_values_file_path = pack_documentation_examples_dir_path.join("#{template_pack_name}_with_default_values.tex")
+          Success(
+            {
+              template_pack_name:,
+              path_name:,
+              keep_aux_files:,
+              pack_documentation_examples_dir_path:,
+              tex_with_default_values_file_path:
+            }
+          )
+        rescue StandardError => e
+          Failure(e.message)
+        end
+
+        def check_setup(config)
+          return Failure('Please specify a template pack name.') if config[:template_pack_name].empty?
+          return Failure("A folder with name '#{config[:template_pack_name]}' does not exist.") unless Dir.exist? config[:path_name] # rub
+
+          Success(config)
+        rescue StandardError => e
+          Failure(e.message)
+        end
+
+        def compile_tex_file(config)
+          make_pdf config[:tex_with_default_values_file_path], config[:pack_documentation_examples_dir_path], cleanup: !config[:keep_aux_files]
+          Success(config)
+        rescue StandardError => e
+          Failure(e.message)
+        end
+
+        def rename_if_necessary(config) # rubocop:disable Metrics/AbcSize
+          configuration = ConfigurationExtractor.new(config[:template_pack_name]).call # TODO: avoid repeated calling of the ConfigurationExtrator
+          @default_values = DefaultValues.new configuration
+          return Success("The pdf has successfully been created as '#{configuration.output_file_name}.") if @default_values.customized_output_file_name == @default_values.default_file_name
+
+          custom_filepath = config[:pack_documentation_examples_dir_path] + @default_values.customized_output_file_name
+          ::FileUtils.rm_f custom_filepath
+          ::FileUtils.mv(config[:pack_documentation_examples_dir_path] + @default_values.default_file_name, custom_filepath)
+          Success("A pdf has successfully been created at '#{custom_filepath}.")
+        rescue StandardError => e
+          Failure(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/indoctrinatr/tools/transactions/template_pack_default_values_parser.rb

@@ -0,0 +1,82 @@
+require 'dry/transaction'
+require 'erubis'
+require 'to_latex'
+require 'fileutils'
+
+module Indoctrinatr
+  module Tools
+    module Transactions
+      class TemplatePackDefaultValuesParser
+        include Dry::Transaction
+
+        step :setup
+        step :check_setup
+        step :read_config_file
+        step :read_tex_file
+        step :parse_tex_file
+        step :write_tex_file
+
+        private
+
+        def setup(template_pack_name)
+          path_name = Pathname.new(Dir.pwd).join template_pack_name
+          pack_documentation_dir_path = path_name.join 'doc'
+          pack_documentation_examples_dir_path = pack_documentation_dir_path.join('examples')
+          tex_with_default_values_file_path = pack_documentation_examples_dir_path.join("#{template_pack_name}_with_default_values.tex")
+          Success(
+            {
+              template_pack_name:,
+              path_name:,
+              pack_documentation_dir_path:,
+              pack_documentation_examples_dir_path:,
+              tex_with_default_values_file_path:
+            }
+          )
+        end
+
+        def check_setup(config)
+          return Failure('Please specify a template pack name.') if config[:template_pack_name].empty?
+          return Failure("A folder with name '#{config[:template_pack_name]}' does not exist.") unless Dir.exist? config[:path_name] # rub
+
+          Success(config)
+        end
+
+        def read_config_file(config)
+          configuration = ConfigurationExtractor.new(config[:template_pack_name]).call
+          default_values = DefaultValues.new configuration
+          default_values._use_default_values
+          config[:default_values] = default_values
+          Success(config)
+        rescue StandardError => e
+          Failure(e.message)
+        end
+
+        def read_tex_file(config)
+          tex_file_path = config[:path_name].join("#{config[:template_pack_name]}.tex.erb")
+          config[:tex_file_content] = File.read tex_file_path
+          Success(config)
+        rescue StandardError => e
+          Failure(e.message)
+        end
+
+        def parse_tex_file(config)
+          config[:parsed_tex_file_content] = Erubis::Eruby.new(config[:tex_file_content]).result(config[:default_values].retrieve_binding)
+          Success(config)
+        rescue StandardError => e
+          Failure(e.message)
+        end
+
+        def write_tex_file(config)
+          # Create directory to avoid file creation errors
+          ::FileUtils.mkdir_p(config[:pack_documentation_dir_path])
+          ::FileUtils.mkdir_p(config[:pack_documentation_examples_dir_path])
+          File.write config[:tex_with_default_values_file_path], config[:parsed_tex_file_content]
+
+          Success("The template pack '#{config[:template_pack_name]}' has been successfully parsed with default values.")
+        rescue StandardError => e
+          Failure(e.message)
+        end
+      end
+    end
+  end
+end