compress: Overhaul the meaning of --aggressiveness.
[paraslash.git] / mm.h
1 /* Copyright (C) 2007 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
2
3 /** \file mm.h Symbols and declarations for mood methods. */
4
5 /**
6 * Assign scores according to a mood_method.
7 *
8 * Each mood_method has its own mood_score_function. The first three parameters
9 * passed to that function are informations about the audio file whose score is
10 * to be computed. The data argument depends on the mood method this function
11 * is used for. It usually is the argument given at the end of a mood line.
12 *
13 * Mood score functions must return values between -100 and +100 inclusively.
14 * Boolean score functions should always return either -100 or +100.
15 *
16 * \sa struct \ref mood_method, \ref mood_parser.
17 */
18 typedef int mood_score_function(const char *path, const struct afs_info *afsi,
19 const struct afh_info *afhi, const void *data);
20
21 /**
22 * Pre-process a mood line.
23 *
24 * The mood_parser of a mood_method is called once at mood open time for each
25 * line of the current mood definition that contains the mood_method's name as
26 * a keyword. The line is passed to the mood_parser as the first argument. The
27 * mood_parser must determine whether the line is syntactically correct and
28 * return a positive value if so and a negative value otherwise.
29 *
30 * Some mood parsers pre-process the data given in the mood line to compute a
31 * structure which depends of the particular mood_method and which is used
32 * later in the mood_score_function of the mood_method. The mood_parser may
33 * store a pointer to its structure via the void** pointer.
34 *
35 * \sa \ref mood_cleanup_function, \ref mood_score_function.
36 */
37 typedef int mood_parser(int, char **, void **);
38
39 /**
40 * Deallocate resources which were allocated by the mood_parser.
41 *
42 * Function to free the resources allocated in \ref mood_method::parser. The
43 * argument is a pointer to mood method specific data returned by ->parser().
44 */
45 typedef void mood_cleanup_function(void *);
46
47 /**
48 * Used for scoring and to determine whether a file is admissible.
49 */
50 struct mood_method {
51 /** The name of the method. */
52 const char *name;
53 /** Pointer to the mood parser. */
54 mood_parser *parser;
55 /** Pointer to the score function */
56 mood_score_function *score_function;
57 /** Optional cleanup function. */
58 mood_cleanup_function *cleanup;
59 };
60
61 /** The array of available mood methods. */
62 extern const struct mood_method mood_methods[];