Fl_Preferences.H

//
// Preferences implementation for the Fast Light Tool Kit (FLTK).
//
// Copyright 2002-2023 by Matthias Melcher.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file.  If this
// file is missing or damaged, see the license at:
//
//     https://www.fltk.org/COPYING.php
//
// Please see the following page on how to report bugs and issues:
//
//     https://www.fltk.org/bugs.php
//
 
/* \file
   Fl_Preferences class . */
 
#ifndef Fl_Preferences_H
#  define Fl_Preferences_H
 
#  include <stdio.h>
#  include "Fl_Export.H"
#  include "fl_attr.h"
 
//class Fl_String;
#if (FLTK_USE_STD)
#include <string>
#endif

class FL_EXPORT Fl_Preferences {
 
public:
  enum Root {
    UNKNOWN_ROOT_TYPE = -1,            
    SYSTEM            =  0,            
    USER,                              
    MEMORY,                            
    ROOT_MASK     = 0x00FF,            
    CORE          = 0x0100,            
    C_LOCALE      = 0x1000,            
    CLEAR         = 0x2000,            
    SYSTEM_L      = SYSTEM | C_LOCALE, 
    USER_L        = USER | C_LOCALE,   
    CORE_SYSTEM_L = CORE | SYSTEM_L,   
    CORE_USER_L   = CORE | USER_L,     
    CORE_SYSTEM   = CORE | SYSTEM,     
    CORE_USER     = CORE | USER        
  };

  typedef void *ID;
 
  static const char *new_UUID();

  static const unsigned int NONE = 0x0000;
  static const unsigned int USER_READ_OK = 0x0001;
  static const unsigned int USER_WRITE_OK = 0x0002;
  static const unsigned int USER_OK = USER_READ_OK | USER_WRITE_OK;
  static const unsigned int SYSTEM_READ_OK = 0x0004;
  static const unsigned int SYSTEM_WRITE_OK = 0x0008;
  static const unsigned int SYSTEM_OK = SYSTEM_READ_OK | SYSTEM_WRITE_OK;
  static const unsigned int APP_OK = SYSTEM_OK | USER_OK;
  static const unsigned int CORE_READ_OK = 0x0010;
  static const unsigned int CORE_WRITE_OK = 0x0020;
  static const unsigned int CORE_OK = CORE_READ_OK | CORE_WRITE_OK;
  static const unsigned int ALL_READ_OK = USER_READ_OK | SYSTEM_READ_OK | CORE_READ_OK;
  static const unsigned int ALL_WRITE_OK = USER_WRITE_OK | SYSTEM_WRITE_OK | CORE_WRITE_OK;
  static const unsigned int ALL = ALL_READ_OK | ALL_WRITE_OK;
 
  static void file_access(unsigned int flags);
  static unsigned int file_access();
  static Root filename( char *buffer, size_t buffer_size, Root root, const char *vendor, const char *application );
 
  Fl_Preferences( Root root, const char *vendor, const char *application );
  Fl_Preferences( const char *path, const char *vendor, const char *application, Root flags );
  Fl_Preferences( Fl_Preferences &parent, const char *group );
  Fl_Preferences( Fl_Preferences *parent, const char *group );
  Fl_Preferences( Fl_Preferences &parent, int groupIndex );
  Fl_Preferences( Fl_Preferences *parent, int groupIndex );
  Fl_Preferences(const Fl_Preferences&);
  Fl_Preferences( ID id );
  virtual ~Fl_Preferences();
 
  FL_DEPRECATED("since 1.4.0 - use Fl_Preferences(path, vendor, application, flags) instead",
                Fl_Preferences( const char *path, const char *vendor, const char *application ) );
 
  Root filename( char *buffer, size_t buffer_size);

  ID id() { return (ID)node; }

  static char remove(ID id_) { return ((Node*)id_)->remove(); }

  const char *name() { return node->name(); }

  const char *path() { return node->path(); }
 
  int groups();
  const char *group( int num_group );
  char group_exists( const char *key );
  char delete_group( const char *group );
  char delete_all_groups();
 
  int entries();
  const char *entry( int index );
  char entry_exists( const char *key );
  char delete_entry( const char *entry );
  char delete_all_entries();
 
  char clear();
 
  char set( const char *entry, int value );
  char set( const char *entry, float value );
  char set( const char *entry, float value, int precision );
  char set( const char *entry, double value );
  char set( const char *entry, double value, int precision );
  char set( const char *entry, const char *value );
  char set( const char *entry, const void *value, int size );
 
