diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contributing.rst | 2 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 9 | ||||
| -rw-r--r-- | docs/types.rst | 13 | ||||
| -rw-r--r-- | docs/yul.rst (renamed from docs/julia.rst) | 45 |
5 files changed, 37 insertions, 34 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 6717a8b9..b95cff1a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -111,7 +111,7 @@ Example: ``./test/libsolidity/syntaxTests/double_stateVariable_declaration.sol`` A syntax test must contain at least the contract under test itself, followed by the seperator ``----``. The additional comments above are used to describe the expected compiler errors or warnings. This section can be empty in case that the contract should compile without any errors or warnings. -In the above example, the state variable ``variable`` was declared twice, which is not allowed. This will result in a ``DeclarationError`` stating that the identifer was already declared. +In the above example, the state variable ``variable`` was declared twice, which is not allowed. This will result in a ``DeclarationError`` stating that the identifier was already declared. The tool that is being used for those tests is called ``isoltest`` and can be found under ``./test/tools/``. It is an interactive tool which allows editing of failing contracts using your prefered text editor. Let's try to break this test by removing the second declaration of ``variable``: diff --git a/docs/index.rst b/docs/index.rst index 80b0d6e7..a57b93e4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -169,7 +169,7 @@ Contents using-the-compiler.rst metadata.rst abi-spec.rst - julia.rst + yul.rst style-guide.rst common-patterns.rst bugs.rst diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index c7c32528..108d4c96 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -190,7 +190,7 @@ 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. +Both kinds of source mappings use integer identifiers 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. @@ -409,8 +409,11 @@ Reserved Keywords These keywords are reserved in Solidity. They might become part of the syntax in the future: -``abstract``, ``after``, ``case``, ``catch``, ``default``, ``final``, ``in``, ``inline``, ``let``, ``match``, ``null``, -``of``, ``relocatable``, ``static``, ``switch``, ``try``, ``type``, ``typeof``. +``abstract``, ``after``, ``alias``, ``apply``, ``auto``, ``case``, ``catch``, ``copyof``, ``default``, +``define``, ``final``, ``immutable``, ``implements``, ``in``, ``inline``, ``let``, ``macro``, ``match``, +``mutable``, ``null``, ``of``, ``override``, ``partial``, ``promise``, ``reference``, ``relocatable``, +``sealed``, ``sizeof``, ``static``, ``supports``, ``switch``, ``try``, ``type``, ``typedef``, ``typeof``, +``unchecked``. Language Grammar ================ diff --git a/docs/types.rst b/docs/types.rst index 08b74241..009896d5 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -60,15 +60,14 @@ operators are :ref:`literals<rational_literals>` (or literal expressions). Division by zero and modulus with zero throws a runtime exception. The result of a shift operation is the type of the left operand. The -expression ``x << y`` is equivalent to ``x * 2**y``, and ``x >> y`` is -equivalent to ``x / 2**y``. This means that shifting negative numbers -sign extends. Shifting by a negative amount throws a runtime exception. +expression ``x << y`` is equivalent to ``x * 2**y``, and, for positive integers, +``x >> y`` is equivalent to ``x / 2**y``. For negative ``x``, ``x >> y`` +is equivalent to dividing by a power of ``2`` while rounding down (towards negative infinity). +Shifting by a negative amount throws a runtime exception. .. warning:: - The results produced by shift right of negative values of signed integer types is different from those produced - by other programming languages. In Solidity, shift right maps to division so the shifted negative values - are going to be rounded towards zero (truncated). In other programming languages the shift right of negative values - works like division with rounding down (towards negative infinity). + Before version ``0.5.0`` a right shift ``x >> y`` for negative ``x`` was equivalent to ``x / 2**y``, + i.e. right shifts used rounding towards zero instead of rounding towards negative infinity. .. index:: ! ufixed, ! fixed, ! fixed point number diff --git a/docs/julia.rst b/docs/yul.rst index 91b91df2..4f5ef98f 100644 --- a/docs/julia.rst +++ b/docs/yul.rst @@ -1,18 +1,19 @@ -################################################# -Joyfully Universal Language for (Inline) Assembly -################################################# +### +Yul +### -.. _julia: +.. _yul: -.. index:: ! assembly, ! asm, ! evmasm, ! julia +.. index:: ! assembly, ! asm, ! evmasm, ! yul, julia, iulia -JULIA is an intermediate language that can compile to various different backends +Yul (previously also called JULIA or IULIA) is an intermediate language that can +compile to various different backends (EVM 1.0, EVM 1.5 and eWASM are planned). Because of that, it is designed to be a usable common denominator of all three platforms. It can already be used for "inline assembly" inside Solidity and -future versions of the Solidity compiler will even use JULIA as intermediate -language. It should also be easy to build high-level optimizer stages for JULIA. +future versions of the Solidity compiler will even use Yul as intermediate +language. It should also be easy to build high-level optimizer stages for Yul. .. note:: @@ -21,14 +22,14 @@ language. It should also be easy to build high-level optimizer stages for JULIA. to the EVM opcodes. Please resort to the inline assembly documentation for details. -The core components of JULIA are functions, blocks, variables, literals, +The core components of Yul are functions, blocks, variables, literals, for-loops, if-statements, switch-statements, expressions and assignments to variables. -JULIA is typed, both variables and literals must specify the type with postfix +Yul is typed, both variables and literals must specify the type with postfix notation. The supported types are ``bool``, ``u8``, ``s8``, ``u32``, ``s32``, ``u64``, ``s64``, ``u128``, ``s128``, ``u256`` and ``s256``. -JULIA in itself does not even provide operators. If the EVM is targeted, +Yul in itself does not even provide operators. If the EVM is targeted, opcodes will be available as built-in functions, but they can be reimplemented if the backend changes. For a list of mandatory built-in functions, see the section below. @@ -69,10 +70,10 @@ and ``add`` to be available. } } -Specification of JULIA -====================== +Specification of Yul +==================== -JULIA code is described in this chapter. JULIA code is usually placed into a JULIA object, which is described in the following chapter. +This chapter describes Yul code. It is usually placed inside a Yul object, which is described in the following chapter. Grammar:: @@ -156,7 +157,7 @@ Literals cannot be larger than the their type. The largest type defined is 256-b Scoping Rules ------------- -Scopes in JULIA are tied to Blocks (exceptions are functions and the for loop +Scopes in Yul are tied to Blocks (exceptions are functions and the for loop as explained below) and all declarations (``FunctionDefinition``, ``VariableDeclaration``) introduce new identifiers into these scopes. @@ -186,7 +187,7 @@ outside of that function. Formal Specification -------------------- -We formally specify JULIA by providing an evaluation function E overloaded +We formally specify Yul by providing an evaluation function E overloaded on the various nodes of the AST. Any functions can have side effects, so E takes two state objects and the AST node and returns two new state objects and a variable number of other values. @@ -303,7 +304,7 @@ We will use a destructuring notation for the AST nodes. Type Conversion Functions ------------------------- -JULIA has no support for implicit type conversion and therefore functions exist to provide explicit conversion. +Yul has no support for implicit type conversion and therefore functions exist to provide explicit conversion. When converting a larger type to a shorter type a runtime exception can occur in case of an overflow. Truncating conversions are supported between the following types: @@ -507,7 +508,7 @@ The following functions must be available: Backends -------- -Backends or targets are the translators from JULIA to a specific bytecode. Each of the backends can expose functions +Backends or targets are the translators from Yul to a specific bytecode. Each of the backends can expose functions prefixed with the name of the backend. We reserve ``evm_`` and ``ewasm_`` prefixes for the two proposed backends. Backend: EVM @@ -525,8 +526,8 @@ Backend: eWASM TBD -Specification of JULIA Object -============================= +Specification of Yul Object +=========================== Grammar:: @@ -537,9 +538,9 @@ Grammar:: HexLiteral = 'hex' ('"' ([0-9a-fA-F]{2})* '"' | '\'' ([0-9a-fA-F]{2})* '\'') StringLiteral = '"' ([^"\r\n\\] | '\\' .)* '"' -Above, ``Block`` refers to ``Block`` in the JULIA code grammar explained in the previous chapter. +Above, ``Block`` refers to ``Block`` in the Yul code grammar explained in the previous chapter. -An example JULIA Object is shown below: +An example Yul Object is shown below: .. code:: |