ELinks 0.16.1.1
options.h File Reference
#include "main/object.h"
#include "util/color.h"
#include "util/lists.h"
#include "util/memory.h"
#include "util/string.h"
Include dependency graph for options.h:

Data Structures

union  option_value
struct  option
struct  change_hook_info
struct  option_resolver
 Some minimal option cache. More...
struct  option_init
 How to initialize and register struct option. More...
union  option_info
 Instructions for registering an option, and storage for the option itself. More...

Macros

#define option   option_elinks
#define get_opt(tree, name, ses, type)
#define get_opt_bool_tree(tree, name, ses)
#define get_opt_int_tree(tree, name, ses)
#define get_opt_long_tree(tree, name, ses)
#define get_opt_str_tree(tree, name, ses)
#define get_opt_codepage_tree(tree, name, ses)
#define get_opt_color_tree(tree, name, ses)
#define get_opt_tree_tree(tree_, name, ses)
#define get_opt_bool(name, ses)
#define get_opt_int(name, ses)
#define get_opt_long(name, ses)
#define get_opt_str(name, ses)
#define get_opt_codepage(name, ses)
#define get_opt_color(name, ses)
#define get_opt_tree(name, ses)
#define get_cmd_opt_bool(name)
#define get_cmd_opt_int(name)
#define get_cmd_opt_long(name)
#define get_cmd_opt_str(name)
#define get_cmd_opt_codepage(name)
#define get_cmd_opt_color(name)
#define get_cmd_opt_tree(name)
#define is_option_name_char(c)
 Check whether the character c may be used in the name of an option.
#define DESC(x)

Typedefs

typedef unsigned short option_flags_T
typedef const char * option_command_fn_T(struct option *option, char ***argv, int *argc)
 Called when an OPT_COMMAND option is found in the command line.
typedef int(* change_hook_T) (struct session *session, struct option *current, struct option *changed)
 To be called when the option (or sub-option if it's a tree) is changed.

Enumerations

enum  option_flags {
  OPT_ZERO = 0 , OPT_HIDDEN = 1 , OPT_AUTOCREATE = 2 , OPT_MUST_SAVE = 4 ,
  OPT_TOUCHED = 8 , OPT_LISTBOX = 16 , OPT_ALLOC = 32 , OPT_SORT = 64 ,
  OPT_DELETED = 128 , OPT_ALIAS_NEGATE = 256
}
 Flags used in the option.flags bitmask. More...
enum  option_type {
  OPT_BOOL = 0 , OPT_INT , OPT_LONG , OPT_STRING ,
  OPT_CODEPAGE , OPT_LANGUAGE , OPT_COLOR , OPT_COMMAND ,
  OPT_ALIAS , OPT_TREE
}
enum  copy_option_flags { CO_NO_LISTBOX_ITEM = (1 << 0) , CO_SHALLOW = (1 << 1) }
enum  referer { REFERER_NONE , REFERER_SAME_URL , REFERER_FAKE , REFERER_TRUE }
enum  verbose_level { VERBOSE_QUIET , VERBOSE_WARNINGS , VERBOSE_ALL , VERBOSE_LEVELS }

Functions

void init_options (void)
void done_options (void)
void register_change_hooks (const struct change_hook_info *change_hooks)
struct option listinit_options_tree (void)
void prepare_mustsave_flags (struct option list *, int set_all)
void untouch_options (struct option list *)
void smart_config_string (struct string *, int, int, struct option list *, char *, int, void(*)(struct string *, struct option *, char *, int, int, int, int))
struct optioncopy_option (struct option *, int)
struct optionget_option_shadow (struct option *, struct option *, struct option *)
 Return the shadow option in shadow_tree of option in tree.
void delete_option (struct option *)
void mark_option_as_deleted (struct option *)
void update_options_visibility (void)
 Update the visibility of the box item of each option in config_options to honour the value of config.show_template.
int commit_option_values (struct option_resolver *resolvers, struct option *root, union option_value *values, int size)
void checkout_option_values (struct option_resolver *resolvers, struct option *root, union option_value *values, int size)
struct optionget_opt_rec (struct option *, const char *)
struct optionget_opt_rec_real (struct option *, const char *)
struct optionindirect_option (struct option *)
union option_valueget_opt_ (char *, int, enum option_type, struct option *, const char *, struct session *)
struct optionadd_opt (struct option *, const char *, const char *, const char *, option_flags_T, enum option_type, long, long, longptr_T, const char *)
void register_options (union option_info info[], struct option *tree)
void unregister_options (union option_info info[], struct option *tree)
int get_https_by_default (void)
const char * get_default_protocol (void)

Variables

struct optionconfig_options
struct optioncmdline_options

Macro Definition Documentation

◆ DESC

#define DESC ( x)
Value:
(x)

◆ get_cmd_opt_bool

#define get_cmd_opt_bool ( name)
Value:
struct option * cmdline_options
Definition options.c:80
#define get_opt_bool_tree(tree, name, ses)
Definition options.h:315
#define NULL
Definition explodename.c:35

◆ get_cmd_opt_codepage

#define get_cmd_opt_codepage ( name)
Value:
#define get_opt_codepage_tree(tree, name, ses)
Definition options.h:319

◆ get_cmd_opt_color

#define get_cmd_opt_color ( name)
Value:
#define get_opt_color_tree(tree, name, ses)
Definition options.h:320

◆ get_cmd_opt_int

#define get_cmd_opt_int ( name)
Value:
#define get_opt_int_tree(tree, name, ses)
Definition options.h:316

◆ get_cmd_opt_long

#define get_cmd_opt_long ( name)
Value:
#define get_opt_long_tree(tree, name, ses)
Definition options.h:317

◆ get_cmd_opt_str

#define get_cmd_opt_str ( name)
Value:
#define get_opt_str_tree(tree, name, ses)
Definition options.h:318

◆ get_cmd_opt_tree

#define get_cmd_opt_tree ( name)
Value:
#define get_opt_tree_tree(tree_, name, ses)
Definition options.h:321

◆ get_opt

#define get_opt ( tree,
name,
ses,
type )
Value:
get_opt_(__FILE__, __LINE__, type, tree, name, ses)
union option_value * get_opt_(char *, int, enum option_type, struct option *, const char *, struct session *)
const char * type
Definition download.c:1812

