summaryrefslogtreecommitdiffstats
path: root/m_option.h
diff options
context:
space:
mode:
Diffstat (limited to 'm_option.h')
-rw-r--r--m_option.h374
1 files changed, 295 insertions, 79 deletions
diff --git a/m_option.h b/m_option.h
index 55a26765bd..cfeb481663 100644
--- a/m_option.h
+++ b/m_option.h
@@ -1,10 +1,23 @@
#ifndef _M_OPTION_H
#define _M_OPTION_H
+/// \defgroup Options
+/// m_option allow to parse, print and copy data of various types.
+/// It is the base of the \ref OptionsStruct, \ref Config and
+/// \ref Properties APIs.
+///@{
+
+/// \file m_option.h
+
+/// \ingroup OptionTypes
typedef struct m_option_type m_option_type_t;
typedef struct m_option m_option_t;
struct m_struct_st;
+/// \defgroup OptionTypes Options types
+/// \ingroup Options
+///@{
+
///////////////////////////// Options types declarations ////////////////////////////
// Simple types
@@ -28,52 +41,99 @@ extern m_option_type_t m_option_type_func_full;
extern m_option_type_t m_option_type_func_param;
extern m_option_type_t m_option_type_func;
+/// Callback used to reset func options.
typedef void (*m_opt_default_func_t)(m_option_t *, char*);
+
+/// Callback used by m_option_type_func_full options.
typedef int (*m_opt_func_full_t)(m_option_t *, char *, char *);
+
+/// Callback used by m_option_type_func_param options.
typedef int (*m_opt_func_param_t)(m_option_t *, char *);
+
+/// Callback used by m_option_type_func options.
typedef int (*m_opt_func_t)(m_option_t *);
-///////////// Backward compat
+
+// Backward compat
typedef m_opt_default_func_t cfg_default_func_t;
typedef m_opt_func_full_t cfg_func_arg_param_t;
typedef m_opt_func_param_t cfg_func_param_t;
typedef m_opt_func_t cfg_func_t;
+/// Extra definition needed for \ref m_option_type_obj_settings_list options.
typedef struct {
+ /// Pointer to an array of pointer to some object type description struct.
void** list;
+ /// Offset of the object type name (char*) in the description struct.
void* name_off;
+ /// Offset of the object type info string (char*) in the description struct.
void* info_off;
+ /// \brief Offset of the object type parameter description (\ref m_struct_st)
+ /// in the description struct.
void* desc_off;
} m_obj_list_t;
-typedef struct {
+/// The data type used by \ref m_option_type_obj_settings_list.
+typedef struct m_obj_settings {
+ /// Type of the object.
char* name;
+ /// NULL terminated array of parameter/value pairs.
char** attribs;
} m_obj_settings_t;
-extern m_option_type_t m_option_type_obj_settings_list;
-
-// Presets are mean to be used with options struct
+/// A parser to setup a list of objects.
+/** It create a NULL terminated array \ref m_obj_settings. The option priv
+ * field (\ref m_option::priv) must point to a \ref m_obj_list_t describing
+ * the available object types.
+ */
+extern m_option_type_t m_option_type_obj_settings_list;
+/// Extra definition needed for \ref m_option_type_obj_presets options.
typedef struct {
+ /// Description of the struct holding the presets.
struct m_struct_st* in_desc;
+ /// Description of the struct that should be set by the presets.
struct m_struct_st* out_desc;
- void* presets; // Pointer to an arry of struct defined by in_desc
- void* name_off; // Offset of the preset name inside the in_struct
+ /// Pointer to an array of struct defining the various presets.
+ void* presets;
+ /// Offset of the preset's name inside the in_struct.
+ void* name_off;
} m_obj_presets_t;
+
+/// Set several fields in a struct at once.
+/** For this two struct description are used. One for the struct holding the
+ * preset and one for the struct beeing set. Every field present in both
+ * struct will be copied from the preset struct to the destination one.
+ * The option priv field (\ref m_option::priv) must point to a correctly
+ * filled \ref m_obj_presets_t.
+ */
extern m_option_type_t m_option_type_obj_presets;
+/// Parse an URL into a struct.
+/** The option priv field (\ref m_option::priv) must point to a
+ * \ref m_struct_st describing which fields of the URL must be used.
+ */
extern m_option_type_t m_option_type_custom_url;
+/// Extra definition needed for \ref m_option_type_obj_params options.
typedef struct {
- struct m_struct_st* desc; // Fields description
- char separator; // Field separator to use
+ /// Fields description.
+ struct m_struct_st* desc;
+ /// Field separator to use.
+ char separator;
} m_obj_params_t;
+
+/// Parse a set of parameters.
+/** Parameters are separated by the given separator and each one
+ * successively set a field from the struct. The option priv field
+ * (\ref m_option::priv) must point to a \ref m_obj_params_t.
+ */
extern m_option_type_t m_option_type_obj_params;
typedef struct {
int start;
int end;
} m_span_t;
+/// Ready made settings to parse a \ref m_span_t with a start-end syntax.
extern m_obj_params_t m_span_params_def;
@@ -102,67 +162,155 @@ extern m_obj_params_t m_span_params_def;
/////////////////////////////////////////////////////////////////////////////////////////////
+/// Option type description
struct m_option_type {
char* name;
- char* comments; // syntax desc, etc
- unsigned int size; // size needed for a save slot
+ /// Syntax desc, etc
+ char* comments;
+ /// Size needed for the data.
+ unsigned int size;
+ /// See \ref OptionTypeFlags.
unsigned int flags;
-
- // parse is the only requiered function all others can be NULL
- // If dst if non-NULL it should create/update the save slot
- // If dst is NULL it should just test the validity of the arg if possible
- // Src tell from where come this setting (ie cfg file, command line, playlist, ....
- // It should return 1 if param was used, 0 if not.
- // On error it must return 1 of the error code below
+
+ /// Parse the data from a string.
+ /** It is the only required function, all others can be NULL.
+ *
+ * \param opt The option that is parsed.
+ * \param name The full option name.
+ * \param param The parameter to parse.
+ * \param dst Pointer to the memory where the data should be writen.
+ * If NULL the parameter validity should still be checked.
+ * \param src Source of the option, see \ref OptionParserModes.
+ * \return On error a negative value is returned, on success the number of argument
+ * consumed. For details see \ref OptionParserReturn.
+ */
int (*parse)(m_option_t* opt,char *name, char *param, void* dst, int src);
- // Print back a value in human form
+
+ /// Print back a value in string form.
+ /** \param opt The option to print.
+ * \param val Pointer to the memory holding the data to be printed.
+ * \return An allocated string containing the text value or (void*)-1
+ * on error.
+ */
char* (*print)(m_option_t* opt, void* val);
- // These 3 will be a memcpy in 50% of the case, it's called to save/restore the status of
- // the var it's there for complex type like CONF_TYPE_FUNC*
- // update a save slot (dst) from the current value in the prog (src)
+ /** \name
+ * These functions are called to save/set/restore the status of the
+ * variables. The difference between the 3 only matter for types like
+ * \ref m_option_type_func where 'setting' need to do more than just
+ * copying some data.
+ */
+ //@{
+
+ /// Update a save slot (dst) from the current value in the prog (src).
+ /** \param opt The option to copy.
+ * \param dst Pointer to the destination memory.
+ * \param src Pointer to the source memory.
+ */
void (*save)(m_option_t* opt,void* dst, void* src);
- // set the current value (dst) from a save slot
+
+ /// Set the value in the prog (dst) from a save slot.
+ /** \param opt The option to copy.
+ * \param dst Pointer to the destination memory.
+ * \param src Pointer to the source memory.
+ */
void (*set)(m_option_t* opt,void* dst, void* src);
- // Copy betewen 2 slot (if NULL and size > 0 a memcpy will be used
+
+ /// Copy the data between two save slots. If NULL and size is > 0 a memcpy will be used.
+ /** \param opt The option to copy.
+ * \param dst Pointer to the destination memory.
+ * \param src Pointer to the source memory.
+ */
void (*copy)(m_option_t* opt,void* dst, void* src);
- // Free the data allocated for a save slot if needed
+ //@}
+
+ /// Free the data allocated for a save slot.
+ /** This is only needed for dynamic types like strings.
+ * \param dst Pointer to the data, usually a pointer that should be freed and
+ * set to NULL.
+ */
void (*free)(void* dst);
};
+///@}
+
+/// Option description
+/** \ingroup Options
+ */
struct m_option {
+ /// Option name.
char *name;
- void *p;
+
+ /// Reserved for higher level APIs, it shouldn't be used by parsers.
+ /** The suboption parser and func types do use it. They should instead
+ * use the priv field but this was herited from older versions of the
+ * config code.
+ */
+ void *p;
+
+ /// Option type.
m_option_type_t* type;
+
+ /// See \ref OptionFlags.
unsigned int flags;
- double min,max;
- // This used to be function pointer to hold a 'reverse to defaults' func.
- // Nom it can be used to pass any type of extra args.
- // Passing a 'default func' is still valid for all func based option types
- void* priv; // Type dependent data (for all kind of extended setting)
+
+ /// \brief Mostly usefull for numeric types, the \ref M_OPT_MIN flags must
+ /// also be set.
+ double min;
+
+ /// \brief Mostly usefull for numeric types, the \ref M_OPT_MAX flags must
+ /// also be set.
+ double max;
+
+ /// Type dependent data (for all kind of extended setting).
+ /** This used to be function pointer to hold a 'reverse to defaults' func.
+ * Now it can be used to pass any type of extra args needed by the parser.
+ * Passing a 'default func' is still valid for all func based option types
+ */
+ void* priv;
};
-//////////////////////////////// Option flags /////////////////////////////////
+/// \defgroup OptionFlags Option flags
+///@{
-// Option flags
+/// The option have a minimum set in \ref m_option::min.
#define M_OPT_MIN (1<<0)
+
+/// The option have a maximum set in \ref m_option::max.
#define M_OPT_MAX (1<<1)
+
+/// The option have a minimum and maximum in \ref m_option::min and \ref m_option::max.
#define M_OPT_RANGE (M_OPT_MIN|M_OPT_MAX)
+
+/// The option is forbidden in config files.
#define M_OPT_NOCFG (1<<2)
+
+/// The option is forbiden on the command line.
#define M_OPT_NOCMD (1<<3)
-// This option is global : it won't be saved on push and the command
-// line parser will set it when it's parsed (ie. it won't be set later)
-// e.g options : -v, -quiet
+
+/// The option is global in the \ref Config.
+/** It won't be saved on push and the command line parser will set it when
+ * it's parsed (ie. it won't be set later)
+ * e.g options : -v, -quiet
+ */
#define M_OPT_GLOBAL (1<<4)
-// Do not save this option : it won't be saved on push but the command
-// line parser will put it with it's entry (ie : it may be set later)
-// e.g options : -include
+
+/// The \ref Config won't save this option on push.
+/** It won't be saved on push but the command line parser will put it with
+ * it's entry (ie : it may be set later)
+ * e.g options : -include
+ */
#define M_OPT_NOSAVE (1<<5)
-// Emulate old behaviour by pushing the option only if it was set by the user
+
+/// \brief The \ref Config will emulate the old behaviour by pushing the
+/// option only if it was set by the user.
#define M_OPT_OLD (1<<6)
-// FIXME: backward compatibility
+/// \defgroup OldOptionFlags Backward compatibility
+///
+/// Those are kept for compatibility with older code.
+/// @{
#define CONF_MIN M_OPT_MIN
#define CONF_MAX M_OPT_MAX
#define CONF_RANGE M_OPT_RANGE
@@ -171,73 +319,135 @@ struct m_option {
#define CONF_GLOBAL M_OPT_GLOBAL
#define CONF_NOSAVE M_OPT_NOSAVE
#define CONF_OLD M_OPT_OLD
-
-
-///////////////////////////// Option type flags ///////////////////////////////////
-
-// These flags are for the parsers. The description here apply to the m_config_t
-// based parsers (ie. cmd line and config file parsers)
-// Some parser will refuse option types that have some of these flags
-
-// This flag is used for the subconfig
-// When this flag is set, opt->p should point to another m_option_t array
-// Only the parse function will be called. If dst is set, it should create/update
-// an array of char* containg opt/val pairs.
-// Then the options in the child array will then be set automaticly.
-// You can only affect the way suboption are parsed.
-// Also note that suboptions may be directly accessed by using -option:subopt blah :-)
+///@}
+
+///@}
+
+/// \defgroup OptionTypeFlags Option type flags
+/// \ingroup OptionTypes
+///
+/// These flags are used to describe special parser capabilities or behaviour.
+///
+///@{
+
+/// Suboption parser flag.
+/** When this flag is set, m_option::p should point to another m_option
+ * array. Only the parse function will be called. If dst is set, it should
+ * create/update an array of char* containg opt/val pairs. The options in
+ * the child array will then be set automatically by the \ref Config.
+ * Also note that sub options may be directly accessed by using
+ * -option:subopt blah.
+ */
#define M_OPT_TYPE_HAS_CHILD (1<<0)
-// If this flag is set the option type support option name with * at the end (used for -aa*)
-// This only affect the option name matching, the option type have to implement
-// the needed stuff.
+
+/// Wildcard matching flag.
+/** If set the option type have a use for option name ending with a *
+ * (used for -aa*), this only affect the option name matching.
+ */
#define M_OPT_TYPE_ALLOW_WILDCARD (1<<1)
-// This flag indicate that the data is dynamicly allocated (opt->p point to a pointer)
-// It enable a little hack wich replace the initial value by a dynamic copy
-// in case the initial value is staticly allocated (pretty common with strings)
+
+/// Dynamic data type.
+/** This flag indicate that the data is dynamicly allocated (m_option::p point
+ * to a pointer). It enable a little hack in the \ref Config wich replace
+ * the initial value of such variables with a dynamic copy in case the
+ * initial value is staticaly allocated (pretty common with strings).
+ */
#define M_OPT_TYPE_DYNAMIC (1<<2)
-/// If this is set the parse function doesn't directly return
-// the wanted thing. Options use this if for some reasons they have to wait
-// until the set call to be able to correctly set the target var.
-// So for those types you have to first parse and then set the target var
-// If this flag isn't set you can parse directly to the target var
-// It's used for the callback based option as the callback call may append
-// later on.
+
+/// Indirect option type.
+/** If this is set the parse function doesn't directly return
+ * the wanted thing. Options use this if for some reasons they have to wait
+ * until the set call to be able to correctly set the target var.
+ * So for those types new values must first be parsed, then set to the target
+ * var. If this flag isn't set then new values can be parsed directly to the
+ * target var. It's used by the callback based option as the callback call
+ * may append later on.
+ */
#define M_OPT_TYPE_INDIRECT (1<<3)
+///@}
///////////////////////////// Parser flags ////////////////////////////////////////
-// Config mode : some parser type behave differently depending
-// on config->mode value wich is passed in the src param of parse()
+/// \defgroup OptionParserModes Option parser modes
+/// \ingroup Options
+///
+/// Some parser behave differently depending on the mode passed in the src
+/// parameter of m_option_type::parse. For example the flag type doesn't take
+/// an argument when parsing from the command line.
+///@{
+
+/// Set when parsing from a config file.
#define M_CONFIG_FILE 0
+/// Set when parsing command line arguments.
#define M_COMMAND_LINE 1
-// Option parser error code
+///@}
+
+/// \defgroup OptionParserReturn Option parser return code
+/// \ingroup Options
+///
+/// On sucess parsers return the number of arguments consumed: 0 or 1.
+///
+/// To indicate that mplayer should exit without playing anything,
+/// parsers return M_OPT_EXIT minus the number of parameters they
+/// consumed: \ref M_OPT_EXIT or \ref M_OPT_EXIT-1.
+///
+/// On error one of the following (negative) error code is returned:
+///@{
+
+/// For use by higer level APIs when the option name is invalid.
#define M_OPT_UNKNOWN -1
+
+/// Returned when a parameter is needed but wasn't provided.
#define M_OPT_MISSING_PARAM -2
+
+/// Returned when the given parameter couldn't be parsed.
#define M_OPT_INVALID -3
+
+/// \brief Returned if the value is "out of range". The exact meaning may
+/// vary from type to type.
#define M_OPT_OUT_OF_RANGE -4
+
+/// Returned if the parser failed for any other reason than a bad parameter.
#define M_OPT_PARSER_ERR -5
+
+/// Returned when MPlayer should exit. Used by various help stuff.
+/** M_OPT_EXIT must be the lowest number on this list.
+ */
#define M_OPT_EXIT -6
-// M_OPT_EXIT must be the lowest number on this list.
-// To indicate that mplayer should exit without playing anything,
-// a parsing function needs to return M_OPT_EXIT less the number
-// of additional command line parameters it consumed.
-// Generally it will return either M_OPT_EXIT or M_OPT_EXIT - 1.
-// FIXME: backward compatibility
+/// \defgroup OldOptionParserReturn Backward compatibility
+///
+/// Those are kept for compatibility with older code.
+///
+///@{
#define ERR_NOT_AN_OPTION M_OPT_UNKNOWN
#define ERR_MISSING_PARAM M_OPT_MISSING_PARAM
#define ERR_OUT_OF_RANGE M_OPT_OUT_OF_RANGE
#define ERR_FUNC_ERR M_OPT_PARSER_ERR
-
+///@}
+
+///@}
+
+/// Find the option matching the given name in the list.
+/** \ingroup Options
+ * This function take the possible wildcards in account (see
+ * \ref M_OPT_TYPE_ALLOW_WILDCARD).
+ *
+ * \param list Pointer to an array of \ref m_option.
+ * \param name Name of the option.
+ * \return The matching option or NULL.
+ */
m_option_t* m_option_list_find(m_option_t* list,char* name);
+/// Helper to parse options, see \ref m_option_type::parse.
inline static int
m_option_parse(m_option_t* opt,char *name, char *param, void* dst, int src) {
return opt->type->parse(opt,name,param,dst,src);
}
+/// Helper to print options, see \ref m_option_type::print.
inline static char*
m_option_print(m_option_t* opt, void* val_ptr) {
if(opt->type->print)
@@ -246,18 +456,21 @@ m_option_print(m_option_t* opt, void* val_ptr) {
return (char*)-1;
}
+/// Helper around \ref m_option_type::save.
inline static void
m_option_save(m_option_t* opt,void* dst, void* src) {
if(opt->type->save)
opt->type->save(opt,dst,src);
}
+/// Helper around \ref m_option_type::set.
inline static void
m_option_set(m_option_t* opt,void* dst, void* src) {
if(opt->type->set)
opt->type->set(opt,dst,src);
}
+/// Helper around \ref m_option_type::copy.
inline static void
m_option_copy(m_option_t* opt,void* dst, void* src) {
if(opt->type->copy)
@@ -266,10 +479,13 @@ m_option_copy(m_option_t* opt,void* dst, void* src) {
memcpy(dst,src,opt->type->size);
}
+/// Helper around \ref m_option_type::free.
inline static void
m_option_free(m_option_t* opt,void* dst) {
if(opt->type->free)
opt->type->free(dst);
}
+/*@}*/
+
#endif /* _M_OPTION_H */