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