Skip to content

Commit fcb864d

Browse files
dedmendedmen
committed
Add ReadTheDocs
1 parent 5388fc2 commit fcb864d

17 files changed

Lines changed: 663 additions & 1 deletion

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,4 @@ CTestTestfile.cmake
5454
.idea/
5555

5656
CMakeSettings\.json
57+
/docs/_build

‎.readthedocs.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# .readthedocs.yml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Build documentation in the docs/ directory with Sphinx
9+
sphinx:
10+
configuration: docs/conf.py
11+
12+
# Build documentation with MkDocs
13+
#mkdocs:
14+
# configuration: mkdocs.yml
15+
16+
# Optionally build your docs in additional formats such as PDF and ePub
17+
formats: all
18+
19+
# Optionally set the version of Python and requirements required to build your docs
20+
python:
21+
version: 3.7

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
This is the Intercept plugin template project.
1+
![docs](https://readthedocs.org/projects/intercept-database/badge/?version=stable)

‎docs/Makefile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/.keep‎

Whitespace-only changes.

‎docs/api/build-queries.rst‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
Building Queries
2+
================
3+
4+
5+
6+
dbPrepareQuery query
7+
~~~~~~~~~~~~~~~~~~~~
8+
9+
Prepares a query.
10+
11+
:query: ``<STRING>`` - The SQL Query String
12+
13+
Returns: ``<QUERY>``
14+
15+
16+
17+
dbPrepareQuery [query, bindValues]
18+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19+
20+
Prepares a query and directly binds some values to it.
21+
22+
:query: ``<STRING>`` - The SQL Query String
23+
:bindValues: ``<ARRAY>`` - List of values to bind to ``?`` in the query string.
24+
25+
Returns: ``<QUERY>``
26+
27+
| Example:
28+
| ``dbPrepareQuery ["SELECT ? FROM ? WHERE ?=?", ["data", "table", "value", 5]]``
29+
| -> ``SELECT data FROM table WHERE value=5``
30+
31+
32+
dbPrepareQueryConfig configName
33+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34+
35+
Prepares a query based on details in the :doc:`config file </intro/config-file>` in ``statements.<configName>``
36+
37+
:configName: ``<STRING>`` - The config name of the query
38+
39+
.. attention::
40+
configName is case-sensitive
41+
42+
Returns: ``<QUERY>``
43+
44+
45+
dbPrepareQueryConfig [configName, bindValues]
46+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47+
48+
Prepares a query based on details in the :doc:`config file </intro/config-file>` in ``statements.<configName>``
49+
50+
:configName: ``<STRING>`` - The config name of the query
51+
:bindValues: ``<ARRAY>`` - List of values to bind to ``?`` in the query string (See above)
52+
53+
.. attention::
54+
configName is case-sensitive
55+
56+
Returns: ``<QUERY>``
57+
58+
59+
60+
61+
query dbBindValue value
62+
~~~~~~~~~~~~~~~~~~~~~~~
63+
:query: ``<QUERY>``
64+
:value: ``<STRING>`` OR ``<NUMBER>`` OR ``<BOOL>`` - Value to bind to the next unbound ``?`` in the query
65+
66+
Returns: ``<NOTHING>``
67+
68+
.. warning::
69+
This command modifies the value in ``query``. If you want to keep the old query intact you need to :ref:`dbCopyQuery <dbCopyQuery>` first.
70+
71+
query dbBindValueArray [value, value...]
72+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73+
74+
Binds multiple values to the next ``?`` in the query, in same order as the ``?`` occur in the query.
75+
76+
77+
:query: ``<QUERY>``
78+
:value: ``<STRING>`` OR ``<NUMBER>`` OR ``<BOOL>`` - Value to bind to the next unbound ``?`` in the query
79+
80+
Returns: ``<NOTHING>``
81+
82+
.. warning::
83+
This command modifies the value in `query`. If you want to keep the old query intact you need to :ref:`dbCopyQuery <dbCopyQuery>` first.
84+
85+
Example: ``_query = dbPrepareQuery "SELECT ? FROM ? WHERE ?=?"``
86+
``_query dbBindValueArray ["data", "table", "value", 5]``
87+
-> ``SELECT data FROM table WHERE value=5``
88+
89+
.. _dbCopyQuery:
90+
91+
dbCopyQuery query
92+
-----------------
93+
query: ``<QUERY>`` - the query object returned by dbPrepareQuery
94+
95+
.. tip::
96+
There is also the short version ``+ query`` which copies just like with Arrays and Numbers.
97+
98+
Returns: ``<NOTHING>``
99+
100+
| Copies a query with all currently bound values.
101+
| Example: ``_query = dbPrepareQuery "SELECT ? FROM ? WHERE ?=?"``
102+
| ``_query dbBindValueArray ["data", "table"]``
103+
| _query -> ``SELECT data FROM table WHERE ?=?``
104+
| ``_copyOfQuery = dbCopyQuery _query;``
105+
| _copyOfQuery -> ``SELECT data FROM table WHERE ?=?``
106+
| ``_copyOfQuery dbBindValueArray ["value", 5]``
107+
| _copyOfQuery -> ``SELECT data FROM table WHERE value=5``
108+
| _query -> ``SELECT data FROM table WHERE ?=?``

‎docs/api/connection.rst‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
Connection commands
2+
===================
3+
4+
dbCreateConnection configName
5+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6+
7+
Creates a connection based on details in the :doc:`config file </intro/config-file>` in ``accounts.<configName>``
8+
9+
.. note::
10+
Connection is not established until the first query.
11+
12+
:configName: ``<STRING>`` - The config name of the connection
13+
14+
.. attention::
15+
configName is case-sensitive
16+
17+
Returns: <DBConnection>
18+
19+
20+
dbCreateConnection [ip, port, user, pw, db]
21+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22+
23+
Creates a connection.
24+
25+
.. note::
26+
Connection is not established until the first query.
27+
28+
:ip: ``<STRING>`` - the IP Address or Domain of the database server
29+
:port: ``<NUMBER>`` - the port of the database server (usually 3306)
30+
:user: ``<STRING>`` - the user to log in with
31+
:pw: ``<STRING>`` - the password (duh)
32+
:db: ``<STRING>`` - the database to use (Equal to `use <db>` SQL command)
33+
34+
Returns: <DBConnection>
35+
36+
37+
38+
dbIsConnected Connection
39+
~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
| Returns whether the connection is currently connected to the database server.
42+
| Also checks if a worker thread is connected.
43+
44+
:connection: ``<DBCONNECTION>`` - A connection
45+
46+
Returns: ``<BOOL>``
47+
48+
49+
50+
51+
52+
dbPing connection
53+
~~~~~~~~~~~~~~~~~
54+
55+
| Executes a ``SELECT 1;`` on the database server and returns true if it get's 1 back. Returns false on error.
56+
| Suspends in scheduled, freezes in unscheduled.
57+
| (Should this return the actual error string somehow?, Should this call error handlers?)
58+
59+
:connection: ``<DBCONNECTION>`` - A connection
60+
61+
Returns: ``<BOOL>``
62+
63+
64+
65+
66+
connection dbAddErrorHandler code
67+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68+
69+
| Registers a global error handler on the connection, if any query on the connection causes an error, that function will be called with ``_this = [errorString, errorCode, query]``.
70+
| There can be multiple error handlers, they will be executed from first to last added.
71+
| If one of the error handlers returns ``true`` the error will be considered handled and the other handlers won't be called.
72+
| If error handlers are present, errors won't be printed to RPT.
73+
| Example _this:
74+
| ``["Lost connection to MySQL server at 'reading authorization packet', system error: 10061",2013,"testQuery5"]``
75+
| ``["You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near 'testQuery5' at line 1",1064,"testQuery5"]``
76+
| ``["Unknown column 'none' in 'field list'",1054,"SELECT none"]``
77+
| #TODO add the query config name to _this too.
78+
79+
:connection: ``<DBCONNECTION>`` - A connection
80+
:code: ``<CODE>`` - Script code.
81+
82+
Returns: ``<NOTHING>``
83+
84+
85+
86+
connection dbLoadSchema schemaName
87+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88+
89+
Executes a SQL file. Path is defined in config.
90+
91+
:connection: ``<DBCONNECTION>`` - A connection
92+
:schemaName: ``<STRING>`` - schema name from config.
93+
94+
.. attention::
95+
schemaName is case-sensitive
96+
97+
Returns: ``<NOTHING>``
98+

‎docs/api/exec-queries.rst‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Executing Queries
2+
=================
3+
4+
5+
6+
7+
connection dbExecute query
8+
~~~~~~~~~~~~~~~~~~~~~~~~~~
9+
10+
| This function behaves differently in scheduled and unscheduled.
11+
| Scheduled: Suspends the script like a sleep/waitUntil would do, and continues once result is ready.
12+
| Unscheduled: Freezes the game until the result is ready. (You probably want to use `dbExecuteAsync`)
13+
14+
15+
:connection: ``<DBConnection>`` - The connection to execute the query on
16+
:query: ``<QUERY>`` - the query object returned by dbPrepareQuery
17+
18+
Returns: ``<RESULT>``
19+
20+
21+
connection dbExecuteAsync query
22+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23+
24+
| This function executes the query in a seperate thread and returns a handle to the task.
25+
| You can bind callbacks to it, or wait on the task to finish (see below)
26+
27+
:connection: ``<DBConnection>`` - The connection to execute the query on
28+
:query: ``<QUERY>`` - the query object returned by dbPrepareQuery
29+
30+
Returns: ``<ASYNC_RESULT>`` (See :doc:`results: Handling Async results`)

‎docs/api/future.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
2+
Future commands that aren't yet implemented
3+
===========================================
4+
5+
6+
7+
dbResultError result
8+
~~~~~~~~~~~~~~~~~~~~
9+
10+
Returns error as string if an error occurred while querying. Returns nil if there is no error. (Should it return empty string instead?)
11+
12+
:result: ``<RESULT>`` - The result
13+
14+
Returns: ``<STRING>``
15+
16+
17+
dbResultErrorNum result
18+
~~~~~~~~~~~~~~~~~~~~~~~
19+
20+
Returns error code if there is one. Returns 0 if there is none.
21+
22+
:result: ``<RESULT>`` - The result
23+
24+
Returns: ``<NUMBER>``
25+
26+
dbResultIsError result
27+
~~~~~~~~~~~~~~~~~~~~~~
28+
29+
Checks if a error occured in the query.
30+
31+
:result: ``<RESULT>`` - The result
32+
33+
Returns: ``<BOOL>``
34+
35+
36+
37+
connection dbConnectionEnableThrow bool
38+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39+
40+
Makes dbExecuteQuery and dbWaitForResult throw SQF Exceptions that can be caught using https://community.bistudio.com/wiki/catch
41+
42+
:connection: ``<DBCONNECTION>`` - A connection
43+
:bool: ``<BOOL>`` - throwing enabled or disabled
44+
45+
Returns: ``<NOTHING>``
46+
47+
48+
query dbBindNamedValue [name, value]
49+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50+
51+
This command modifies the value in `query`. If you want to keep the old query intact you need to :ref:`dbCopyQuery <dbCopyQuery>` first.
52+
53+
:query: ``<QUERY>``
54+
:name: ``<STRING>`` - Name of the value to bind
55+
:value: ``<STRING>`` OR ``<NUMBER>`` OR ``<BOOL>`` - Value to bind to the next unbound `<name>` in the query
56+
57+
Returns: ``<NOTHING>``
58+
59+
60+
| Example: ``SELECT <value> FROM <table>;``
61+
| dbBindNamedValue ["value", "onions"];
62+
| dbBindNamedValue ["table", "shoppinglist"];
63+
| -> ``SELECT onions FROM shoppinglist``
64+
65+
| Maybe other syntax would be better? ``$name``? ``:name`` ?
66+
67+
| ``:name`` seems to be standard elsewhere
68+
| https://www.php.net/manual/de/pdostatement.bindparam.php
69+
| https://www.javaworld.com/article/2077706/named-parameters-for-preparedstatement.html
70+
| https://docs.oracle.com/cd/B10501_01/appdev.920/a96584/oci05bnd.htm
71+
| https://www.sqlite.org/c3ref/bind_blob.html

‎docs/api/misc.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
===============
2+
Miscellaneous commands
3+
===============
4+
5+
6+
dbVersion
7+
~~~~~~~~~
8+
Returns: ``<STRING>``
9+
10+
Returns current version of InterceptDB extension.

0 commit comments

Comments
 (0)