diff --git a/README.md b/README.md index 6c9bb43..564d0ca 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,19 @@ # skript-db -> Awesome direct database access for Skript - -## Syntax + > Sensible SQL support for Skript. +--- ### Expression `Data Source` => `datasource` +Stores the connection information for a data source. This should be saved to a variable in a + `script load` event or manually through an effect command. -This stores the connection information for a data source. This should be saved to a variable in a `script load` event or manually through an effect command. - -The url format for your database may vary! The example below uses a MySQL database. - + The url format for your database may vary! The example provided uses a MySQL database. #### Syntax +``` +[the] data(base|[ ]source) [(of|at)] %string% +``` -`[the] data(base|[ ]source) [(of|at)] %string%` - -#### Example - +#### Examples ``` set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password=12345&useSSL=false" ``` @@ -23,50 +21,52 @@ set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password --- ### Effect `Execute Statement` +Executes a statement on a database and optionally stores the result in a variable. Expressions + embedded in the query will be escaped to avoid SQL injection. -Executes a statement on a database and optionally stores the result in a variable. Expressions embedded in the query will be escaped to avoid SQL injection. - -If a single variable, such as `{test}`, is passed, the variable will be set to the number of affected rows. - -If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list variable in the form `{test::::}` + If a single variable, such as `{test}`, is passed, the variable will be set to the number of + affected rows. + If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list + variable in the form `{test::::}` #### Syntax +``` +execute %string% (in|on) %datasource% [and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %-objects%] +``` -`execute %text% (in|on) %datasource% - [and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %variable%]` - -#### Example - +#### Examples ``` execute "select * from table" in {sql} and store the result in {output::*} +``` +``` execute "select * from %{table variable}%" in {sql} and store the result in {output::*} ``` --- -### Expression `Unsafe Expression` => `text` - -Opts out of automatic SQL injection protection for a specific expression in a statement. - +### Expression `Last Data Source Error` => `text` +Stores the error from the last executed statement, if there was one. #### Syntax - -`unsafe %text%` - -#### Example - ``` -execute "select %unsafe {columns variable}% from %{table variable}%" in {sql} and store the result in {output::*} +[the] [last] (sql|db|data(base|[ ]source)) error +``` + +--- + +### Expression `Unsafe Expression` => `text` +Opts out of automatic SQL injection protection for a specific expression in a statement. +#### Syntax +``` +unsafe %text% +``` + +#### Examples +``` +execute "select %unsafe {columns variable}% from %{table variable}%" in {sql} +``` +``` execute unsafe {fully dynamic query} in {sql} ``` --- -### Expression `Last Data Source Error` => `text` - -Stores the error from the last executed statement, if there was one. - -#### Syntax - -`[the] [last] (sql|db|data(base|[ ]source)) error` - ---- diff --git a/build.gradle b/build.gradle index c392572..fd4a924 100644 --- a/build.gradle +++ b/build.gradle @@ -33,3 +33,13 @@ dependencies { shadow 'ch.njol:skript:2.2-SNAPSHOT' compile 'com.zaxxer:HikariCP:2.6.2' } + +task buildReadme(type: Javadoc) { + source = sourceSets.main.allJava + classpath = sourceSets.main.compileClasspath + destinationDir = projectDir + options.docletpath = [file('tools/skriptdoclet.jar')] + options.doclet = 'com.btk5h.skriptdoclet.SkriptDoclet' + options.addStringOption('file', 'README.md') + options.addStringOption('markdown', '-quiet') +} diff --git a/src/main/java/com/btk5h/skriptdb/SkriptDB.java b/src/main/java/com/btk5h/skriptdb/SkriptDB.java index ab026b7..70b9f0c 100644 --- a/src/main/java/com/btk5h/skriptdb/SkriptDB.java +++ b/src/main/java/com/btk5h/skriptdb/SkriptDB.java @@ -35,7 +35,15 @@ import javax.sql.rowset.RowSetProvider; import ch.njol.skript.Skript; import ch.njol.skript.SkriptAddon; +import ch.njol.skript.doc.Since; +/** + * # skript-db + * + * > Sensible SQL support for Skript. + * + * @index -1 + */ public final class SkriptDB extends JavaPlugin { private static SkriptDB instance; diff --git a/src/main/java/com/btk5h/skriptdb/skript/EffExecuteStatement.java b/src/main/java/com/btk5h/skriptdb/skript/EffExecuteStatement.java index 92a984b..f3afe39 100644 --- a/src/main/java/com/btk5h/skriptdb/skript/EffExecuteStatement.java +++ b/src/main/java/com/btk5h/skriptdb/skript/EffExecuteStatement.java @@ -31,6 +31,23 @@ import ch.njol.skript.lang.VariableString; import ch.njol.skript.variables.Variables; import ch.njol.util.Kleenean; +/** + * Executes a statement on a database and optionally stores the result in a variable. Expressions + * embedded in the query will be escaped to avoid SQL injection. + * + * If a single variable, such as `{test}`, is passed, the variable will be set to the number of + * affected rows. + * + * If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list + * variable in the form `{test::::}` + * + * @name Execute Statement + * @pattern execute %string% (in|on) %datasource% [and store [[the] (output|result)[s]] (to|in) + * [the] [var[iable]] %-objects%] + * @example execute "select * from table" in {sql} and store the result in {output::*} + * @example execute "select * from %{table variable}%" in {sql} and store the result in {output::*} + * @since 0.1.0 + */ public class EffExecuteStatement extends Delay { static { Skript.registerEffect(EffExecuteStatement.class, @@ -169,7 +186,7 @@ public class EffExecuteStatement extends Delay { while (crs.next()) { for (int i = 1; i <= columnCount; i++) { setVariable(e, baseVariable + meta.getColumnLabel(i).toLowerCase(Locale.ENGLISH) - + Variable.SEPARATOR + rowNumber, crs.getObject(i)); + + Variable.SEPARATOR + rowNumber, crs.getObject(i)); } rowNumber++; } diff --git a/src/main/java/com/btk5h/skriptdb/skript/ExprDBError.java b/src/main/java/com/btk5h/skriptdb/skript/ExprDBError.java index 0f9d900..b4f3d45 100644 --- a/src/main/java/com/btk5h/skriptdb/skript/ExprDBError.java +++ b/src/main/java/com/btk5h/skriptdb/skript/ExprDBError.java @@ -9,6 +9,14 @@ import ch.njol.skript.lang.SkriptParser; import ch.njol.skript.lang.util.SimpleExpression; import ch.njol.util.Kleenean; +/** + * Stores the error from the last executed statement, if there was one. + * + * @name Last Data Source Error + * @pattern [the] [last] (sql|db|data(base|[ ]source)) error + * @return text + * @since 0.1.0 + */ public class ExprDBError extends SimpleExpression { static { Skript.registerExpression(ExprDBError.class, String.class, diff --git a/src/main/java/com/btk5h/skriptdb/skript/ExprDataSource.java b/src/main/java/com/btk5h/skriptdb/skript/ExprDataSource.java index f565447..ffce075 100644 --- a/src/main/java/com/btk5h/skriptdb/skript/ExprDataSource.java +++ b/src/main/java/com/btk5h/skriptdb/skript/ExprDataSource.java @@ -11,6 +11,19 @@ import ch.njol.skript.lang.SkriptParser; import ch.njol.skript.lang.util.SimpleExpression; import ch.njol.util.Kleenean; +/** + * Stores the connection information for a data source. This should be saved to a variable in a + * `script load` event or manually through an effect command. + * + * The url format for your database may vary! The example provided uses a MySQL database. + * + * @name Data Source + * @index -1 + * @pattern [the] data(base|[ ]source) [(of|at)] %string% + * @return datasource + * @example set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password=12345&useSSL=false" + * @since 0.1.0 + */ public class ExprDataSource extends SimpleExpression { static { Skript.registerExpression(ExprDataSource.class, HikariDataSource.class, @@ -33,7 +46,7 @@ public class ExprDataSource extends SimpleExpression { HikariDataSource ds = new HikariDataSource(); ds.setJdbcUrl(jdbcUrl); - return new HikariDataSource[] {ds}; + return new HikariDataSource[]{ds}; } @Override diff --git a/src/main/java/com/btk5h/skriptdb/skript/ExprUnsafe.java b/src/main/java/com/btk5h/skriptdb/skript/ExprUnsafe.java index c8acd73..53984f4 100644 --- a/src/main/java/com/btk5h/skriptdb/skript/ExprUnsafe.java +++ b/src/main/java/com/btk5h/skriptdb/skript/ExprUnsafe.java @@ -9,6 +9,16 @@ import ch.njol.skript.lang.SkriptParser; import ch.njol.skript.lang.util.SimpleExpression; import ch.njol.util.Kleenean; +/** + * Opts out of automatic SQL injection protection for a specific expression in a statement. + * + * @name Unsafe Expression + * @pattern unsafe %text% + * @return text + * @example execute "select %unsafe {columns variable}% from %{table variable}%" in {sql} + * @example execute unsafe {fully dynamic query} in {sql} + * @since 0.1.0 + */ public class ExprUnsafe extends SimpleExpression { static { Skript.registerExpression(ExprUnsafe.class, String.class, ExpressionType.COMBINED, diff --git a/tools/skriptdoclet.jar b/tools/skriptdoclet.jar new file mode 100644 index 0000000..af2e668 Binary files /dev/null and b/tools/skriptdoclet.jar differ