scholar-rename 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdb5cff14beb38b02d6e11aa44a05c8770dcea22aa520f6b61e77c25c9e8088b
-  data.tar.gz: 36d7dc8907251cb05df51f66323ec5ba2c55046fbb03247c33ca1a962ef5ceec
+  metadata.gz: 8ff9c16c734ec953edfc836e232ebaf70fb62d2902b0240a91f0631cfe077bdc
+  data.tar.gz: 24455839f23d27ccada557d23e5e1a27b63ff2a35bb44407da07b9577e66e76f
 SHA512:
-  metadata.gz: fa2b9fd4f226bfb6ca45c2847c9e16ec6bebe97a99e00b3cb4f220414bda6d55cf3b7f7a898c58fc843e5e08ed7ba66b86d5fee2733fe2eef6d89da01898c85d
-  data.tar.gz: e24de26e632677c59ebddb7464eba87434a4ecabbe8579278399b2a4edb9cf7d9c63f38f82e60719b0df027fe90bde61eb44cc2375ecf8447b29284ce1af3e32
+  metadata.gz: '085102e70f448e2e72862acb6ba3204e6b652907587aca0e972346f606399cb29ab3ad7d8b9c03a6c6591d2975b48631e4bcde32077734808a60e5d6939bf732'
+  data.tar.gz: 10844926e2c3ff6e525811b8582d3b3c9d02c37a57c47225a561a061e71b37241c897f715338eef276160bd285d97702e9038c782c0d8c338ccec99526cb7e92

data/bin/scholar-rename

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 # by jeremy warner, started fall 2016
 # scholar-rename: interactive pdf-namer
@@ -7,7 +8,7 @@
 # renames a pdf file to author-title-year.pdf
 # or other formats based on your selection
 
-require_relative "../lib/selector"
-require_relative "../lib/renamer"
+require_relative '../lib/selector'
+require_relative '../lib/renamer'
 
-r = Renamer.new ARGV
+Renamer.new ARGV

data/lib/renamer.rb

@@ -1,82 +1,90 @@
-require_relative "./version.rb"
+# frozen_string_literal: true
+
+require 'English'
+require_relative 'version'
 
 class Renamer
   attr_reader :version, :formats, :selector, :format
 
+  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+  # Legacy CLI arg-parser predating this cleanup pass; splitting it apart is a
+  # real refactor, not a lint fix, so it's exempted rather than restructured here.
   def initialize(*args)
     args = args.flatten
     a0 = args.first
     al = args.last
 
     @real_file = false
-    @options = { :format => 0, :auto => false, :debug => false, :test => false }
-    @version = SR::Version
+    @options = { format: 0, auto: false, debug: false, test: false, no_lookup: false }
+    @version = SR::VERSION
     @selector = Selector.new
-    @formats = @selector.gen_forms("Year", "Title", "Author")
+    @formats = @selector.gen_forms('Year', 'Title', 'Author')
 
-    if args.include? "--debug"
-      @options[:debug] = true
-    end
+    @options[:debug] = true if args.include? '--debug'
 
-    if args.include? "--test"
+    if args.include? '--test'
       @options[:test] = true
-      def puts(*x) x; end
+      def puts(*x) = x
     end
 
+    @options[:no_lookup] = true if args.include? '--no-lookup'
+
+    @options[:auto] = true if args.include? '--auto'
+
+    @options[:format] = args[args.index('--format') + 1].to_i if args.include? '--format'
+
     # Filename comes last.
-    if !al.nil? && al[0] != "-"
+    if !al.nil? && al[0] != '-'
       @file = File.join(Dir.pwd, args.last).to_s
       @real_file = @file && File.file?(@file)
     end
     if @file && !@real_file
       puts "Input #{@file} not found."
-      puts "Please specify a pdf file to use with scholar-rename."
+      puts 'Please specify a pdf file to use with scholar-rename.'
       exit 1
     end
 
     # Main argument processing.
