bibsonomy 0.4.0

data/README.md

@@ -0,0 +1,121 @@
+# BibSonomy
+
+BibSonomy client for Ruby
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bibsonomy'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bibsonomy
+
+## Usage
+
+Getting posts from BibSonomy:
+
+```ruby
+require 'bibsonomy'
+api = BibSonomy::API.new('yourusername', 'yourapikey', 'ruby')
+posts = api.get_posts_for_user('jaeschke', 'publication', ['myown'], 0, 20)
+```
+
+Rendering posts with [CSL](http://citationstyles.org/):
+
+```ruby
+require 'bibsonomy/csl'
+csl = BibSonomy::CSL.new('yourusername', 'yourapikey')
+html = csl.render('jaeschke', ['myown'], 100)
+print html
+```
+
+A command line wrapper to the CSL renderer:
+
+```ruby
+#!/usr/bin/ruby
+require 'bibsonomy/csl'
+print BibSonomy::main(ARGV)
+```
+
+## Jekyll
+
+A [Jekyll](http://jekyllrb.com/) plugin:
+
+```ruby
+# coding: utf-8
+require 'time'
+require 'bibsonomy/csl'
+
+module Jekyll
+
+  class BibSonomyPostList < Liquid::Tag
+    def initialize(tag_name, text, tokens)
+      super
+      parts = text.split(/\s+/)
+      @user = parts[0]
+      @tag = parts[1]
+      @count = Integer(parts[2])
+    end
+    
+    def render(context)
+      site = context.registers[:site]
+
+      # user name and API key for BibSonomy
+      user_name = site.config['bibsonomy_user']
+      api_key = site.config['bibsonomy_apikey']
+      csl = BibSonomy::CSL.new(user_name, api_key)
+
+      # target directory for PDF documents
+      pdf_dir = site.config['bibsonomy_document_directory']
+      csl.pdf_dir = pdf_dir
+      
+      # CSL style for rendering
+      style = site.config['bibsonomy_style']
+      csl.style = style
+
+      html = csl.render(@user, [@tag], @count)
+
+      # set date to now
+      context.registers[:page]["date"] = Time.new
+      
+      return html
+    end
+  end
+
+end
+
+Liquid::Template.register_tag('bibsonomy', Jekyll::BibSonomyPostList)
+```
+
+The plugin can be used inside Markdown files as follows:
+
+```
+{% bibsonomy jaeschke myown 100 %}
+```
+
+Add the following options to your `_config.yml`:
+
+```
+bibsonomy_user: yourusername
+bibsonomy_apikey: yourapikey
+bibsonomy_document_directory: pdf
+# other: apa, acm-siggraph
+bibsonomy_style: springer-lecture-notes-in-computer-science
+```
+
+
+## Contributing
+
+1. Fork it ( https://github.com/rjoberon/bibsonomy-ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bibsonomy.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bibsonomy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bibsonomy"
+  spec.version       = BibSonomy::VERSION
+  spec.authors       = ["Robert Jäschke"]
+  spec.email         = ["jaeschke@l3s.de"]
+  spec.summary       = %q{Wraps the BibSonomy REST API.}
+  spec.description   = %q{Enables calls to the BibSonomy REST API with Ruby.}
+  spec.homepage      = "https://github.com/rjoberon/bibsonomy-ruby"
+  spec.license       = "LGPL 2.1"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.4"
+  spec.add_development_dependency "vcr", "~> 2.9"
+  spec.add_development_dependency "webmock", "~> 1.19"
+
+  spec.add_dependency "faraday", "~> 0.9"
+  spec.add_dependency "json", "~> 1.8"
+  spec.add_dependency "citeproc", "~> 1.0"
+  spec.add_dependency "csl-styles", "~> 1.0"
+  spec.add_dependency "bibtex-ruby", "~> 4.0"
+  
+end

data/lib/bibsonomy.rb

@@ -0,0 +1,7 @@
+require_relative "bibsonomy/version"
+require_relative "bibsonomy/post"
+require_relative "bibsonomy/api"
+
+module BibSonomy
+  # Your code goes here...  
+end

data/lib/bibsonomy/api.rb

@@ -0,0 +1,150 @@
+# coding: utf-8
+require 'faraday'
+require 'json'
+
+#
+# TODO:
+# - error handling
+# - getting more than 1000 posts
+#
+
+# configuration options
+$API_URL = "https://www.bibsonomy.org/"
+$MAX_POSTS_PER_REQUEST = 20
+
+#
+# allowed shortcuts for resource types
+#
+$resource_types_bookmark = ['bookmark', 'bookmarks', 'book', 'link', 'links', 'url']
+$resource_types_bibtex = ['bibtex', 'pub', 'publication', 'publications', 'publ']
+
+#
+# The BibSonomy REST client for Ruby.
+#
+module BibSonomy
+  class API
+
+    # Initializes the client with the given credentials.
+    #
+    # @param user_name [String] The name of the user account used for
+    # accessing the API
+    #
+    # @param api_key [String] The API key corresponding to the user
+    # account - can be obtained from
+    # http://www.bibsonomy.org/settings?selTab=1
+    #
+    # @param format [String] The requested return format. One of:
+    # 'xml', 'json', 'ruby', 'csl', 'bibtex'. The default is 'ruby'
+    # which returns Ruby objects defined by this library. Currently,
+    # 'csl' and 'bibtex' are only available for publications.
+    #
+    def initialize(user_name, api_key, format = 'ruby')
+
+      # configure output format
+      if format == 'ruby'
+        @format = 'json'
+        @parse = true
+      else
+        @format = format
+        @parse = false
+      end
+
+      @conn = Faraday.new(:url => $API_URL) do |faraday|
+        faraday.request  :url_encoded             # form-encode POST params
+        #faraday.response :logger
+        faraday.adapter  Faraday.default_adapter  # make requests with
+                                                  # Net::HTTP
+      end
+
+      @conn.basic_auth(user_name, api_key)
+
+    end
+
+
+    #
+    # Get a single post
+    #
+    # @param user_name [String] The name of the post's owner.
+    # @param intra_hash [String] The intrag hash of the post.
+    # @return [BibSonomy::Post] the requested post
+    #
+    def get_post(user_name, intra_hash)
+      response = @conn.get "/api/users/" + CGI.escape(user_name) + "/posts/" + CGI.escape(intra_hash), { :format => @format }
+
+      if @parse
+        attributes = JSON.parse(response.body)
+        return Post.new(attributes["post"])
+      end
+      return response.body
+    end
+
+    #
+    # Get posts owned by a user, optionally filtered by tags.
+    #
+    # @param user_name [String] The name of the posts' owner.
+    # @resource_type [String] The type of the post. Currently
+    # supported are 'bookmark' and 'publication'.
+    #
+    def get_posts_for_user(user_name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST)
+      params = {
+        :format => @format,
+        :resourcetype => self.get_resource_type(resource_type),
+        :start => start,
+        :end => endc
+      }
+      # add tags, if requested
+      if tags != nil
+        params[:tags] = tags.join(" ")
+      end
+      response = @conn.get "/api/users/" + CGI.escape(user_name) + "/posts", params
+
+      if @parse
+        posts = JSON.parse(response.body)["posts"]["post"]
+        return posts.map { |attributes| Post.new(attributes) }
+      end
+      return response.body
+    end
+
+    def get_document_href(user_name, intra_hash, file_name)
+      return "/api/users/" + CGI.escape(user_name) + "/posts/" + CGI.escape(intra_hash) + "/documents/" + CGI.escape(file_name)
+    end
+
+    #
+    # get a document belonging to a post
+    #
+    def get_document(user_name, intra_hash, file_name)
+      response = @conn.get get_document_href(user_name, intra_hash, file_name)
+      if response.status == 200
+        return [response.body, response.headers['content-type']]
+      end
+      return nil, nil
+    end
+
+    def get_document_preview(user_name, intra_hash, file_name, size)
+      response = get_document_href(user_name, intra_hash, file_name), { :preview => size }
+      if response.status = 200
+        return [response.body, 'image/jpeg']
+      end
+      return nil, nil
+    end
+
+    #
+    # Convenience method to allow sloppy specification of the resource
+    # type.
+    #
+    # @private
+    #
+    def get_resource_type(resource_type)
+      if $resource_types_bookmark.include? resource_type.downcase()
+        return "bookmark"
+      end
+
+      if $resource_types_bibtex.include? resource_type.downcase()
+        return "bibtex"
+      end
+
+      raise ArgumentError.new("Unknown resource type:  #{resource_type}. Supported resource types are ")
+    end
+
+  end
+end

data/lib/bibsonomy/csl.rb

@@ -0,0 +1,395 @@
+# coding: utf-8
+
+require 'optparse'
+require 'citeproc'
+require 'csl/styles'
+require 'bibtex'
+require 'json'
+require 'bibsonomy'
+
+#
+# Generates a list of publication posts from BibSonomy
+#
+# required parameters:
+# - user name
+# - api key
+# optional parameters:
+# - user name
+# - tags
+# - number of posts
+# - style
+# - directory
+#
+# Changes:
+# 2015-02-24
+# - initial version
+#
+# TODO:
+# - escape data
+# - make sorting, etc. configurable
+# - add link to BibSonomy
+# - automatically rename files (TODO: CSL lacks BibTeX key)
+# - add intra_hash, user_name, DOI to CSL
+# - integrate AJAX abstract
+# - make all options available via command line
+
+module BibSonomy
+  class CSL
+
+    #
+    # Create a new BibSonomy instance
+    # Params:
+    # +user_name+:: BibSonomy user name
+    # +api_key+:: API key of the given user (get at http://www.bibsonomy.org/settings?selTab=1)
+    def initialize(user_name, api_key)
+      super()
+      @bibsonomy = BibSonomy::API.new(user_name, api_key, 'csl')
+      # setting some defaults
+      @style = 'apa.csl'
+      @pdf_dir = nil
+      @css_class = 'publications'
+      @year_headings = true
+      @public_doc_postfix = '_oa.pdf'
+
+      # optional parts to be rendered (or not)
+      @doi_link = true
+      @url_link = true
+      @bibtex_link = true
+      @bibsonomy_link = true
+      @opt_sep = ' | '
+    end
+
+    #
+    # Download +count+ posts for the given +user+ and +tag(s)+ and render them with CSL.
+    # Params:
+    # +user+:: user name
+    # +tags+:: an array of tags
+    # +count+:: number of posts to download
+    def render(user, tags, count)
+      # get posts from BibSonomy
+      posts = JSON.parse(@bibsonomy.get_posts_for_user(user, 'publication', tags, 0, count))
+
+      # render them with citeproc
+      cp = CiteProc::Processor.new style: @style, format: 'html'
+      cp.import posts
+
+      # to check for duplicate file names
+      file_names = []
+
+      # sort posts by year
+      sorted_keys = posts.keys.sort { |a,b| get_sort_posts(posts[b], posts[a]) }
+
+      result = ""
+
+      # print first heading
+      last_year = 0
+
+      if @year_headings and sorted_keys.length > 0
+        last_year = get_year(posts[sorted_keys[0]])
+        result += "<h3>" + last_year + "</h3>"
+      end
+
+      result += "<ul class='#{@publications}'>\n"
+      for post_id in sorted_keys
+        post = posts[post_id]
+
+        # print heading
+        if @year_headings
+          year = get_year(post)
+          if year != last_year
+            last_year = year
+            result += "</ul>\n<h3>" + last_year + "</h3>\n<ul class='#{@publications}'>\n"
+          end
+        end
+
+        # render metadata
+        csl = cp.render(:bibliography, id: post_id)
+        result += "<li class='" + post["type"] + "'>#{csl[0]}"
+
+        # extract the post's id
+        intra_hash, user_name = get_intra_hash(post_id)
+
+        # optional parts
+        options = []
+        # attach documents
+        if @pdf_dir
+          for doc in get_public_docs(post["documents"])
+            # fileHash, fileName, md5hash, userName
+            file_path = get_document(@bibsonomy, intra_hash, user_name, doc, @pdf_dir, file_names)
+            options << "<a href='#{file_path}'>PDF</a>"
+          end
+        end
+        # attach DOI
+        doi = post["DOI"]
+        if @doi_link and doi != ""
+          options << "DOI:<a href='http://dx.doi.org/#{doi}'>#{doi}</a>"
+        end
+        # attach URL
+        url = post["URL"]
+        if @url_link and url != ""
+          options << "<a href='#{url}'>URL</a>"
+        end
+        # attach BibTeX
+        if @bibtex_link
+          options << "<a href='http://www.bibsonomy.org/bib/publication/#{intra_hash}/#{user_name}'>BibTeX</a>"
+        end
+        # attach link to BibSonomy
+        if @bibsonomy_link
+          options << "<a href='http://www.bibsonomy.org/publication/#{intra_hash}/#{user_name}'>BibSonomy</a>"
+        end
+
+        # attach options
+        if options.length > 0
+          result += " <span class='opt'>[" + options.join(@opt_sep) + "]</span>"
+        end
+        
+        result += "</li>\n"
+      end
+      result += "</ul>\n"
+
+      return result
+    end
+    
+    def get_year(post)
+      return post["issued"]["literal"]
+    end
+
+    def get_sort_posts(a, b)
+      person_a = a["author"]
+      if person_a.length == 0
+        person_a = a["editor"]
+      end
+      person_b = b["author"]
+      if person_b.length == 0
+        person_b = b["editor"]
+      end
+      return [get_year(a), a["type"], person_b[0]["family"]] <=> [get_year(b), b["type"], person_a[0]["family"]]
+    end
+
+    #
+    # only show PDF files and if
+    #
+    def get_public_docs(documents)
+      result = []
+      for doc in documents
+        file_name = doc["fileName"]
+        if file_name.end_with? ".pdf"
+          if documents.length < 2 or file_name.end_with? @public_doc_postfix
+            result << doc
+          end
+        end
+      end
+      return result
+    end
+
+    def warn(m)
+      print("WARN: " + m + "\n")
+    end
+
+    #
+    # downloads the documents for the posts (if necessary)
+    #
+    def get_document(bib, intra_hash, user_name, doc, dir, file_names)
+      # fileHash, fileName, md5hash, userName
+      file_name = doc["fileName"]
+      # strip doc prefix for public documents
+      if file_name.end_with? @public_doc_postfix
+        file_name = file_name[0, file_name.length - @public_doc_postfix.length] + ".pdf"
+      end
+      # check for possible duplicate file names
+      if file_names.include? file_name
+        warn "duplicate file name " + file_name + " for post " + intra_hash
+      end
+      # remember file name
+      file_names << file_name
+      # produce file path
+      file_path = dir + "/" + file_name
+      # download PDF if it not already exists
+      if not File.exists? file_path
+        pdf, mime = bib.get_document(user_name, intra_hash, doc["fileName"])
+        if pdf == nil
+          warn "could not download file " + intra_hash + "/" + user_name + "/" + file_name
+        else
+          File.binwrite(file_path, pdf)
+        end
+      end
+      return file_path
+    end
+
+    # format of the post ID for CSL: [0-9a-f]{32}USERNAME
+    def get_intra_hash(post_id)
+      return [post_id[0, 32], post_id[32, post_id.length]]
+    end
+
+    #
+    # setters
+    #
+
+    #
+    # Set the output directory for downloaded PDF files (default: +nil+)
+    # Params:
+    # +pdf_dir+:: directory for downloaded PDF files. If set to +nil+, no documents are downloaded.
+    def pdf_dir=(pdf_dir)
+      @pdf_dir = pdf_dir
+    end
+
+    #
+    # Set the CSL style used for rendering (default: +apa.csl+)
+    # Params:
+    # +style+:: CSL style used for rendering
+    def style=(style)
+      @style = style
+    end
+
+    #
+    # Enable/disable headings for years (default: enabled)
+    # Params:
+    # +year_headings+:: boolean indicating whether year headings shall be rendered
+    def year_headings=(year_headings)
+      @year_headings = year_headings
+    end
+
+    #
+    # The CSS class used to render the surrounding +<ul>+ list (default: 'publications')
+    # Params:
+    # +css_class+:: string indicating the CSS class for rendering the publication list
+    def css_class=(css_class)
+      @css_class = css_class
+    end
+
+    #
+    # Shall links for DOIs be rendered? (default: true)
+    # Params:
+    # +doi_link+:: render DOI link
+    def doi_link=(doi_link)
+      @doi_link = doi_link
+    end
+
+    #
+    # Shall links for URLs of posts be rendered? (default: true)
+    # Params:
+    # +url_link+:: render URL link
+    def url_link=(url_link)
+      @url_link = url_link
+    end
+
+    #
+    # Shall links to the BibTeX of a post (in BibSonomy) be rendered? (default: true)
+    # Params:
+    # +bibtex_link+:: render BibTeX link
+    def bibtex_link=(bibtex_link)
+      @bibtex_link = bibtex_link
+    end
+
+    #
+    # Shall links to BibSonomy be rendered? (default: true)
+    # Params:
+    # +bibsonomy_link+:: render BibSonomy link
+    def bibsonomy_link=(bibsonomy_link)
+      @bibsonomy_link = bibsonomy_link
+    end
+
+    #
+    # Separator between options (default: ' | ')
+    # Params:
+    # +opt_sep+:: option separator
+    def opt_sep=(opt_sep)
+      @opt_sep = opt_sep
+    end
+
+    #
+    # When a post has several documents and the filename of one of
+    # them ends with +public_doc_postfix+, only this document is
+    # downloaded and linked, all other are ignored. (default:
+    # '_oa.pdf')
+    # Params:
+    # +public_doc_postfix+:: postfix to check at document filenames
+    def public_doc_postfix=(public_doc_postfix)
+      @public_doc_postfix = public_doc_postfix
+    end
+    
+  end
+
+
+  # parse command line options
+  def self.main(args)
+
+    # setting default options
+    options = OpenStruct.new
+    options.documents = false
+    options.directory = nil
+    options.tags = []
+    options.style = "apa.csl"
+    options.posts = 1000
+
+    opt_parser = OptionParser.new do |opts|
+      opts.banner = "Usage: csl.rb [options] user_name api_key"
+
+      opts.separator ""
+      opts.separator "Specific options:"
+
+      # mandatory arguments are handled separately
+
+      # optional arguments
+      opts.on('-u', '--user USER', 'return posts for USER instead of user') { |v| options[:user] = v }
+      opts.on('-t', '--tags TAG,TAG,...', Array, 'return posts with the given tags') { |v| options[:tags] = v }
+      opts.on('-s', '--style STYLE', 'use CSL style STYLE for rendering') { |v| options[:style] = v }
+      opts.on('-n', '--number-of-posts [COUNT]', Integer, 'number of posts to download') { |v| options[:posts] = v }
+      opts.on('-d', '--directory DIR', 'target directory', '  (if not given, no documents are downloaed)') { |v| options[:directory] = v }
+
+      opts.separator ""
+      opts.separator "Common options:"
+
+      opts.on('-h', '--help', 'show this help message and exit') do
+        puts opts
+        exit
+      end
+
+      opts.on_tail('-v', "--version", "show version") do
+        puts BibSonomy::VERSION
+        exit
+      end
+
+    end
+
+    opt_parser.parse!(args)
+
+    # handle mandatory arguments
+    begin
+      mandatory = [:user_name, :api_key]
+      missing = []
+
+      options[:api_key] = args.pop
+      missing << :api_key unless options[:api_key]
+
+      options[:user_name] = args.pop
+      missing << :user_name unless options[:user_name]
+
+      if not missing.empty?
+        puts "Missing options: #{missing.join(', ')}"
+        puts opt_parser
+        exit
+      end
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument
+      puts $!.to_s
+      puts opt_parser
+      exit
+    end
+
+    # set defaults for optional arguments
+    options[:user] = options[:user_name] unless options[:user]
+
+    #
+    # do the actual work
+    #
+    csl = BibSonomy::CSL.new(options[:user_name], options[:api_key])
+    csl.pdf_dir(options[:directory])
+    csl.style(options[:style])
+
+    html = csl.render(options[:user], options[:tags], options[:posts])
+
+    return html
+
+  end
+
+end