github.com/tiagovtristao/plz@v13.4.0+incompatible/src/parse/asp/README.md (about)

     1  ASP
     2  ===
     3  
     4  This package implements a custom parser for BUILD files.
     5  
     6  The so-far-unnamed BUILD language is (almost) a subset of Python,
     7  with many of its more advanced or dynamic features stripped out. Obviously
     8  it is not easy to implement even a subset of it and so many aspects
     9  remain unimplemented. Some of the notable differences are:
    10   * The `import`, `try`, `except`, `finally`, `class`, `global`, `nonlocal`,
    11     `while` and `async` keywords are not available. It is therefore possible but
    12     discouraged to use these as identifiers.
    13   * The `raise` and `assert` statements are supported, but since it is not
    14     possible to catch exceptions they only serve to signal catastrophic errors.
    15   * List and dict comprehensions are supported, but not Python's more general
    16     generator expressions. Up to two 'for' clauses are permitted.
    17   * Most builtin functions are not available.
    18   * Dictionaries are supported, but can only be keyed by strings.
    19   * The only builtin types are `bool`, `int`, `str`, `list`, `dict` and functions.
    20     There are no `float`, `complex`, `set`, `frozenset` or `bytes` types.
    21   * Operators `+`, `<`, `>`, `%`, `and`, `or`, `in`, `not in`, `==`, `>=`,
    22     `<=` and `!=` are supported in most appropriate cases. Other operators
    23     are not available.
    24   * Limited string interpolation is available via `%`. `format()` is also available
    25     but its implementation is incomplete and use is discouraged.
    26   * The `+=` augmented assignment operator is available in addition to `=` for
    27     normal assignment. Other augmented assignment operations aren't available.
    28   * Operator precedence is not always the same as Python's at present.
    29     This may well change in later versions, although users are encouraged to
    30     avoid relying on precedence details where possible.
    31   * The accepted syntax likely differs in minor ways from Python's due to
    32     implementation details on our part or limitations in how our parser
    33     treats files. In general we try to match Python's semantics but only
    34     as a best-effort; many of the differences mentioned here are deliberate.
    35   * `append` and `extend` on list objects are troublesome - our lists are a little
    36     more immutable (80% of the time they're immutable every time) than Python lists
    37     and hence those functions sort of work but don't have exactly the same semantics
    38     as the original (e.g. they may not always modify the original if it originated
    39     from a surrounding scope).
    40     Users are encouraged to use the `+=` augmented assignment operator instead.
    41   * `subinclude()` has slightly different semantics now. Subincluded files must
    42     include their dependencies (it is not sufficient simply to do them in order).
    43     Subincludes should not attempt to mutate global objects.
    44  
    45  TODOs (in no particular order of importance):
    46   * Better guarantees around ordering. Consider banishing sorted().
    47   * Better operator precedence.
    48  
    49  The name is reminiscent of AST, and a play on an asp being a smaller snake than a python.