| # Copyright (C) 2013 Google Inc. All rights reserved. |
| # |
| # Redistribution and use in source and binary forms, with or without |
| # modification, are permitted provided that the following conditions are |
| # met: |
| # |
| # * Redistributions of source code must retain the above copyright |
| # notice, this list of conditions and the following disclaimer. |
| # * Redistributions in binary form must reproduce the above |
| # copyright notice, this list of conditions and the following disclaimer |
| # in the documentation and/or other materials provided with the |
| # distribution. |
| # * Neither the name of Google Inc. nor the names of its |
| # contributors may be used to endorse or promote products derived from |
| # this software without specific prior written permission. |
| # |
| # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| |
| """Parser for Blink IDL. |
| |
| The parser uses the PLY (Python Lex-Yacc) library to build a set of parsing |
| rules which understand the Blink dialect of Web IDL. |
| It derives from a standard Web IDL parser, overriding rules where Blink IDL |
| differs syntactically or semantically from the base parser, or where the base |
| parser diverges from the Web IDL standard. |
| |
| Web IDL: |
| http://www.w3.org/TR/WebIDL/ |
| Web IDL Grammar: |
| http://www.w3.org/TR/WebIDL/#idl-grammar |
| PLY: |
| http://www.dabeaz.com/ply/ |
| |
| Design doc: |
| http://www.chromium.org/developers/design-documents/idl-compiler#TOC-Front-end |
| """ |
| |
| # Disable check for line length and Member as Function due to how grammar rules |
| # are defined with PLY |
| # |
| # pylint: disable=R0201 |
| # pylint: disable=C0301 |
| # |
| # Disable attribute validation, as lint can't import parent class to check |
| # pylint: disable=E1101 |
| |
| import os.path |
| import sys |
| |
| # PLY is in Chromium src/third_party/ply |
| module_path, module_name = os.path.split(__file__) |
| third_party = os.path.join(module_path, os.pardir, os.pardir, os.pardir, os.pardir) |
| # Insert at front to override system libraries, and after path[0] == script dir |
| sys.path.insert(1, third_party) |
| from ply import yacc |
| |
| # Base parser is in Chromium src/tools/idl_parser |
| tools_dir = os.path.join(module_path, os.pardir, os.pardir, os.pardir, os.pardir, os.pardir, 'tools') |
| idl_parser_dir = os.path.join(module_path, os.pardir, os.pardir, os.pardir, os.pardir, os.pardir, 'tools', 'idl_parser') |
| sys.path.append(tools_dir) |
| sys.path.append(idl_parser_dir) |
| |
| from idl_parser.idl_parser import IDLParser, ListFromConcat |
| from idl_parser.idl_parser import ParseFile as parse_file |
| |
| from blink_idl_lexer import BlinkIDLLexer |
| import blink_idl_lexer |
| |
| |
| # Explicitly set starting symbol to rule defined only in base parser. |
| # BEWARE that the starting symbol should NOT be defined in both the base parser |
| # and the derived one, as otherwise which is used depends on which line number |
| # is lower, which is fragile. Instead, either use one in base parser or |
| # create a new symbol, so that this is unambiguous. |
| # FIXME: unfortunately, this doesn't work in PLY 3.4, so need to duplicate the |
| # rule below. |
| STARTING_SYMBOL = 'Definitions' |
| |
| # We ignore comments (and hence don't need 'Top') but base parser preserves them |
| # FIXME: Upstream: comments should be removed in base parser |
| REMOVED_RULES = ['Top', # [0] |
| 'Comments', # [0.1] |
| 'CommentsRest', # [0.2] |
| ] |
| |
| # Remove rules from base class |
| # FIXME: add a class method upstream: @classmethod IDLParser._RemoveRules |
| for rule in REMOVED_RULES: |
| production_name = 'p_' + rule |
| delattr(IDLParser, production_name) |
| |
| |
| class BlinkIDLParser(IDLParser): |
| # [1] |
| # FIXME: Need to duplicate rule for starting symbol here, with line number |
| # *lower* than in the base parser (idl_parser.py). |
| # This is a bug in PLY: it determines starting symbol by lowest line number. |
| # This can be overridden by the 'start' parameter, but as of PLY 3.4 this |
| # doesn't work correctly. |
| def p_Definitions(self, p): |
| """Definitions : ExtendedAttributeList Definition Definitions |
| | """ |
| if len(p) > 1: |
| p[2].AddChildren(p[1]) |
| p[0] = ListFromConcat(p[2], p[3]) |
| |
| # Below are grammar rules used by yacc, given by functions named p_<RULE>. |
| # * The docstring is the production rule in BNF (grammar). |
| # * The body is the yacc action (semantics). |
| # |
| # The PLY framework builds the actual low-level parser by introspecting this |
| # parser object, selecting all attributes named p_<RULE> as grammar rules. |
| # It extracts the docstrings and uses them as the production rules, building |
| # the table of a LALR parser, and uses the body of the functions as actions. |
| # |
| # Reference: |
| # http://www.dabeaz.com/ply/ply.html#ply_nn23 |
| # |
| # Review of yacc: |
| # Yacc parses a token stream, internally producing a Concrete Syntax Tree |
| # (CST), where each node corresponds to a production rule in the grammar. |
| # At each node, it runs an action, which is usually "produce a node in the |
| # Abstract Syntax Tree (AST)" or "ignore this node" (for nodes in the CST |
| # that aren't included in the AST, since only needed for parsing). |
| # |
| # The rules use pseudo-variables; in PLY syntax: |
| # p[0] is the left side: assign return value to p[0] instead of returning, |
| # p[1] ... p[n] are the right side: the values can be accessed, and they |
| # can be modified. |
| # (In yacc these are $$ and $1 ... $n.) |
| # |
| # The rules can look cryptic at first, but there are a few standard |
| # transforms from the CST to AST. With these in mind, the actions should |
| # be reasonably legible. |
| # |
| # * Ignore production |
| # Discard this branch. Primarily used when one alternative is empty. |
| # |
| # Sample code: |
| # if len(p) > 1: |
| # p[0] = ... |
| # # Note no assignment if len(p) == 1 |
| # |
| # * Eliminate singleton production |
| # Discard this node in the CST, pass the next level down up the tree. |
| # Used to ignore productions only necessary for parsing, but not needed |
| # in the AST. |
| # |
| # Sample code: |
| # p[0] = p[1] |
| # |
| # * Build node |
| # The key type of rule. In this parser, produces object of class IDLNode. |
| # There are several helper functions: |
| # * BuildProduction: actually builds an IDLNode, based on a production. |
| # * BuildAttribute: builds an IDLAttribute, which is a temporary |
| # object to hold a name-value pair, which is then |
| # set as a Property of the IDLNode when the IDLNode |
| # is built. |
| # * BuildNamed: Same as BuildProduction, and sets the 'NAME' property. |
| # * BuildTrue: BuildAttribute with value True, for flags. |
| # See base idl_parser.py for definitions and more examples of use. |
| # |
| # Sample code: |
| # # Build node of type NodeType, with value p[1], and children. |
| # p[0] = self.BuildProduction('NodeType', p, 1, children) |
| # |
| # # Build named node of type NodeType, with name and value p[1]. |
| # # (children optional) |
| # p[0] = self.BuildNamed('NodeType', p, 1) |
| # |
| # # Make a list |
| # # Used if one node has several children. |
| # children = ListFromConcat(p[2], p[3]) |
| # p[0] = self.BuildProduction('NodeType', p, 1, children) |
| # |
| # # Also used to collapse the right-associative tree |
| # # produced by parsing a list back into a single list. |
| # """Foos : Foo Foos |
| # |""" |
| # if len(p) > 1: |
| # p[0] = ListFromConcat(p[1], p[2]) |
| # |
| # # Add children. |
| # # Primarily used to add attributes, produced via BuildTrue. |
| # # p_StaticAttribute |
| # """StaticAttribute : STATIC Attribute""" |
| # p[2].AddChildren(self.BuildTrue('STATIC')) |
| # p[0] = p[2] |
| # |
| # Numbering scheme for the rules is: |
| # [1] for Web IDL spec (or additions in base parser) |
| # These should all be upstreamed to the base parser. |
| # [b1] for Blink IDL changes (overrides Web IDL) |
| # [b1.1] for Blink IDL additions, auxiliary rules for [b1] |
| # Numbers are as per Candidate Recommendation 19 April 2012: |
| # http://www.w3.org/TR/2012/CR-WebIDL-20120419/ |
| |
| # [b27] Add strings, more 'Literal' productions |
| # 'Literal's needed because integers and strings are both internally strings |
| def p_ConstValue(self, p): |
| """ConstValue : BooleanLiteral |
| | FloatLiteral |
| | IntegerLiteral |
| | StringLiteral |
| | null""" |
| # Standard is (no 'string', fewer 'Literal's): |
| # ConstValue : BooleanLiteral |
| # | FloatLiteral |
| # | integer |
| # | NULL |
| p[0] = p[1] |
| |
| # [b27.1] |
| def p_IntegerLiteral(self, p): |
| """IntegerLiteral : integer""" |
| p[0] = ListFromConcat(self.BuildAttribute('TYPE', 'integer'), |
| self.BuildAttribute('NAME', p[1])) |
| |
| # [b27.2] |
| def p_StringLiteral(self, p): |
| """StringLiteral : string""" |
| p[0] = ListFromConcat(self.BuildAttribute('TYPE', 'DOMString'), |
| self.BuildAttribute('NAME', p[1])) |
| |
| # [b47] |
| def p_ExceptionMember(self, p): |
| """ExceptionMember : Const |
| | ExceptionField |
| | Attribute |
| | ExceptionOperation""" |
| # Standard is (no Attribute, no ExceptionOperation): |
| # ExceptionMember : Const |
| # | ExceptionField |
| # FIXME: In DOMException.idl, Attributes should be changed to |
| # ExceptionFields, and Attribute removed from this rule. |
| p[0] = p[1] |
| |
| # [b47.1] FIXME: rename to ExceptionAttribute |
| def p_Attribute(self, p): |
| """Attribute : ReadOnly ATTRIBUTE Type identifier ';'""" |
| p[0] = self.BuildNamed('Attribute', p, 4, |
| ListFromConcat(p[1], p[3])) |
| |
| # [b47.2] |
| def p_ExceptionOperation(self, p): |
| """ExceptionOperation : Type identifier '(' ')' ';'""" |
| # Needed to handle one case in DOMException.idl: |
| # // Override in a Mozilla compatible format |
| # [NotEnumerable] DOMString toString(); |
| # Limited form of Operation to prevent others from being added. |
| # FIXME: Should be a stringifier instead. |
| p[0] = self.BuildNamed('ExceptionOperation', p, 2, p[1]) |
| |
| # Extended attributes |
| # [b49] Override base parser: remove comment field, since comments stripped |
| # FIXME: Upstream |
| def p_ExtendedAttributeList(self, p): |
| """ExtendedAttributeList : '[' ExtendedAttribute ExtendedAttributes ']' |
| | """ |
| if len(p) > 3: |
| items = ListFromConcat(p[2], p[3]) |
| p[0] = self.BuildProduction('ExtAttributes', p, 1, items) |
| |
| # Error handling for ExtendedAttributeList. |
| # We can't upstream this because we override ExtendedAttributeList. |
| def p_ExtendedAttributeListError(self, p): |
| """ExtendedAttributeList : '[' ExtendedAttribute ',' error""" |
| p[0] = self.BuildError(p, "ExtendedAttributeList") |
| |
| # [b50] Allow optional trailing comma |
| # Blink-only, marked as WONTFIX in Web IDL spec: |
| # https://www.w3.org/Bugs/Public/show_bug.cgi?id=22156 |
| def p_ExtendedAttributes(self, p): |
| """ExtendedAttributes : ',' ExtendedAttribute ExtendedAttributes |
| | ',' |
| |""" |
| if len(p) > 3: |
| p[0] = ListFromConcat(p[2], p[3]) |
| |
| # [b51] Add ExtendedAttributeStringLiteral and ExtendedAttributeStringLiteralList |
| def p_ExtendedAttribute(self, p): |
| """ExtendedAttribute : ExtendedAttributeNoArgs |
| | ExtendedAttributeArgList |
| | ExtendedAttributeIdent |
| | ExtendedAttributeIdentList |
| | ExtendedAttributeNamedArgList |
| | ExtendedAttributeStringLiteral |
| | ExtendedAttributeStringLiteralList""" |
| p[0] = p[1] |
| |
| # Blink extension: Add support for string literal Extended Attribute values |
| def p_ExtendedAttributeStringLiteral(self, p): |
| """ExtendedAttributeStringLiteral : identifier '=' StringLiteral """ |
| def unwrap_string(ls): |
| """Reach in and grab the string literal's "NAME".""" |
| return ls[1].value |
| |
| value = self.BuildAttribute('VALUE', unwrap_string(p[3])) |
| p[0] = self.BuildNamed('ExtAttribute', p, 1, value) |
| |
| # Blink extension: Add support for compound Extended Attribute values over string literals ("A","B") |
| def p_ExtendedAttributeStringLiteralList(self, p): |
| """ExtendedAttributeStringLiteralList : identifier '=' '(' StringLiteralList ')' """ |
| value = self.BuildAttribute('VALUE', p[4]) |
| p[0] = self.BuildNamed('ExtAttribute', p, 1, value) |
| |
| # Blink extension: one or more string literals. The values aren't propagated as literals, |
| # but their by their value only. |
| def p_StringLiteralList(self, p): |
| """StringLiteralList : StringLiteral ',' StringLiteralList |
| | StringLiteral""" |
| def unwrap_string(ls): |
| """Reach in and grab the string literal's "NAME".""" |
| return ls[1].value |
| |
| if len(p) > 3: |
| p[0] = ListFromConcat(unwrap_string(p[1]), p[3]) |
| else: |
| p[0] = ListFromConcat(unwrap_string(p[1])) |
| |
| def __init__(self, |
| # common parameters |
| debug=False, |
| # local parameters |
| rewrite_tables=False, |
| # idl_parser parameters |
| lexer=None, verbose=False, mute_error=False, |
| # yacc parameters |
| outputdir='', optimize=True, write_tables=False, |
| picklefile=None): |
| if debug: |
| # Turn off optimization and caching, and write out tables, |
| # to help debugging |
| optimize = False |
| outputdir = None |
| picklefile = None |
| write_tables = True |
| if outputdir: |
| picklefile = picklefile or os.path.join(outputdir, 'parsetab.pickle') |
| if rewrite_tables: |
| try: |
| os.unlink(picklefile) |
| except OSError: |
| pass |
| |
| lexer = lexer or BlinkIDLLexer(debug=debug, |
| outputdir=outputdir, |
| optimize=optimize) |
| self.lexer = lexer |
| self.tokens = lexer.KnownTokens() |
| # Using SLR (instead of LALR) generates the table faster, |
| # but produces the same output. This is ok b/c Web IDL (and Blink IDL) |
| # is an SLR grammar (as is often the case for simple LL(1) grammars). |
| # |
| # Optimized mode substantially decreases startup time (by disabling |
| # error checking), and also allows use of Python's optimized mode. |
| # See: Using Python's Optimized Mode |
| # http://www.dabeaz.com/ply/ply.html#ply_nn38 |
| # |
| # |picklefile| allows simpler importing than |tabmodule| (parsetab.py), |
| # as we don't need to modify sys.path; virtually identical speed. |
| # See: CHANGES, Version 3.2 |
| # http://ply.googlecode.com/svn/trunk/CHANGES |
| self.yaccobj = yacc.yacc(module=self, |
| start=STARTING_SYMBOL, |
| method='SLR', |
| debug=debug, |
| optimize=optimize, |
| write_tables=write_tables, |
| picklefile=picklefile) |
| self.parse_debug = debug |
| self.verbose = verbose |
| self.mute_error = mute_error |
| self._parse_errors = 0 |
| self._parse_warnings = 0 |
| self._last_error_msg = None |
| self._last_error_lineno = 0 |
| self._last_error_pos = 0 |
| |
| |
| ################################################################################ |
| |
| def main(argv): |
| # If file itself executed, cache lex/parse tables |
| try: |
| outputdir = argv[1] |
| except IndexError as err: |
| print('Usage: %s OUTPUT_DIR' % argv[0]) |
| return 1 |
| blink_idl_lexer.main(argv) |
| # Important: rewrite_tables=True causes the cache file to be deleted if it |
| # exists, thus making sure that PLY doesn't load it instead of regenerating |
| # the parse table. |
| parser = BlinkIDLParser(outputdir=outputdir, rewrite_tables=True) |
| |
| |
| if __name__ == '__main__': |
| sys.exit(main(sys.argv)) |
