program

Name

program -- Functions to collect, handle and store data about programs.

Synopsis


#include <history.h>


gboolean    program_info_in_cache           (gchar *name);
gboolean    program_add_description         (gchar *name,
                                             gchar *descr);
const gchar* program_get_description        (gchar *name);
gboolean    program_add_long_description    (gchar *name,
                                             gchar *longdesc);
const gchar* program_get_long_description   (gchar *name);
xmlNodePtr  program_add_option              (gchar *name,
                                             gchar *option);
gboolean    program_add_option_with_descr   (gchar *name,
                                             gchar *option,
                                             gchar *descr);
gboolean    program_add_longopt             (gchar *name,
                                             gchar *longopt);
gboolean    program_add_longopt_with_descr  (gchar *name,
                                             gchar *longopt,
                                             gchar *descr);
gboolean    program_add_options_with_descr  (gchar *name,
                                             gchar *option,
                                             gchar *longopt,
                                             gchar *descr);
TypingCheckResult program_check_longopt_typing
                                            (const gchar *name,
                                             const gchar *longopt);
const gchar* program_get_argument_category  (const gchar *name,
                                             gint position);
gboolean    program_get_argument_iterate    (const gchar *name,
                                             gint position);
gboolean    program_get_argument_optional   (const gchar *name,
                                             gint position);
gchar*      program_get_option_description  (const gchar *name,
                                             const gchar *option);
GList*      program_get_option_list         (const gchar *name,
                                             const gchar *restraint);
void        program_increment_option_history_counter
                                            (const gchar *name,
                                             const gchar *option);
            program_info;
            program_option;
void        program_reset_all_history_counter
                                            (void);
xmlNodePtr  synopsis_create_node            (const gchar *name);
xmlNodePtr  synopsis_create_node_with_long_option
                                            (const gchar *option);
xmlNodePtr  synopsis_create_node_with_long_option_argument
                                            (const gchar *option,
                                             const gchar *argument,
                                             const gchar *op);
xmlNodePtr  synopsis_create_node_with_option
                                            (const gchar *option);
xmlNodePtr  synopsis_create_node_with_option_argument
                                            (const gchar *option,
                                             const gchar *argument,
                                             const gchar *op);
xmlNodePtr  synopsis_create_operator_node   (gchar operator,
                                             xmlNodePtr arg1,
                                             xmlNodePtr arg2);
void        synopsis_remove_nodes_from_program
                                            (const gchar *name);
void        synopsis_add_node_to_program    (const gchar *name,
                                             xmlNodePtr node);

Description

These functions help to collect and store data about the programs. The collected data can be used to change the behaviour of the program and to create graphical user interface for the direct manipulation of the commands. All the collected data are stored in an XML file so we speak about nodes and attributes specifying the functions.

Details

program_info_in_cache ()

gboolean    program_info_in_cache           (gchar *name);

Checks if we have information in the cache about the given program.

name :

the name of the program

Returns :

TRUE if we have this program in cache


program_add_description ()

gboolean    program_add_description         (gchar *name,
                                             gchar *descr);

Creates a new node for the program, then stores the description for it. This function will not change the description if the program or the description itself has a protection="read-write" attribute setting.

name :

the name of the program

descr :

the short description of the program

Returns :

TRUE if the operation could be performed


program_get_description ()

const gchar* program_get_description        (gchar *name);

Returns the description belongs to the program.

name :

the name of the program

Returns :

the description for the program


program_add_long_description ()

gboolean    program_add_long_description    (gchar *name,
                                             gchar *longdesc);

Creates a new node for the program, then stores the long description for it. This function will not change the long description if the program or the long description itself has a protection="read-write" attribute setting.

name :

the name of the program

longdesc :

Returns :

TRUE if the operation could be performed


program_get_long_description ()

const gchar* program_get_long_description   (gchar *name);

Returns the long description belongs to the given program.

name :

the name of the program

Returns :

name long description of the program


program_add_option ()

xmlNodePtr  program_add_option              (gchar *name,
                                             gchar *option);

Adds a new option to the given program.

name :

the name of the program

option :

the option name starting with a dash

Returns :

TRUE if the opertation suceeded


program_add_option_with_descr ()

gboolean    program_add_option_with_descr   (gchar *name,
                                             gchar *option,
                                             gchar *descr);

