├── .gitignore ├── README.md ├── build.gradle ├── gradle.properties ├── gradle └── wrapper │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat ├── settings.gradle └── src └── main └── kotlin └── samples ├── CheckedExceptions.kt ├── DslMarker.kt ├── DslMarkerWithSafeBuilders.kt ├── SafeBuilders.kt └── Transactions.kt /.gitignore: -------------------------------------------------------------------------------- 1 | # Created by .ignore support plugin (hsz.mobi) 2 | ### Gradle template 3 | .gradle 4 | /build/ 5 | 6 | # Ignore Gradle GUI config 7 | gradle-app.setting 8 | 9 | # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored) 10 | !gradle-wrapper.jar 11 | 12 | # Cache of project 13 | .gradletasknamecache 14 | 15 | # # Work around https://youtrack.jetbrains.com/issue/IDEA-116898 16 | # gradle/wrapper/gradle-wrapper.properties 17 | ### Kotlin template 18 | # Compiled class file 19 | *.class 20 | 21 | # Log file 22 | *.log 23 | 24 | # BlueJ files 25 | *.ctxt 26 | 27 | # Mobile Tools for Java (J2ME) 28 | .mtj.tmp/ 29 | 30 | # Package Files # 31 | *.jar 32 | *.war 33 | *.nar 34 | *.ear 35 | *.zip 36 | *.tar.gz 37 | *.rar 38 | 39 | # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml 40 | hs_err_pid* 41 | ### JetBrains template 42 | # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm 43 | # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 44 | 45 | # User-specific stuff 46 | .idea/ 47 | 48 | # IntelliJ 49 | out/ 50 | 51 | # mpeltonen/sbt-idea plugin 52 | .idea_modules/ -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # kotlin-contracts-samples 2 | 3 | This repository provides samples of using prototype of new feature of kotlin contracts system -- contextual contracts (in develop). On [wiki](https://github.com/demiurg906/kotlin-contracts-samples/wiki) you can examine detailed description of that system (in russian). 4 | 5 | This is not final implementation and there is no guarantees that this feature will be supported in released Koltin compiler. 6 | 7 | ## Installation 8 | 9 | For enabling contracts in IDE you should install some IDEA plugins: 10 | 1. Forked version of Kotlin plugin 11 | - [IDEA 2018.2](https://teamcity.jetbrains.com/repository/download/Kotlin_dev_CompilerAllPlugins/1833129:id/kotlin-plugin-1.3.30-dev-245-IJ2018.2-1.zip) 12 | - [IDEA 2018.3](https://teamcity.jetbrains.com/repository/download/Kotlin_dev_CompilerAllPlugins/1833129:id/kotlin-plugin-1.3.30-dev-245-IJ2018.3-1.zip) 13 | 2. Core contracts [plugin](https://teamcity.jetbrains.com/repository/download/Kotlin_dev_CompilerAllPlugins/1833129:id/kotlin-plugin-1.3.30-dev-245-IJ2018.2-1.zip!/Kotlin/lib/kotlin-contracts-plugin.jar) 14 | 3. Contracts subplugins [plugin](https://teamcity.jetbrains.com/repository/download/Kotlin_dev_CompilerAllPlugins/1833129:id/kotlin-compiler-1.3.30-dev-245.zip!/kotlinc/lib/kotlin-contracts-compiler-subplugins.jar) 15 | 16 | For enabling contracts in compiler, you should configure your _build.gradle_ and _settings.gradle_ files as follows in sample([build.gradle](build.gradle), [settings.gradle](settings.gradle)). 17 | 18 | ## Implemented contracts 19 | 20 | By now there is four different types of contracts are implemented: 21 | - Checked exceptions ([wiki](https://github.com/demiurg906/kotlin/wiki/05.Implemented_cases#checked-exceptions), [samples](src/main/kotlin/samples/CheckedExceptions.kt)) 22 | - Safe builders ([wiki](https://github.com/demiurg906/kotlin/wiki/05.Implemented_cases#transactions), [samples](src/main/kotlin/samples/SafeBuilders.kt)) 23 | - Transactions ([wiki](https://github.com/demiurg906/kotlin/wiki/05.Implemented_cases#dsl-marker), [samples](src/main/kotlin/samples/Transactions.kt)) 24 | - Dsl Marker ([wiki](https://github.com/demiurg906/kotlin/wiki/05.Implemented_cases#safe-builders), [samples](src/main/kotlin/samples/DslMarker.kt)) 25 | 26 | ## Actual restrictions 27 | 28 | Contextual contracts is a prototype and it contains some restrictions (they are not described in wiki): 29 | 30 | #### Generics 31 | 32 | Using generic parameters in contracts is forbidden now, so you can not write contracts like that: 33 | ```kotlin 34 | fun runCatching(block: () -> Unit) { 35 | contract { 36 | callsIn(block, CatchesException()) 37 | } 38 | ... 39 | } 40 | ``` 41 | 42 | Most likely this feature will be able in near future. 43 | 44 | #### DSL and Instance duality 45 | 46 | Some contracts cases (_transactions_ and _safe builders_) could be used in two ways: 47 | 48 | **DSL style:** 49 | ```kotlin 50 | fun build(init: Builder.() -> Unit): Foo { 51 | val builder = Builder() 52 | builder.init() 53 | return builder.build() 54 | } 55 | 56 | fun foo(): Foo = 57 | build { 58 | setX(1) 59 | setY(2) 60 | } 61 | ``` 62 | 63 | **Instance style:** 64 | ```kotlin 65 | fun foo(): Foo { 66 | val builder = Builder() 67 | builder.setX(1) 68 | builder.setY(2) 69 | return builder.build() 70 | } 71 | ``` 72 | 73 | At this moment is allowed: 74 | - _DSL style_ for _safe builders_ contracts 75 | - _Instance style_ for _transactions_ contracts 76 | 77 | In near future both styles will be allowed for both types of contracts, but with one restriction: you can use only one style and can not mix them. 78 | 79 | #### Usage of functions with extension lambdas 80 | 81 | Usage of functions with extension lambdas (like `with`) in _Instance style_ is not supported, so for correct work do not use that functions. 82 | 83 | **Example of bad code:** 84 | ```kotlin 85 | fun foo() { 86 | val transaction = Transaction() 87 | transaction.open() 88 | with (transaction) { 89 | commit() 90 | } 91 | } 92 | ``` 93 | -------------------------------------------------------------------------------- /build.gradle: -------------------------------------------------------------------------------- 1 | buildscript { 2 | ext.kotlinVersion = '1.3.30-dev-245' 3 | 4 | repositories { 5 | mavenCentral() 6 | maven { url "https://dl.bintray.com/kotlin/kotlin-dev" } 7 | } 8 | 9 | dependencies { 10 | classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion") 11 | } 12 | } 13 | 14 | apply plugin: 'kotlin' 15 | 16 | group 'kotlin-contracts-samples' 17 | version '1.0' 18 | 19 | repositories { 20 | mavenCentral() 21 | maven { url "https://dl.bintray.com/kotlin/kotlin-dev" } 22 | } 23 | 24 | /* 25 | * This configurations used for configuring contracts 26 | */ 27 | configurations { 28 | // configuration for package with core contract plugin 29 | kotlinContracts 30 | // configuration for packages with contracts subplugins 31 | contractPlugin 32 | } 33 | 34 | dependencies { 35 | compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion" 36 | 37 | // package with core contextual contracts dsl 38 | compile "org.jetbrains.kotlin:kotlin-contracts-dsl:$kotlinVersion" 39 | 40 | // package with contracts subplugin dsl 41 | compile "org.jetbrains.kotlin:kotlin-contracts-subplugins-dsl:$kotlinVersion" 42 | // compile "another contracts subplugin dsl" 43 | 44 | kotlinContracts "org.jetbrains.kotlin:kotlin-contracts:$kotlinVersion" 45 | contractPlugin "org.jetbrains.kotlin:kotlin-contracts-subplugins:$kotlinVersion" 46 | // contractPlugin "another contracts subplugin" 47 | } 48 | 49 | compileKotlin { 50 | kotlinOptions.jvmTarget = "1.8" 51 | 52 | /* 53 | * This is a magic that registers contracts plugins in compiler 54 | */ 55 | doFirst { 56 | def contractPlugin = configurations.kotlinContracts 57 | for (file in contractPlugin.asCollection()) { 58 | def dep = contractPlugin.dependencies.first() 59 | def path = file.absolutePath 60 | if (path.endsWith("${dep.name}-${dep.version}.jar")) { 61 | kotlinOptions.freeCompilerArgs += ['-XXLanguage:+ContextualEffects', "-Xplugin=${path}"] 62 | } 63 | } 64 | 65 | def subplugins = configurations.contractPlugin 66 | for (file in subplugins.asCollection()) { 67 | def path = file.absolutePath 68 | for (dep in subplugins.dependencies) { 69 | if (path.endsWith("${dep.name}-${dep.version}.jar")) { 70 | kotlinOptions.freeCompilerArgs += ['-P', "plugin:org.jetbrains.kotlin.contracts:contract=${path}"] 71 | } 72 | } 73 | } 74 | 75 | println(kotlinOptions.freeCompilerArgs) 76 | } 77 | } 78 | compileTestKotlin { 79 | kotlinOptions.jvmTarget = "1.8" 80 | 81 | doFirst { 82 | def contractPlugin = configurations.kotlinContracts 83 | for (file in contractPlugin.asCollection()) { 84 | def dep = contractPlugin.dependencies.first() 85 | def path = file.absolutePath 86 | if (path.endsWith("${dep.name}-${dep.version}.jar")) { 87 | kotlinOptions.freeCompilerArgs += ['-XXLanguage:+ContextualEffects', "-Xplugin=${path}"] 88 | } 89 | } 90 | 91 | def subplugins = configurations.contractPlugin 92 | for (file in subplugins.asCollection()) { 93 | def path = file.absolutePath 94 | for (dep in subplugins.dependencies) { 95 | if (path.endsWith("${dep.name}-${dep.version}.jar")) { 96 | kotlinOptions.freeCompilerArgs += ['-P', "plugin:org.jetbrains.kotlin.contracts:contract=${path}"] 97 | } 98 | } 99 | } 100 | } 101 | } 102 | 103 | -------------------------------------------------------------------------------- /gradle.properties: -------------------------------------------------------------------------------- 1 | kotlin.code.style=official -------------------------------------------------------------------------------- /gradle/wrapper/gradle-wrapper.properties: -------------------------------------------------------------------------------- 1 | #Mon Oct 29 14:50:39 MSK 2018 2 | distributionBase=GRADLE_USER_HOME 3 | distributionPath=wrapper/dists 4 | zipStoreBase=GRADLE_USER_HOME 5 | zipStorePath=wrapper/dists 6 | distributionUrl=https\://services.gradle.org/distributions/gradle-4.8-all.zip 7 | -------------------------------------------------------------------------------- /gradlew: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env sh 2 | 3 | ############################################################################## 4 | ## 5 | ## Gradle start up script for UN*X 6 | ## 7 | ############################################################################## 8 | 9 | # Attempt to set APP_HOME 10 | # Resolve links: $0 may be a link 11 | PRG="$0" 12 | # Need this for relative symlinks. 13 | while [ -h "$PRG" ] ; do 14 | ls=`ls -ld "$PRG"` 15 | link=`expr "$ls" : '.*-> \(.*\)$'` 16 | if expr "$link" : '/.*' > /dev/null; then 17 | PRG="$link" 18 | else 19 | PRG=`dirname "$PRG"`"/$link" 20 | fi 21 | done 22 | SAVED="`pwd`" 23 | cd "`dirname \"$PRG\"`/" >/dev/null 24 | APP_HOME="`pwd -P`" 25 | cd "$SAVED" >/dev/null 26 | 27 | APP_NAME="Gradle" 28 | APP_BASE_NAME=`basename "$0"` 29 | 30 | # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. 31 | DEFAULT_JVM_OPTS="" 32 | 33 | # Use the maximum available, or set MAX_FD != -1 to use that value. 34 | MAX_FD="maximum" 35 | 36 | warn () { 37 | echo "$*" 38 | } 39 | 40 | die () { 41 | echo 42 | echo "$*" 43 | echo 44 | exit 1 45 | } 46 | 47 | # OS specific support (must be 'true' or 'false'). 48 | cygwin=false 49 | msys=false 50 | darwin=false 51 | nonstop=false 52 | case "`uname`" in 53 | CYGWIN* ) 54 | cygwin=true 55 | ;; 56 | Darwin* ) 57 | darwin=true 58 | ;; 59 | MINGW* ) 60 | msys=true 61 | ;; 62 | NONSTOP* ) 63 | nonstop=true 64 | ;; 65 | esac 66 | 67 | CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar 68 | 69 | # Determine the Java command to use to start the JVM. 70 | if [ -n "$JAVA_HOME" ] ; then 71 | if [ -x "$JAVA_HOME/jre/sh/java" ] ; then 72 | # IBM's JDK on AIX uses strange locations for the executables 73 | JAVACMD="$JAVA_HOME/jre/sh/java" 74 | else 75 | JAVACMD="$JAVA_HOME/bin/java" 76 | fi 77 | if [ ! -x "$JAVACMD" ] ; then 78 | die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME 79 | 80 | Please set the JAVA_HOME variable in your environment to match the 81 | location of your Java installation." 82 | fi 83 | else 84 | JAVACMD="java" 85 | which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 86 | 87 | Please set the JAVA_HOME variable in your environment to match the 88 | location of your Java installation." 89 | fi 90 | 91 | # Increase the maximum file descriptors if we can. 92 | if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then 93 | MAX_FD_LIMIT=`ulimit -H -n` 94 | if [ $? -eq 0 ] ; then 95 | if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then 96 | MAX_FD="$MAX_FD_LIMIT" 97 | fi 98 | ulimit -n $MAX_FD 99 | if [ $? -ne 0 ] ; then 100 | warn "Could not set maximum file descriptor limit: $MAX_FD" 101 | fi 102 | else 103 | warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" 104 | fi 105 | fi 106 | 107 | # For Darwin, add options to specify how the application appears in the dock 108 | if $darwin; then 109 | GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" 110 | fi 111 | 112 | # For Cygwin, switch paths to Windows format before running java 113 | if $cygwin ; then 114 | APP_HOME=`cygpath --path --mixed "$APP_HOME"` 115 | CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` 116 | JAVACMD=`cygpath --unix "$JAVACMD"` 117 | 118 | # We build the pattern for arguments to be converted via cygpath 119 | ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` 120 | SEP="" 121 | for dir in $ROOTDIRSRAW ; do 122 | ROOTDIRS="$ROOTDIRS$SEP$dir" 123 | SEP="|" 124 | done 125 | OURCYGPATTERN="(^($ROOTDIRS))" 126 | # Add a user-defined pattern to the cygpath arguments 127 | if [ "$GRADLE_CYGPATTERN" != "" ] ; then 128 | OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" 129 | fi 130 | # Now convert the arguments - kludge to limit ourselves to /bin/sh 131 | i=0 132 | for arg in "$@" ; do 133 | CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` 134 | CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option 135 | 136 | if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition 137 | eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` 138 | else 139 | eval `echo args$i`="\"$arg\"" 140 | fi 141 | i=$((i+1)) 142 | done 143 | case $i in 144 | (0) set -- ;; 145 | (1) set -- "$args0" ;; 146 | (2) set -- "$args0" "$args1" ;; 147 | (3) set -- "$args0" "$args1" "$args2" ;; 148 | (4) set -- "$args0" "$args1" "$args2" "$args3" ;; 149 | (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; 150 | (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; 151 | (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; 152 | (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; 153 | (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; 154 | esac 155 | fi 156 | 157 | # Escape application args 158 | save () { 159 | for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done 160 | echo " " 161 | } 162 | APP_ARGS=$(save "$@") 163 | 164 | # Collect all arguments for the java command, following the shell quoting and substitution rules 165 | eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" 166 | 167 | # by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong 168 | if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then 169 | cd "$(dirname "$0")" 170 | fi 171 | 172 | exec "$JAVACMD" "$@" 173 | -------------------------------------------------------------------------------- /gradlew.bat: -------------------------------------------------------------------------------- 1 | @if "%DEBUG%" == "" @echo off 2 | @rem ########################################################################## 3 | @rem 4 | @rem Gradle startup script for Windows 5 | @rem 6 | @rem ########################################################################## 7 | 8 | @rem Set local scope for the variables with windows NT shell 9 | if "%OS%"=="Windows_NT" setlocal 10 | 11 | set DIRNAME=%~dp0 12 | if "%DIRNAME%" == "" set DIRNAME=. 13 | set APP_BASE_NAME=%~n0 14 | set APP_HOME=%DIRNAME% 15 | 16 | @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. 17 | set DEFAULT_JVM_OPTS= 18 | 19 | @rem Find java.exe 20 | if defined JAVA_HOME goto findJavaFromJavaHome 21 | 22 | set JAVA_EXE=java.exe 23 | %JAVA_EXE% -version >NUL 2>&1 24 | if "%ERRORLEVEL%" == "0" goto init 25 | 26 | echo. 27 | echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 28 | echo. 29 | echo Please set the JAVA_HOME variable in your environment to match the 30 | echo location of your Java installation. 31 | 32 | goto fail 33 | 34 | :findJavaFromJavaHome 35 | set JAVA_HOME=%JAVA_HOME:"=% 36 | set JAVA_EXE=%JAVA_HOME%/bin/java.exe 37 | 38 | if exist "%JAVA_EXE%" goto init 39 | 40 | echo. 41 | echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 42 | echo. 43 | echo Please set the JAVA_HOME variable in your environment to match the 44 | echo location of your Java installation. 45 | 46 | goto fail 47 | 48 | :init 49 | @rem Get command-line arguments, handling Windows variants 50 | 51 | if not "%OS%" == "Windows_NT" goto win9xME_args 52 | 53 | :win9xME_args 54 | @rem Slurp the command line arguments. 55 | set CMD_LINE_ARGS= 56 | set _SKIP=2 57 | 58 | :win9xME_args_slurp 59 | if "x%~1" == "x" goto execute 60 | 61 | set CMD_LINE_ARGS=%* 62 | 63 | :execute 64 | @rem Setup the command line 65 | 66 | set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar 67 | 68 | @rem Execute Gradle 69 | "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS% 70 | 71 | :end 72 | @rem End local scope for the variables with windows NT shell 73 | if "%ERRORLEVEL%"=="0" goto mainEnd 74 | 75 | :fail 76 | rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of 77 | rem the _cmd.exe /c_ return code! 78 | if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 79 | exit /b 1 80 | 81 | :mainEnd 82 | if "%OS%"=="Windows_NT" endlocal 83 | 84 | :omega 85 | -------------------------------------------------------------------------------- /settings.gradle: -------------------------------------------------------------------------------- 1 | pluginManagement { 2 | repositories { 3 | mavenCentral() 4 | maven { url 'https://plugins.gradle.org/m2/' } 5 | maven { url "https://dl.bintray.com/kotlin/kotlin-dev" } 6 | } 7 | } 8 | rootProject.name = 'kotlin-contracts-samples' 9 | 10 | -------------------------------------------------------------------------------- /src/main/kotlin/samples/CheckedExceptions.kt: -------------------------------------------------------------------------------- 1 | package samples 2 | 3 | import org.jetbrains.kotlin.contracts.contextual.callsIn 4 | import org.jetbrains.kotlin.contracts.contextual.exceptions.CatchesException 5 | import org.jetbrains.kotlin.contracts.contextual.requires 6 | import java.io.FileNotFoundException 7 | import java.io.IOException 8 | import kotlin.contracts.ExperimentalContracts 9 | import kotlin.contracts.InvocationKind 10 | import kotlin.contracts.contract 11 | 12 | /* 13 | * Declaration of function that throws an exception 14 | */ 15 | @ExperimentalContracts 16 | fun throwsFileNotFoundException() { 17 | contract { 18 | requires(CatchesException()) 19 | } 20 | throw FileNotFoundException() 21 | } 22 | 23 | /* 24 | * Declaration of function that catches Exception 25 | * Note: there is must be `callsInPlace` contract 26 | * on lambda that run in `try` block must 27 | * Note: contracts with generics are not supported yet 28 | * but most likely will be in future 29 | */ 30 | @ExperimentalContracts 31 | inline fun myCatchIOException(block: () -> Unit) { 32 | contract { 33 | callsInPlace(block, InvocationKind.EXACTLY_ONCE) 34 | callsIn(block, CatchesException()) 35 | } 36 | try { 37 | block() 38 | } catch (e: IOException) { 39 | e.printStackTrace() 40 | } 41 | } 42 | 43 | /* 44 | * Example of usage functions with exception contracts 45 | */ 46 | @ExperimentalContracts 47 | fun foo() { 48 | throwsFileNotFoundException() // Warning 49 | 50 | myCatchIOException { 51 | throwsFileNotFoundException() // OK 52 | } 53 | } 54 | 55 | 56 | @ExperimentalContracts 57 | fun alsoThrowsException() { 58 | contract { 59 | requires(CatchesException()) 60 | } 61 | throwsFileNotFoundException() 62 | } -------------------------------------------------------------------------------- /src/main/kotlin/samples/DslMarker.kt: -------------------------------------------------------------------------------- 1 | package samples 2 | 3 | import org.jetbrains.kotlin.contracts.contextual.callsIn 4 | 5 | import org.jetbrains.kotlin.contracts.contextual.dslmarker.DslMarkers 6 | import org.jetbrains.kotlin.contracts.contextual.requires 7 | import kotlin.contracts.ExperimentalContracts 8 | import kotlin.contracts.InvocationKind 9 | import kotlin.contracts.contract 10 | import kotlin.contracts.receiverOf 11 | 12 | /* 13 | * DslMarker contracts is equivalent of @DSLMarker annotation. 14 | * (see https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-dsl-marker/index.html) 15 | * Usage of DslMarker contracts: 16 | * - member functions of classes used in dsl must has contract 17 | * `requires(DslMarkers([reference to this]))` 18 | * - dsl functions with lambda must has contract 19 | * `callsIn(lambda, DslMarkers(receiverOf(lambda)))` 20 | * and also it must be marked as `callsInPlace` 21 | */ 22 | 23 | data class Foo(val x: Int, val bar: Bar) 24 | 25 | data class Bar(val y : Int) 26 | 27 | @ExperimentalContracts 28 | class BarBuilder { 29 | private var y_: Int? = null 30 | fun setY(value: Int = 0) { 31 | contract { 32 | requires(DslMarkers(this@BarBuilder)) 33 | } 34 | y_ = value 35 | } 36 | 37 | fun create(): Bar = Bar(y_!!) 38 | } 39 | 40 | @ExperimentalContracts 41 | class FooBuilder { 42 | private var x_: Int? = null 43 | private var bar_: Bar? = null 44 | fun setX(value: Int = 0) { 45 | contract { 46 | requires(DslMarkers(this@FooBuilder)) 47 | } 48 | x_ = value 49 | } 50 | 51 | fun buildBar(init: BarBuilder.() -> Unit) { 52 | contract { 53 | callsInPlace(init, kotlin.contracts.InvocationKind.EXACTLY_ONCE) 54 | callsIn(init, DslMarkers(receiverOf(init))) 55 | requires(DslMarkers(this@FooBuilder)) 56 | } 57 | val builder = BarBuilder() 58 | builder.init() 59 | bar_ = builder.create() 60 | } 61 | 62 | fun create() = Foo(x_!!, bar_!!) 63 | } 64 | 65 | @ExperimentalContracts 66 | fun buildFoo(init: FooBuilder.() -> Unit): Foo { 67 | contract { 68 | callsInPlace(init, InvocationKind.EXACTLY_ONCE) 69 | callsIn(init, DslMarkers(receiverOf(init))) 70 | } 71 | val builder = FooBuilder() 72 | builder.init() 73 | return builder.create() 74 | } 75 | 76 | // ---------------- TESTS ---------------- 77 | 78 | @ExperimentalContracts 79 | fun DslMarkerTest1(): Foo = 80 | buildFoo { // OK 81 | setX() 82 | buildBar { 83 | setY() 84 | } 85 | } 86 | 87 | @ExperimentalContracts 88 | fun test_2(): Foo = 89 | buildFoo { 90 | buildBar { 91 | setX() // Warning 92 | setY() 93 | } 94 | } 95 | -------------------------------------------------------------------------------- /src/main/kotlin/samples/DslMarkerWithSafeBuilders.kt: -------------------------------------------------------------------------------- 1 | package samples 2 | 3 | import org.jetbrains.kotlin.contracts.contextual.callsIn 4 | 5 | import org.jetbrains.kotlin.contracts.contextual.dslmarker.DslMarkers 6 | import org.jetbrains.kotlin.contracts.contextual.expectsTo 7 | import org.jetbrains.kotlin.contracts.contextual.provides 8 | import org.jetbrains.kotlin.contracts.contextual.requires 9 | import org.jetbrains.kotlin.contracts.contextual.safebuilders.CallKind 10 | import org.jetbrains.kotlin.contracts.contextual.safebuilders.Calls 11 | import kotlin.contracts.ExperimentalContracts 12 | import kotlin.contracts.InvocationKind 13 | import kotlin.contracts.contract 14 | import kotlin.contracts.receiverOf 15 | 16 | data class Fooz(val x: Int, val bar: Baz) 17 | 18 | data class Baz(val y : Int) 19 | 20 | @ExperimentalContracts 21 | class BazBuilder { 22 | private var y_: Int? = null 23 | fun setY(value: Int = 0) { 24 | contract { 25 | requires(DslMarkers(this@BazBuilder)) 26 | provides(Calls(::setY, this@BazBuilder)) 27 | } 28 | y_ = value 29 | } 30 | 31 | fun create(): Baz = Baz(y_!!) 32 | } 33 | 34 | @ExperimentalContracts 35 | class FoozBuilder { 36 | private var x_: Int? = null 37 | private var baz_: Baz? = null 38 | fun setX(value: Int = 0) { 39 | contract { 40 | requires(DslMarkers(this@FoozBuilder)) 41 | provides(Calls(::setX, this@FoozBuilder)) 42 | } 43 | x_ = value 44 | } 45 | 46 | fun buildBaz(init: BazBuilder.() -> Unit) { 47 | contract { 48 | callsInPlace(init, kotlin.contracts.InvocationKind.EXACTLY_ONCE) 49 | callsIn(init, DslMarkers(receiverOf(init))) 50 | expectsTo(init, CallKind(BazBuilder::setY, InvocationKind.EXACTLY_ONCE, receiverOf(init))) 51 | requires(DslMarkers(this@FoozBuilder)) 52 | provides(Calls(::buildBaz, this@FoozBuilder)) 53 | } 54 | val builder = BazBuilder() 55 | builder.init() 56 | baz_ = builder.create() 57 | } 58 | 59 | fun create() = Fooz(x_!!, baz_!!) 60 | } 61 | 62 | @ExperimentalContracts 63 | fun buildFooz(init: FoozBuilder.() -> Unit): Fooz { 64 | contract { 65 | callsInPlace(init, InvocationKind.EXACTLY_ONCE) 66 | callsIn(init, DslMarkers(receiverOf(init))) 67 | expectsTo(init, CallKind(FoozBuilder::setX, InvocationKind.EXACTLY_ONCE, receiverOf(init))) 68 | expectsTo(init, CallKind(FoozBuilder::buildBaz, InvocationKind.EXACTLY_ONCE, receiverOf(init))) 69 | } 70 | val builder = FoozBuilder() 71 | builder.init() 72 | return builder.create() 73 | } 74 | 75 | // ---------------- TESTS ---------------- 76 | 77 | @ExperimentalContracts 78 | fun SBDslMarkerTest1(): Fooz = 79 | buildFooz { // OK 80 | setX() 81 | buildBaz { 82 | setY() 83 | } 84 | } -------------------------------------------------------------------------------- /src/main/kotlin/samples/SafeBuilders.kt: -------------------------------------------------------------------------------- 1 | package samples 2 | 3 | import org.jetbrains.kotlin.contracts.contextual.expectsTo 4 | import org.jetbrains.kotlin.contracts.contextual.provides 5 | import org.jetbrains.kotlin.contracts.contextual.safebuilders.CallKind 6 | import org.jetbrains.kotlin.contracts.contextual.safebuilders.Calls 7 | import kotlin.contracts.ExperimentalContracts 8 | import kotlin.contracts.InvocationKind 9 | import kotlin.contracts.contract 10 | import kotlin.contracts.receiverOf 11 | 12 | /* 13 | * Workflow of Safe builders contracts: 14 | * There is a builder class with some setter functions and 15 | * corresponding build function that takes initializer (lambda 16 | * with receiver), applies it to builder and returns built object. 17 | * With contracts you can check, how many times each function 18 | * has been called in initializer. 19 | * On setter functions you must write contract that says 20 | * 'call of that function provides effect that this function 21 | * has been called once' 22 | * In build function you must write contracts on init lambda 23 | * that says 'I expected that `function` in init lambda will 24 | * be called `InvocationKind` times. 25 | * Note: init lambda in builder function must has contract 26 | * `callsInPlace` 27 | * 28 | * Note: at this times that contracts don't work with builder 29 | * instances (see [builderInstance] and Readme) 30 | * 31 | * InvocationKind: InvocationKind is enumeration that used to 32 | * describe contract system how many times function should be called 33 | * Available values: 34 | * - EXACTLY_ONCE -- exactly one time 35 | * - AT_LEAST_ONCE -- one or more times 36 | * - AT_MOST_ONCE -- zero or one time 37 | */ 38 | 39 | 40 | data class XYZ(val x: Int, var y: Int, val z: Int = 0) 41 | 42 | /* 43 | * Builder class with contracts on setters 44 | * Note: contracts on getters and setters are not supported yet 45 | */ 46 | @ExperimentalContracts 47 | class XYZBuilder { 48 | private var x: Int? = null 49 | private var y: Int? = null 50 | private var z: Int? = null 51 | 52 | fun setValX(value: Int) { 53 | contract { 54 | provides(Calls(::setValX, this@XYZBuilder)) 55 | } 56 | this.x = value 57 | } 58 | 59 | fun setVarY(value: Int) { 60 | contract { 61 | provides(Calls(::setVarY, this@XYZBuilder)) 62 | } 63 | y = value 64 | } 65 | 66 | fun setDefaultValZ(value: Int) { 67 | contract { 68 | provides(Calls(::setDefaultValZ, this@XYZBuilder)) 69 | } 70 | z = value 71 | } 72 | 73 | fun create(): XYZ { 74 | return if (z == null) { 75 | XYZ(x!!, y!!) 76 | } else { 77 | XYZ(x!!, y!!, z!!) 78 | } 79 | } 80 | } 81 | 82 | /* 83 | * Build function with contract 84 | */ 85 | @ExperimentalContracts 86 | fun build(init : XYZBuilder.() -> Unit): XYZ { 87 | contract { 88 | callsInPlace(init, InvocationKind.EXACTLY_ONCE) 89 | expectsTo(init, CallKind(XYZBuilder::setValX, InvocationKind.EXACTLY_ONCE, receiverOf(init))) 90 | expectsTo(init, CallKind(XYZBuilder::setVarY, InvocationKind.AT_LEAST_ONCE, receiverOf(init))) 91 | expectsTo(init, CallKind(XYZBuilder::setDefaultValZ, InvocationKind.AT_MOST_ONCE, receiverOf(init))) 92 | } 93 | 94 | val xyzBuilder = XYZBuilder() 95 | xyzBuilder.init() 96 | return xyzBuilder.create() 97 | } 98 | 99 | /* 100 | * Samples of usage of build functions 101 | */ 102 | @ExperimentalContracts 103 | fun buildersTest1(): XYZ = 104 | build { // OK 105 | setValX(10) 106 | setVarY(11) 107 | setDefaultValZ(12) 108 | } 109 | 110 | @ExperimentalContracts 111 | fun buildersTest2(): XYZ = 112 | build { // OK 113 | setValX(10) 114 | setVarY(11) 115 | setVarY(12) 116 | } 117 | 118 | @ExperimentalContracts 119 | fun buildersTest3(): XYZ = 120 | build { // Warning 121 | setDefaultValZ(11) 122 | setDefaultValZ(12) 123 | } 124 | 125 | /** 126 | * Not supported yet 127 | */ 128 | @ExperimentalContracts 129 | fun builderInstance(): XYZ { 130 | val builder = XYZBuilder() 131 | builder.setValX(10) 132 | builder.setDefaultValZ(11) 133 | builder.setDefaultValZ(12) 134 | return builder.create() 135 | } -------------------------------------------------------------------------------- /src/main/kotlin/samples/Transactions.kt: -------------------------------------------------------------------------------- 1 | package samples 2 | 3 | import org.jetbrains.kotlin.contracts.contextual.closes 4 | import org.jetbrains.kotlin.contracts.contextual.requires 5 | import org.jetbrains.kotlin.contracts.contextual.starts 6 | import org.jetbrains.kotlin.contracts.contextual.transactions.OpenedTransaction 7 | import kotlin.contracts.ExperimentalContracts 8 | import kotlin.contracts.contract 9 | 10 | /* 11 | * Transaction contracts workflow: 12 | * there is class with methods that: 13 | * - opens transaction 14 | * - does some work with transaction 15 | * - closes transactions 16 | * Rules that contracts checks: 17 | * - you can do actions only with opened transaction 18 | * - you can close only opened transaction 19 | * - you can not open already opened transaction 20 | * Note: after closing transaction you can reuse it again 21 | * Note: aliasing is not supported yet (see [aliasingTest]) 22 | * Note: using contracts on transaction dsl (like builders) 23 | * will be released soon (see Readme) 24 | * Note: don't use transactions contract with extension lambdas, 25 | * it not supported yet (see [transactionWith] and Readme) 26 | */ 27 | @ExperimentalContracts 28 | class Transaction { 29 | fun start() { 30 | contract { 31 | starts(OpenedTransaction(this@Transaction)) 32 | } 33 | // open transaction 34 | } 35 | 36 | fun setData() { 37 | contract { 38 | requires(OpenedTransaction(this@Transaction)) 39 | } 40 | // something useful 41 | } 42 | 43 | fun commit() { 44 | contract { 45 | closes(OpenedTransaction(this@Transaction)) 46 | } 47 | // commit transaction 48 | } 49 | } 50 | 51 | // ---------------- TESTS ---------------- 52 | 53 | @ExperimentalContracts 54 | fun transactionTest1() { 55 | val transaction = Transaction() 56 | 57 | // OK 58 | transaction.start() 59 | transaction.setData() 60 | transaction.commit() 61 | } 62 | 63 | @ExperimentalContracts 64 | fun transactionTest2() { 65 | val transaction = Transaction() 66 | 67 | transaction.setData() // Warning: transaction is not opened 68 | transaction.commit() // Warning: transaction is not opened 69 | } 70 | 71 | @ExperimentalContracts 72 | fun transactionTest3() { 73 | val transaction = Transaction() 74 | 75 | transaction.start() 76 | transaction.commit() 77 | transaction.setData() // Warning: transaction is not opened 78 | } 79 | 80 | @ExperimentalContracts 81 | fun transactionTest4() { 82 | val transaction = Transaction() 83 | transaction.commit() // Warning: transaction is not opened 84 | } 85 | 86 | @ExperimentalContracts 87 | fun transactionTest5() { 88 | val transaction = Transaction() // Warning: transaction transaction must be closed 89 | transaction.start() 90 | } 91 | 92 | @ExperimentalContracts 93 | fun transactionTest6() { 94 | val transaction = Transaction() 95 | 96 | transaction.start() 97 | transaction.start() // Warning: transaction transaction already started 98 | transaction.commit() 99 | } 100 | 101 | @ExperimentalContracts 102 | fun reuseTransactionTest() { 103 | val transaction = Transaction() 104 | 105 | transaction.start() 106 | transaction.commit() 107 | // OK 108 | transaction.start() 109 | transaction.commit() 110 | } 111 | 112 | @ExperimentalContracts 113 | fun aliasingTest() { 114 | /* 115 | * Contracts can analyze only effects connected 116 | * to direct variable 117 | */ 118 | val transaction1 = Transaction() 119 | transaction1.start() 120 | val transaction2 = transaction1 121 | transaction2.commit() // Warning 122 | } 123 | 124 | @ExperimentalContracts 125 | fun transactionWith() { 126 | val transaction = Transaction() 127 | 128 | transaction.start() 129 | // Not supported 130 | with (transaction) { 131 | commit() 132 | setData() // should be warning 133 | } 134 | } --------------------------------------------------------------------------------