-    if args.length == 0 || a0 == "--h" || a0 == "--help"
-      puts "usage: scholar-rename (--format #) (--auto) [file.pdf]"
+    if args.empty? || a0 == '--h' || a0 == '--help'
+      puts 'usage: scholar-rename (--format #) (--auto) (--no-lookup) [file.pdf]'
       puts "\t--show-formats\tshow format options"
       puts "\t--auto\tpick default formatter"
+      puts "\t--no-lookup\tdisable Semantic Scholar metadata lookup"
       puts "\t-v, --version\tshow version number"
-    elsif a0 == "-v" || a0 == "--version"
+    elsif ['-v', '--version'].include?(a0)
       puts @version
       exit 0 unless @options[:test]
-    elsif !has_prereq?
-      puts "please install pdftotext (via poppler) to use scholar-rename"
-      puts "OSX: brew install pkg-config poppler"
+    elsif !prereq?
+      puts 'please install pdftotext (via poppler) to use scholar-rename'
+      puts 'OSX: brew install pkg-config poppler'
       exit 1
-    elsif a0 == "--show-formats"
+    elsif a0 == '--show-formats'
       @formats.each_with_index { |x, i| puts "\t#{i}: #{x}" }
-    elsif a0 == "--format"
-      @options[:format] = args[1].to_i
-    elsif a0 == "--auto"
-      @options[:auto] = true
     end
 
     rename args if @real_file
   end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
-  def has_prereq?
-    system("pdftotext -v 2> /dev/null")
-    $?.success?
+  def prereq?
+    system('pdftotext -v 2> /dev/null')
+    $CHILD_STATUS.success?
   end
 
   def rename(args)
     raw = `pdftotext -q '#{@file}' -` # may contain non-ascii characters
-    content = raw.encode("UTF-8", :invalid => :replace, :undef => :replace)
-    
+    content = raw.encode('UTF-8', invalid: :replace, undef: :replace)
+
     # Choose pdf qualities
-    @selector.set_content(content)
+    @selector.content = content
     @selector.options = @options
     @selector.select_all
     md = @selector.metadata
 
     if @options[:debug]
-      puts md[:year] if args.include? "--show-year"
-      puts md[:title] if args.include? "--show-title"
-      puts md[:author] if args.include? "--show-author"
+      puts md[:year] if args.include? '--show-year'
+      puts md[:title] if args.include? '--show-title'
+      puts md[:author] if args.include? '--show-author'
     else
       File.rename(@file, @selector.title)
       puts "Saved #{@selector.title}"