  char get( const char *entry, int &value, int defaultValue );
  char get( const char *entry, float &value,  float defaultValue );
  char get( const char *entry, double &value, double defaultValue );
  char get( const char *entry, char *&value,  const char *defaultValue );
  char get( const char *entry, char *value,   const char *defaultValue, int maxSize );
  char get( const char *entry, void *&value,  const void *defaultValue, int defaultSize );
  char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int maxSize );
  char get( const char *entry, void *value,   const void *defaultValue, int defaultSize, int *size );
 
//  char set( const char *entry, const Fl_String &value );
//  char get( const char *entry, Fl_String &value, const Fl_String &defaultValue );
 
#if (FLTK_USE_STD)
  char set( const char *entry, const std::string &value );
  char get( const char *entry, std::string &value, const std::string &defaultValue );
#endif
 
  int size( const char *entry );
 
  char get_userdata_path( char *path, int pathlen );
 
  int flush();
 
  int dirty();

  static const char *newUUID() { return new_UUID(); }
  char groupExists( const char *key ) { return group_exists(key); }
  char deleteGroup( const char *group ) { return delete_group(group); }
  char deleteAllGroups() { return delete_all_groups(); }
  char entryExists( const char *key ) { return entry_exists(key); }
  char deleteEntry( const char *entry ) { return delete_entry(entry); }
  char deleteAllEntries() { return delete_all_entries(); }
  char getUserdataPath( char *path, int pathlen ) { return get_userdata_path(path, pathlen); }

  class FL_EXPORT Name {
 
    char *data_;
 
  public:
    Name( unsigned int n );
    Name( const char *format, ... );

    operator const char *() { return data_; }
    ~Name();
  };

  struct Entry {
    char *name, *value;
  };
 
private:
  Fl_Preferences() : node(0), rootNode(0) { }
  Fl_Preferences &operator=(const Fl_Preferences&);
 
  static char nameBuffer[128];
  static char uuidBuffer[40];
  static Fl_Preferences *runtimePrefs;
  static unsigned int fileAccess_;
 
public:  // older Sun compilers need this (public definition of the following classes)
  class RootNode;
 
  class FL_EXPORT Node {        // a node contains a list to all its entries
                                // and all means to manage the tree structure
    Node *first_child_, *next_;
    union {                     // these two are mutually exclusive
      Node *parent_;            // top_ bit clear
      RootNode *root_node_;     // top_ bit set
    };
    char *path_;
    Entry *entry_;
    int nEntry_, NEntry_;
    unsigned char dirty_:1;
    unsigned char top_:1;
    unsigned char indexed_:1;
    // indexing routines
    Node **index_;
    int nIndex_, NIndex_;
    void createIndex();
    void updateIndex();
    void deleteIndex();
  public:
    static int lastEntrySet;
  public:
    Node( const char *path );
    ~Node();
    // node methods
    int write( FILE *f );
    const char *name();
    const char *path() { return path_; }
    Node *find( const char *path );
    Node *search( const char *path, int offset=0 );
    Node *childNode( int ix );
    Node *addChild( const char *path );
    void setParent( Node *parent );
    Node *parent() { return top_?0L:parent_; }
    void setRoot(RootNode *r) { root_node_ = r; top_ = 1; }
    RootNode *findRoot();
    char remove();
    char dirty();
    void clearDirtyFlags();
    void deleteAllChildren();
    // entry methods
    int nChildren();
    const char *child( int ix );
    void set( const char *name, const char *value );
    void set( const char *line );
    void add( const char *line );
    const char *get( const char *name );
    int getEntry( const char *name );
    char deleteEntry( const char *name );
    void deleteAllEntries();
    int nEntry() { return nEntry_; }
    Entry &entry(int i) { return entry_[i]; }
  };
  friend class Node;
 
  class FL_EXPORT RootNode {    // the root node manages file paths and basic reading and writing
    Fl_Preferences *prefs_;
    char *filename_;
    char *vendor_, *application_;
    Root root_type_;
  public:
    RootNode( Fl_Preferences *, Root root, const char *vendor, const char *application );
    RootNode( Fl_Preferences *, const char *path, const char *vendor, const char *application, Root flags );
    RootNode( Fl_Preferences * );
    ~RootNode();
    int read();
    int write();
    char getPath( char *path, int pathlen );
    char *filename() { return filename_; }
    Root root() { return root_type_; }
  };
  friend class RootNode;
 
protected:
  Node *node;
  RootNode *rootNode;
};
 
#endif // !Fl_Preferences_H