nucleus/applications/nechung/nechung_oracle.h

   1 #ifndef NECHUNG_CLASS
   2 #define NECHUNG_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : nechung_oracle                                                    *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *  Purpose:                                                                   *
  10 *                                                                             *
  11 *    This is the root nechung functionality.  It provides a means of          *
  12 *  randomly selecting an item out of a specially formatted file.  If no index *
  13 *  file has previously been built for the file, then one is created.  The     *
  14 *  index file makes choosing a fortune randomly very quick; only a seek on    *
  15 *  the much smaller index is needed in order to find the position of the      *
  16 *  fortune to be shown.                                                       *
  17 *                                                                             *
  18 *******************************************************************************
  19 * Copyright (c) 1991-$now By Author.  This program is free software; you can  *
  20 * redistribute it and/or modify it under the terms of the GNU General Public  *
  21 * License as published by the Free Software Foundation; either version 2 of   *
  22 * the License or (at your option) any later version.  This is online at:      *
  23 *     http://www.fsf.org/copyleft/gpl.html                                    *
  24 * Please send any updates to: fred@gruntose.com                               *
  25 \*****************************************************************************/
  26
  27 // Nechung works with a particular form of data file and will extract a random
  28 // and hopefully auspicious message out of that file.  An example of the file
  29 // format is:
  30 //   msg1
  31 //   ~
  32 //   msg2
  33 //   ~
  34 //   (... more messages and tildes...)
  35 // The tilde is the separation character mentioned below.
  36
  37 #include <basis/astring.h>
  38 #include <mathematics/chaos.h>
  39
  40 //#define DEBUG_NECHUNG
  41   // uncomment this to get the debugging version.  it is used by several files
  42   // that are part of nechung.
  43
  44 const char NECHUNG_SEPARATION_CHARACTER = '~';
  45   // this character separates the entries in the fortunes database.
  46
  47 class nechung_oracle
  48 {
  49 public:
  50   nechung_oracle(const basis::astring &data_filename, const basis::astring &index_filename);
  51     // the constructor needs the name of a nechung format data file in
  52     // "data_filename" and the name of the index file to be used for that data
  53     // file in "index_filename".
  54
  55   virtual ~nechung_oracle();
  56
  57   DEFINE_CLASS_NAME("nechung_oracle");
  58
  59   basis::astring pick_random();
  60     // returns a randomly chosen fortune.
  61
  62   void display_random();
  63     // selects an oracular pronouncement from the file and then shows it on
  64     // standard output.
  65
  66 private:
  67   mathematics::chaos c_randomizer;  // the random number generator we use.
  68   basis::astring c_filename_held;  // the data file's name.
  69   basis::astring c_index_held;  // the index file's name.
  70   int c_number_of_fortunes;  // how many fortunes exist in the file.
  71
  72   void parse_file();
  73     // given the data file and index file, this will ensure that the index
  74     // file is made up to date.  it creates, if necessary, the file that
  75     // contains the positions of fortunes in the data file.  this is what
  76     // we'll use to find the start of each fortune.  if the file already
  77     // exists, then it will just retrieve the number of fortunes from the index
  78     // file.  after this method, the pick_random() and display_random() methods
  79     // are available.
  80
  81   // disallowed.
  82   nechung_oracle(const nechung_oracle &);
  83   nechung_oracle &operator =(const nechung_oracle &);
  84 };
  85
  86 #endif
  87