resme 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b346f37deb079117dd466833d47d6b1f9d4b01e916c19c5b853652297fd3d67
-  data.tar.gz: 0dfceeaabf0074a619d9f67faf499882ad641128e918b995cb8eb0d7a3b6fde2
+  metadata.gz: 27d07b29ff7369747e8f43ad9cbdc29efe1023cca20de554f94c02fdc33c57f8
+  data.tar.gz: fc048d5417183cba079e387caa3c08d2540fb937a384aae05759622b91b82846
 SHA512:
-  metadata.gz: 2d7013a8e980341a3d3abdbb3d3f814df116b98915711257c8a79ca5b0cac1406ec4f158629c1190af332200667afffc1f8c8e88caa5f521bb63578a64416750
-  data.tar.gz: d57c6fd89c9acf4ead44af434ed4ccba9b0c0117e1e1a653f6e0ba15307d1572d384550efa606c529516c37f1c548e77524a292573c2830aba6391ff1e2490e2
+  metadata.gz: 77bab2cbc35e21bb7ce669100d6b0f66d4b9f60e496814b35aec3a1fb3346730bbfe0700d884cde697500a479007cbac61dc834dcd358b3b1ab4375e59ee60db
+  data.tar.gz: fa2c84c4358a0c86469f83f11cb8c361a8a90602ed58eadf8cf53701757d4525d1f27f27599fdf361af46a2fcce0243c2e014395375c84a82489834be5b56118

data/CHANGELOG.org

@@ -0,0 +1,19 @@
+#+TITLE: CHANGELOG
+#+AUTHOR: Adolfo Villafiorita
+
+* Version 1.5.0
+  - [user] New command =view= allows to view the template used
+    for generating a resume in a specific format
+  - [user] Check command is now based on ClassyHash
+  - [code] Various changes to the code
+
+* Version 1.4.0
+  - [user] New option =--skip= allows to skip some top-level sections.
+    You mileage might vary, as some formats might require the
+    information you are trying to skip
+  - [user] New command =generate= is now used to generate the Resume
+    in different formats.
+  - [user] New option =--erb= allows to specify a custom template for
+    generating the resume. Use it in conjunction with =view= (released
+    in version 1.5.0) to jump-start your layout.
+  

data/README.org

