src/insets/InsetCitation.cpp

   1 /**
   2  * \file InsetCitation.cpp
   3  * This file is part of LyX, the document processor.
   4  * Licence details can be found in the file COPYING.
   5  *
   6  * \author Angus Leeming
   7  * \author Herbert Voß
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  */
  11
  12 #include <config.h>
  13
  14 #include "InsetCitation.h"
  15
  16 #include "Buffer.h"
  17 #include "BufferParams.h"
  18 #include "debug.h"
  19 #include "DispatchResult.h"
  20 #include "FuncRequest.h"
  21 #include "LaTeXFeatures.h"
  22
  23 #include "support/fs_extras.h"
  24 #include "support/lstrings.h"
  25
  26 #include <algorithm>
  27
  28 #include <boost/filesystem/operations.hpp>
  29 #include <boost/filesystem/exception.hpp>
  30
  31
  32 namespace lyx {
  33
  34 using support::FileName;
  35 using support::getStringFromVector;
  36 using support::getVectorFromString;
  37 using support::ltrim;
  38 using support::prefixIs;
  39 using support::rtrim;
  40 using support::split;
  41 using support::tokenPos;
  42
  43 using std::endl;
  44 using std::string;
  45 using std::vector;
  46
  47 namespace fs = boost::filesystem;
  48
  49
  50 namespace {
  51
  52 vector<string> const init_possible_cite_commands()
  53 {
  54         char const * const possible[] = {
  55                 "cite", "citet", "citep", "citealt", "citealp",
  56                 "citeauthor", "citeyear", "citeyearpar",
  57                 "citet*", "citep*", "citealt*", "citealp*", "citeauthor*",
  58                 "Citet",  "Citep",  "Citealt",  "Citealp",  "Citeauthor",
  59                 "Citet*", "Citep*", "Citealt*", "Citealp*", "Citeauthor*",
  60                 "fullcite",
  61                 "footcite", "footcitet", "footcitep", "footcitealt",
  62                 "footcitealp", "footciteauthor", "footciteyear", "footciteyearpar",
  63                 "citefield", "citetitle", "cite*"
  64         };
  65         size_t const size_possible = sizeof(possible) / sizeof(possible[0]);
  66
  67         return vector<string>(possible, possible + size_possible);
  68 }
  69
  70
  71 vector<string> const & possible_cite_commands()
  72 {
  73         static vector<string> const possible = init_possible_cite_commands();
  74         return possible;
  75 }
  76
  77
  78 //FIXME See the header for the issue.
  79 string const default_cite_command(biblio::CiteEngine engine)
  80 {
  81         string str;
  82         switch (engine) {
  83                 case biblio::ENGINE_BASIC:
  84                         str = "cite";
  85                         break;
  86                 case biblio::ENGINE_NATBIB_AUTHORYEAR:
  87                         str = "citet";
  88                         break;
  89                 case biblio::ENGINE_NATBIB_NUMERICAL:
  90                         str = "citep";
  91                         break;
  92                 case biblio::ENGINE_JURABIB:
  93                         str = "cite";
  94                         break;
  95         }
  96         return str;
  97 }
  98
  99
 100 string const
 101                 asValidLatexCommand(string const & input, biblio::CiteEngine const engine)
 102 {
 103         string const default_str = default_cite_command(engine);
 104         if (!InsetCitation::isCompatibleCommand(input))
 105                 return default_str;
 106
 107         string output;
 108         switch (engine) {
 109                 case biblio::ENGINE_BASIC:
 110                         output = default_str;
 111                         break;
 112
 113                 case biblio::ENGINE_NATBIB_AUTHORYEAR:
 114                 case biblio::ENGINE_NATBIB_NUMERICAL:
 115                         if (input == "cite" || input == "citefield" ||
 116                                                         input == "citetitle" || input == "cite*")
 117                                 output = default_str;
 118                         else if (prefixIs(input, "foot"))
 119                                 output = input.substr(4);
 120                         else
 121                                 output = input;
 122                         break;
 123
 124                 case biblio::ENGINE_JURABIB: {
 125                         // Jurabib does not support the 'uppercase' natbib style.
 126                         if (input[0] == 'C')
 127                                 output = string(1, 'c') + input.substr(1);
 128                         else
 129                                 output = input;
 130
 131                         // Jurabib does not support the 'full' natbib style.
 132                         string::size_type const n = output.size() - 1;
 133                         if (output != "cite*" && output[n] == '*')
 134                                 output = output.substr(0, n);
 135
 136                         break;
 137                 }
 138         }
 139
 140         return output;
 141 }
 142
 143
 144 docstring const getNatbibLabel(Buffer const & buffer,
 145                             string const & citeType, docstring const & keyList,
 146                             docstring const & before, docstring const & after,
 147                             biblio::CiteEngine engine)
 148 {
 149         // Only start the process off after the buffer is loaded from file.
 150         if (!buffer.isFullyLoaded())
 151                 return docstring();
 152
 153         // Cache the labels
 154         typedef std::map<Buffer const *, BiblioInfo> CachedMap;
 155         static CachedMap cached_keys;
 156
 157         // and cache the timestamp of the bibliography files.
 158         static std::map<FileName, time_t> bibfileStatus;
 159
 160         BiblioInfo biblist;
 161
 162         vector<FileName> const & bibfilesCache = buffer.getBibfilesCache();
 163         // compare the cached timestamps with the actual ones.
 164         bool changed = false;
 165         for (vector<FileName>::const_iterator it = bibfilesCache.begin();
 166                         it != bibfilesCache.end(); ++ it) {
 167                 FileName const f = *it;
 168                 try {
 169                         std::time_t lastw = f.lastModified();
 170                         if (lastw != bibfileStatus[f]) {
 171                                 changed = true;
 172                                 bibfileStatus[f] = lastw;
 173                         }
 174                 }
 175                 catch (fs::filesystem_error & fserr) {
 176                         changed = true;
 177                         lyxerr << "Couldn't find or read bibtex file "
 178                                << f << endl;
 179                         LYXERR(Debug::DEBUG) << "Fs error: "
 180                                              << fserr.what() << endl;
 181                 }
 182         }
 183
 184         // build the list only if the bibfiles have been changed
 185         if (cached_keys[&buffer].empty() || bibfileStatus.empty() || changed) {
 186                 biblist.fillWithBibKeys(&buffer);
 187                 cached_keys[&buffer] = biblist;
 188         } else {
 189                 // use the cached keys
 190                 biblist = cached_keys[&buffer];
 191         }
 192
 193         if (biblist.empty())
 194                 return docstring();
 195
 196         // the natbib citation-styles
 197         // CITET:       author (year)
 198         // CITEP:       (author,year)
 199         // CITEALT:     author year
 200         // CITEALP:     author, year
 201         // CITEAUTHOR:  author
 202         // CITEYEAR:    year
 203         // CITEYEARPAR: (year)
 204         // jurabib supports these plus
 205         // CITE:        author/<before field>
 206
 207         // We don't currently use the full or forceUCase fields.
 208         string cite_type = asValidLatexCommand(citeType, engine);
 209         if (cite_type[0] == 'C')
 210                 //If we were going to use them, this would mean ForceUCase
 211                 cite_type = string(1, 'c') + cite_type.substr(1);
 212         if (cite_type[cite_type.size() - 1] == '*')
 213                 //and this would mean FULL
 214                 cite_type = cite_type.substr(0, cite_type.size() - 1);
 215
 216         docstring before_str;
 217         if (!before.empty()) {
 218                 // In CITET and CITEALT mode, the "before" string is
 219                 // attached to the label associated with each and every key.
 220                 // In CITEP, CITEALP and CITEYEARPAR mode, it is attached
 221                 // to the front of the whole only.
 222                 // In other modes, it is not used at all.
 223                 if (cite_type == "citet" ||
 224                     cite_type == "citealt" ||
 225                     cite_type == "citep" ||
 226                     cite_type == "citealp" ||
 227                     cite_type == "citeyearpar")
 228                         before_str = before + ' ';
 229                 // In CITE (jurabib), the "before" string is used to attach
 230                 // the annotator (of legal texts) to the author(s) of the
 231                 // first reference.
 232                 else if (cite_type == "cite")
 233                         before_str = '/' + before;
 234         }
 235
 236         docstring after_str;
 237         if (!after.empty()) {
 238                 // The "after" key is appended only to the end of the whole.
 239                 after_str = ", " + after;
 240         }
 241
 242         // One day, these might be tunable (as they are in BibTeX).
 243         char const op  = '('; // opening parenthesis.
 244         char const cp  = ')'; // closing parenthesis.
 245         // puctuation mark separating citation entries.
 246         char const * const sep = ";";
 247
 248         docstring const op_str = ' ' + docstring(1, op);
 249         docstring const cp_str = docstring(1, cp) + ' ';
 250         docstring const sep_str = from_ascii(sep) + ' ';
 251
 252         docstring label;
 253         vector<docstring> keys = getVectorFromString(keyList);
 254         vector<docstring>::const_iterator it  = keys.begin();
 255         vector<docstring>::const_iterator end = keys.end();
 256         for (; it != end; ++it) {
 257                 // get the bibdata corresponding to the key
 258                 docstring const author(biblist.getAbbreviatedAuthor(*it));
 259                 docstring const year(biblist.getYear(*it));
 260
 261                 // Something isn't right. Fail safely.
 262                 if (author.empty() || year.empty())
 263                         return docstring();
 264
 265                 // authors1/<before>;  ... ;
 266                 //  authors_last, <after>
 267                 if (cite_type == "cite" && engine == biblio::ENGINE_JURABIB) {
 268                         if (it == keys.begin())
 269                                 label += author + before_str + sep_str;
 270                         else
 271                                 label += author + sep_str;
 272
 273                 // (authors1 (<before> year);  ... ;
 274                 //  authors_last (<before> year, <after>)
 275                 } else if (cite_type == "citet") {
 276                         switch (engine) {
 277                         case biblio::ENGINE_NATBIB_AUTHORYEAR:
 278                                 label += author + op_str + before_str +
 279                                         year + cp + sep_str;
 280                                 break;
 281                         case biblio::ENGINE_NATBIB_NUMERICAL:
 282                                 label += author + op_str + before_str + '#' + *it + cp + sep_str;
 283                                 break;
 284                         case biblio::ENGINE_JURABIB:
 285                                 label += before_str + author + op_str +
 286                                         year + cp + sep_str;
 287                                 break;
 288                         case biblio::ENGINE_BASIC:
 289                                 break;
 290                         }
 291
 292                 // author, year; author, year; ...
 293                 } else if (cite_type == "citep" ||
 294                            cite_type == "citealp") {
 295                         if (engine == biblio::ENGINE_NATBIB_NUMERICAL) {
 296                                 label += *it + sep_str;
 297                         } else {
 298                                 label += author + ", " + year + sep_str;
 299                         }
 300
 301                 // (authors1 <before> year;
 302                 //  authors_last <before> year, <after>)
 303                 } else if (cite_type == "citealt") {
 304                         switch (engine) {
 305                         case biblio::ENGINE_NATBIB_AUTHORYEAR:
 306                                 label += author + ' ' + before_str +
 307                                         year + sep_str;
 308                                 break;
 309                         case biblio::ENGINE_NATBIB_NUMERICAL:
 310                                 label += author + ' ' + before_str + '#' + *it + sep_str;
 311                                 break;
 312                         case biblio::ENGINE_JURABIB:
 313                                 label += before_str + author + ' ' +
 314                                         year + sep_str;
 315                                 break;
 316                         case biblio::ENGINE_BASIC:
 317                                 break;
 318                         }
 319
 320                 // author; author; ...
 321                 } else if (cite_type == "citeauthor") {
 322                         label += author + sep_str;
 323
 324                 // year; year; ...
 325                 } else if (cite_type == "citeyear" ||
 326                            cite_type == "citeyearpar") {
 327                         label += year + sep_str;
 328                 }
 329         }
 330         label = rtrim(rtrim(label), sep);
 331
 332         if (!after_str.empty()) {
 333                 if (cite_type == "citet") {
 334                         // insert "after" before last ')'
 335                         label.insert(label.size() - 1, after_str);
 336                 } else {
 337                         bool const add =
 338                                 !(engine == biblio::ENGINE_NATBIB_NUMERICAL &&
 339                                   (cite_type == "citeauthor" ||
 340                                    cite_type == "citeyear"));
 341                         if (add)
 342                                 label += after_str;
 343                 }
 344         }
 345
 346         if (!before_str.empty() && (cite_type == "citep" ||
 347                                     cite_type == "citealp" ||
 348                                     cite_type == "citeyearpar")) {
 349                 label = before_str + label;
 350         }
 351
 352         if (cite_type == "citep" || cite_type == "citeyearpar")
 353                 label = op + label + cp;
 354
 355         return label;
 356 }
 357
 358
 359 docstring const getBasicLabel(docstring const & keyList, docstring const & after)
 360 {
 361         using support::contains;
 362
 363         docstring keys = keyList;
 364         docstring label;
 365
 366         if (contains(keys, ',')) {
 367                 // Final comma allows while loop to cover all keys
 368                 keys = ltrim(split(keys, label, ',')) + ',';
 369                 while (contains(keys, ',')) {
 370                         docstring key;
 371                         keys = ltrim(split(keys, key, ','));
 372                         label += ", " + key;
 373                 }
 374         } else
 375                 label = keys;
 376
 377         if (!after.empty())
 378                 label += ", " + after;
 379
 380         return '[' + label + ']';
 381 }
 382
 383 } // anon namespace
 384
 385
 386 InsetCitation::InsetCitation(InsetCommandParams const & p)
 387         : InsetCommand(p, "citation")
 388 {}
 389
 390
 391 CommandInfo const * InsetCitation::findInfo(std::string const & /* cmdName */)
 392 {
 393         // standard cite does only take one argument if jurabib is
 394         // not used, but jurabib extends this to two arguments, so
 395         // we have to allow both here. InsetCitation takes care that
 396         // LaTeX output is nevertheless correct.
 397         static const char * const paramnames[] =
 398                 {"after", "before", "key", ""};
 399         static const bool isoptional[] = {true, true, false};
 400         static const CommandInfo info = {3, paramnames, isoptional};
 401         return &info;
 402 }
 403
 404
 405 bool InsetCitation::isCompatibleCommand(std::string const & cmd)
 406 {
 407         vector<string> const & possibles = possible_cite_commands();
 408         vector<string>::const_iterator const end = possibles.end();
 409         return std::find(possibles.begin(), end, cmd) != end;
 410 }
 411
 412
 413 docstring const InsetCitation::generateLabel(Buffer const & buffer) const
 414 {
 415         docstring const before = getParam("before");
 416         docstring const after  = getParam("after");
 417
 418         docstring label;
 419         biblio::CiteEngine const engine = buffer.params().getEngine();
 420         if (engine != biblio::ENGINE_BASIC) {
 421                 label = getNatbibLabel(buffer, getCmdName(), getParam("key"),
 422                                        before, after, engine);
 423         }
 424
 425         // Fallback to fail-safe
 426         if (label.empty()) {
 427                 label = getBasicLabel(getParam("key"), after);
 428         }
 429
 430         return label;
 431 }
 432
 433
 434 docstring const InsetCitation::getScreenLabel(Buffer const & buffer) const
 435 {
 436         biblio::CiteEngine const engine = buffer.params().getEngine();
 437         if (cache.params == params() && cache.engine == engine)
 438                 return cache.screen_label;
 439
 440         // The label has changed, so we have to re-create it.
 441         docstring const glabel = generateLabel(buffer);
 442
 443         unsigned int const maxLabelChars = 45;
 444
 445         docstring label = glabel;
 446         if (label.size() > maxLabelChars) {
 447                 label.erase(maxLabelChars-3);
 448                 label += "...";
 449         }
 450
 451         cache.engine  = engine;
 452         cache.params = params();
 453         cache.generated_label = glabel;
 454         cache.screen_label = label;
 455
 456         return label;
 457 }
 458
 459
 460 int InsetCitation::plaintext(Buffer const & buffer, odocstream & os,
 461                              OutputParams const &) const
 462 {
 463         docstring str;
 464
 465         if (cache.params == params() &&
 466             cache.engine == buffer.params().getEngine())
 467                 str = cache.generated_label;
 468         else
 469                 str = generateLabel(buffer);
 470
 471         os << str;
 472         return str.size();
 473 }
 474
 475
 476 static docstring const cleanupWhitespace(docstring const & citelist)
 477 {
 478         docstring::const_iterator it  = citelist.begin();
 479         docstring::const_iterator end = citelist.end();
 480         // Paranoia check: make sure that there is no whitespace in here
 481         // -- at least not behind commas or at the beginning
 482         docstring result;
 483         char_type last = ',';
 484         for (; it != end; ++it) {
 485                 if (*it != ' ')
 486                         last = *it;
 487                 if (*it != ' ' || last != ',')
 488                         result += *it;
 489         }
 490         return result;
 491 }
 492
 493
 494 int InsetCitation::docbook(Buffer const &, odocstream & os,
 495                            OutputParams const &) const
 496 {
 497         os << "<citation>"
 498            << cleanupWhitespace(getParam("key"))
 499            << "</citation>";
 500         return 0;
 501 }
 502
 503
 504 int InsetCitation::textString(Buffer const & buf, odocstream & os,
 505                        OutputParams const & op) const
 506 {
 507         return plaintext(buf, os, op);
 508 }
 509
 510
 511 // Have to overwrite the default InsetCommand method in order to check that
 512 // the \cite command is valid. Eg, the user has natbib enabled, inputs some
 513 // citations and then changes his mind, turning natbib support off. The output
 514 // should revert to \cite[]{}
 515 int InsetCitation::latex(Buffer const & buffer, odocstream & os,
 516                          OutputParams const &) const
 517 {
 518         biblio::CiteEngine cite_engine = buffer.params().getEngine();
 519         // FIXME UNICODE
 520         docstring const cite_str = from_utf8(
 521                 asValidLatexCommand(getCmdName(), cite_engine));
 522
 523         os << "\\" << cite_str;
 524
 525         docstring const & before = getParam("before");
 526         docstring const & after  = getParam("after");
 527         if (!before.empty() && cite_engine != biblio::ENGINE_BASIC)
 528                 os << '[' << before << "][" << after << ']';
 529         else if (!after.empty())
 530                 os << '[' << after << ']';
 531
 532         os << '{' << cleanupWhitespace(getParam("key")) << '}';
 533
 534         return 0;
 535 }
 536
 537
 538 void InsetCitation::validate(LaTeXFeatures & features) const
 539 {
 540         switch (features.bufferParams().getEngine()) {
 541         case biblio::ENGINE_BASIC:
 542                 break;
 543         case biblio::ENGINE_NATBIB_AUTHORYEAR:
 544         case biblio::ENGINE_NATBIB_NUMERICAL:
 545                 features.require("natbib");
 546                 break;
 547         case biblio::ENGINE_JURABIB:
 548                 features.require("jurabib");
 549                 break;
 550         }
 551 }
 552
 553
 554 } // namespace lyx