data/lib/scholar_lookup.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'openssl'
+
+# Queries the Semantic Scholar Graph API to cross-reference a rough title
+# guess against real paper metadata. Always returns a Hash or nil; never
+# raises, so a network hiccup just means the caller falls back to its own
+# heuristics.
+class ScholarLookup
+  ENDPOINT = 'https://api.semanticscholar.org/graph/v1/paper/search'
+  FIELDS = 'title,authors,year,venue'
+  SOURCE_NAME = 'Semantic Scholar'
+
+  # Exceptions expected from a flaky network/API, silently treated as "no
+  # match". Anything else (e.g. a response-shape change breaking #parse) is
+  # still caught so a rename can never crash, but is reported via warn so the
+  # regression isn't invisible.
+  EXPECTED_ERRORS = [
+    SocketError,
+    Timeout::Error,
+    SystemCallError,
+    OpenSSL::SSL::SSLError,
+    Net::ProtocolError,
+    JSON::ParserError
+  ].freeze
+
+  # A match only counts if at least half of the query's words also appear in
+  # the returned title -- guards against a short/generic query (e.g. a running
+  # header) fuzzy-matching an unrelated paper.
+  MIN_WORD_OVERLAP = 0.5
+
+  def initialize(open_timeout: 2, read_timeout: 3)
+    @open_timeout = open_timeout
+    @read_timeout = read_timeout
+  end
+
+  def source_name
+    SOURCE_NAME
+  end
+
+  def lookup(query)
+    return nil if query.nil? || query.strip.length < 4
+
+    body = fetch(build_uri(query.strip))
+    return nil if body.nil?
+
+    match = parse(body)
+    return nil unless match && plausible_match?(query, match[:title])
+
+    match
+  rescue *EXPECTED_ERRORS
+    nil
+  rescue StandardError => e
+    warn "scholar-rename: unexpected lookup error (#{e.class}): #{e.message}"
+    nil
+  end
+
+  private
+
+  def plausible_match?(query, title)
+    query_words = normalize_words(query)
+    title_words = normalize_words(title)
+    return false if query_words.empty? || title_words.empty?
+
+    overlap = (query_words & title_words).length
+    overlap.to_f / query_words.length >= MIN_WORD_OVERLAP
+  end
+
+  def normalize_words(str)
+    str.downcase.gsub(/[^a-z0-9\s]/, '').split
+  end
+
+  def build_uri(query)
+    uri = URI(ENDPOINT)
+    uri.query = URI.encode_www_form('query' => query, 'fields' => FIELDS, 'limit' => '1')
+    uri
+  end
+
+  def fetch(uri)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = true
+    http.open_timeout = @open_timeout
+    http.read_timeout = @read_timeout
+
+    req = Net::HTTP::Get.new(uri)
+    req['User-Agent'] = 'scholar-rename'
+
+    res = http.request(req)
+    return nil unless res.is_a?(Net::HTTPSuccess)
+
+    res.body
+  end
+
+  def parse(body)
+    papers = JSON.parse(body)['data']
+    return nil if papers.nil? || papers.empty?
+
+    paper = papers.first
+    title = paper['title']
+    author = format_authors(paper['authors'])
+    return nil if title.nil? || title.strip.empty? || author.nil?
+
+    {
+      title: title,
+      author: author,
+      year: paper['year']&.to_s,
+      venue: paper['venue']
+    }
+  end
+
+  def format_authors(authors)
+    return nil if authors.nil? || authors.empty?
+
+    last_names = authors.map { |a| a['name'].to_s.split.last }.compact
+    return nil if last_names.empty?
+
+    case last_names.length
+    when 1, 2
+      last_names.join(' ')
+    else
+      "#{last_names.first} et al"
+    end
+  end
+end

data/lib/selector.rb

@@ -1,69 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'scholar_lookup'
+
 # Class for choosing and displaying the information from the pdf.
-# I wonder if this could be augmented with information from google scholar
-# somehow, there is probably a ruby (or at least python) api.
 
 class Selector
   attr_reader :title, :metadata, :content
   attr_accessor :options
 
-  def initialize(c = "Test\nPDF\nContent", opts = { :format => 0, :auto => true })
-    set_content(c)
+  def initialize(c = "Test\nPDF\nContent", opts = { format: 0, auto: true, no_lookup: false }, lookup = nil)
+    self.content = c
     @options = opts
-    if opts[:test]
-      def puts(*x) x; end
-    end
+    @lookup = lookup || ScholarLookup.new
+    return unless opts[:test]
+
+    def puts(*x) = x
   end
 
-  def set_content(str)
+  def content=(str)
     @full_text = str.split("\n")
     @content = @full_text[0..14]
-      .reject { |x| x.length < 2 }
-      .map { |x| x[0..100] } # trim
+               .reject { |x| x.length < 2 }
+               .map { |x| x[0..100] } # trim
   end
 
   def select_all
