#include <stddef.h>
#include "param_set.h"

Typedefs
typedef struct TASK_SET_st	TASK_SET

typedef struct TASK_st	TASK

Functions
int	TASK_SET_new (TASK_SET **newObj)

void	TASK_SET_free (TASK_SET *obj)

int	TASK_SET_add (TASK_SET task_set, int id, const char name, const char man, const char atleastone, const char forb, const char ignore)

int	TASK_SET_analyzeConsistency (TASK_SET task_set, PARAM_SET set, double sensitivity)

int	TASK_SET_getConsistentTask (TASK_SET task_set, TASK *task)

int	TASK_SET_isOneFromSetTheTarget (TASK_SET task_set, double diff, int ID)

int	TASK_SET_cleanIgnored (TASK_SET task_set, TASK task, int *removed)

char *	TASK_SET_suggestions_toString (TASK_SET task_set, int depth, char buf, size_t buf_len)

char *	TASK_SET_howToRepair_toString (TASK_SET task_set, PARAM_SET set, int ID, const char prefix, char buf, size_t buf_len)

int	TASK_getID (TASK *task)

const char *	TASK_getName (TASK *task)

PARAM_SET *	TASK_getSet (TASK *task)

Typedef Documentation

◆ TASK

typedef struct TASK_st TASK

Consistent task object that is extracted from the TASK_SET.

◆ TASK_SET

typedef struct TASK_SET_st TASK_SET

A set of task definitions that can be analyzed against PARAM_SET object to extract a single consistent task.

Function Documentation

◆ TASK_getID()

int TASK_getID ( TASK * task )

Gets the TASK ID.

Parameters

task	TASK object.

Returns: Task ID.

◆ TASK_getName()

const char* TASK_getName ( TASK * task )

Gets the TASK name.

Parameters

task	TASK object.

Returns: Task name.

◆ TASK_getSet()

PARAM_SET* TASK_getSet ( TASK * task )

Gets the PARAM_SET object used to analyze task's consistency (see TASK_SET_analyzeConsistency).

Parameters

task	TASK object.

Returns: PARAM_SET object.

◆ TASK_SET_add()

int TASK_SET_add	(	TASK_SET *	task_set,
		int	id,
		const char *	name,
		const char *	man,
		const char *	atleastone,
		const char *	forb,
		const char *	ignore
	)

Adds tasks to the task set. Task is composed from ID, name and different groups of command-line parameters. Command-line parameter is said to be set when PARAM object from PARAM_SET is not empty (is specified on command line, with or without a value). A group is specified by string containing command-line parameter names separated with comma (e.g. 'input,output,h'). Note that the names do not contain prefix '-' and '--' where parameters are parsed from command line (see PARAM_SET_parseCMD).

Command-line parameter groups:

mandatory - All parameters specified must be set.
at least one - At least one parameter from group must be set.
forbidden - Any parameter from this group must NOT be set.
ignored - All parameters from this set can be ignored or even removed (see TASK_SET_cleanIgnored).

Parameters

task_set	TASK_SET object.
id	The `ID` of the task.
name	Name or description of the task.
man	Mandatory parameters.
atleastone	Parameter where at least one must be set. Can be `NULL`.
forb	Forbidden parameters. Can be `NULL`.
ignore	Ignored parameters. Can be `NULL`.

Returns: PST_OK if successful, error code otherwise.

◆ TASK_SET_analyzeConsistency()

int TASK_SET_analyzeConsistency	(	TASK_SET *	task_set,
		PARAM_SET *	set,
		double	sensitivity
	)

Performs analysis on the TASK_SET with parameters from PARAM_SET. After analyzing it is possible to extract one consistent TASK from the TASK_SET (see TASK_SET_getConsistentTask) or in case of an error, check if one task from the TASK_SET stands out as the possible target and give user some hints how to fix it. If it is not possible to assume what task the user is trying to accomplish, shows user the tasks that have the most similar patterns compared to the given input (see TASK_SET_isOneFromSetTheTarget, TASK_SET_howToRepair_toString and TASK_SET_suggestions_toString).

The analysis and error handling is based on the task consistency value. Consistency 1.0 means that it is possible to perform the task with given parameters and less than 1.0 means it is not. The consistency of a task is calculated from command-line parameter groups (see TASK_SET_add). To get a consistent task, all mandatory parameters must be set and there must not be a single forbidden parameter set. The consistency of a task is calculated as follows:

                   man_mis + atl_mis + forbidden
consistency = 1 -  -----------------------------  , where
                       man_count + atl_count
  atl_count - Count of parameters that are set from group 'at least one'.
  atl_mis   - 0 if at least one parameter from group 'at least one' is set, 1 otherwise.
  forbidden - Count of forbidden parameters that are set.
  man_count - Count of all mandatory parameters.
  man_mis   - Count of missing mandatory parameters.

During analysis consistency of all parameters is calculated and values are sorted starting from the most consistent and ending with least consistent. If two tasks have very similar consistency, the weighted comparison is used (the difference is specified with sensitivity). If weighted comparison does not give better results, two tasks are considered as equal. Weighted comparison is calculated as described below:

