## cr-parser

cr-parser

## Synopsis

                        CRParser;
                        CRParserPriv;
    CRParser *          cr_parser_new                       (CRTknzr *a_tknzr);
    CRParser *          cr_parser_new_from_buf              (guchar *a_buf,
                                                             gulong a_len,
                                                             enum CREncoding a_enc,
                                                             gboolean a_free_buf);
    CRParser *          cr_parser_new_from_file             (const guchar *a_file_uri,
                                                             enum CREncoding a_enc);
    CRParser *          cr_parser_new_from_input            (CRInput *a_input);
    enum CRStatus       cr_parser_set_tknzr                 (CRParser *a_this,
                                                             CRTknzr *a_tknzr);
    enum CRStatus       cr_parser_get_tknzr                 (CRParser *a_this,
                                                             CRTknzr **a_tknzr);
    enum CRStatus       cr_parser_get_parsing_location      (CRParser const *a_this,
                                                             CRParsingLocation *a_loc);
    enum CRStatus       cr_parser_try_to_skip_spaces_and_comments
                                                            (CRParser *a_this);
    enum CRStatus       cr_parser_set_sac_handler           (CRParser *a_this,
                                                             CRDocHandler *a_handler);
    enum CRStatus       cr_parser_get_sac_handler           (CRParser *a_this,
                                                             CRDocHandler **a_handler);
    enum CRStatus       cr_parser_set_use_core_grammar      (CRParser *a_this,
                                                             gboolean a_use_core_grammar);
    enum CRStatus       cr_parser_get_use_core_grammar      (CRParser const *a_this,
                                                             gboolean *a_use_core_grammar);
    enum CRStatus       cr_parser_parse                     (CRParser *a_this);
    enum CRStatus       cr_parser_parse_file                (CRParser *a_this,
                                                             const guchar *a_file_uri,
                                                             enum CREncoding a_enc);
    enum CRStatus       cr_parser_parse_buf                 (CRParser *a_this,
                                                             const guchar *a_buf,
                                                             gulong a_len,
                                                             enum CREncoding a_enc);
    enum CRStatus       cr_parser_set_default_sac_handler   (CRParser *a_this);
    enum CRStatus       cr_parser_parse_term                (CRParser *a_this,
                                                             CRTerm **a_term);
    enum CRStatus       cr_parser_parse_expr                (CRParser *a_this,
                                                             CRTerm **a_expr);
    enum CRStatus       cr_parser_parse_prio                (CRParser *a_this,
                                                             CRString **a_prio);
    enum CRStatus       cr_parser_parse_declaration         (CRParser *a_this,
                                                             CRString **a_property,
                                                             CRTerm **a_expr,
                                                             gboolean *a_important);
    enum CRStatus       cr_parser_parse_statement_core      (CRParser *a_this);
    enum CRStatus       cr_parser_parse_ruleset             (CRParser *a_this);
    enum CRStatus       cr_parser_parse_import              (CRParser *a_this,
                                                             GList **a_media_list,
                                                             CRString **a_import_string,
                                                             CRParsingLocation *a_location);
    enum CRStatus       cr_parser_parse_media               (CRParser *a_this);
    enum CRStatus       cr_parser_parse_page                (CRParser *a_this);
    enum CRStatus       cr_parser_parse_charset             (CRParser *a_this,
                                                             CRString **a_value,
                                                             CRParsingLocation *a_charset_sym_location);
    enum CRStatus       cr_parser_parse_font_face           (CRParser *a_this);
    void                cr_parser_destroy                   (CRParser *a_this);

## Description

## Details

### CRParser

    typedef struct {
            CRParserPriv *priv ;
    } CRParser;

### CRParserPriv

    typedef struct _CRParserPriv CRParserPriv;

### cr_parser_new ()

    CRParser *          cr_parser_new                       (CRTknzr *a_tknzr);

Creates a new parser to parse data coming the input stream given in parameter.

`a_tknzr` : | the tokenizer to use for the parsing.
Returns : | the newly created instance of CRParser, or NULL if an error occured.

### cr_parser_new_from_buf ()

    CRParser *          cr_parser_new_from_buf              (guchar *a_buf,
                                                             gulong a_len,
                                                             enum CREncoding a_enc,
                                                             gboolean a_free_buf);

Instanciates a new parser from a memory buffer.

`a_buf` : | the buffer to parse.
`a_len` : | the length of the data in the buffer.
`a_enc` : | the encoding of the input buffer a_buf.
`a_free_buf` : | if set to TRUE, a_buf will be freed during the destruction of the newly built instance of CRParser. If set to FALSE, it is up to the caller to eventually free it.
Returns : | the newly built parser, or NULL if an error arises.

### cr_parser_new_from_file ()

    CRParser *          cr_parser_new_from_file             (const guchar *a_file_uri,
                                                             enum CREncoding a_enc);

`a_file_uri` : | the uri of the file to parse.
`a_enc` : | the file encoding to use.
Returns : | the newly built parser.

