├── .gitignore
├── duckdb.nimble
├── .github
    └── workflows
    │   └── install_and_test.yml
├── CHANGELOG.md
├── README.md
├── tests
    └── test_duckdb.nim
├── src
    ├── duckdb
    │   └── duckdb_wrapper.nim
    └── duckdb.nim
└── LICENSE.txt


/.gitignore:
--------------------------------------------------------------------------------
 1 | *
 2 | !**/
 3 | !*.*
 4 | 
 5 | nimcache/
 6 | build/
 7 | docs/build/
 8 | .cache
 9 | .DS_Store
10 | .vscode
11 | 
12 | # Package specific
13 | *.duckdb
14 | *.duckdb.wal


--------------------------------------------------------------------------------
/duckdb.nimble:
--------------------------------------------------------------------------------
 1 | # Package
 2 | 
 3 | version       = "0.4.0"
 4 | author        = "ayman albaz"
 5 | description   = "A DuckDB wrapper written in Nim."
 6 | license       = "Apache-2.0"
 7 | srcDir        = "src"
 8 | 
 9 | 
10 | # Dependencies
11 | 
12 | requires "nim >= 2.0.0"
13 | requires "nimterop >= 0.6.13"


--------------------------------------------------------------------------------
/.github/workflows/install_and_test.yml:
--------------------------------------------------------------------------------
 1 | name: InstallAndTest
 2 | 
 3 | on: [push]
 4 | 
 5 | jobs:
 6 |   tests-linux:
 7 |     runs-on: ubuntu-latest
 8 |     steps:
 9 |       - uses: actions/checkout@v2
10 |       - uses: jiro4989/setup-nim-action@v1
11 |         with:
12 |           nim-version: "2.0.0"
13 |       - run: nimble install -y
14 |       - run: nimble test -y
15 |   tests-windows:
16 |     runs-on: windows-latest
17 |     steps:
18 |       - uses: actions/checkout@v2
19 |       - uses: jiro4989/setup-nim-action@v1
20 |         with:
21 |           nim-version: "2.0.0"
22 |       - run: nimble install -y
23 |       - run: nimble test -y
24 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Changelog
 2 | All notable changes to this project will be documented in this file.
 3 | 
 4 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 5 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 6 | 
 7 | ## [Unreleased]
 8 | 
 9 | 
