cr-parser: Libcroco Reference Manual

## cr-parser cr-parser |

## Functions

CRParser * | cr_parser_new ()
CRParser * | cr_parser_new_from_buf ()
CRParser * | cr_parser_new_from_file ()
CRParser * | cr_parser_new_from_input ()
enum CRStatus | cr_parser_set_tknzr ()
enum CRStatus | cr_parser_get_tknzr ()
enum CRStatus | cr_parser_get_parsing_location ()
enum CRStatus | cr_parser_try_to_skip_spaces_and_comments ()
enum CRStatus | cr_parser_set_sac_handler ()
enum CRStatus | cr_parser_get_sac_handler ()
enum CRStatus | cr_parser_set_use_core_grammar ()
enum CRStatus | cr_parser_get_use_core_grammar ()
enum CRStatus | cr_parser_parse ()
enum CRStatus | cr_parser_parse_file ()
enum CRStatus | cr_parser_parse_buf ()
enum CRStatus | cr_parser_set_default_sac_handler ()
enum CRStatus | cr_parser_parse_term ()
enum CRStatus | cr_parser_parse_expr ()
enum CRStatus | cr_parser_parse_prio ()
enum CRStatus | cr_parser_parse_declaration ()
enum CRStatus | cr_parser_parse_statement_core ()
enum CRStatus | cr_parser_parse_ruleset ()
enum CRStatus | cr_parser_parse_import ()
enum CRStatus | cr_parser_parse_media ()
enum CRStatus | cr_parser_parse_page ()
enum CRStatus | cr_parser_parse_charset ()
enum CRStatus | cr_parser_parse_font_face ()
void | cr_parser_destroy ()

## Types and Values

struct | CRParser
| CRParserPriv

## Description

## Functions

### cr_parser_new ()

    CRParser *
    cr_parser_new (CRTknzr *a_tknzr);

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

Returns the newly created instance of CRParser, or NULL if an error occurred.

#### Parameters

a_tknzr | the tokenizer to use for the parsing. |

### 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.

Returns the newly built parser, or NULL if an error arises.

#### Parameters

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. |

### cr_parser_new_from_file ()

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

Returns the newly built parser.

#### Parameters

a_file_uri | the uri of the file to parse. |
a_enc | the file encoding to use. |

### cr_parser_new_from_input ()

    CRParser *
    cr_parser_new_from_input (CRInput *a_input);

Returns a newly built parser input.

#### Parameters

a_input | the parser input stream to use. |

### cr_parser_set_tknzr ()

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

Returns CR_OK upon successful completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser; |
a_tknzr | the new tokenizer. |

### cr_parser_get_tknzr ()

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

Getter of the parser's underlying tokenizer

Returns CR_OK upon succesful completion, an error code otherwise

#### Parameters

a_this | the current instance of CRParser |
a_tknzr | out parameter. The returned tokenizer |

### cr_parser_get_parsing_location ()

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

Gets the current parsing location.

Returns CR_OK upon succesful completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser |
a_loc | the parsing location to get. |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the "this pointer" of the current instance of CRParser. |
a_handler | the handler to set. |

### cr_parser_get_sac_handler ()

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

Gets the SAC document handler.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the "this pointer" of the current instance of CRParser. |
a_handler | out parameter. The returned handler. |

### cr_parser_set_use_core_grammar ()

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

Returns CR_OK upon succesful completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |
a_use_core_grammar | where to parse against the css core grammar. |

### cr_parser_get_use_core_grammar ()

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

Returns CR_OK upon succesful completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |
a_use_core_grammar | wether to use the core grammar or not. |

### 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.

Returns CR_OK upon succesful completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

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. |

### 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

Returns CR_OK upon successful completion, an error code otherwise.

#### Parameters

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 |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | a pointer to the current instance of CRParser. |

### 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'

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_term | out parameter. The successfully parsed term. |

### 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 ]*

Returns CR_OK upon successful completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |
a_expr | out parameter. the parsed expression. |

### 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*

Returns CR_OK upon successful completion, an error code otherwise.

#### Parameters

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. |

### 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?]?

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

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. |

### 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;

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the "this pointer" of the current instance of CRParser. |

### 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*

Returns CR_OK upon sucessfull completion, an error code otherwise.

#### Parameters

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 |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the "this pointer" of the current instance of CRParser. |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the "this pointer" of the current instance of CRParser. |

### 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* ';'

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

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 |

### 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.

Returns CR_OK upon successfull completion, an error code otherwise.

#### Parameters

a_this | the current instance of CRParser. |

### cr_parser_destroy ()

    void
    cr_parser_destroy (CRParser *a_this);

Destroys the current instance of CRParser.

#### Parameters

a_this | the current instance of CRParser to destroy. |

## Types and Values

### struct CRParser

    struct CRParser {
            CRParserPriv *priv ;
    };

### CRParserPriv

    typedef struct _CRParserPriv CRParserPriv;