Grammar - Grammar structure module
[Syntactic tools level]

Definition and handling of grammar data structure (former grammaire module). More...

Data Structures
struct	RulesLexicon
	Lexicon of syntactical rules. More...
struct	Grammar
	Grammar. More...
struct	FileId
	Unique file identifier. More...
Defines
#define	CONV_FILE_EXT   "-conv"
	Postfix of the binary files that save the conversion table of Grammar::rules field.
#define	RULE_FILE_EXT   "-rule"
	Postfix of the binary files that save the rules lexicon of Grammar::rules field.
#define	NUMBER_OF_RULES(grammar)   lexiconGetSize((grammar)->rules->elements)
	Return the number of syntactic rules stored by a grammar.
#define	SLPLEX_FILE_ID   "SLPLex binary grammar file v2.2 07/00"
	Grammar binary file format definition.
#define	INDIC_LEXICAL   '"'
	Character that initiates a lexical term in a grammar textual file.
#define	DEFAULT_TOP_LEVEL_NT   512
	Default value of the Grammar::top_level_nt field.
#define	GRAMMAR_FILE_EXT   ".slpgram"
	File extension of the grammar binary file.
Functions
LexicalEntryIndex	grammarAddRule (Grammar *grammar, const char *left_part, StringArray *right_part, const Probability probability)
Probability	grammarIncrementRuleFrequency (Grammar *grammar, LexicalEntryIndex *rule_index, const char *left_part, StringArray *right_part)
int	grammarCreate (Grammar *grammar)
void	grammarFree (Grammar *grammar)
int	grammarSave (const Grammar *grammar, const char *lexicon_filename, const char *grammar_filename)
int	grammarLoad (Grammar *grammar, const char *grammar_filename)
int	grammarImport (Grammar *grammar, const char *filename, const gboolean probabilistic)
void	grammarGetNTString (const Grammar *grammar, const LexicalEntryIndex nt_index, GString *output)
LexicalEntryIndex	grammarGetNTInternalCode (const Grammar *grammar, const char *nt)
void	grammarDump (const Grammar *grammar, int(*print)(const char *,...), const gboolean rules_number)
int	grammarExport (const Grammar *grammar, const char *filename)
LongArray *	grammarGetIndexFromRule (const Grammar *grammar, const char *left_part, const StringArray *right_part)
void	grammarGetRuleFromIndex (const Grammar *grammar, const LexicalEntryIndex rule_index, char **left_part, StringArray *right_part, Probability *probability)

---

Detailed Description

Definition and handling of grammar data structure (former grammaire module).

SlpTK Library 0.6.0

Required header

<grammar.h>

Author:

Jean-Cédric Chappelier (creation on 26.03.1997)

Antonin Merçay (revision on 18.01.2005)

Date:

2 March 2005

Version:

0.6.0

---

Define Documentation

#define CONV_FILE_EXT   "-conv"

Postfix of the binary files that save the conversion table of Grammar::rules field.

See also:

grammarLoad() grammarSave()

#define RULE_FILE_EXT   "-rule"

Postfix of the binary files that save the rules lexicon of Grammar::rules field.

See also:

grammarLoad() grammarSave()

---

Function Documentation

LexicalEntryIndex grammarAddRule	(	Grammar *	grammar,
		const char *	left_part,
		StringArray *	right_part,
		const Probability	probability
	)

Add a new syntactic rule to the grammar

Parameters:

[in]	grammar	The destination grammar
[in]	left_part	The left part of the rule
[in]	right_part	The right part of the rule
[in]	probability	The probability associated to the rule

Returns:

The index of the inserted rules (0 if operation fails)

See also:

grammarIncrementRuleFrequency()

Former(s) function(s):

Ajoute_Regle

int grammarCreate

(

Grammar *

grammar

)

Allow and initialize a new grammar

Parameters:

[out]

grammar

The grammar to instantiate

Returns:

A not null error code if operation fails

See also:

grammarFree()

Former(s) function(s):

Init_Grammaire

void grammarDump	(	const Grammar *	grammar,
		int(*)(const char *,...)	print,
		const gboolean	rules_number
	)

Dump the list of syntactic rules stored by a grammar

Parameters:

[in]	grammar	The source grammar
[in]	print	The print function used to dump
[in]	rules_number	Flag indicating whether rules numeration must be printed or not

Former(s) function(s):

Liste_Grammaire

int grammarExport	(	const Grammar *	grammar,
		const char *	filename
	)

Save the list of syntactic rules of a grammar in a human-readable ASCII file. The content of the destination file corresponds to a grammarDump() call.

Parameters:

[in]	grammar	The source grammar
[in]	filename	The textual filename where to output

Returns:

A not null error code if operation fails

See also:

grammarImport()

Former(s) function(s):

Exporte_Grammaire

void grammarFree

(

Grammar *

grammar

)

Free the memory allocated to a grammar

Parameters:

[in]

grammar

The grammar to free

Remarks:

If the grammar has been loaded with grammarLoad(), the Grammar::words field is also freed

See also:

grammarCreate()

Former(s) function(s):

Libere_Grammaire

LongArray * grammarGetIndexFromRule	(	const Grammar *	grammar,
		const char *	left_part,
		const StringArray *	right_part
	)

Look for all index (maybe several or none) of rules specified by given left and right parts

Parameters:

[in]	grammar	The source grammar
[in]	left_part	The left part of the rule(s) to look for
[in]	right_part	The right part of the rule(s) to look for

Returns:

The list of rules index

See also:

