Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added missing docs. #37

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Added missing docs. #37

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
85f85ff
Added missing docs.
matcracker Jun 19, 2020
67fce27
Update README.md
matcracker Jun 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# libasynql v3.0.0 <img src="https://poggit.pmmp.io/ci.badge/poggit/libasynql/libasynql" align="right"/>
# libasynql v3.3.0 <img src="https://poggit.pmmp.io/ci.badge/poggit/libasynql/libasynql" align="right"/>
Asynchronous SQL access library for PocketMine plugins.

## Usage
Expand Down Expand Up @@ -168,6 +168,12 @@ A variable declaration declares the required and optional variables for this que
#### Symbol
- `:`

### Nullable variable declaration
Declare if the variable can accepts `null` values. It is only allowed inside a query declaration.

#### Symbol
- `?`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong place. This section is for the statement types, i.e. the symbol immediately following -- #. ? is a modifier to the argument type, not a statement type.


#### Arguments
##### VAR_NAME
The name of the variable. Any characters apart from spaces, tabs and colons are allowed. However, to comply with ordinary SQL editors, using "normal" symbols (e.g. variable names in other programming languages) is recommended.
Expand All @@ -178,6 +184,8 @@ The variable type. Possible values:
- `int`
- `float`
- `bool`
- `timestamp`
- `list`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

list is not a type. list:{type} is a modifier on other types. You would probably want to change this to list:{type} instead of list.


##### VAR_DEFAULT
If the variable is optional, it declares a default value.
Expand All @@ -198,6 +206,26 @@ A numeric value that can be parsed by [`(float)` cast, equivalent to `floatval`]
###### `bool` default
`true`, `on`, `yes` or `1` will result in true. Other values, as long as there is something, will result default false. (If there is nothing, the variable will not be optional)

###### `timestamp` default
A numeric value that can be parsed by [`(int)` cast, equivalent to `intval`](https://php.net/intval) or [`(float)` cast, equivalent to `floatval`](https://php.net/floatval)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider restructuring this section entirely. This section is supposed to describe default values, not to describe the types. Since description of the type is required, consider restructuring the section such that each type has its documentation and VAR_DEFAULT doesn't have its own place.


**Allowed default values:**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This font doesn't look good in rendered form.
image

- `0`
- `NOW`

###### `list`
An array of values whose type must be specified in the same way as the variable declaration.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this allowed? Just reading the documentation, I would expect this to be usable in INSERT INTO tbl (a, b) VALUES (:a, :b) where a and b are lists. But in fact this is only allowed in the IN context.
Furthermore, should it be used as WHERE col IN :list or WHERE col IN (:list)? Please clarify.


**Default value is not allowed**

Example:
```sql
-- #{ group.name
-- # :var_name1 list:int
-- # :var_name2 list?float
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does list? mean? Please explain it better.

-- #}
```

### Query text
Query text is not a command, but the non-commented part between the start and end commands of a query declaration.

Expand Down