### cr_parser_new_from_input ()

    CRParser *          cr_parser_new_from_input            (CRInput *a_input);

`a_input` : | the parser input stream to use.
Returns : | a newly built parser input.

### cr_parser_set_tknzr ()

    enum CRStatus       cr_parser_set_tknzr                 (CRParser *a_this,
                                                             CRTknzr *a_tknzr);

`a_this` : | the current instance of CRParser;
`a_tknzr` : | the new tokenizer.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_parser_get_tknzr ()

    enum CRStatus       cr_parser_get_tknzr                 (CRParser *a_this,
                                                             CRTknzr **a_tknzr);

Getter of the parser's underlying tokenizer

`a_this` : | the current instance of CRParser
`a_tknzr` : | out parameter. The returned tokenizer
Returns : | CR_OK upon succesful completion, an error code otherwise

### cr_parser_get_parsing_location ()

    enum CRStatus       cr_parser_get_parsing_location      (CRParser const *a_this,
                                                             CRParsingLocation *a_loc);

Gets the current parsing location.

`a_this` : | the current instance of CRParser
`a_loc` : | the parsing location to get.
Returns : | CR_OK upon succesful completion, an error code otherwise.

### cr_parser_try_to_skip_spaces_and_comments ()

    enum CRStatus       cr_parser_try_to_skip_spaces_and_comments
                                                            (CRParser *a_this);

Same as `cr_parser_try_to_skip_spaces()` but this one skips spaces and comments.

`a_this` : | the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_set_sac_handler ()

    enum CRStatus       cr_parser_set_sac_handler           (CRParser *a_this,
                                                             CRDocHandler *a_handler);

Sets a SAC document handler to the parser.

`a_this` : | the "this pointer" of the current instance of CRParser.
`a_handler` : | the handler to set.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_get_sac_handler ()

    enum CRStatus       cr_parser_get_sac_handler           (CRParser *a_this,
                                                             CRDocHandler **a_handler);

Gets the SAC document handler.

`a_this` : | the "this pointer" of the current instance of CRParser.
`a_handler` : | out parameter. The returned handler.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_set_use_core_grammar ()

    enum CRStatus       cr_parser_set_use_core_grammar      (CRParser *a_this,
                                                             gboolean a_use_core_grammar);

`a_this` : | the current instance of CRParser.
`a_use_core_grammar` : | where to parse against the css core grammar.
Returns : | CR_OK upon succesful completion, an error code otherwise.

### cr_parser_get_use_core_grammar ()

    enum CRStatus       cr_parser_get_use_core_grammar      (CRParser const *a_this,
                                                             gboolean *a_use_core_grammar);

`a_this` : | the current instance of CRParser.
`a_use_core_grammar` : | wether to use the core grammar or not.
Returns : | CR_OK upon succesful completion, an error code otherwise.

### cr_parser_parse ()

    enum CRStatus       cr_parser_parse                     (CRParser *a_this);

Parses the data that comes from the input previously associated to the current instance of CRParser.

`a_this` : | the current instance of CRParser.
Returns : | CR_OK upon succesful completion, an error code otherwise.

### cr_parser_parse_file ()

    enum CRStatus       cr_parser_parse_file                (CRParser *a_this,
                                                             const guchar *a_file_uri,
                                                             enum CREncoding a_enc);

Parses a the given in parameter.

`a_this` : | a pointer to the current instance of CRParser.
`a_file_uri` : | the uri to the file to load. For the time being,
`a_enc` : | the encoding of the file to parse. only local files are supported.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_buf ()

    enum CRStatus       cr_parser_parse_buf                 (CRParser *a_this,
                                                             const guchar *a_buf,
                                                             gulong a_len,
                                                             enum CREncoding a_enc);

Parses a stylesheet from a buffer

`a_this` : | the current instance of CRparser
`a_buf` : | the input buffer
`a_len` : | the length of the input buffer
`a_enc` : | the encoding of the buffer
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_parser_set_default_sac_handler ()

    enum CRStatus       cr_parser_set_default_sac_handler   (CRParser *a_this);

Sets the SAC handler associated to the current instance of CRParser to the default SAC handler.

`a_this` : | a pointer to the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_term ()

    enum CRStatus       cr_parser_parse_term                (CRParser *a_this,
                                                             CRTerm **a_term);

Parses a "term" as defined in the css2 spec, appendix D.1: term ::= unary_operator? [NUMBER S* | PERCENTAGE S* | LENGTH S* | EMS S* | EXS S* | ANGLE S* | TIME S* | FREQ S* | function ] | STRING S* | IDENT S* | URI S* | RGB S* | UNICODERANGE S* | hexcolor

TODO: handle parsing of 'RGB'

`a_this` : |
`a_term` : | out parameter. The successfully parsed term.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_expr ()

    enum CRStatus       cr_parser_parse_expr                (CRParser *a_this,
                                                             CRTerm **a_expr);

Parses an expression as defined by the css2 spec in appendix D.1: expr: term [ operator term ]*