-    if !@options[:auto]
-      puts "Options:"
+    title, author, year = lookup_metadata unless @options[:no_lookup]
+    title, author, year = manual_metadata if title.nil?
+
+    forms = gen_forms(year, title, author)
+    @metadata = { year: year, title: title, author: author }
+    @title = forms[@options[:format]]
+  end
+
+  # Query the lookup source with our best title guess, and let the user
+  # accept or reject the match (--auto always accepts, matching how #choose
+  # behaves elsewhere). Returns a [title, author, year] triple, or nil if
+  # there was no match or it was rejected.
+  def lookup_metadata
+    match = @lookup.lookup(@content.first)
+    return nil unless match
+
+    summary = "#{match[:title]} -- #{match[:author]}"
+    summary += " (#{match[:year]})" if match[:year]
+    summary += " [#{match[:venue]}]" if match[:venue]
+    puts "Found match via #{@lookup.source_name}: #{summary}"
+
+    if @options[:auto]
+      puts '(auto-accepted)'
+    else
+      printf 'Use this? [Y/n]: '
+      resp = $stdin.gets.to_s.strip.downcase
+      return nil unless resp.empty? || resp == 'y' || resp == 'yes'
+    end
+
+    [match[:title], match[:author], match[:year] || gen_year]
+  end
+
+  # Ask the user to pick the title/author lines by hand. Returns a
+  # [title, author, year] triple.
+  def manual_metadata
+    unless @options[:auto]
+      puts 'Options:'
       @content.each_with_index { |l, i| puts "#{i}\t#{l}" }
     end
-    printf "Select title line number " unless @options[:auto]
+    printf 'Select title line number:' unless @options[:auto]
     title = choose(@content, print: false)
 
-    printf "Select author line number " unless @options[:auto]
+    printf 'Select author line number:' unless @options[:auto]
     authors = choose(@content, print: false)
 
-    puts "Select author form:" unless @options[:auto]
+    puts 'Select author form:' unless @options[:auto]
     author = gen_authors(authors)
 
-    # Automatically match.
-    year = gen_year
-    
-    forms = gen_forms(year, title, author)
-    @metadata = {:year => year, :title => title, :author => author}
-    @title = forms[@options[:format]]
+    [title, author, gen_year]
   end
 
   # based on the collected information, generate different forms of the title.
   def gen_forms(y, t, a)
+    y = sanitize_path_component(y)
+    t = sanitize_path_component(t)
+    a = sanitize_path_component(a)
     ad = a.downcase
     au = a.upcase
-    return [
-             "#{y} - #{a} - #{t}.pdf",
-             "#{y} #{a} #{t}.pdf",
-             "#{a}_#{y}_#{t}.pdf".gsub(" ", "_"),
-             "#{au}_#{y}_#{t}.pdf".gsub(" ", "_"),
-             "#{ad}_#{y}_#{t}.pdf".gsub(" ", "_"),
-             "#{a} #{y} #{t}.pdf",
-             "#{au} #{y} #{t}.pdf",
-             "#{ad} #{y} #{t}.pdf",
-           ]
+    [
+      "#{y} - #{a} - #{t}.pdf",
+      "#{y} #{a} #{t}.pdf",
+      "#{a}_#{y}_#{t}.pdf".gsub(' ', '_'),
+      "#{au}_#{y}_#{t}.pdf".gsub(' ', '_'),
+      "#{ad}_#{y}_#{t}.pdf".gsub(' ', '_'),
+      "#{a} #{y} #{t}.pdf",
+      "#{au} #{y} #{t}.pdf",
+      "#{ad} #{y} #{t}.pdf"
+    ]
+  end
+
+  # Filenames are built by combining year/title/author into a single path
+  # segment -- strip path separators so a "/" in a title (manually picked or
+  # fetched from an external source) can't turn File.rename into a move into
+  # a different (likely non-existent) directory.
+  def sanitize_path_component(s)
+    s.to_s.gsub(%r{[/\\]}, '-')
   end
 
   # Pass in an array to list and be selected, and return the element that the
   # user selects back to the calling method. this is a way to interpret
   # the users input as a range (e.g., 0..2) or an integer (1).
   def choose(list, print: true)
-    raise "List is empty." if list.empty?
+    raise 'List is empty.' if list.empty?
 
     if @options[:auto]
       line = 0
@@ -73,19 +117,19 @@ class Selector
         list.each_with_index { |l, i| puts "#{i}\t#{l}" }
         printf "[0 - #{options.length - 1}]: "
       end