name :

option :

descr :

Returns :


program_add_longopt ()

gboolean    program_add_longopt             (gchar *name,
                                             gchar *longopt);

name :

longopt :

Returns :


program_add_longopt_with_descr ()

gboolean    program_add_longopt_with_descr  (gchar *name,
                                             gchar *longopt,
                                             gchar *descr);

name :

longopt :

descr :

Returns :


program_add_options_with_descr ()

gboolean    program_add_options_with_descr  (gchar *name,
                                             gchar *option,
                                             gchar *longopt,
                                             gchar *descr);

name :

option :

longopt :

descr :

Returns :


program_check_longopt_typing ()

TypingCheckResult program_check_longopt_typing
                                            (const gchar *name,
                                             const gchar *longopt);

name :

longopt :

Returns :


program_get_argument_category ()

const gchar* program_get_argument_category  (const gchar *name,
                                             gint position);

Returns the category of the nth argument.

name :

the name of the argument

position :

which argument to read

Returns :

the category of the given argument


program_get_argument_iterate ()

gboolean    program_get_argument_iterate    (const gchar *name,
                                             gint position);

Returns TRUE if the given argument can be repeated.

name :

the name of the program

position :

which argument to check

Returns :

TRUE if the argument is iterated


program_get_argument_optional ()

gboolean    program_get_argument_optional   (const gchar *name,
                                             gint position);

Returns TRUE if the argument can be omitted.

name :

the name of the program

position :

which argument to check

Returns :

TRUE if the given argument is optional


program_get_option_description ()

gchar*      program_get_option_description  (const gchar *name,
                                             const gchar *option);

Returns the one sentence description of the option in a newly allocated xml encoded string.

name :

the name of the program

option :

the short or long option starting with a dash

Returns :

one sentence description in a newly allocated string


program_get_option_list ()

GList*      program_get_option_list         (const gchar *name,
                                             const gchar *restraint);

name :

restraint :

Returns :

a list with the options (short or long option names) for the given program with the given restraint. The list contains strings statically allocated, should not be tamered with.


program_increment_option_history_counter ()

void        program_increment_option_history_counter
                                            (const gchar *name,
                                             const gchar *option);

name :

option :


program_info

typedef struct {
	gchar *name;		/* The name of the program. 		*/
	gchar *info;		/* One line description.		*/
	GList *longopts;
	GList *opts;
} program_info;


program_option

typedef struct {
	gchar *option;
	gchar *description;
} program_option;


program_reset_all_history_counter ()

void        program_reset_all_history_counter
                                            (void);


synopsis_create_node ()

xmlNodePtr  synopsis_create_node            (const gchar *name);

Creates a single node which later must be added to the document. See synopsis_add_node_to_program how to add a new synopsis node to the program.

name :

the name of the node

Returns :

a new node


synopsis_create_node_with_long_option ()

xmlNodePtr  synopsis_create_node_with_long_option
                                            (const gchar *option);

Creates a new node representing a long option.

option :

the long option name starting with two dashes

Returns :

the new node


synopsis_create_node_with_long_option_argument ()

xmlNodePtr  synopsis_create_node_with_long_option_argument
                                            (const gchar *option,
                                             const gchar *argument,
                                             const gchar *op);

option :

argument :

op :

Returns :


synopsis_create_node_with_option ()

xmlNodePtr  synopsis_create_node_with_option
                                            (const gchar *option);

Creates a new node representing an option.

option :

the option name starting with a dash

Returns :

the new node


synopsis_create_node_with_option_argument ()

xmlNodePtr  synopsis_create_node_with_option_argument
                                            (const gchar *option,
                                             const gchar *argument,
                                             const gchar *op);

option :

argument :

op :

Returns :


synopsis_create_operator_node ()

xmlNodePtr  synopsis_create_operator_node   (gchar operator,
                                             xmlNodePtr arg1,
                                             xmlNodePtr arg2);

operator :

arg1 :

arg2 :

Returns :


synopsis_remove_nodes_from_program ()

void        synopsis_remove_nodes_from_program
                                            (const gchar *name);

name :


synopsis_add_node_to_program ()

void        synopsis_add_node_to_program    (const gchar *name,
                                             xmlNodePtr node);

name :

node :