10 | ## [0.4.0] - 2024-03-03
11 | ### Added
12 | - Upgraded duckdb library from v0.5.0 to v0.10.0
13 | 
14 | ## [0.3.1] - 2022-11-16
15 | ### Added
16 | - Upgraded duckdb library from v0.5.0 to v0.5.1
17 | 
18 | ## [0.3.0] - 2022-09-11
19 | ### Added
20 | - Changed library API to match sqlite in stdlib
21 | - Library now more memory safe due to use of destructors
22 | 
23 | ## [0.2.0] - 2022-09-10
24 | ### Added
25 | - Added better error messaging
26 | - Removed config options
27 | 
28 | 
29 | ## [0.1.0] - 2021-11-28
30 | ### Added
31 | - Created nim-duckdb library
32 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | ![Linux Build Status (Github Actions)](https://github.com/ayman-albaz/nim-duckdb/actions/workflows/install_and_test.yml/badge.svg) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 2 | 
 3 | # nim-duckdb
 4 | 
 5 | This library is a DuckDB wrapper in nim. It uses nimterop to generate the C Bindings.
 6 | 
 7 | 
 8 | ## Supported Functions
 9 | 
10 | Opening/closing a database:
11 | ```Nim
12 | import duckdb
13 | 
14 | # Open database and connection.
15 | # Connection and database closed automatically with destructors
16 | var dbConn = connect("mydb.db")
17 | ```
18 | 
19 | Opening/closing an in-memory database:
20 | ```Nim
21 | import duckdb
22 | 
23 | # Open database and connection
24 | # Connection and database closed automatically with destructors
25 | var dbConn = connect()
26 | ```
27 | 
28 | Executing commands and fetching a prepared statement
29 | ```Nim
30 | dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
31 | dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
32 | var items: seq[seq[string]]
33 | for item in dbConn.rows("SELECT * FROM integers WHERE i = ? or j = ?", 3, "6"):
34 |   items.add(item)
35 | assert items == @[@["3", "4"], @["5", "6"]]
36 | ```
37 | 
38 | Executing commands and fast inserting. Fast inserting is much faster than inserting in a loop.
39 | ```Nim
40 | dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
41 | dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
42 | dbConn.fastInsert(
43 |   "integers",
44 |   @[
45 |     @["11", "NULL"]
46 |   ],
47 | )
48 | var items: seq[seq[string]]
49 | for item in dbConn.rows(
50 |   """SELECT i, j, i + j
51 |   FROM integers"""
52 |   ): items.add(item)
53 | 
54 | check items == @[@["3", "4", "7"], @["5", "6", "11"], @["7", "NULL", "NULL"], @["11", "NULL", "NULL"]]
55 | ```
56 | 
57 | Null items are represented by `"NULL"`
58 | 
59 | 
60 | ## Acknowledgments
61 | Special thanks to [@Clonkk](https://github.com/Clonkk/duckdb_wrapper) as I used his nimterop script to generate the wrapper.
62 | 
63 | 
64 | ## Contact
65 | I can be reached at aymanalbaz98@gmail.com


--------------------------------------------------------------------------------
/tests/test_duckdb.nim:
--------------------------------------------------------------------------------
 1 | import unittest
 2 | import ../src/duckdb
 3 | 
 4 | 
 5 | suite "tests":
 6 | 
 7 |   test "DuckDB init":
 8 |     var dbConn = connect()
 9 | 
10 |   test "Bad result":
11 |     var dbConn = connect()
12 |     expect DuckDBOperationError:
13 |       dbConn.exec("CREATE BAD COMMAND!")
14 | 
15 |   test "DuckDB exec":
16 |     var dbConn = connect()
17 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
18 |     dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
19 | 
20 |   test "DuckDB exec prepared rows":
21 |     var dbConn = connect()
22 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
23 |     dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (?, NULL);", 7)
24 |     var items: seq[seq[string]]
25 |     for item in dbConn.rows("SELECT * FROM integers"): items.add(item)
26 |     check items == @[@["3", "4"], @["5", "6"], @["7", "NULL"]]
27 | 
28 |   test "DuckDB exec bad prepared rows":
29 |     var dbConn = connect()
30 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
31 |     expect DuckDBOperationError:
32 |       dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (?, NULL);", "NANA")
33 | 
34 |   test "DuckDB exec rows prepared":
35 |     var dbConn = connect()
36 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
37 |     dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
38 |     var items: seq[seq[string]]
39 |     for item in dbConn.rows("SELECT * FROM integers WHERE i = ? or j = ?", 3, "6"): items.add(item)
40 |     check items == @[@["3", "4"], @["5", "6"]]
41 | 
42 |   test "DuckDB exec rows bad prepared":
43 |     var dbConn = connect()
44 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
45 |     dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
46 |     var items: seq[seq[string]]
47 |     expect DuckDBOperationError:
48 |       for item in dbConn.rows("SELECT * FROM integers WHERE i = ? or j = ?", 3, "NANA"): items.add(item)
49 | 
50 |   test "DuckDB exec fast insert":
51 |     var dbConn = connect()
52 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
53 |     dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
54 |     dbConn.fastInsert(
55 |       "integers",
56 |       @[
57 |         @["11", "NULL"]
58 |       ],
59 |     )
60 |     var items: seq[seq[string]]
61 |     for item in dbConn.rows(
62 |       """SELECT i, j, i + j
63 |       FROM integers"""
64 |       ): items.add(item)
65 | 
66 |     check items == @[@["3", "4", "7"], @["5", "6", "11"], @["7", "NULL", "NULL"], @["11", "NULL", "NULL"]]
67 | 
68 |   test "DuckDB exec bad fast insert":
69 |     var dbConn = connect()
70 |     dbConn.exec("CREATE TABLE integers(i INTEGER, j INTEGER);")
71 |     dbConn.exec("INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);")
72 |     expect DuckDBOperationError:
73 |       dbConn.fastInsert(
74 |         "integers",
75 |         @[
76 |           @["11", "NANA"]
77 |         ],
78 |       )
79 | 


--------------------------------------------------------------------------------
/src/duckdb/duckdb_wrapper.nim:
--------------------------------------------------------------------------------
 1 | import nimterop/cimport
 2 | import nimterop/build
 3 | import os
 4 | 
 5 | when defined(buildDuckDb):
 6 |   const duckdbUrl = "https://github.com/duckdb/duckdb/releases/download/v0.10.0/libduckdb-src.zip"
 7 | 
 8 | else:
 9 |   when defined(Linux):
10 |     const duckdbUrl = "https://github.com/duckdb/duckdb/releases/download/v0.10.0/libduckdb-linux-amd64.zip"
11 |     const duckdbLib = "libduckdb.so"
12 |   when defined(macosx):
13 |     const duckdbUrl = "https://github.com/duckdb/duckdb/releases/download/v0.10.0/libduckdb-osx-universal.zip"
14 |     const duckdbLib = "libduckdb.dylib"
15 |   when defined(Windows):
16 |     const duckdbLib = "duckdb.dll"
17 |     when defined(cpu64):
18 |       const duckdbUrl = "https://github.com/duckdb/duckdb/releases/download/v0.10.0/libduckdb-windows-amd64.zip"
19 |     when defined(cpu32):
20 |       const duckdbUrl = "https://github.com/duckdb/duckdb/releases/download/v0.10.0/libduckdb-windows-i386.zip"
21 | 
22 | const baseDir = getProjectCacheDir("duckdb") & "/"
23 | 
24 | static:
25 |   # cDebug()
26 | 
27 |   const duckdbZip = lastPathPart(duckdbUrl)
28 |   downloadUrl(duckdbUrl, baseDir)
29 | 
30 |   const outdir = "."
31 |   extractZip(normalizedPath(baseDir & duckdbzip), outdir)
32 | 
33 | cPlugin:
34 |   proc onSymbol*(sym: var Symbol) {.exportc, dynlib.} =
35 |     case sym.name:
36 |     of "_Bool": sym.name = "bool"
37 |     of "__deprecated_data": sym.name = "deprecated_data"
38 |     of "__deprecated_nullmask": sym.name = "deprecated_nullmask"
39 |     of "__deprecated_type": sym.name = "deprecated_type"
40 |     of "__deprecated_name": sym.name = "deprecated_name"
41 |     of "__deprecated_column_count": sym.name = "deprecated_column_count"
42 |     of "__deprecated_row_count": sym.name = "deprecated_row_count"
43 |     of "__deprecated_rows_changed": sym.name = "deprecated_rows_changed"
44 |     of "__deprecated_columns": sym.name = "deprecated_columns"
45 |     of "__deprecated_error_message": sym.name = "deprecated_error_message"
46 |     of "_duckdb_vector": sym.name = "duckdb_vector"
47 |     of "__vctr": sym.name = "vctr"
48 |     of "_duckdb_database": sym.name = "duckdb_database"
49 |     of "__db": sym.name = "db"
50 |     of "_duckdb_connection": sym.name = "duckdb_connection"
51 |     of "__conn": sym.name = "conn"
52 |     of "_duckdb_prepared_statement": sym.name = "duckdb_prepared_statement"
53 |     of "__prep": sym.name = "prep"
54 |     of "_duckdb_extracted_statements": sym.name = "duckdb_extracted_statements"
55 |     of "__extrac": sym.name = "extrac"
56 |     of "_duckdb_pending_result": sym.name = "duckdb_pending_result"
57 |     of "__pend": sym.name = "pend"
58 |     of "_duckdb_appender": sym.name = "duckdb_appender"
59 |     of "__appn": sym.name = "appn"
60 |     of "_duckdb_config": sym.name = "duckdb_config"
61 |     of "_duckdb_logical_type": sym.name = "duckdb_logical_type"
62 |     of "__cnfg": sym.name = "cnfg"
63 |     of "__lglt": sym.name = "lglt"
64 |     of "_duckdb_data_chunk": sym.name = "duckdb_data_chunk"
65 |     of "__dtck": sym.name = "dtck"
66 |     of "_duckdb_value": sym.name = "duckdb_value"
67 |     of "__val": sym.name = "val"
68 |     of "_duckdb_arrow": sym.name = "duckdb_arrow"
69 |     of "__arrw": sym.name = "arrw"
70 |     of "_duckdb_arrow_stream": sym.name = "duckdb_arrow_stream"
71 |     of "__arrwstr": sym.name = "arrwstr"
72 |     of "_duckdb_arrow_schema": sym.name = "duckdb_arrow_schema"
73 |     of "__arrs": sym.name = "arrs"
74 |     of "_duckdb_arrow_array": sym.name = "duckdb_arrow_array"
75 |     of "__arra": sym.name = "arra"
76 |     else: discard
77 | 
78 | const duckDbH = normalizedPath(baseDir & "duckdb.h")
79 | 
80 | when defined(buildDuckDb):
81 |   const duckDbSource = normalizedPath(baseDir & "duckdb.cpp")
82 |   cPassL("-lstdc++ -lpthread")
83 |   cCompile(duckDbSource)
84 |   cImport(duckDbH)
85 | 
86 | else:
87 |   const duckDbLibPath = normalizedPath(baseDir & duckdbLib)
88 |   cImport(duckDbH, recurse = true, dynlib = duckDbLibPath)
89 | 


--------------------------------------------------------------------------------
/src/duckdb.nim:
--------------------------------------------------------------------------------
  1 | import duckdb/duckdb_wrapper
  2 | 
  3 | type
  4 |   DuckDBBaseError* = object of CatchableError
  5 |   DuckDBOperationError* = object of DuckDBBaseError
  6 |   DuckDBRow* = seq[string]
  7 |   DuckDBState* = duckdb_state
  8 |   # User defined objects
  9 |   DuckDBConn* = object
 10 |     database: duckdbDatabase
 11 |     connection: duckdbConnection
 12 |   DuckDBResult* = object
 13 |     result: duckdbResult
 14 |   DuckDBPreparedStatement = object
 15 |     statement: duckdbPreparedStatement
 16 |   DuckDBValueVarchar = object
 17 |     varchar: cstring
 18 |   DuckDBAppender = object
 19 |     appender: duckdbAppender
 20 | 
 21 | proc close*(conn: DuckDBConn) =
 22 |   ## Closes a duckDB database.
 23 |   duckdbClose(conn.database.addr)
 24 | 
 25 | proc disconnect*(conn: DuckDBConn) =
 26 |   ## Disconnects the connection to a duckDB database.
 27 |   duckdbDisconnect(conn.connection.addr)
 28 | 
 29 | proc `=destroy`(conn: var DuckDBConn) =
 30 |   if not isNil(conn.connection.addr):
 31 |     conn.disconnect()
 32 |   if not isNil(conn.database.addr):
 33 |     conn.close()
 34 | 
 35 | proc `=destroy`(result: var DuckDBResult) =
 36 |   if not isNil(result.result.addr):
 37 |     duckdbDestroyResult(result.result.addr)
 38 | 
 39 | proc `=destroy`(statement: var DuckDBPreparedStatement) =
 40 |   if not isNil(statement.statement.addr):
 41 |     duckdbDestroyPrepare(statement.statement.addr)
 42 | 
 43 | proc `=destroy`(varchar: var DuckDBValueVarchar) =
 44 |   if not isNil(varchar.varchar):
 45 |     duckdbFree(varchar.varchar)
 46 | 
 47 | proc `=destroy`(appender: var DuckDBAppender) =
 48 |   if not isNil(appender.appender.addr):
 49 |     discard duckdbAppenderDestroy(appender.appender.addr)
 50 | 
 51 | proc isStateSuccessful(state: DuckDBState): bool =
 52 |   result = state == DuckDBSuccess
 53 | 
 54 | proc checkStateSuccessful(state: DuckDBState) =
 55 |   if not isStateSuccessful(state):
 56 |     raise newException(DuckDBOperationError, "DuckDB operation did not complete sucessfully.")
 57 | 
 58 | proc checkStateSuccessful(state: DuckDBState, result: DuckDBResult) =
 59 |   if not isStateSuccessful(state):
 60 |     let errorMessage = result.result.addr.duckdbResultError()
 61 |     raise newException(DuckDBOperationError,
 62 |         "DuckDB operation did not complete sucessfully. Reason:\n" & $errorMessage)
 63 | 
 64 | proc checkStateSuccessful(state: DuckDBState,
 65 |     statement: DuckDBPreparedStatement) =
 66 |   if not isStateSuccessful(state):
 67 |     let errorMessage = statement.statement.duckdbPrepareError()
 68 |     raise newException(DuckDBOperationError,
 69 |         "DuckDB operation did not complete sucessfully. Reason:\n" & $errorMessage)
 70 | 
 71 | proc checkStateSuccessful(state: DuckDBState, appender: DuckDBAppender) =
 72 |   if not isStateSuccessful(state):
 73 |     let errorMessage = appender.appender.duckdbAppenderError()
 74 |     raise newException(DuckDBOperationError,
 75 |         "DuckDB operation did not complete sucessfully. Reason:\n" & $errorMessage)
 76 | 
 77 | proc connect*(path: string): DuckDBConn =
 78 |   ## Opens a DuckDB database
 79 |   ## `path` is the path of the output DuckDB. Set to ":memory:" to open an in-memory database.
 80 |   var state1 = duckdbOpen(path.cstring, result.database.addr)
 81 |   checkStateSuccessful(state1)
 82 |   var state2 = duckdbConnect(result.database, result.connection.addr)
 83 |   checkStateSuccessful(state2)
 84 | 
 85 | proc connect*(): DuckDBConn =
 86 |   ## Opens an in-memory DuckDB database.
 87 |   result = connect(":memory:")
 88 | 
 89 | proc execWithoutArgs(conn: DuckDBConn, sqlQuery: string) =
 90 |   ## Executes a SQL query to a duckDB database.
 91 |   var result = DuckDBResult()
 92 |   var state = duckdbQuery(conn.connection, sqlQuery.cstring, result.result.addr)
 93 |   checkStateSuccessful(state, result)
 94 | 
 95 | proc execWithArgs(conn: DuckDBConn, sqlQuery: string, args: varargs[string, `$`]) =
 96 |   ## Executes a SQL query to a duckDB database.
 97 |   var statement = DuckDBPreparedStatement()
 98 | 
 99 |   # Create prepared statement
100 |   let state1 = duckdbPrepare(conn.connection, sqlQuery.cstring,
101 |       statement.statement.addr)
102 |   checkStateSuccessful(state1, statement)
103 | 
104 |   # Parse prepared statement
105 |   for i, arg in args:
106 |     let state2 = duckdbBindVarchar(statement.statement, (i + 1).idx_t, arg.cstring)
107 |     checkStateSuccessful(state2)
108 | 
109 |   # Result handler
110 |   let result = DuckDBResult()
111 |   let state3 = duckdbExecutePrepared(statement.statement,
112 |       result.result.addr)
113 |   checkStateSuccessful(state3, result)
114 | 
115 | proc exec*(conn: DuckDBConn, sqlQuery: string, args: varargs[string, `$`]) =
116 |   if args.len() == 0: conn.execWithoutArgs(sqlQuery)
117 |   else: conn.execWithArgs(sqlQuery, args)
118 | 
119 | iterator getRows(result: DuckDBResult): DuckDBRow =
120 |   var rowCount = result.result.addr.duckdbRowCount()
121 |   var columnCount = result.result.addr.duckdbColumnCount()
122 |   var duckDBRow = newSeq[string](columnCount)
123 |   for idxRow in 0..<rowCount:
124 |     for idxCol in 0..<columnCount:
125 |       var varchar = DuckDBValueVarchar(varchar: duckdbValueVarchar(
126 |           result.result.addr, idxCol, idxRow))
127 |       duckDBRow[idxCol] = (
128 |         if varchar.varchar.isNil():
129 |         "NULL"
130 |       else:
131 |         $varchar.varchar
132 |       )
133 |     yield duckDBRow
134 | 
135 | iterator rowsWithoutArgs(conn: DuckDBConn, sqlQuery: string): DuckDBRow =
136 |   ## Executes a SELECT SQL query to a duckDB database.
137 | 
138 |   var result = DuckDBResult()
139 |   var state = duckdbQuery(conn.connection, sqlQuery.cstring, result.result.addr)
140 |   checkStateSuccessful(state, result)
141 |   for duckDBRow in getRows(result):
142 |     yield duckDBRow
143 | 
144 | iterator rowsWithArgs(conn: DuckDBConn, sqlQuery: string, args: varargs[string,
145 |     `$`]): DuckDBRow =
146 |   ## Executes a prepared SELECT SQL query to a duckDB database.
147 |   var statement = DuckDBPreparedStatement()
148 | 
149 |   # Create prepared statement
150 |   let state1 = duckdbPrepare(conn.connection, sqlQuery.cstring,
151 |       statement.statement.addr)
152 |   checkStateSuccessful(state1, statement)
153 | 
154 |   # Parse prepared statement
155 |   for i, arg in args:
156 |     let state2 = duckdbBindVarchar(statement.statement, (i + 1).idx_t, arg.cstring)
157 |     checkStateSuccessful(state2)
158 | 
159 |   # Result handler
160 |   let result = DuckDBResult()
161 |   let state3 = duckdbExecutePrepared(statement.statement,
162 |       result.result.addr)
163 |   checkStateSuccessful(state3, result)
164 |   for duckDBRow in getRows(result):
165 |     yield duckDBRow
166 | 
167 | iterator rows*(conn: DuckDBConn, sqlQuery: string, args: varargs[string,
168 |     `$`]): DuckDBRow =
169 |   if args.len() == 0:
170 |     for duckDBRow in rowsWithoutArgs(conn, sqlQuery):
171 |       yield duckDBRow
172 |   else:
173 |     for duckDBRow in rowsWithArgs(conn, sqlQuery, args):
174 |       yield duckDBRow
175 | 
176 | proc fastInsert*(conn: DuckDBConn, table: string, ent: seq[DuckDBRow]) =
177 |   var appender = DuckDBAppender()
178 |   let state1 = duckdbAppenderCreate(conn.connection, nil, table.cstring,
179 |       appender.appender.addr)
180 |   checkStateSuccessful(state1, appender)
181 |   for row in ent:
182 |     for column in row:
183 |       let state2 = (
184 |         if column == "NULL": duckdbAppendNull(appender.appender)
185 |         else: duckdbAppendVarchar(appender.appender, column.cstring)
186 |       )
187 |       checkStateSuccessful(state2)
188 |     let state3 = duckdbAppenderEndRow(appender.appender)
189 |     checkStateSuccessful(state3)
190 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
  1 | 
  2 |                                  Apache License
  3 |                            Version 2.0, January 2004
  4 |                         http://www.apache.org/licenses/
  5 | 
  6 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  7 | 
  8 |    1. Definitions.
  9 | 
 10 |       "License" shall mean the terms and conditions for use, reproduction,
 11 |       and distribution as defined by Sections 1 through 9 of this document.
 12 | 
 13 |       "Licensor" shall mean the copyright owner or entity authorized by
 14 |       the copyright owner that is granting the License.
 15 | 
 16 |       "Legal Entity" shall mean the union of the acting entity and all
 17 |       other entities that control, are controlled by, or are under common
 18 |       control with that entity. For the purposes of this definition,
 19 |       "control" means (i) the power, direct or indirect, to cause the
 20 |       direction or management of such entity, whether by contract or
 21 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 22 |       outstanding shares, or (iii) beneficial ownership of such entity.
 23 | 
 24 |       "You" (or "Your") shall mean an individual or Legal Entity
 25 |       exercising permissions granted by this License.
 26 | 
 27 |       "Source" form shall mean the preferred form for making modifications,
 28 |       including but not limited to software source code, documentation
 29 |       source, and configuration files.
 30 | 
 31 |       "Object" form shall mean any form resulting from mechanical
 32 |       transformation or translation of a Source form, including but
 33 |       not limited to compiled object code, generated documentation,
 34 |       and conversions to other media types.
 35 | 
 36 |       "Work" shall mean the work of authorship, whether in Source or
 37 |       Object form, made available under the License, as indicated by a
 38 |       copyright notice that is included in or attached to the work
 39 |       (an example is provided in the Appendix below).
 40 | 
 41 |       "Derivative Works" shall mean any work, whether in Source or Object
 42 |       form, that is based on (or derived from) the Work and for which the
 43 |       editorial revisions, annotations, elaborations, or other modifications
 44 |       represent, as a whole, an original work of authorship. For the purposes
 45 |       of this License, Derivative Works shall not include works that remain
 46 |       separable from, or merely link (or bind by name) to the interfaces of,
 47 |       the Work and Derivative Works thereof.
 48 | 
 49 |       "Contribution" shall mean any work of authorship, including
 50 |       the original version of the Work and any modifications or additions
 51 |       to that Work or Derivative Works thereof, that is intentionally
 52 |       submitted to Licensor for inclusion in the Work by the copyright owner
 53 |       or by an individual or Legal Entity authorized to submit on behalf of
 54 |       the copyright owner. For the purposes of this definition, "submitted"
 55 |       means any form of electronic, verbal, or written communication sent
 56 |       to the Licensor or its representatives, including but not limited to
 57 |       communication on electronic mailing lists, source code control systems,
 58 |       and issue tracking systems that are managed by, or on behalf of, the
 59 |       Licensor for the purpose of discussing and improving the Work, but
 60 |       excluding communication that is conspicuously marked or otherwise
 61 |       designated in writing by the copyright owner as "Not a Contribution."
 62 | 
 63 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 64 |       on behalf of whom a Contribution has been received by Licensor and
 65 |       subsequently incorporated within the Work.
 66 | 
 67 |    2. Grant of Copyright License. Subject to the terms and conditions of
 68 |       this License, each Contributor hereby grants to You a perpetual,
 69 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 70 |       copyright license to reproduce, prepare Derivative Works of,
 71 |       publicly display, publicly perform, sublicense, and distribute the
 72 |       Work and such Derivative Works in Source or Object form.
 73 | 
 74 |    3. Grant of Patent License. Subject to the terms and conditions of
 75 |       this License, each Contributor hereby grants to You a perpetual,
 76 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 77 |       (except as stated in this section) patent license to make, have made,
 78 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 79 |       where such license applies only to those patent claims licensable
 80 |       by such Contributor that are necessarily infringed by their
 81 |       Contribution(s) alone or by combination of their Contribution(s)
 82 |       with the Work to which such Contribution(s) was submitted. If You
 83 |       institute patent litigation against any entity (including a
 84 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 85 |       or a Contribution incorporated within the Work constitutes direct
 86 |       or contributory patent infringement, then any patent licenses
 87 |       granted to You under this License for that Work shall terminate
 88 |       as of the date such litigation is filed.
 89 | 
 90 |    4. Redistribution. You may reproduce and distribute copies of the
 91 |       Work or Derivative Works thereof in any medium, with or without
 92 |       modifications, and in Source or Object form, provided that You
 93 |       meet the following conditions:
 94 | 
 95 |       (a) You must give any other recipients of the Work or
 96 |           Derivative Works a copy of this License; and
 97 | 
 98 |       (b) You must cause any modified files to carry prominent notices
 99 |           stating that You changed the files; and
100 | 
101 |       (c) You must retain, in the Source form of any Derivative Works
102 |           that You distribute, all copyright, patent, trademark, and
103 |           attribution notices from the Source form of the Work,
104 |           excluding those notices that do not pertain to any part of
105 |           the Derivative Works; and
106 | 
107 |       (d) If the Work includes a "NOTICE" text file as part of its
108 |           distribution, then any Derivative Works that You distribute must
109 |           include a readable copy of the attribution notices contained
110 |           within such NOTICE file, excluding those notices that do not
111 |           pertain to any part of the Derivative Works, in at least one
112 |           of the following places: within a NOTICE text file distributed
113 |           as part of the Derivative Works; within the Source form or
114 |           documentation, if provided along with the Derivative Works; or,
115 |           within a display generated by the Derivative Works, if and
116 |           wherever such third-party notices normally appear. The contents
117 |           of the NOTICE file are for informational purposes only and
118 |           do not modify the License. You may add Your own attribution
119 |           notices within Derivative Works that You distribute, alongside
120 |           or as an addendum to the NOTICE text from the Work, provided
121 |           that such additional attribution notices cannot be construed
122 |           as modifying the License.
123 | 
124 |       You may add Your own copyright statement to Your modifications and
125 |       may provide additional or different license terms and conditions
126 |       for use, reproduction, or distribution of Your modifications, or
127 |       for any such Derivative Works as a whole, provided Your use,
128 |       reproduction, and distribution of the Work otherwise complies with
129 |       the conditions stated in this License.
130 | 
131 |    5. Submission of Contributions. Unless You explicitly state otherwise,
132 |       any Contribution intentionally submitted for inclusion in the Work
133 |       by You to the Licensor shall be under the terms and conditions of
134 |       this License, without any additional terms or conditions.
135 |       Notwithstanding the above, nothing herein shall supersede or modify
136 |       the terms of any separate license agreement you may have executed
137 |       with Licensor regarding such Contributions.
138 | 
139 |    6. Trademarks. This License does not grant permission to use the trade
140 |       names, trademarks, service marks, or product names of the Licensor,
141 |       except as required for reasonable and customary use in describing the
142 |       origin of the Work and reproducing the content of the NOTICE file.
143 | 
144 |    7. Disclaimer of Warranty. Unless required by applicable law or
145 |       agreed to in writing, Licensor provides the Work (and each
146 |       Contributor provides its Contributions) on an "AS IS" BASIS,
147 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148 |       implied, including, without limitation, any warranties or conditions
149 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150 |       PARTICULAR PURPOSE. You are solely responsible for determining the
151 |       appropriateness of using or redistributing the Work and assume any
152 |       risks associated with Your exercise of permissions under this License.
153 | 
154 |    8. Limitation of Liability. In no event and under no legal theory,
155 |       whether in tort (including negligence), contract, or otherwise,
156 |       unless required by applicable law (such as deliberate and grossly
157 |       negligent acts) or agreed to in writing, shall any Contributor be
158 |       liable to You for damages, including any direct, indirect, special,
159 |       incidental, or consequential damages of any character arising as a
160 |       result of this License or out of the use or inability to use the
161 |       Work (including but not limited to damages for loss of goodwill,
162 |       work stoppage, computer failure or malfunction, or any and all
163 |       other commercial damages or losses), even if such Contributor
164 |       has been advised of the possibility of such damages.
165 | 
166 |    9. Accepting Warranty or Additional Liability. While redistributing
167 |       the Work or Derivative Works thereof, You may choose to offer,
168 |       and charge a fee for, acceptance of support, warranty, indemnity,
169 |       or other liability obligations and/or rights consistent with this
170 |       License. However, in accepting such obligations, You may act only
171 |       on Your own behalf and on Your sole responsibility, not on behalf
172 |       of any other Contributor, and only if You agree to indemnify,
173 |       defend, and hold each Contributor harmless for any liability
174 |       incurred by, or claims asserted against, such Contributor by reason
175 |       of your accepting any such warranty or additional liability.
176 | 
177 |    END OF TERMS AND CONDITIONS
178 | 
179 |    APPENDIX: How to apply the Apache License to your work.
180 | 
181 |       To apply the Apache License to your work, attach the following
182 |       boilerplate notice, with the fields enclosed by brackets "[]"
183 |       replaced with your own identifying information. (Don't include
184 |       the brackets!)  The text should be enclosed in the appropriate
185 |       comment syntax for the file format. We also recommend that a
186 |       file or class name and description of purpose be included on the
187 |       same "printed page" as the copyright notice for easier
188 |       identification within third-party archives.
189 | 
190 |    Copyright 2021 Ayman Albaz
191 | 
192 |    Licensed under the Apache License, Version 2.0 (the "License");
193 |    you may not use this file except in compliance with the License.
194 |    You may obtain a copy of the License at
195 | 
196 |        http://www.apache.org/licenses/LICENSE-2.0
197 | 
198 |    Unless required by applicable law or agreed to in writing, software
199 |    distributed under the License is distributed on an "AS IS" BASIS,
200 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201 |    See the License for the specific language governing permissions and
202 |    limitations under the License.
203 | 


--------------------------------------------------------------------------------