@@ -0,0 +1,272 @@
+#+TITLE: RESME - A Resume Generator
+#+AUTHOR: Adolfo Villafiorita
+#+DATE: <2020-07-14 Tue>
+#+STARTUP: showall
+
+Keep your resume in YAML and output it in various formats, including
+Org Mode, Markdown, JSON, and the Europass XML format.
+
+The rendering engine is based on ERB. This simplifies the creation of
+new output formats (and extending/modifying the YML structure to one's
+needs).
+
+** Installation
+   :PROPERTIES:
+   :CUSTOM_ID: installation
+   :END:
+
+Add this line to your application's Gemfile:
+
+#+BEGIN_SRC ruby
+      gem 'resme'
+#+END_SRC
+
+And then execute:
+
+#+BEGIN_EXAMPLE
+  $ bundle
+#+END_EXAMPLE
+
+Or install it yourself as:
+
+#+BEGIN_EXAMPLE
+  $ gem install resme
+#+END_EXAMPLE
+
+** Usage
+   :PROPERTIES:
+   :CUSTOM_ID: usage
+   :END:
+
+Start with:
+
+#+BEGIN_EXAMPLE
+  resme init
+#+END_EXAMPLE
+
+which generates a YML template for your resume in the current directory.
+Comments in the YML file should help you fill the various entries.
+Notice that most entries are optional and you can remove sections which
+are not relevant for your resume.
+
+You can now generate a resume using one of the existing formats:
+
+#+begin_example
+  resme --to org resume.yml
+#+end_example
+
+Supported formats include:
+
+- =org=: Org Mode format
+- =md=: Markdown format
+- =europass=: Europass format
+  (http://interop.europass.cedefop.europa.eu/web-services/remote-upload/)
+- =json=: JSON format (https://jsonresume.org/)
+
+If you are not satisfied with the provided templates, you can write
+your own (see below).
+
+Notice that you can specify more than one YML file in input. This allows you to
+store data about your resume in different files, if you like to do so
+(e.g., work experiences could be in one file and talks in another).
+The YML files are merged before processing them.
+
+Full syntax:
+
+#+begin_src shell :results raw output :wrap example
+resme help
+#+end_src
+
+#+RESULTS:
+#+begin_example
+resme command [options] [args]
+Available commands:
+  view --template FORMAT # Print template used for format
+  console # enter the console
+  man # print resme manual page
+  help [command] # print command usage
+  init [options] # generate an empty resume.yml file
+  check resume.yml # Check syntax of resume.yml
+  list resume.yml # List main sections in resume.yml
+  version # print version information
+  generate [options] resume.yml ... # output resume
+#+end_example
+
+** Checking validity
+   :PROPERTIES:
+   :CUSTOM_ID: checking-validity
+   :END:
+
+Use the =check= command to verify whether your YAML file conforms with
+the intended syntax.
+
+#+BEGIN_SRC ruby
+  resme check resume.yaml
+#+END_SRC
+
+** Dates in the resume
+   :PROPERTIES:
+   :CUSTOM_ID: dates-in-the-resume
+   :END:
+
+Enter dates in the resume in one of the following formats:
+
+- Any format accepted by Ruby for a full date (year, month, day)
+- YYYY-MM-DD
+- YYYY-MM
+- YYYY
+
+The third and the forth format allows you to enter "partial" dates
+(e.g., when the month or the day have been forgotten or are irrelevant).
+
+** Creating your own templates
+   :PROPERTIES:
+   :CUSTOM_ID: creating-your-own-templates
+   :END:
+
+The resumes are generated from the YML matter using ERB templates. The
+provided output formats should support different back ends.  Org Mode
+and Markdown, for instance, easily allow for generation of PDFs, HTML,
+and ODT, to mention a few.
+
+However, if you want, you can define your own templates.
+
+Use the command =view= to print one of the templates used by =resme=
+and build from that.
+
+#+begin_example
+resme view --template md
+#+end_example
+
+Notice that all the data in the resume is made available in the =data=
+variable.  Thus, for instance, the following code snippets generates a
+list of all the work experiences:
+
+#+BEGIN_EXAMPLE
+  <% data["work"] each do |exp| %>
+  - <%= exp["who"] %>
+    From: <%=  exp["from"] %> till: <%= exp["till"] %>
+  <% end %>
+#+END_EXAMPLE
+
+To specify your own ERB template to build your resume use the option
+=-e= (=--erb=). Thus, for instance:
+
+#+BEGIN_EXAMPLE
+  $ resme render -e template.md.erb [-o output_filename] file.yaml ...
+#+END_EXAMPLE
+
+uses =template.md.erb= to generate the resume.
+
+Some functions can be used in the templates to better control the
+output.
+
+String manipulation functions:
+
+- =clean string= removes any space at the beginning of =string=
+- =reflow string, n= makes =string= into an array of strings of length
+  lower or equal to =n= (useful if you are outputting a textual format,
+  for instance.
+
+Dates manipulation functions:
+
+- =period= generates a string recapping a period. The function abstracts
+  different syntax you can use for entries (i.e., =date= or =from= and
+  =till=) and different values for the entries (e.g., a missing value
+  for =till=)
+- =year string=, =month string=, =day string= return, respectively the
+  year, month and day from strings in the format =YYYY-MM-DD=s
+- =has_month input= returns true if =input= has a month, that is, it is
+  a date or it is in the form =YYYY-MM=
+- =has_day input= returns true if =input= has a day, that is, it is a
+  date or it is in the form =YYYY-MM-DD=
+
+You can find the templates in =lib/resme/templates=. These might be good
+starting points if you want to develop your own.
+
+** Contributing your templates
+   :PROPERTIES:
+   :CUSTOM_ID: contributing-your-templates
+   :END:
+
+If you develop an output template and want to make it available, please
+let me know, so that I can include it in future releases of this gem.
+
+** Development
+   :PROPERTIES:
+   :CUSTOM_ID: development
+   :END:
+
+After checking out the repo, run =bin/setup= to install dependencies.
+You can also run =bin/console= for an interactive prompt that will allow
+you to experiment.
+
+To install this gem onto your local machine, run
+=bundle exec rake install=. To release a new version, update the version
+number in =version.rb=, and then run =bundle exec rake release=, which
+will create a git tag for the version, push git commits and tags, and
+push the =.gem= file to [[https://rubygems.org][rubygems.org]].
+
+** Contributing
+   :PROPERTIES:
+   :CUSTOM_ID: contributing
+   :END:
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/avillafiorita/resme.
+
+** License
+   :PROPERTIES:
+   :CUSTOM_ID: license
+   :END:
+
+The gem is available as open source under the terms of the
+[[http://opensource.org/licenses/MIT][MIT License]].
+
+** Change Log
+
+In =doc/changelog.org=
+
+** Roadmap
+   :PROPERTIES:
+   :CUSTOM_ID: roadmap
+   :END:
+
+In =doc/todo.org= ... guess what is my preferred editor!
+
+** Bugs
+   :PROPERTIES:
+   :CUSTOM_ID: bugs
+   :END:
+
+There are still slight differences in the syntax of entries and in the
+way in which the information is formatted in various output formats. For
+instance, gender and birthdate are used in the Europass format, but not
+in the Markdown format. This is in part due to the different standards
+and in part due to personal preferences.
+
+*Entries are not sorted by date before outputting them. Make sure you
+put them in the order you want them to appear in your resume.*
+
+Unknown number of unknown bugs.
+
+** Release History
+   :PROPERTIES:
+   :CUSTOM_ID: release-history
+   :END:
+
+- *0.4.0* refactors all generation commands under =generate=, provides
+  new filtering options, adds =-e= option (for custom templates), and
+  refactors various portions of code.  It also revises this document
+  and fixes some minor bugs.
+- *0.3.2* and *0.3.1* fix errors with the Europass format: lists of
+  projects, interests, ... are now properly formatted.
+- *0.3* introduces output to org-mode, introduces references for the CV,
+  improves output to JSON, adds a =check= command, removes useless blank
+  lines in the output, supports =-%>= in the ERB templates, fixes
+  various typos in the documentation, introduces various new formatting
+  functions, to simplify template generation
+- *0.2* improves output of volunteering activities and other information
+  in the Europass and *significantly improves error and warning
+  reporting*
+- *0.1* is the first release

data/exe/resme

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require 'resme'
+require "resme"
 
 # read-eval-print-step passing all commands and the argument
-Resme::CommandSemantics.reps Resme::CommandSyntax.commands, ARGV
+Resme::CommandSemantics.execute Resme::CommandSyntax.commands, ARGV

data/lib/resme/cli/command_semantics.rb

@@ -1,90 +1,89 @@
-require 'resme/version'
-require 'readline'
-require 'fileutils'
-require 'date'
-require 'yaml'
-require 'erb'
-require 'json'
-require 'kwalify'
+require "resme/version"
+require "readline"
+require "fileutils"
+require "date"
+require "yaml"
+require "erb"
+require "json"
 
 module Resme
   module CommandSemantics
-    APPNAME = 'resme'
+    APPNAME = "resme"
     VERSION = Resme::VERSION
 
     #
     # Main App Starts Here!
     #
-    def self.version opts = nil, argv = []
+    def self.version(opts = nil, argv = [])
       puts "#{APPNAME} version #{VERSION}"
     end
 
-    def self.man opts = nil, argv = []
-      path = File.join(File.dirname(__FILE__), "/../../../README.md")
+    def self.man(opts = nil, argv = [])
+      path = File.join(File.dirname(__FILE__), "/../../../README.org")
       file = File.open(path, "r")
-      contents = file.read
-      puts contents
+      puts file.read
     end
 
-    def self.help opts = nil, argv = []
+    def self.help(opts = nil, argv = [])
       all_commands = CommandSyntax.commands
       
       if argv != []
-        argv.map { |x| puts all_commands[x.to_sym][2] }
+        argv.map do |x|
+          puts all_commands[x.to_sym][:help]
+          puts "\n\n"
+        end
       else
-        puts "#{APPNAME} command [options] [args]"
-        puts ""
-        puts "Available commands:"
-        puts ""
-        all_commands.keys.each do |key|
-          puts "  " + all_commands[key][0].banner
+        puts "#{APPNAME} command [options] [args]\n"
+        puts "Available commands:\n"
+        all_commands.each_key do |key|
+          puts "  #{all_commands[key][:options].banner}"
         end
       end
     end
 
-    def self.console opts, argv = []
+    def self.console(opts, argv = [])
       all_commands = CommandSyntax.commands
       all_commands.delete(:console)
       
       i = 0
       while true
         string = Readline.readline("#{APPNAME}:%03d> " % i, true)
-        string.gsub!(/^#{APPNAME} /, "") # as a courtesy, remove any leading appname string
-        if string == "exit" or string == "quit" or string == "." then
-          exit 0
-        end
-        reps all_commands, string.split(' ')
+        # as a courtesy, remove any leading appname string
+        string.gsub!(/^#{APPNAME} /, "")
+        exit 0 if %w[exit quit .].include? string
+        execute all_commands, string.split(" ")
         i = i + 1
       end
     end
 
     # read-eval-print step
-    def self.reps all_commands, argv
+    # check if argv is in any of all_commands, parse options
+    # according to the specification in all_commands and invoke
+    # a function in this class to actually do the work
+    def self.execute(all_commands, argv)
       if argv == [] or argv[0] == "--help" or argv[0] == "-h"
-        CommandSemantics.help
+        help
         exit 0
       else
         command = argv[0]
-        syntax_and_semantics = all_commands[command.to_sym]
-        if syntax_and_semantics
-          opts = syntax_and_semantics[0]
-          function = syntax_and_semantics[1]
-          
-          begin
-            parser = Slop::Parser.new(opts)
+        command_spec = all_commands[command.to_sym]
 
-            result = parser.parse(argv[1..-1])
-            options = result.to_hash
-            arguments = result.arguments
+        if command_spec
+          command_name = command_spec[:name]
+          option_parser = command_spec[:options]
 
-            eval "CommandSemantics::#{function}(options, arguments)"
-          rescue Slop::Error => e
-            puts "#{APPNAME}: #{e}"
+          begin
+            argv.shift # remove command name from ARGV
+            options = {}
+            parser = option_parser.parse!(into: options)
+            eval "CommandSemantics::#{command_name}(options, argv)"
           rescue Exception => e
-            puts e
+            puts "#{APPNAME} error: #{e}"
+            puts "Help with \"#{APPNAME} help #{command_name}\""
           end
         else
-          puts "#{APPNAME}: '#{command}' is not a valid command. See '#{APPNAME} help'"
+          puts "#{APPNAME} error: "#{command}" is not a valid command."
+          puts "List commands with \"#{APPNAME} help\"."
         end
       end
     end
@@ -92,40 +91,37 @@ module Resme
     #
     # APP SPECIFIC COMMANDS
     #
-    def self.check opts, argv
-      schema = Kwalify::Yaml.load_file(File.join(File.dirname(__FILE__), "/../templates/schema.yml"))
-      ## or
-      # schema = YAML.load_file('schema.yaml')
-
-      ## create validator
-      validator = Kwalify::Validator.new(schema)
-
-      ## load document
-      document = Kwalify::Yaml.load_file(argv[0])
-      ## or
-      #document = YAML.load_file('document.yaml')
-
-      ## validate
-      errors = validator.validate(document)
-
-      ## show errors
-      if errors && !errors.empty?
-        for e in errors
-          puts "[#{e.path}] #{e.message}"
+    def self.check(opts, argv)
+      begin
+        document = YAML.load_file(argv[0], permitted_classes: [Date])
+      rescue Psych::SyntaxError => ex
+        puts "The file #{argv[0]} has an invalid structure."
+        puts ex.message
+        exit 1
+      end
+        
+      begin
+        errors = ResumeStructureValidator.validate(document)
+      rescue Exception => ex
+        puts "The files #{argv[0]} does not validate"
+        ex.entries.each do |error|
+          puts "#{error[:full_path]}: #{error[:message]}"
         end
-      else
-        puts "The file #{argv[0]} validates."
+        exit 1
       end
+      puts "The file #{argv[0]} has a valid structure."
     end
 
-    def self.init opts, argv
+    def self.init(opts, argv)
       output = opts[:output] || "resume.yml"
       force = opts[:force]
-      template = File.join(File.dirname(__FILE__), "/../templates/resume.yml")
+      path = File.dirname(__FILE__), "/../templates/resume.yml"
+      template = File.join(path)
 
-      # avoid catastrophy
-      if File.exist?(output) and not force
-        puts "Error: file #{output} already exists.  Use --force if you want to overwrite it"
+      # avoid catastrophe
+      if File.exist?(output) && !force
+        puts "#{APPNAME} error: file #{output} already exists."
+        puts "Use --force if you want to overwrite it."
       else
         content = File.read(template)
         backup_and_write output, content
@@ -133,60 +129,71 @@ module Resme
       end
     end
 
-    def self.md opts, argv
-      output = opts[:output] || "resume-#{Date.today}.md"
-      template = File.join(File.dirname(__FILE__), "/../templates/resume.md.erb")
-
-      render argv, template, output
-      puts "Resume generated in #{output}"
+    def self.list(opts, argv)
+      data = {}
+      argv.each do |file|
+        data = data.merge(YAML.load_file(file, permitted_classes: [Date]))
+      end
+      puts "Sections included in #{argv.join(", ")}:"
+      data.keys.each do |key|
+        puts "- #{key}: #{(data[key] || []).size} entries"
+      end
     end
 
-    def self.org opts, argv
-      output = opts[:output] || "resume-#{Date.today}.org"
-      template = File.join(File.dirname(__FILE__), "/../templates/resume.org.erb")
-
-      render argv, template, output
-      puts "Resume generated in #{output}"
+    def self.view(opts, argv)
+      format = opts[:template] == "europass" ? "xml" : opts[:template]
+      template = File.join(File.dirname(__FILE__), "/../templates/resume.#{format}.erb")
+      puts File.read template
     end
 
-    def self.json opts, argv
-      output = opts[:output] || "resume-#{Date.today}.json"
-      template = File.join(File.dirname(__FILE__), "/../templates/resume.json.erb")
+    def self.generate(opts, argv)
+      format = opts[:to] == "europass" ? "xml" : opts[:to]
+      output = opts[:output] || "resume-#{Date.today}.#{format}"
 
-      render argv, template, output
-      puts "Resume generated in #{output}"
-    end
+      if opts[:erb]
+        template = opts[:erb]
+      else
+        template = File.join(File.dirname(__FILE__), "/../templates/resume.#{format}.erb")
+      end
 
-    def self.europass opts, argv
-      output = opts[:output] || "resume-#{Date.today}.xml"
-      template = File.join(File.dirname(__FILE__), "/../templates/europass/eu.xml.erb")
+      skipped_sections = opts[:skip] || []
 
-      render argv, template, output
+      if !File.exists?(template)
+        puts "#{APPNAME} error: format #{format} is not understood."
+      end
+
+      render argv, template, output, skipped_sections
       puts "Resume generated in #{output}"
-      puts "Render via, e.g., http://interop.europass.cedefop.europa.eu/web-services/remote-upload/"
+
+      if format == "xml" then
+        puts "Europass XML generated. Render via, e.g., http://interop.europass.cedefop.europa.eu/web-services/remote-upload/"
+      end
     end
 
     private
 
-    def self.render yml_files, template_filename, output_filename
-      data = Hash.new
+    def self.render(yml_files, template_name, output_name, skipped_sections)
+      data = {}
       yml_files.each do |file|
-        data = data.merge(YAML.load_file(file))
+        data = data.merge(YAML.load_file(file, permitted_classes: [Date]))
+      end
+      skipped_sections.each do |section|
+        data.reject! { |k| k == section } 
       end
-      template = File.read(template_filename)
-      output = ERB.new(template, nil, '-').result(binding)
+      template = File.read(template_name)
+      output = ERB.new(template, trim_mode: "-").result(binding)
       # it is difficult to write readable ERBs with no empty lines...
       # we use gsub to replace multiple empty lines with \n\n in the final output
       output.gsub!(/([\t ]*\n){3,}/, "\n\n")
-      backup_and_write output_filename, output
+      backup_and_write output_name, output
     end
 
-    def self.backup filename
+    def self.backup(filename)
       FileUtils::cp filename, filename + "~"
       puts "Backup copy #{filename} created in #{filename}~."
     end
 
-    def self.backup_and_write filename, content
+    def self.backup_and_write(filename, content)
       backup(filename) if File.exist?(filename)
       File.open(filename, "w") { |f| f.puts content }
     end