◆ get_opt_bool

#define get_opt_bool ( name,
ses )
Value:
struct option * config_options
Definition options.c:79

◆ get_opt_bool_tree

#define get_opt_bool_tree ( tree,
name,
ses )
Value:
get_opt(tree, name, ses, OPT_BOOL)->number
@ OPT_BOOL
Definition options.h:104
#define get_opt(tree, name, ses, type)
Definition options.h:309

◆ get_opt_codepage

#define get_opt_codepage ( name,
ses )

◆ get_opt_codepage_tree

#define get_opt_codepage_tree ( tree,
name,
ses )
Value:
get_opt(tree, name, ses, OPT_CODEPAGE)->number
@ OPT_CODEPAGE
Definition options.h:109

◆ get_opt_color

#define get_opt_color ( name,
ses )

◆ get_opt_color_tree

#define get_opt_color_tree ( tree,
name,
ses )
Value:
get_opt(tree, name, ses, OPT_COLOR)->color
@ OPT_COLOR
Definition options.h:111

◆ get_opt_int

#define get_opt_int ( name,
ses )
Value:

◆ get_opt_int_tree

#define get_opt_int_tree ( tree,
name,
ses )
Value:
get_opt(tree, name, ses, OPT_INT)->number
@ OPT_INT
Definition options.h:105

◆ get_opt_long

#define get_opt_long ( name,
ses )
Value:

◆ get_opt_long_tree

#define get_opt_long_tree ( tree,
name,
ses )
Value:
get_opt(tree, name, ses, OPT_LONG)->big_number
@ OPT_LONG
Definition options.h:106

◆ get_opt_str

#define get_opt_str ( name,
ses )
Value:

◆ get_opt_str_tree

#define get_opt_str_tree ( tree,
name,
ses )
Value:
get_opt(tree, name, ses, OPT_STRING)->string
@ OPT_STRING
Definition options.h:107

