diff options
Diffstat (limited to 'docs/miscellaneous.rst')
| -rw-r--r-- | docs/miscellaneous.rst | 118 |
1 files changed, 117 insertions, 1 deletions
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 85fc286c..304fce14 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -95,6 +95,59 @@ is simplified to code which can also be compiled from even though the instructions contained a jump in the beginning. +.. index:: source mappings + +*************** +Source Mappings +*************** + +As part of the AST output, the compiler provides the range of the source +code that is represented by the respective node in the AST. This can be +used for various purposes ranging from static analysis tools that report +errors based on the AST and debugging tools that highlight local variables +and their uses. + +Furthermore, the compiler can also generate a mapping from the bytecode +to the range in the source code that generated the instruction. This is again +important for static analysis tools that operate on bytecode level and +for displaying the current position in the source code inside a debugger +or for breakpoint handling. + +Both kinds of source mappings use integer indentifiers to refer to source files. +These are regular array indices into a list of source files usually called +``"sourceList"``, which is part of the combined-json and the output of +the json / npm compiler. + +The source mappings inside the AST use the following +notation: + +``s:l:f`` + +Where ``s`` is the byte-offset to the start of the range in the source file, +``l`` is the length of the source range in bytes and ``f`` is the source +index mentioned above. + +The encoding in the source mapping for the bytecode is more complicated: +It is a list of ``s:l:f:j`` separated by ``;``. Each of these +elements corresponds to an instruction, i.e. you cannot use the byte offset +but have to use the instruction offset (push instructions are longer than a single byte). +The fields ``s``, ``l`` and ``f`` are as above and ``j`` can be either +``i``, ``o`` or ``-`` signifying whether a jump instruction goes into a +function, returns from a function or is a regular jump as part of e.g. a loop. + +In order to compress these source mappings especially for bytecode, the +following rules are used: + + - If a field is empty, the value of the preceding element is used. + - If a ``:`` is missing, all following fields are considered empty. + +This means the following source mappings represent the same information: + +``1:2:1;1:9:1;2:1:2;2:1:2;2:1:2`` + +``1:2:1;:9;2::2;;`` + + .. index:: ! commandline compiler, compiler;commandline, ! solc, ! linker .. _commandline-compiler: @@ -149,6 +202,69 @@ Tips and Tricks Cheatsheet ********** +.. index:: precedence + +.. _order: + +Order of Precedence of Operators +================================ + +The following is the order of precedence for operators, listed in order of evaluation. + ++------------+-------------------------------------+--------------------------------------------+ +| Precedence | Description | Operator | ++============+=====================================+============================================+ +| *1* | Postfix increment and decrement | ``++``, ``--`` | ++ +-------------------------------------+--------------------------------------------+ +| | Function-like call | ``<func>(<args...>)`` | ++ +-------------------------------------+--------------------------------------------+ +| | Array subscripting | ``<array>[<index>]`` | ++ +-------------------------------------+--------------------------------------------+ +| | Member access | ``<object>.<member>`` | ++ +-------------------------------------+--------------------------------------------+ +| | Parentheses | ``(<statement>)`` | ++------------+-------------------------------------+--------------------------------------------+ +| *2* | Prefix increment and decrement | ``++``, ``--`` | ++ +-------------------------------------+--------------------------------------------+ +| | Unary plus and minus | ``+``, ``-`` | ++ +-------------------------------------+--------------------------------------------+ +| | Unary operations | ``after``, ``delete`` | ++ +-------------------------------------+--------------------------------------------+ +| | Logical NOT | ``!`` | ++ +-------------------------------------+--------------------------------------------+ +| | Bitwise NOT | ``~`` | ++------------+-------------------------------------+--------------------------------------------+ +| *3* | Exponentiation | ``**`` | ++------------+-------------------------------------+--------------------------------------------+ +| *4* | Multiplication, division and modulo | ``*``, ``/``, ``%`` | ++------------+-------------------------------------+--------------------------------------------+ +| *5* | Addition and subtraction | ``+``, ``-`` | ++------------+-------------------------------------+--------------------------------------------+ +| *6* | Bitwise shift operators | ``<<``, ``>>`` | ++------------+-------------------------------------+--------------------------------------------+ +| *7* | Bitwise AND | ``&`` | ++------------+-------------------------------------+--------------------------------------------+ +| *8* | Bitwise XOR | ``^`` | ++------------+-------------------------------------+--------------------------------------------+ +| *9* | Bitwise OR | ``|`` | ++------------+-------------------------------------+--------------------------------------------+ +| *10* | Inequality operators | ``<``, ``>``, ``<=``, ``>=`` | ++------------+-------------------------------------+--------------------------------------------+ +| *11* | Equality operators | ``==``, ``!=`` | ++------------+-------------------------------------+--------------------------------------------+ +| *12* | Logical AND | ``&&`` | ++------------+-------------------------------------+--------------------------------------------+ +| *13* | Logical OR | ``||`` | ++------------+-------------------------------------+--------------------------------------------+ +| *14* | Ternary operator | ``<conditional> ? <if-true> : <if-false>`` | ++------------+-------------------------------------+--------------------------------------------+ +| *15* | Assignment operators | ``=``, ``|=``, ``^=``, ``&=``, ``<<=``, | +| | | ``>>=``, ``+=``, ``-=``, ``*=``, ``/=``, | +| | | ``%=`` | ++------------+-------------------------------------+--------------------------------------------+ +| *16* | Comma operator | ``,`` | ++------------+-------------------------------------+--------------------------------------------+ + .. index:: block, coinbase, difficulty, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, now, gas price, origin, sha3, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, send Global Variables @@ -192,7 +308,7 @@ Function Visibility Specifiers - ``public``: visible externally and internally (creates accessor function for storage/state variables) - ``private``: only visible in the current contract -- ``external``: only visible externally (only for functions) - i.e. can only be message-called (via ``this.fun``) +- ``external``: only visible externally (only for functions) - i.e. can only be message-called (via ``this.func``) - ``internal``: only visible internally |