pintos-os.org Git - pspp/blob - src/output/driver-provider.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2007, 2009, 2010, 2012, 2014 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 #ifndef OUTPUT_DRIVER_PROVIDER_H
  18 #define OUTPUT_DRIVER_PROVIDER_H 1
  19
  20 #include <stdbool.h>
  21
  22 #include "data/settings.h"
  23 #include "libpspp/compiler.h"
  24 #include "output/driver.h"
  25
  26 struct output_item;
  27 struct output_iterator;
  28 struct string_map;
  29 struct file_handle;
  30 struct page_setup;
  31
  32 /* A configured output driver. */
  33 struct output_driver
  34   {
  35     const struct output_driver_class *class; /* Driver class. */
  36     char *name;                              /* Name of this driver. */
  37     enum settings_output_devices device_type; /* One of SETTINGS_DEVICE_*. */
  38   };
  39
  40 void output_driver_init (struct output_driver *,
  41                          const struct output_driver_class *,
  42                          const char *, enum settings_output_devices);
  43
  44 void output_driver_destroy (struct output_driver *);
  45
  46 const char *output_driver_get_name (const struct output_driver *);
  47
  48 char *output_driver_substitute_heading_vars (const char *, int page_number);
  49
  50 /* One kind of output driver.
  51
  52    Output driver implementations must not call msg() to report errors.  This
  53    can lead to reentrance in the output driver, because msg() may report error
  54    messages using the output drivers.  Instead, this code should report errors
  55    with error(), which will never call into the output drivers.  */
  56 struct output_driver_class
  57   {
  58     /* Name of this driver class. */
  59     const char *name;
  60
  61     /* Closes and frees DRIVER. */
  62     void (*destroy) (struct output_driver *driver);
  63
  64     /* Passes ITEM to DRIVER to be written as output.  The caller retains
  65        ownership of ITEM (but DRIVER may keep a copy of it by incrementing the
  66        reference count by calling output_item_ref). */
  67     void (*submit) (struct output_driver *driver,
  68                     const struct output_item *item);
  69
  70     /* Changes DRIVER's output page setup to PS, if possible.  This may be NUL
  71        if the driver doesn't support page setup. */
  72     void (*setup) (struct output_driver *driver, const struct page_setup *ps);
  73
  74     /* Ensures that any output items passed to the 'submit' function for DRIVER
  75        have actually been displayed.
  76
  77        This is called from the text-based UI before showing the command prompt,
  78        to ensure that the user has actually been shown any preceding output If
  79        it doesn't make sense for DRIVER to be used this way, then this function
  80        need not do anything. */
  81     void (*flush) (struct output_driver *driver);
  82
  83     /* Ordinarily, the core driver code will skip passing hidden output items
  84        to 'submit'.  If this member is true, the core driver hands them to the
  85        driver to let it handle them itself. */
  86     bool handles_show;
  87
  88     /* Ordinarily, the core driver code will flatten groups of output items
  89        before passing them to 'submit'.  If this member is true, the core
  90        driver code leaves them in place for the driver to handle. */
  91     bool handles_groups;
  92   };
  93
  94 /* An abstract way for the output subsystem to create an output driver. */
  95 struct output_driver_factory
  96   {
  97     /* The file extension, without the leading dot, e.g. "pdf". */
  98     const char *extension;
  99
 100     /* The default file name, including extension.
 101
 102        If this is "-", that implies that by default output will be directed to
 103        stdout. */
 104     const char *default_file_name;
 105
 106     /* Creates a new output driver of this class.  NAME and TYPE should be
 107        passed directly to output_driver_init.  Returns the new output driver if
 108        successful, otherwise a null pointer.
 109
 110        It is up to the driver class to decide how to interpret OPTIONS.  The
 111        create function should delete pairs that it understands from OPTIONS,
 112        because the caller may issue errors about unknown options for any pairs
 113        that remain.  The functions in output/options.h can be useful.
 114
 115        The returned driver should not have been registered (with
 116        output_driver_register).  The caller will register the driver (if this
 117        is desirable). */
 118     struct output_driver *(*create) (struct file_handle *,
 119                                      enum settings_output_devices type,
 120                                      struct string_map *options);
 121   };
 122
 123 #endif /* output/driver-provider.h */