◆ get_opt_tree

#define get_opt_tree ( name,
ses )
Value:

◆ get_opt_tree_tree

#define get_opt_tree_tree ( tree_,
name,
ses )
Value:
get_opt(tree_, name, ses, OPT_TREE)->tree
@ OPT_TREE
Definition options.h:117

◆ is_option_name_char

#define is_option_name_char ( c)
Value:
(isasciialnum(c) || (c) == '_' \
|| (c) == '-' || (c) == '+' || (c) == '*')
#define isasciialnum(c)
Definition string.h:138

Check whether the character c may be used in the name of an option.

This does not allow the '.' used in multi-part names like "config.comments". If you want to allow that too, check for it separately.

If you modify this, please update the error message in check_option_name().

◆ option

#define option   option_elinks

Typedef Documentation

◆ change_hook_T

typedef int(* change_hook_T) (struct session *session, struct option *current, struct option *changed)

To be called when the option (or sub-option if it's a tree) is changed.

Parameters
sessionis the session via which the user changed the options, or NULL if not known. Because the options are currently not session-specific, it is best to ignore this parameter. In a future version of ELinks, this parameter might mean the session to which the changed options apply.
currentis the option whose change hook is being called. It is never NULL.
changedis the option that was changed, or NULL if multiple descendants of current may have been changed.
Returns
If it returns zero, we will continue descending the options tree checking for change handlers.

◆ option_command_fn_T

typedef const char * option_command_fn_T(struct option *option, char ***argv, int *argc)

Called when an OPT_COMMAND option is found in the command line.

Parameters
optionThe option that was named in the command line, either directly or via an OPT_ALIAS. Its option.type is OPT_COMMAND, and its option_value.command points to this function.
[in,out]argvThe next arguments to be parsed from the command line. This function can consume some of those arguments by incremenenting *argv and decrementing *argc.
[in,out]argcNumber of arguments remaining in the command line.
Returns
NULL if successful, or a localized error string that the caller will not free.

◆ option_flags_T

typedef unsigned short option_flags_T

Enumeration Type Documentation

◆ copy_option_flags

Enumerator
CO_NO_LISTBOX_ITEM 
CO_SHALLOW 

◆ option_flags

Flags used in the option.flags bitmask.

Enumerator
OPT_ZERO 
OPT_HIDDEN 

The option is hidden - it serves for internal purposes, never is read, never is written, never is displayed, never is crawled through etc.

OPT_AUTOCREATE 

For OPT_TREE, automatically create missing hiearchy piece just under this category when adding an option.

The 'template' for the added hiearchy piece (category) is stored as "_template_" category.

OPT_MUST_SAVE 

The option has been modified in some way and must be saved to elinks.conf.

ELinks uses this flag only while it is saving the options. When the "config.saving_style" option has value 3, saving works like this:

  1. First, ELinks sets OPT_MUST_SAVE in the options that have OPT_TOUCHED or OPT_DELETED, and clears it in the rest.
  2. ELinks then parses the old configuration file and any files named in "include" commands.
    • While parsing the old configuration file itself, ELinks copies the commands and comments from it to the new configuration file (actually just a string variable in this phase). However, if the old configuration file contains a "set" or "unset" command for this option, then instead of copying the command as is, ELinks rewrites it to match the current value of the option and clears OPT_MUST_SAVE.
    • While parsing included files, ELinks does not copy the commands anywhere. (It never automatically modifies included configuration files.) However, it still looks for "set" and "unset" commands for this option. If it finds any, it compares the value of the option to the value given in the command. ELinks clears OPT_MUST_SAVE if the values match, or sets it if they differ.
  3. After ELinks has rewritten the configuration file and parsed the included files, it appends the options that still have the OPT_MUST_SAVE flag.

Other saving styles are variants of this:

OPT_TOUCHED 

This is used to mark options modified after the last save.

That's being useful if you want to save only the options whose value changed.

OPT_LISTBOX 

If set on the tree argument to add_opt (not necessarily the direct parent) or on the option itself, it will create the listbox (options manager) item for the option.

OPT_ALLOC 

This is used to mark that the option and the option name is allocated and should be freed when the option is released.

OPT_SORT 

For OPT_TREE, automatically sort the content of the tree alphabetically (but all subtrees in front of ordinary options) when adding new options.

Note that this applies only to the one level below - it will not apply to the sub-trees in this tree. Also, this can be quite expensive for busy-adding big trees, so think twice before doing it - in fact, it is supposed to be used only where you add stuff from more modules, not all at once; typically the config_options root tree. Especially NOT RECOMMENDED to be used on the template trees.

OPT_DELETED 

This is used to mark option as deleted.

OPT_ALIAS_NEGATE 

Specifies that values of boolean aliases should be inverted.

◆ option_type

Enumerator
OPT_BOOL 
OPT_INT 
OPT_LONG 
OPT_STRING 
OPT_CODEPAGE 
OPT_LANGUAGE 
OPT_COLOR 
OPT_COMMAND 
OPT_ALIAS 
OPT_TREE 

◆ referer

enum referer
Enumerator
REFERER_NONE 
REFERER_SAME_URL 
REFERER_FAKE 
REFERER_TRUE 

◆ verbose_level

Enumerator
VERBOSE_QUIET 
VERBOSE_WARNINGS 
VERBOSE_ALL 
VERBOSE_LEVELS 

Function Documentation

◆ add_opt()

struct option * add_opt ( struct option * ,
const char * ,
const char * ,
const char * ,
option_flags_T ,
enum option_type,
long ,
long ,
longptr_T ,
const char *  )
related

◆ checkout_option_values()

void checkout_option_values ( struct option_resolver * resolvers,
struct option * root,
union option_value * values,
int size )
related

◆ commit_option_values()

int commit_option_values ( struct option_resolver * resolvers,
struct option * root,
union option_value * values,
int size )
related

◆ copy_option()

struct option * copy_option ( struct option * ,
int  )
related

◆ delete_option()

void delete_option ( struct option * )
related

◆ done_options()

void done_options ( void )
extern

◆ get_default_protocol()

const char * get_default_protocol ( void )

◆ get_https_by_default()

int get_https_by_default ( void )

◆ get_opt_()

union option_value * get_opt_ ( char * ,
int ,
enum option_type,
struct option * ,
const char * ,
struct session *  )
related

◆ get_opt_rec()

struct option * get_opt_rec ( struct option * ,
const char *  )
related

◆ get_opt_rec_real()

struct option * get_opt_rec_real ( struct option * ,
const char *  )
related

◆ get_option_shadow()

struct option * get_option_shadow ( struct option * option,
struct option * tree,
struct option * shadow_tree )

Return the shadow option in shadow_tree of option in tree.

If option isn't yet shadowed in shadow_tree, shadow it (i.e. create a copy in shadow_tree) along with any ancestors that aren't shadowed.

◆ indirect_option()

struct option * indirect_option ( struct option * )
related

◆ init_options()

void init_options ( void )
extern

◆ init_options_tree()

struct option list * init_options_tree ( void )
related

◆ mark_option_as_deleted()

void mark_option_as_deleted ( struct option * )
related

◆ prepare_mustsave_flags()

void prepare_mustsave_flags ( struct option list * ,
int set_all )
related

◆ register_change_hooks()

void register_change_hooks ( const struct change_hook_info * change_hooks)
related

◆ register_options()

void register_options ( union option_info info[],
struct option * tree )
related

◆ smart_config_string()

void smart_config_string ( struct string * ,
int ,
int ,
struct option list * ,
char * ,
int ,
void(*  )(struct string *, struct option *, char *, int, int, int, int) )
related

◆ unregister_options()

void unregister_options ( union option_info info[],
struct option * tree )
related

◆ untouch_options()

void untouch_options ( struct option list * )
related

◆ update_options_visibility()

void update_options_visibility ( void )

Update the visibility of the box item of each option in config_options to honour the value of config.show_template.

Variable Documentation

◆ cmdline_options

struct option* cmdline_options
extern

◆ config_options

struct option* config_options
extern