-      line = STDIN.gets.chomp || 0
+      line = $stdin.gets&.chomp || 0
     end
 
     meta = "list[#{line}]"
-    mout = eval meta
-    mout = mout.join " " if mout.is_a? (Array)
+    mout = eval meta # rubocop:disable Security/Eval -- `line` is local interactive/--auto input only, never external
+    mout = mout.join ' ' if mout.is_a?(Array)
     mout
   end
 
   # Generate different forms for author selection, enumerating the different
   # author that you want to save the file as. Split based on a comma.
   def gen_authors(aline)
-    lines = aline.split(", ").map { |a| a.sub(/\d$/, "") } # delete ref number.
+    lines = aline.split(', ').map { |a| a.sub(/\d$/, '') } # delete ref number.
     if lines.is_a?(String)
       aline
     else # its an array, augment w/ lname and choose
@@ -99,7 +143,7 @@ class Selector
   def gen_year
     @full_text.each do |l| # find year
       lm = l.match(/(19|20)\d\d/)
-      return lm[0] if !lm.nil?
+      return lm[0] unless lm.nil?
     end
 
     Time.now.year.to_s # not matched, just return current year

data/lib/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module SR
-  Version = "0.4.1"
+  VERSION = '0.4.2'
 end

data/readme.md

@@ -1,7 +1,8 @@
 # scholar-rename
 
-[![MIT](https://img.shields.io/npm/l/alt.svg?style=flat)](http://jeremywrnr.com/mit-license)
 [![Gem Version](https://badge.fury.io/rb/scholar-rename.svg)](https://badge.fury.io/rb/scholar-rename)
+[![CI](https://github.com/jeremywrnr/scholar-rename/actions/workflows/ci.yml/badge.svg)](https://github.com/jeremywrnr/scholar-rename/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/npm/l/alt.svg?style=flat)](http://jeremywrnr.com/mit-license)
 
 an interactive pdf-renamer tool.
 
@@ -15,11 +16,26 @@ for macOS, you can install w/ brew:
 
     brew install pkg-config poppler
 
+for Ubuntu:
+
+    sudo apt-get install poppler-utils
+
 ## about
 
 renames a pdf file to author-title-year.pdf or other formats based on your
-selection. there isn't actually anything scholarly about this tool, though
-academic people may find it useful for renaming pdfs that come in arbitrarily
-named file formats. services like mendeley kind of make this not super
-relevant. it helps when searching for a specific pdf and when labeling pdfs.
+selection. academic people may find it useful for renaming pdfs that come in
+arbitrarily named file formats. it helps when searching for a specific pdf
+and when labeling pdfs.
+
+## metadata lookup
+
+by default, scholar-rename queries the [Semantic Scholar Graph
+API](https://api.semanticscholar.org/) using the extracted pdf text to
+suggest an authoritative title/author/year. you'll be asked to confirm the
+match (auto-accepted when using `--auto`). if there's no internet
+connection, the api times out, or no match is found, scholar-rename falls
+back to its original manual line-picking flow -- nothing ever crashes or
+hangs waiting on the network. use `--no-lookup` to skip the network step
+entirely (useful when offline, batch-renaming many files, or avoiding the
+api's rate limits).
 

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: scholar-rename
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Jeremy Warner
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +24,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -47,14 +60,16 @@ extra_rdoc_files: []
 files:
 - bin/scholar-rename
 - lib/renamer.rb
+- lib/scholar_lookup.rb
 - lib/selector.rb
 - lib/version.rb
 - readme.md
-homepage: http://github.com/jeremywrnr/scholar-rename
+homepage: https://github.com/jeremywrnr/scholar-rename
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  source_code_uri: https://github.com/jeremywrnr/scholar-rename
+  bug_tracker_uri: https://github.com/jeremywrnr/scholar-rename/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -62,15 +77,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Rename pdfs based on author/title/year.
 test_files: []