Merge branch 'release-2.140.101'
[feisty_meow.git] / 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