`a_this` : | the current instance of CRParser.
`a_expr` : | out parameter. the parsed expression.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_parser_parse_prio ()

    enum CRStatus       cr_parser_parse_prio                (CRParser *a_this,
                                                             CRString **a_prio);

Parses a declaration priority as defined by the css2 grammar in appendix C: prio: IMPORTANT_SYM S*

`a_this` : | the current instance of CRParser.
`a_prio` : | a string representing the priority. Today, only "!important" is returned as only this priority is defined by css2.
Returns : | CR_OK upon successful completion, an error code otherwise.

### cr_parser_parse_declaration ()

    enum CRStatus       cr_parser_parse_declaration         (CRParser *a_this,
                                                             CRString **a_property,
                                                             CRTerm **a_expr,
                                                             gboolean *a_important);

TODO: return the parsed priority, so that upper layers can take benefit from it. Parses a "declaration" as defined by the css2 spec in appendix D.1: declaration ::= [property ':' S* expr prio?]?

`a_this` : | the "this pointer" of the current instance of CRParser.
`a_property` : | the successfully parsed property. The caller *must* free the returned pointer.
`a_expr` : | the expression that represents the attribute value. The caller *must* free the returned pointer.
`a_important` : |
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_statement_core ()

    enum CRStatus       cr_parser_parse_statement_core      (CRParser *a_this);

Parses a statement as defined by the css core grammar in chapter 4.1 of the css2 spec. statement : ruleset | at-rule;

`a_this` : | the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_ruleset ()

    enum CRStatus       cr_parser_parse_ruleset             (CRParser *a_this);

Parses a "ruleset" as defined in the css2 spec at appendix D.1. ruleset ::= selector [ ',' S* selector ]* '{' S* declaration? [ ';' S* declaration? ]* '}' S*;

This methods calls the the SAC handler on the relevant SAC handler callbacks whenever it encounters some specific constructions. See the documentation of CRDocHandler (the SAC handler) to know when which SAC handler is called.

`a_this` : | the "this pointer" of the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_import ()

    enum CRStatus       cr_parser_parse_import              (CRParser *a_this,
                                                             GList **a_media_list,
                                                             CRString **a_import_string,
                                                             CRParsingLocation *a_location);

Parses an 'import' declaration as defined in the css2 spec in appendix D.1:

import ::= @import [STRING|URI] S* [ medium [ ',' S* medium]* ]? ';' S*

`a_this` : | the "this pointer" of the current instance of CRParser.
`a_media_list` : | out parameter. A linked list of CRString Each CRString is a string that contains a 'medium' declaration part of the successfully parsed 'import' declaration.
`a_import_string` : | out parameter. A string that contains the 'import string". The import string can be either an uri (if it starts with the substring "uri(") or a any other css2 string. Note that *a_import_string must be initially set to NULL or else, this function will return CR_BAD_PARAM_ERROR.
`a_location` : | the location (line, column) where the import has been parsed
Returns : | CR_OK upon sucessfull completion, an error code otherwise.

### cr_parser_parse_media ()

    enum CRStatus       cr_parser_parse_media               (CRParser *a_this);

Parses a 'media' declaration as specified in the css2 spec at appendix D.1:

media ::= @media S* medium [ ',' S* medium ]* '{' S* ruleset* '}' S*

Note that this function calls the required sac handlers during the parsing to notify media productions. See CRDocHandler to know the callback called during @media parsing.

`a_this` : | the "this pointer" of the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_page ()

    enum CRStatus       cr_parser_parse_page                (CRParser *a_this);

Parses '@page' rule as specified in the css2 spec in appendix D.1: page ::= PAGE_SYM S* IDENT? pseudo_page? S* '{' S* declaration [ ';' S* declaration ]* '}' S*

This function also calls the relevant SAC handlers whenever it encounters a construction that must be reported to the calling application.

`a_this` : | the "this pointer" of the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_charset ()

    enum CRStatus       cr_parser_parse_charset             (CRParser *a_this,
                                                             CRString **a_value,
                                                             CRParsingLocation *a_charset_sym_location);

Parses a charset declaration as defined implictly by the css2 spec in appendix D.1: charset ::= CHARSET_SYM S* STRING S* ';'

`a_this` : | the "this pointer" of the current instance of CRParser.
`a_value` : | out parameter. The actual parsed value of the charset declararation. Note that for safety check reasons, *a_value must be set to NULL.
`a_charset_sym_location` : | the parsing location of the charset rule
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_parse_font_face ()

    enum CRStatus       cr_parser_parse_font_face           (CRParser *a_this);

Parses the "@font-face" rule specified in the css1 spec in appendix D.1:

font_face ::= FONT_FACE_SYM S* '{' S* declaration [ ';' S* declaration ]* '}' S*

This function will call SAC handlers whenever it is necessary.

`a_this` : | the current instance of CRParser.
Returns : | CR_OK upon successfull completion, an error code otherwise.

### cr_parser_destroy ()

    void                cr_parser_destroy                   (CRParser *a_this);

Destroys the current instance of CRParser.

`a_this` : | the current instance of CRParser to destroy.