Task A is more consistent when ConsitencyA * WA > ConsistencyB * WB
Wx = atl_count_x + man_count_x - set_in_both  , where
  atl_count_x - Count of parameters that are set from group "at least one".
  man_count_x - Count of parameters that are set from group "mandatory".
  set_in_both - All parameter that are set in both A nd B.

Parameters

task_set	TASK_SET object.
set	PARAM_SET object.
sensitivity	Analysis sensitivity.

Returns: PST_OK if successful, error code otherwise. Some more common error codes: PST_TASK_SET_HAS_NO_DEFINITIONS and PST_TASK_UNABLE_TO_ANALYZE_PARAM_SET_CHANGED.

◆ TASK_SET_cleanIgnored()

int TASK_SET_cleanIgnored	(	TASK_SET *	task_set,
		TASK *	task,
		int *	removed
	)

Removes all ignored parameters (see TASK_SET_add) from the PARAM_SET object used to perform analysis (see TASK_SET_analyzeConsistency).

Parameters

task_set	TASK_SET object.
task	TASK object.
removed	Output parameter for the count of removed values.

Returns: PST_OK if successful, error code otherwise.

◆ TASK_SET_free()

void TASK_SET_free ( TASK_SET * obj )

Frees the TASK_SET object.

Parameters

obj	TASK_SET object.

◆ TASK_SET_getConsistentTask()

int TASK_SET_getConsistentTask	(	TASK_SET *	task_set,
		TASK **	task
	)

Extracts one single consistent task, the one that user wants to execute, from the TASK_SET. Before this TASK_SET_analyzeConsistency must be called.

Parameters

task_set	TASK_SET object.
task	Pointer to receiving pointer to TASK object.

Returns: PST_OK if successful, error code otherwise. Some more common error codes: PST_TASK_SET_HAS_NO_DEFINITIONS, PST_TASK_SET_NOT_ANALYZED, PST_TASK_ZERO_CONSISTENT_TASKS and PST_TASK_MULTIPLE_CONSISTENT_TASKS.

◆ TASK_SET_howToRepair_toString()

char* TASK_SET_howToRepair_toString	(	TASK_SET *	task_set,
		PARAM_SET *	set,
		int	ID,
		const char *	prefix,
		char *	buf,
		size_t	buf_len
	)

Generates suggestion message from pre-analyzed TASK_SET to help user figure out how to fix the task with ID (see TASK_SET_analyzeConsistency; see TASK_SET_isOneFromSetTheTarget to get ID of the task that user is trying to accomplish).

Parameters

task_set	TASK_SET object.
set	PARAM_SET object.
ID	Tasks `ID`.
prefix	Prefix for the message. Can be `NULL`.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

◆ TASK_SET_isOneFromSetTheTarget()

int TASK_SET_isOneFromSetTheTarget	(	TASK_SET *	task_set,
		double	diff,
		int *	ID
	)

Extracts the most consistent task from the TASK_SET which may have more than one consistent task in it. If there is no single consistent task in TASK_SET, it is possible that user has made an error by specifying too few or too many parameters. In this case, it may be possible to extract the task that is assumed to be the one that user is trying to accomplish. Task is extracted if there is a single task that has consistency higher than any other task by the value of diff.

Parameters

task_set	TASK_SET object.
diff	Task `consistency` difference.
ID	Output parameter for task `ID`.

Returns: PST_OK if successful, error code otherwise.

◆ TASK_SET_new()

int TASK_SET_new ( TASK_SET ** newObj )

Creates an empty TASK_SET object.

Parameters

newObj Pointer to receiving pointer to TASK_SET object.

Returns: PST_OK if successful, error code otherwise.

◆ TASK_SET_suggestions_toString()

char* TASK_SET_suggestions_toString	(	TASK_SET *	task_set,
		int	depth,
		char *	buf,
		size_t	buf_len
	)

Generates suggestion message from pre-analyzed TASK_SET to help user figure out what task he or she wants to accomplish. The maximum number of tasks suggested is specified by depth. Suggested tasks are ordered by the consistency value starting from the highest (see TASK_SET_analyzeConsistency).

Parameters

task_set	TASK_SET object.
depth	Maximum count of tasks displayed.
buf	Receiving buffer.
buf_len	Receiving buffer size.

Returns: buf if successful, NULL otherwise.

Typedefs

Functions

Typedef Documentation

◆ TASK

◆ TASK_SET

Function Documentation

◆ TASK_getID()

◆ TASK_getName()

◆ TASK_getSet()

◆ TASK_SET_add()

◆ TASK_SET_analyzeConsistency()

◆ TASK_SET_cleanIgnored()

◆ TASK_SET_free()

◆ TASK_SET_getConsistentTask()

◆ TASK_SET_howToRepair_toString()

◆ TASK_SET_isOneFromSetTheTarget()

◆ TASK_SET_new()

◆ TASK_SET_suggestions_toString()