Documentación de Solidity 0.4.5 en español - 5. Diseño de un archivo fuente de Solidity
Puedes seguir desde aquí todos los capítulos traducidos, y la documentación original en inglés.
Los archivos fuente puede contener un número arbitrario de definiciones de contrato, incluye las directrices y las de pragma.
Versión Pragma
Los archivos fuente pueden (y deben) ser anotados con una versión pragma para razachar que sea compilado con versiones futuras del compilador que puedan introducir cambios incompatibles. Intentamos mantener tales cambios en el mínimo absoluto, especialmente al introducir cambios que de alguna manera requieran cambios en la sintaxis, pero esto no es siempre posible. Debido a ello, siempre es una buena idea leer el registro de cambios al menos por nuevos lanzamientos que contengan cambios rompedores (N. del T: esta documentación podría haber quedado algo obsoleta), esos lanzamientos siempre tendrán versiones de la forma 0.x.0 o x.0.0.
Versión pragma es utilizado así:
pragma solidity ^0.4.0;
Tal archivo fuente no compilará con un compilador anterior a la versión 0.4.0, y tampoco no funciunará con un compilador empezando de la forma version 0.5.0(esta segunda condición es añadida usando^). La idea detrás de esto es que no habrá cambios rompedores de hasta la versión 0.5.0, así que siempre podemos estar seguros de que nuestro código compilará como está destinado a hacer. No fijamos la versión exacta del compilador, así que los bugs de los lanzamientos son aún posibles.
Es posible especificar reglas mucho más complejas, las expresiones que siguen a aquellas usadas por npm.
Importando otros archivos fuente
Sintaxis y semántica
Solidity soporta sentencias import que son muy similares a aquellas disponibles en JavaScript (desde ES6 en adelante), sin embargo, no conoce el conepto de una "exportación por defecto".
A un nivel global, puedes usar las sentencias import de la siguiente forma:
import "filename";
Esta sentencia importa todos los símbolos globales de "filename" (y los símbolos importados ahí) en el ámbito global actual (es diferente que es ES6 pero al revés compatible con Solidity)
import * as symbolName from "filename";
...crea un símbolo global nuevo symbolName cuyos miembros son todos los símbolos globales de "filename".
import {symbol1 as alias, symbol2} from "filename";
...crea nuevos símbolos globales alias y symbol2 los cuales hacen referencia a symbol1 y symbol2 de "filename".
Otra sintaxis que no es parte de ES6, pero probablemente conveniente:
import "filename" as symbolName;
...la cual es equivalente a import * as symbolName from "filename";
Paths
Arriba, "filename" es siempre tratado como un path con / como directorio separador, . como el actual y .. como el directorio padre. Los nombres de path que no empiezan con . son tratados como paths absolutos.
Para importar un archivo x desde el mismo directorio que el archivo actual, usa ìmport "./x" as x;. Si usas import "x" as x;, otro archivo podría ser referenciado en su lugar (en un "directorio include" global).
Depende del compilador (mira abajo) resolver actualmente los paths. En general, la jerarquía de directorios no necesita reasignar estrictamente en tu sistema de archivos local, y también puede asignar a recursos descubiertos mediante e.g. ipfs, http o git.
Uso en compiladores actuales
Cuando se invoca al compilador, no es sólo posible especificar cómo descubrir el primer elemento de un path, si no que es posible especificar reasignaciones de prefijos de los paths, así por ejemplo github.com/ethereum/dapp-bin/library es remapeado a /usr/local/dapp-bin/library y el compilador leerá los archivos de ahí. Si las keys de la reasignación son prefijos u otras, se intenta primero la más larga. Esto permite un replanteo de los mapas, por ejemplo "" asigna a "/usr/local/include/solidity". Además, esas reasignaciones pueden depender del contexto, el cual te permite configurar packages para importar, por ejemplo, diferentes versiones de una biblioteca del mismo nombre.
solc:
Para solc (el compilador de línea de comandos), estas reasignaciones son provistos como argumentos context:prefix=target, donde ambas partes context: y =targetson opcionales (donde el 'target' predeterminado es 'prefix', en este caso). Todos los valores de reasignación que son archivos regulares son compilados (incluyendo sus dependencias). Este mecanismo es completamente compatible hacia atrás (siempre y cuando un nombre de archivo no contenga = o :) y no generará una ruptura. Todos las importanciones en archivos en o debajo del contexto del directorio que importan un archivo que empeza con prefijo son redireccionados reemplazando el 'prefix' mediante 'target'.
Así que, como ejemplo, si clonas github.com/ethereum/dapp-bin/ locally a /usr/local/dapp-binpuedes usar lo siguiente en tu archivo fuente:
import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;
y entonces ejecutar el compilador como
solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol
Como ejemplo más complejo, suponte que confías en algún módulo que usa una versión muy antigua de dapp-bin. Esa antigua versión de dapp-bin es verificadoa en /usr/local/dapp-bin_old, entonces puede usar
solc module1:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ \
module2:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin_old/ \
source.sol
así que todas las importaciones en module2 apuntan a la antigua versión las importaciones en module1 obtienen la nueva versión.
Observa que solc sólo te permite incluir archivos de determinados directorios: ellos tiene que estar en el directorio (o subdirectorio) de uno de los especificados explícitamente como archivos fuente o en el directorio (o subdirectorio) de un
Si hay múltiples reasignaciones que dirigen a un archivo válido, es elegida la reasignación con el prefijo común más larga.
browser-solidity:
El compilador basado en navegador provee una reasignación automática para github y también puede rcuperar ek archivo sobre la red: puedes importar la asignación iterable, por ejemplo
import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;.
Otros proveedores de código fuente puede ser añadidos en el futuro.
Comentarios
Son posibles los comentarios de una sóla línea // y comentarios de varias líneas /*...*/.
Single-line comments (//) and multi-line comments (/.../) are possible.
// Esto es comentario en una línea.
/*
Esto es un comentario
de varias líneas.
*/
Adicionalmente, hay otro tipo de comentario llamado un comentario natspec. este es escrito con una triple barra /// o un bloque de arestico doble /** ... */ y debe ser usadi directamente encima de declaraciones. Puedes usar las etiquetas de estilo Doxygen dentro de esos comentarios para documentar funcines, anotar condiciones para verificación formal, y proveer un texto de confirmación el cual es mostrado a los usuarios cuando intente invocar una función.
En el siguiente ejemplo documentamos el título del contrato, la explicación de los dos parámetros de entrada y los dos valores que devuelve.
pragma solidity ^0.4.0;
/** @title Shape calculator.*/
contract shapeCalculator{
/**@dev Calculates a rectangle's surface and perimeter.
* @param w Width of the rectangle.
* @param h Height of the rectangle.
* @return s The calculated surface.
* @return p The calculated perimeter.
*/
function rectangle(uint w, uint h) returns (uint s, uint p) {
s = w * h;
p = 2 * (w + h);
}
}