gappi: Get A PhilPapers Item

gappi is a very simple Bash script, which uses curl to conduct a search on PhilPapers (http://philpapers.org), and output the BibTeX record for the first search result.

Installation

Requirements: Bash is the default shell for most forms of *nix, including Mac OS X, and most linux distributions; if you’re using one of those, you have it already. You also need curl. I think curl comes pre-installed on OS X; it comes pre-installed on many linux distributions as well, and in any case is almost certainly available through your distribution’s package repository. Windows users can probably use Cygwin, and its curl package, though this has not been tested.

Steps to install:

  1. Acquire the script. You may do this in at least three ways: (a) download the tarball and extract the (lone) file gappi; (b) copy and paste the code below into your favorite text editor and save the file; (c) fetch it with curl, which would have the added advantage of ensuring that curl is properly installed on your system:
    curl http://people.umass.edu/klement/gappi/gappi -o gappi
  2. Move the script to one of the folders listed in your $PATH environmental variable; the folder $HOME/bin is a good choice if available.
  3. Make sure the script is executable: chmod 755 gappi
  4. Execute the command gappi --help to ensure that it is ready to use.

Examples of usage

gappi is first and foremost a command-line tool. It takes one or more arguments and outputs the BibTeX record for first/most-relevant result in PhilPaper’s database.

For example, the command below would result in the following output: (In the examples below, the initial $ just indicates the terminal prompt; it is not part of the command.)

$ gappi "Kaplan How to Russell a Frege-Church"
@article{Kaplan1975-KAPHTR,
	title = {How to Russell a Frege-Church},
	journal = {Journal of Philosophy},
	pages = {716--729},
	volume = {72},
	year = {1975},
	author = {David Kaplan},
	number = {19}
}

gappi outputs to stdout, but you can use normal i/o redirection techniques to create or append to a file. For instance, the following could be used to add the Kaplan entry to a BibTeX .bib file:

$ gappi "Kaplan How to Russell a Frege-Church" >> myreferences.bib

(Be sure to use >> rather than just > to avoid overwriting the file.)

You can use the more complicated syntax for PhilPapers searches listed at http://philpapers.org/help/search.html. For example:

$ gappi "@authors Eklund @title Inconsistent Languages"
@article{Eklund2002-EKLIL,
	year = {2002},
	journal = {Philosophy and Phenomenological Research},
	title = {Inconsistent Languages},
	author = {Matti Eklund},
	volume = {64},
	pages = {251--275},
	number = {2}
}

Note that it is “@authors” with an “s” not “@author”, even when there is only one. It is a good idea to use this syntax as much as possible, especially for books, as otherwise you are likely to a get an entry for a book review, rather than the entry for the book itself.

Thanks to improvements by David Sanson, you can retrieve more than one record for your search. To do this use gappi -n # prior to your search query, replacing # with the number of records you want to retrieve.

$ gappi -n 2 "@authors Bertrand Russell @title Truth"
@incollection{Russell1992-RUSWJC,
	publisher = {Routledge},
	editor = {William James and Doris Olin},
	author = {Bertrand Russell},
	title = {William James's Conception of Truth},
	abstract = {The original 1907 text of James' Pragmatism is accompanied with a series of critical essays from scholars including Moore and Russell. In the introduction Olin evaluates the strength of the criticisms made against James.},
	year = {1992},
	booktitle = {William James: Pragmatism, in Focus}
}
@book{Russell1995-RUSAII,
	publisher = {Routledge},
	author = {Bertrand Russell},
	title = {An Inquiry Into Meaning and Truth: The William James Lectures for 1940 Delivered at Harvard University},
	year = {1995},
	abstract = {Russell examines the foundations of knowledge through a discussion of language and investigates the way a knowledge of the structure of language helps our understanding of the structure of the world.}
}

You also can do more than one search at a time. The parameter for each search should be demarcated with its own quotation marks. For a literal ", escape it with a backslash \".

$ gappi "@authors Stalnaker @title Presuppositions" "@authors Lewis @title \"scorekeeping in a language game\""
@article{Stalnaker1973-STAP-5,
	author = {Robert Stalnaker},
	title = {Presuppositions},
	year = {1973},
	journal = {Journal of Philosophical Logic},
	number = {4},
	volume = {2},
	pages = {447--457}
}

@article{Lewis1979-LEWSIA,
	author = {David Lewis},
	year = {1979},
	number = {1},
	title = {Scorekeeping in a Language Game},
	volume = {8},
	journal = {Journal of Philosophical Logic},
	pages = {339--359}
}

Proficient command-line users can do no doubt think of other things to do as well.

If there are no search results, gappi will just output a blank line.

Integration with editors such as vim

When I was a vim user, I added the following to my ~/.vimrc:

autocmd BufNewFile,BufRead *.bib nnoremap _ :r!gappi ""<Left>

When editing .bib files, this maps the underscore key to invoke gappi. I need only type my search parameters, and press enter, and the resulting record is inserted into my document.

Similar things could no doubt be programmed for other “smart” text editors which allow one to invoke external commands.

Limitations and frustrations

gappi is only as good as the PhilPapers search ranking algorithms and BibTeX export routine allow it to be. Unfortunately, these could be improved significantly. That PhilPapers never seems to include the address field for @Book entries is particularly annoying, as is its tendency to treat a book review as more relevant than the book itself. At least the latter can usually be circumvented with additional search parameters. However, it would be best for those of us with any technical know-how to stop complaining and volunteer to improve PhilPapers.

The script itself

Yes, this is the whole thing. The core of the program is two whopping lines of code.

#!/bin/bash
#
# Get A Phil Papers Item (gappi); version 0.4
# by Kevin C. Klement (klement@philos.umass.edu)
# With improvements by David Sanson
# Feel free to email Kevin with suggestions or questions
# License: GPLv3
#

# get the name of the script
SCRIPTNAME="$(basename "$0")"
 
# function to show usage info
usage_info() {
    cat > /dev/stderr << EOF
USAGE: $SCRIPTNAME [-n NN] "search item 1" "search item 2" ...
 
For each search item, gappi will fetch the BibTeX record
for the first [or first NN] PhilPapers result for that search item. Each
item's individual search parameters should be enclosed in quotes.

You can use the additional search parameters listed at.

    http://philpapers.org/help/search.html

E.g.:
$SCRIPTNAME "@authors Strawson @title On Referring"

Note that it is "@authors" with an s, not "@author", even
when there is only one.

Use an backslash escaped \" for a literal quotation mark.
EOF
}
MATCHES=1 # default number of matches to return

# if there are no search items given, then show usage info
if [[ "$#" == 0 ]] ; then
    usage_info
fi

# loop for each search item
while [[ "$#" -gt 0 ]] ; do
    # help users who ask for it
    if [[ "$1" == "-help" ]] ||
        [[ "$1" == "--help" ]] ||
        [[ "$1" == "-h" ]] ||
        [[ "$1" == "-?" ]] ; then
        usage_info
        exit 0
    fi
    # -n NN sets the number of matches to be returned
    if [[ "$1" == "-n" ]] ; then
        shift
        if [[ "$1" -gt 0 ]] ; then
            MATCHES="$1"
            shift
        else
            echo "The option '-n' must be followed by a positive integer." > /dev/stderr
            usage_info
            exit 1
        fi
    fi

    # replace spaces with %20 for URLS
    SEARCHSTRING="${1// /%20}"
    # get BibTeX entry for that match, send to stdout
    curl --silent --data-urlencode -G \
        -d "search_header=search_header.html&searchStr=$SEARCHSTRING&filterMode=keywords&limit=$MATCHES&newWindow=on&sort=relevance&showCategories=on&proOnly=on&format=bib" \
        "http://philpapers.org/asearch.pl" 
    # add a line of padding
    echo ""
    # move to next search item
    shift
done
exit 0

Improving gappi

If you have any suggestions for improvement, etc., or other feedback, email Kevin at klement@philos.umass.edu, or post to the LaTeXoSoPHeRs Facebook group. Also feel free to make your own improvements and post them, e.g., on pastebin, etc. Thanks to David Sanson for suggesting improvements to a previous version.

License

gappi is made available under the GNU/General Programming License (GPL) v3. You may edit it, redistribute it, etc., in any way you see fit.