grammarGetRuleFromIndex()

Former(s) function(s):

Regle_vers_Numero

LexicalEntryIndex grammarGetNTInternalCode	(	const Grammar *	grammar,
		const char *	nt
	)

Return the (internal) numeric value associated to a (surface) textual format non-terminal

Parameters:

[in]	grammar	The source grammar
[in]	nt	The non-terminal (NT) to look for. If the NT is surrounded by a couple of INDIC_LEXICAL characters, the encapsulated string is considered as a vocabulary word and searched into the Grammar::words field. If the graphy is not found, an error is raised

Returns:

The value associated to the given non-terminal (0 if not found)

See also:

grammarGetNTString()

Former(s) function(s):

Convert_NT_char

void grammarGetNTString	(	const Grammar *	grammar,
		const LexicalEntryIndex	nt_index,
		GString *	output
	)

Return the (external) textual value associated to a (internal) numeric format non-terminal using the following conventions:

• null index (0) is not used;
• index from 1 to Grammar::top_level_nt - 1 are pre-terminals (parts of speech of Grammar::words);
• index from Grammar::top_level_nt to Grammar::top_level_nt + lexiconGetSize(RulesLexicon::conversion) are non-terminals from RulesLexicon::conversion;
• greater index are decoded as lexicalized terminals using the unsigned value of - nt_index - 1.

Parameters:

[in]	grammar	The source grammar
[in]	nt_index	The intern (numeric) representation of the non-terminal to convert
[out]	output	The string where to output

Remarks:

According to the mentioned conventions, the number of vocabulary words (stored by the Grammar::words) added to the number of non-terminals (stored by RulesLexicon::conversion) must be inferior to ULONG_MAX

See also:

grammarGetNTInternalCode()

Former(s) function(s):

Convert_NT

void grammarGetRuleFromIndex	(	const Grammar *	grammar,
		const LexicalEntryIndex	rule_index,
		char **	left_part,
		StringArray *	right_part,
		Probability *	probability
	)

Extract the syntactic rule from its index

Parameters:

[in]	grammar	The source grammar
[in]	rule_index	The index of the rule to extract
[out]	left_part	The left part of the extracted rule
[out]	right_part	The right part of the extracted rule
[out]	probability	The probability of the extracted rule

Returns:

The list of rules index

Remarks:

If no rule is found (invalid index), left_part parameter is set to NULL

See also:

grammarGetIndexFromRule()

Former(s) function(s):

Numero_vers_Regle

int grammarImport	(	Grammar *	grammar,
		const char *	filename,
		const gboolean	probabilistic
	)

Load a grammar from the content of a human-readable ASCII file. For proper processing, it's mandatory that the first non-terminal met in the input file must be the top level NT.

Parameters:

[out]	grammar	The grammar where to import
[in]	filename	The name of the textual file to import
[in]	probabilistic	Set if the given textual file contains probabilities

Returns:

A not null error code if operation fails

Remarks:

The Grammar::words field must be set to the vocabulary lexicon associated to the imported grammar

See also:

grammarExport()

Former(s) function(s):

Importe_Grammaire

Probability grammarIncrementRuleFrequency	(	Grammar *	grammar,
		LexicalEntryIndex *	rule_index,
		const char *	left_part,
		StringArray *	right_part
	)

Increment from one unity the probability field of a syntactic rule. The specified rule is added with a probability of 1 if it doesn't exist already in the grammar. When the rule insertion process is over, a lexiconNormalizeProba(grammar->rules->elements) computes the right probability for each rule.

Parameters:

[in]	grammar	The destination grammar
[in]	rule_index	The syntactic rule index If the given index (not its pointer) is 0, its value is ignored (for example in case of single rule) and set to the index of the incremented rule; if the given index corresponds to specified rule, its probability is incremented (useful when many rules have the same left and right parts); if the given index doesn't correspond to an other rule from the specified one, nothing is done; if the specified rule index is not used, the given rule is added with a probability of 1 and the rule index is set to the one of the new rule.
[in]	left_part	The left part of the rule
[in]	right_part	The right part of the rule

Returns:

The value of the probability field of the specified rule after the incrementation.

See also:

grammarAddRule()

Former(s) function(s):

Ajoute_Une_Occurence_Regle

int grammarLoad	(	Grammar *	grammar,
		const char *	grammar_filename
	)

Load a grammar from a set of binary files. See grammarSave for more informations on the required files.

Parameters:

[out]	grammar	The grammar where to load
[in]	grammar_filename	The filename of the grammar header file

Returns:

A not null error code if operation fails

Former(s) function(s):

Read_Grammaire

int grammarSave	(	const Grammar *	grammar,
		const char *	lexicon_filename,
		const char *	grammar_filename
	)

Save a grammar in a set of binary files. The operation generates:

• a (human-readable) header file named grammar_filename + GRAMMAR_FILE_EXT that stores the internal (numeric) value of the top level non-terminal, the binary filename of the word lexicon, the names of the binary files that store the rules lexicon and the conversion table;
• a set of binary files starting with grammar_filename + RULE_FILE_EXT and that store the rule lexicon;
• a set of binary files starting with grammar_filename + CONV_FILE_EXT and that store the conversion table.

Parameters:

[in]	grammar	The grammar to save
[in]	lexicon_filename	The binary filename of the word lexicon associated to the grammar
[in]	grammar_filename	The base filename of the saved grammar

Returns:

A not null error code if operation fails

See also:

grammarLoad()

Former(s) function(s):

Write_Grammaire

---