From 3c2e5ab119c2ac5585e5c19e8d00fb03d2127f0a Mon Sep 17 00:00:00 2001 From: Richard Ore Date: Mon, 21 Aug 2023 03:14:18 +0100 Subject: [PATCH] Fixes to the SSL module. --- libs/bcrypt.b | 8 +- libs/http/client.b | 10 +- libs/http/index.b | 12 +- libs/http/response.b | 2 +- libs/math.b | 276 +++++++++++++++-------------- libs/mime.b | 45 ++--- libs/os.b | 101 +++++------ libs/url.b | 2 +- libs/zip.b | 2 +- packages/clib/clib/index.b | 58 +++--- packages/clib/clib/types.b | 14 +- packages/curl/curl/curl.b | 76 ++++---- packages/curl/curl/index.b | 5 +- packages/json/json/encoder.b | 23 ++- packages/json/json/index.b | 18 +- packages/sqlite/sqlite/cursor.b | 28 ++- packages/sqlite/sqlite/exception.b | 10 +- packages/sqlite/sqlite/index.b | 4 +- packages/sqlite/sqlite/sqlite3.b | 37 ++-- packages/ssl/ssl.c | 19 +- packages/ssl/ssl.h | 5 +- packages/ssl/ssl/bio.b | 152 +++++++--------- packages/ssl/ssl/context.b | 34 ++-- packages/ssl/ssl/index.b | 9 +- packages/ssl/ssl/server.b | 262 ++------------------------- packages/ssl/ssl/socket.b | 4 +- packages/zlib/zlib/index.b | 111 ++++++------ 27 files changed, 543 insertions(+), 784 deletions(-) diff --git a/libs/bcrypt.b b/libs/bcrypt.b index 76732e31..fb151b79 100644 --- a/libs/bcrypt.b +++ b/libs/bcrypt.b @@ -664,7 +664,7 @@ def _generate_salt(rounds) { * * Generates a hash for the given string. If _salt_length_ is not given, * the length of the salt will be equal to `DEFAULT_LOG2_ROUNDS`. - * @throws Exception + * @dies Exception * @return string */ def hash(str, salt_length) { @@ -683,7 +683,7 @@ def hash(str, salt_length) { * compare(str: string, known_hash: string) * * Tests a string against a known hash. - * @throws Exception + * @dies Exception * @return string */ def compare(str, known_hash) { @@ -712,7 +712,7 @@ def compare(str, known_hash) { * get_rounds(hash: string) * * Gets the number of rounds used to encrypt the specified hash. - * @throws Exception + * @dies Exception * @return number */ def get_rounds(hash) { @@ -726,7 +726,7 @@ def get_rounds(hash) { * * Gets the salt portion from a hash. * @note This function does not validate the hash. - * @throws Exception + * @dies Exception * @return string */ def get_salt(hash) { diff --git a/libs/http/client.b b/libs/http/client.b index 30c7e1c6..5f5b30b1 100644 --- a/libs/http/client.b +++ b/libs/http/client.b @@ -89,7 +89,7 @@ class HttpClient { * * @default method: GET * @return HttpResponse - * @throws SocketException, Exception + * @dies SocketException, Exception */ send_request(uri, method, data) { @@ -134,7 +134,7 @@ class HttpClient { * * sends an Http GET request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ get(url) { return self.send_request(url, 'GET') @@ -145,7 +145,7 @@ class HttpClient { * * sends an Http POST request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ post(url, data) { return self.send_request(url, 'POST', data) @@ -156,7 +156,7 @@ class HttpClient { * * sends an Http PUT request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ put(url, data) { return self.send_request(url, 'PUT', data) @@ -167,7 +167,7 @@ class HttpClient { * * sends an Http DELETE request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ delete(url) { return self.send_request(url, 'DELETE', nil) diff --git a/libs/http/index.b b/libs/http/index.b index 33031089..e485c162 100644 --- a/libs/http/index.b +++ b/libs/http/index.b @@ -85,7 +85,7 @@ var _client = HttpClient() * echo client.get('/current-user').body.to_string() * ``` * @return HttpClient - * @throws Exception + * @dies Exception */ def set_headers(headers) { if !is_dict(headers) @@ -100,7 +100,7 @@ def set_headers(headers) { * sends an Http GET request and returns an HttpResponse * or throws one of SocketException or Exception if it fails. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ def get(url) { return _client.get(url) @@ -111,7 +111,7 @@ def get(url) { * * sends an Http POST request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ def post(url, data) { return _client.post(url, data) @@ -122,7 +122,7 @@ def post(url, data) { * * sends an Http PUT request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ def put(url, data) { return _client.put(url, data) @@ -133,7 +133,7 @@ def put(url, data) { * * sends an Http DELETE request and returns an HttpResponse. * @return HttpResponse - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ def delete(url) { return _client.send_request(url, 'DELETE', nil) @@ -144,7 +144,7 @@ def delete(url) { * * Creates an new HttpServer instance. * @return HttpServer - * @throws Exception, SocketExcepion, HttpException + * @dies Exception, SocketExcepion, HttpException */ def server(port, address) { return HttpServer(port, address) diff --git a/libs/http/response.b b/libs/http/response.b index 22f4bebe..a291a405 100644 --- a/libs/http/response.b +++ b/libs/http/response.b @@ -119,7 +119,7 @@ class HttpResponse { * correct mimetype for the file. If the status code is given, the * response will be sent with the given status code. * - * @throws {Exception} + * @dies {Exception} */ file(path, status_code) { if status_code != nil { diff --git a/libs/math.b b/libs/math.b index 39cebe0e..dcc77846 100644 --- a/libs/math.b +++ b/libs/math.b @@ -98,11 +98,8 @@ def factorial(n) { # implemented internally in C to leverage precision, machine instructions and speed. /** - * sin(n: number) - * - * returns a numeric value between -1 and 1, which - * represents the sine of the angle given in radians - * @return number + * Returns a numeric value between -1 and 1, which + * represents the sine of the angle given in radians. * * Example: * @@ -110,17 +107,17 @@ def factorial(n) { * %> math.sin(46) * 0.9017883476488092 * ``` + * + * @param number n + * @return number */ def sin(n) { return _math.sin(n) } /** - * cos(n: number) - * - * returns a numeric value between -1 and 1, which - * represents the cosine of the angle - * @return number + * Returns a numeric value between -1 and 1, which + * represents the cosine of the angle. * * Example: * @@ -128,17 +125,17 @@ def sin(n) { * %> math.cos(93) * 0.3174287015197017 * ``` + * + * @param number n + * @return number */ def cos(n) { return _math.cos(n) } /** - * tan(n: number) - * - * returns a numeric value that represents the tangent - * of the angle given - * @return number + * Returns a numeric value that represents the tangent + * of the angle given. * * Example: * @@ -146,16 +143,16 @@ def cos(n) { * %> math.tan(11.43) * -2.155225644164932 * ``` + * + * @param number n + * @return number */ def tan(n) { return _math.tan(n) } /** - * sinh(n: number) - * - * returns the hyperbolic sine (in radians) of number n - * @return number + * Returns the hyperbolic sine (in radians) of number n. * * Example: * @@ -163,16 +160,16 @@ def tan(n) { * %> math.sinh(1.4) * 1.904301501451534 * ``` + * + * @param number n + * @return number */ def sinh(n) { return _math.sinh(n) } /** - * cosh(n: number) - * - * returns the hyperbolic cosine (in radians) of number n - * @return number + * Returns the hyperbolic cosine (in radians) of number n. * * Example: * @@ -180,22 +177,25 @@ def sinh(n) { * %> math.cosh(1.91) * 3.450584592563374 * ``` + * + * @param number n + * @return number */ def cosh(n) { return _math.cosh(n) } /** - * tanh(n: number) - * - * returns the hyperbolic tangent (in radians) of number n - * @return number + * Returns the hyperbolic tangent (in radians) of number n. * * Example: * * ```blade-repl * %> math.tanh(2.19) - * 0.9752591705196751 + * 0.975 + * + * @param number n + * @return number2591705196751 * ``` */ def tanh(n) { @@ -203,10 +203,9 @@ def tanh(n) { } /** - * returns a numeric value between -(π/2) and π/2 radians + * Returns a numeric value between -(π/2) and π/2 radians * for x between -1 and 1. - * If the value of x is outside this range, it returns NaN - * @return number + * If the value of x is outside this range, it returns NaN. * * Example: * @@ -214,19 +213,18 @@ def tanh(n) { * %> math.asin(0.123) * 0.123312275191872 * ``` + * + * @param number n + * @return number */ def asin(n) { return _math.asin(n) } /** - * acos(n: number) - * - * returns a numeric value between 0 and π radians for x - * between -1 and 1. - * - * @note If the value of x is outside this range, it returns NaN - * @return number + * Returns a numeric value between 0 and π radians for x + * between -1 and 1. If the value of x is outside this range, it + * returns NaN. * * Example: * @@ -234,14 +232,16 @@ def asin(n) { * %> math.acos(0.471) * 1.080372275769021 * ``` + * + * @param number n + * @return number */ def acos(n) { return _math.acos(n) } /** - * returns a numeric value between -(π/2) and π/2 radians. - * @return number + * Returns a numeric value between -(π/2) and π/2 radians. * * Example: * @@ -249,21 +249,19 @@ def acos(n) { * %> math.atan(math.Infinity) * 1.570796326794897 * ``` + * + * @param number n + * @return number */ def atan(n) { return _math.atan(n) } /** - * atan2(n: number) - * - * returns a numeric value between -π and π representing the + * Returns a numeric value between -π and π representing the * angle theta of an (x, y) point. This is the counterclockwise angle, * measured in radians, between the positive X axis, and the point (x, y). * - * @note the arguments to this function pass the y-coordinate first and the x-coordinate second - * @return number - * * Example: * * ```blade-repl @@ -274,16 +272,17 @@ def atan(n) { * %> math.atan2(-1.5, 2.4) * -0.5585993153435624 * ``` + * + * @note the arguments to this function pass the y-coordinate first and the x-coordinate second. + * @param number n + * @return number */ def atan2(x, y) { return _math.atan2(x, y) } /** - * asinh(n: number) - * - * returns the hyperbolic arcsine (in radians) of number n - * @return number + * Returns the hyperbolic arcsine (in radians) of number n. * * Example: * @@ -291,16 +290,16 @@ def atan2(x, y) { * %> math.asinh(3.42) * 1.943507380182802 * ``` + * + * @param number n + * @return number */ def asinh(n) { return _math.asinh(n) } /** - * acosh(n: number) - * - * returns the hyperbolic arccosine (in radians) of number n - * @return number + * Returns the hyperbolic arccosine (in radians) of number n. * * Example: * @@ -308,16 +307,16 @@ def asinh(n) { * %> math.acosh(1.21) * 0.637237379754108 * ``` + * + * @param number n + * @return number */ def acosh(n) { return _math.acosh(n) } /** - * atanh(n: number) - * - * returns the hyperbolic arctangent (in radians) of number n - * @return number + * Returns the hyperbolic arctangent (in radians) of number n. * * Example: * @@ -325,19 +324,18 @@ def acosh(n) { * %> math.atanh(0.11) * 0.1104469157900971 * ``` + * + * @param number n + * @return number */ def atanh(n) { return _math.atanh(n) } /** - * exp(n: number) - * - * returns e ** x, where x is the argument, and e is Euler's + * Returns e ** x, where x is the argument, and e is Euler's * number (also known as Napier's constant), the base of the - * natural logarithms - * - * @return number + * natural logarithms. * * Example: * @@ -345,18 +343,17 @@ def atanh(n) { * %> math.exp(4) * 54.59815003314424 * ``` + * + * @param number n + * @return number */ def exp(n) { return _math.exp(n) } /** - * expm1(n: number) - * - * returns (e ** x) - 1, where x is the argument, and e the base of - * the natural logarithms - * - * @return number + * Returns (e ** x) - 1, where x is the argument, and e the base of + * the natural logarithms. * * Example: * @@ -364,16 +361,16 @@ def exp(n) { * %> math.expm1(1) * 1.718281828459045 * ``` + * + * @param number n + * @return number */ def expm1(n) { return _math.expm1(n) } /** - * ceil(n: number) - * - * returns number n rounded up to the next largest integer - * @return number + * Returns number n rounded up to the next largest integer. * * Example: * @@ -383,16 +380,16 @@ def expm1(n) { * %> math.ceil(1.01) * 2 * ``` + * + * @param number n + * @return number */ def ceil(n) { return _math.ceil(n) } /** - * round(n: number) - * - * returns the value of a number rounded to the nearest integer - * @return number + * Returns the value of a number rounded to the nearest integer. * * Example: * @@ -402,18 +399,16 @@ def ceil(n) { * %> math.round(103.49) * 103 * ``` + * + * @param number n + * @return number */ def round(n) { return _math.round(n) } /** - * log(n: number) - * - * returns the natural logarithm (base e) of a number (mathematical ln(x)) - * @note If the value of x is 0, the return value is always -inf - * @note If the value of x is negative, the return value is always NaN - * @return number + * Returns the natural logarithm (base e) of a number (mathematical ln(x)). * * Example: * @@ -421,17 +416,19 @@ def round(n) { * %> math.log(45) * 3.80666248977032 * ``` + * + * @note If the value of x is 0, the return value is always -inf. + * @note If the value of x is negative, the return value is always NaN. + * @param number n + * @return number */ def log(n) { return _math.log(n) } /** - * log2(n: number) - * - * returns the base 2 logarithm of the given number. + * Returns the base 2 logarithm of the given number. * If the number is negative, NaN is returned - * @return number * * Example: * @@ -439,17 +436,17 @@ def log(n) { * %> math.log2(45) * 5.491853096329675 * ``` + * + * @param number n + * @return number */ def log2(n) { return _math.log2(n) } /** - * log10(n: number) - * - * returns the base 10 logarithm of the given number. - * If the number is negative, NaN is returned - * @return number + * Returns the base 10 logarithm of the given number. + * If the number is negative, NaN is returned. * * Example: * @@ -457,14 +454,15 @@ def log2(n) { * %> math.log10(45) * 1.653212513775344 * ``` + * + * @param number n + * @return number */ def log10(n) { return _math.log10(n) } /** - * log1p(n: number) - * * For very small values of x, adding 1 can reduce or eliminate precision. * The double floats used in JS give you about 15 digits of precision. * 1 + 1e-15 = 1.000000000000001, but 1 + 1e-16 = 1.000000000000000 and therefore @@ -483,7 +481,6 @@ def log10(n) { * * returns the natural logarithm (base e) of 1 + a number * If the value of x is less than -1, the return value is always NaN. - * @return number * * Example: * @@ -491,16 +488,16 @@ def log10(n) { * %> math.log1p(45) * 3.828641396489095 * ``` + * + * @param number n + * @return number */ def log1p(n) { return _math.log1p(n) } /** - * cbrt(n: number) - * - * returns the cube root of a number n - * @return number + * Returns the cube root of a number n. * * Example: * @@ -508,6 +505,9 @@ def log1p(n) { * %> math.cbrt(64) * 4 * ``` + * + * @param number n + * @return number */ def cbrt(n) { if !is_number(n) { @@ -520,12 +520,9 @@ def cbrt(n) { } /** - * sign(n: number) - * - * returns either a positive or negative +/- 1, indicating the sign of + * Returns either a positive or negative +/- 1, indicating the sign of * a number passed into the argument. * If the number passed into sign() is 0, it will return a 0. - * @return number * * Example: * @@ -539,6 +536,9 @@ def cbrt(n) { * %> math.sign(0) * 0 * ``` + * + * @param number n + * @return number */ def sign(n) { if !is_number(n) n = to_number(n) @@ -549,11 +549,8 @@ def sign(n) { } /** - * floor(n: number) - * * A number representing the largest integer less than or * equal to the specified number - * @return number * * Example: * @@ -561,6 +558,9 @@ def sign(n) { * %> math.floor(1.92) * 1 * ``` + * + * @param number n + * @return number */ def floor(n) { return _math.floor(n) @@ -569,7 +569,9 @@ def floor(n) { /** * is_nan(n: number) * - * returns true if the given number is equal to NaN or false otherwise + * returns true if the given number is equal to NaN or false otherwise. + * + * @param number n * @return bool */ def is_nan(n) { @@ -577,11 +579,8 @@ def is_nan(n) { } /** - * is_inf(n: number) - * - * returns true if the given number is equal to Infinity or -Infinity - * or false otherwise - * @return bool + * Returns `true` if the given number is equal to Infinity or -Infinity + * or `false` otherwise. * * Example: * @@ -593,16 +592,16 @@ def is_nan(n) { * %> math.is_inf(0) * false * ``` + * + * @param number n + * @return bool */ def is_inf(n) { return n == Infinity or n == -Infinity } /** - * is_finite(n: number) - * - * return true if x is neither an Infinity nor a NaN, and false otherwise - * @return bool + * Return `true` if x is neither an Infinity nor a NaN, and `false` otherwise. * * Example: * @@ -614,16 +613,16 @@ def is_inf(n) { * %> math.is_finite(-math.Infinity) * false * ``` + * + * @param number n + * @return bool */ def is_finite(n) { return !is_inf(n) and !is_nan(n) } /** - * trunc(n: number) - * - * returns the integer part of a number by removing any fractional - * @return number + * Returns the integer part of a number by removing any fractional. * * Example: * @@ -637,6 +636,9 @@ def is_finite(n) { * %> math.trunc(-1.01) * -1 * ``` + * + * @param number n + * @return number */ def trunc(n) { if !is_number(n) { @@ -647,10 +649,7 @@ def trunc(n) { } /** - * sqrt(n: number) - * - * returns the square root of a nunmber - * @return number + * Returns the square root of a nunmber. * * Example: * @@ -658,6 +657,9 @@ def trunc(n) { * %> math.sqrt(100) * 10 * ``` + * + * @param number n + * @return number */ def sqrt(n) { if !is_number(n) { @@ -668,12 +670,9 @@ def sqrt(n) { } /** - * sum(arg: iterable) - * - * calculate the sum of all the elements in the input iterable + * Calculates the sum of all the elements in the input iterable * the default start value for the product is 1. * when the iterable is empty, it returns 1 - * @return number * * Example: * @@ -681,6 +680,9 @@ def sqrt(n) { * %> math.sum([1, 2, [3, 4, [5, 6]]]) * 21 * ``` + * + * @param iterable arg + * @return number */ def sum(arg) { if !is_iterable(arg) { @@ -702,12 +704,9 @@ def sum(arg) { } /** - * product(arg: iterable) - * - * calculate the product of all the elements in the input iterable + * Calculates the product of all the elements in the input iterable * the default start value for the product is 1. * when the iterable is empty, it returns 1 - * @return number * * Example: * @@ -715,6 +714,9 @@ def sum(arg) { * %> math.product([1, 2, [3, 4, [5, 6]]]) * 720 * ``` + * + * @param iterable arg + * @return number */ def product(arg) { if !is_iterable(arg) { @@ -737,11 +739,8 @@ def product(arg) { /** - * fraction(n: number) - * - * returns the fractional part of a number as a whole number + * Returns the fractional part of a number as a whole number * by removing any integer - * @return number * * Example: * @@ -749,6 +748,9 @@ def product(arg) { * %> math.fraction(1.92) * 92 * ``` + * + * @param number n + * @return number */ def fraction(n) { if !is_number(n) { diff --git a/libs/mime.b b/libs/mime.b index 683f4b3d..3607c837 100644 --- a/libs/mime.b +++ b/libs/mime.b @@ -16,11 +16,12 @@ * Mime format representation class. */ class MimeFormat { + /** - * MimeFormat(mimetype: string [, header: list | bytes]) - * - * @constructor + * @param string mimetype + * @param {list|bytes|nil} header * @note only the first 16 bytes of a file header will be used. + * @constructor */ MimeFormat(mimetype, header) { if !is_string(mimetype) @@ -389,12 +390,8 @@ var _mimes = { /** - * detect_from_name(name: string) * Detects the mimetype of a file based on the * extension defined in it's path. - * - * @return string - * @note For popular files such as Jpeg and Pngs, calling this method directly is more efficient and provides a faster lookup. * * Example, * @@ -402,6 +399,10 @@ var _mimes = { * import mime * echo mime.detect_from_name('myimage.png') * ``` + * + * @note For popular files such as Jpeg and Pngs, calling this method directly is more efficient and provides a faster lookup. + * @param string name + * @return string */ def detect_from_name(name) { if !is_string(name) @@ -414,17 +415,11 @@ def detect_from_name(name) { } /** - * detect_from_header(file: file) * Detects the mimetype of a file based on it's file header. * * When multiple file formats share very similar or shadowing * file headers (such as the relationship between Zip files and Docx files), * this method will perform an extension before returning it's result. - * - * @return string - * @note For dealing with files without extension, or where the accuracy of the file extension cannot be trusted, this method provides a more efficient lookup. - * @note This method may produce slightly more rigorous results - * @note This method requires that the file must be opened in binary mode * * Example, * @@ -433,6 +428,12 @@ def detect_from_name(name) { * var f = file('my_file.ext', 'rb') * echo mime.detect_from_header(f) * ``` + * + * @note For dealing with files without extension, or where the accuracy of the file extension cannot be trusted, this method provides a more efficient lookup. + * @note This method may produce slightly more rigorous results + * @note This method requires that the file must be opened in binary mode. + * @param file file + * @return string */ def detect_from_header(file) { if !is_file(file) @@ -474,7 +475,6 @@ def detect_from_header(file) { } /** - * detect(file: file) * Performs mimetype detection on a file. * * this method is capable of detecting file mimetypes even @@ -483,9 +483,6 @@ def detect_from_header(file) { * If the file is opened in binary mode, it first attempt the more * accurate header check. If the header check returns a generic result * (i.e. application/octet-stream), it performs an extension lookup. - * - * @return string - * @note this method gives the best result, but slightly slower than a direct lookup of name or header. * * Example, * @@ -499,6 +496,10 @@ def detect_from_header(file) { * * echo mime.detect(f) * ``` + * + * @note this method gives the best result, but slightly slower than a direct lookup of name or header. + * @param file file + * @return string */ def detect(file) { if !is_file(file) @@ -515,14 +516,9 @@ def detect(file) { } /** - * extend(extension: string, format: MimeFormat) - * * Extends the mime module with support for files with the given _extension_ as * defined in the given _format_. * - * @return bool - * @note the extension MUST start with `.` - * * Example, * * ```blade-repl @@ -534,6 +530,11 @@ def detect(file) { * %> mime.detect_from_name('myfile.ppk') * 'file/ppk' * ``` + * + * @note the extension MUST start with `.` + * @param string extension + * @param MimeFormat format + * @return bool */ def extend(extension, format) { if !is_string(extension) or extension[0] != '.' diff --git a/libs/os.b b/libs/os.b index b606847e..a9d247eb 100644 --- a/libs/os.b +++ b/libs/os.b @@ -99,13 +99,9 @@ var DT_WHT = _os.DT_WHT /** - * exec(cmd: string) - * * Executes the given shell (or command prompt for Windows) commands and * returns the output as string. * - * @return string - * * Example, * * ```blade-repl @@ -114,14 +110,15 @@ var DT_WHT = _os.DT_WHT * -rw-r--r--@ 1 username staff 705 Aug 27 2021 buggy.b * -rw-r--r-- 1 username staff 197 Mar 5 05:13 myprogram.b' * ``` + * + * @param string cmd + * @return string */ def exec(cmd) { return _os.exec(cmd) } /** - * info() - * * Returns information about the current operation system and machine as a dictionary. * The returned dictionary will contain: * @@ -131,8 +128,6 @@ def exec(cmd) { * - `release`: The release level/version * - `machine`: The hardware/processor type. * - * @return dict - * * Example, * * ```blade-repl @@ -141,23 +136,23 @@ def exec(cmd) { * 21.1.0: Wed Oct 13 17:33:24 PDT 2021; root:xnu-8019.41.5~1/RELEASE_ARM64_T8101, * release: 21.1.0, machine: arm64} * ``` + * + * @return dict */ def info() { return _os.info() } /** - * sleep(duration: number) - * * Causes the current thread to sleep for the specified number of seconds. + * + * @param number duration */ def sleep(duration) { _os.sleep(duration) } /** - * get_env(name: string) - * * Returns the given environment variable if exists or nil otherwise * @return string * @@ -168,16 +163,16 @@ def sleep(duration) { * %> os.get_env('ENV1') * '20' * ``` + * + * @param string name + * @return {string|nil} */ def get_env(name) { return _os.getenv(name) } /** - * set_env(name: string, value: string, overwrite: bool = true) - * * Sets the named environment variable to the given value. - * @return string * * Example, * @@ -203,6 +198,10 @@ def get_env(name) { * ``` * * @note Environment variables set will not persist after application exists. + * @param string name + * @param string value + * @param bool? overwrite: Default value is `false`. + * @return string */ def set_env(name, value, overwrite) { if overwrite == nil overwrite = false @@ -210,13 +209,14 @@ def set_env(name, value, overwrite) { } /** - * create_dir(path: string, [permission: number = 0c777 [, recursive: boolean = true]]) - * * Creates the given directory with the specified permission and optionaly * add new files into it if any is given. * * @note if the directory already exists, it returns `false` otherwise, it returns `true`. * @note permission should be given as octal number. + * @param string path + * @param number? permission: Default value is `0c777` + * @param bool? recursive: Default value is `true`. * @return boolean */ def create_dir(path, permission, recursive) { @@ -250,8 +250,6 @@ def create_dir(path, permission, recursive) { } /** - * read_dir(path: string) - * * Scans the given directory and returns a list of all matched files * @return list[string] * @@ -264,27 +262,30 @@ def create_dir(path, permission, recursive) { * * @note `.` indicates current directory and can be used as argument to _os.path_ as well. * @note `..` indicates parent directory and can be used as argument to _os.path_ as well. + * @param string path + * @return List[string] */ def read_dir(path) { return _os.readdir(path) } /** - * chmod(path: string, mod: number) - * - * Changes the permission set on a directory + * Changes the permission set on a directory to the given mode. It is advisable + * to set the mode with an octal number (e.g. 0c777) as this is consistent with + * operating system values. * - * @note mod should be octal number (e.g. 0c777) + * @param string path + * @param number mode * @return boolean */ -def chmod(path, mod) { - return _os.chmod(path, mod) +def chmod(path, mode) { + return _os.chmod(path, mode) } /** - * is_dir(path: string) - * * Returns `true` if the path is a directory or `false` otherwise. + * + * @param string path * @return bool */ def is_dir(path) { @@ -292,10 +293,11 @@ def is_dir(path) { } /** - * remove_dir(path: string [, recursive: boolean = false]) - * * Deletes a non-empty directory. If recursive is `true`, non-empty directories * will have their contents deleted first. + * + * @param string path + * @param bool recursive: Default value is `false`. * @return bool */ def remove_dir(path, recursive) { @@ -309,9 +311,8 @@ def remove_dir(path, recursive) { } /** - * cwd() + * Returns the current working directory. * - * Returns the current working directory * @return string */ def cwd() { @@ -319,9 +320,9 @@ def cwd() { } /** - * change_dir(path: string) - * * Navigates the working directory into the specified path. + * + * @param string path * @return bool */ def change_dir(path) { @@ -329,9 +330,9 @@ def change_dir(path) { } /** - * exists(path: string) - * * Returns `true` if the directory exists or `false` otherwise. + * + * @param string path * @return bool */ def dir_exists(path) { @@ -339,9 +340,9 @@ def dir_exists(path) { } /** - * exit(code: number) - * * Exit the current process and quits the Blade runtime. + * + * @param number code * @return */ def exit(code) { @@ -349,11 +350,8 @@ def exit(code) { } /** - * join_paths(paths...) - * * Concatenates the given paths together into a format that is valied on the * current operating system. - * @return string * * Example, * @@ -361,6 +359,9 @@ def exit(code) { * %> os.join_paths('/home/user', 'path/to/myfile.ext') * '/home/user/path/to/myfile.ext' * ``` + * + * @param string... paths + * @return string */ def join_paths(...) { var result = '' @@ -384,10 +385,10 @@ def join_paths(...) { } /** - * real_path(path: string) + * Returns the original path to a relative path. * - * returns the original path to a relative path. - * @note if the path is a file, see `abs_path()` + * @note if the path is a file, see `abs_path()`. + * @param string path * @return string */ def real_path(path) { @@ -395,10 +396,10 @@ def real_path(path) { } /** - * abs_path(path: string) + * Returns the original path to a relative path. * - * returns the original path to a relative path. - * @note unlike real_path(), this function returns full path for a file + * @note unlike real_path(), this function returns full path for a file. + * @param string path * @return string */ def abs_path(path) { @@ -421,12 +422,12 @@ def abs_path(path) { } /** - * dir_name(path: string) - * * Returns the parent directory of the pathname pointed to by `path`. Any trailing * `/` characters are not counted as part of the directory name. If `path` is an * empty string, or contains no `/` characters, dir_name() returns the string ".", * signifying the current directory. + * + * @param string path * @return string */ def dir_name(path) { @@ -434,12 +435,12 @@ def dir_name(path) { } /** - * base_name(path: string) - * * The base_name() function returns the last component from the pathname pointed to by * `path`, deleting any trailing `/` characters. If path consists entirely of `/` * characters, the string '/' is returned. If path is an empty string, the string '.' * is returned. + * + * @param string path * @return string */ def base_name(path) { diff --git a/libs/url.b b/libs/url.b index eb19cacc..51f7980f 100644 --- a/libs/url.b +++ b/libs/url.b @@ -12,7 +12,7 @@ * * Constructing a URL is vey simple. Here is an example. * - * ### Example, + * ### Example * * ```blade-repl * %> import url diff --git a/libs/zip.b b/libs/zip.b index a4a7700d..f7350def 100644 --- a/libs/zip.b +++ b/libs/zip.b @@ -875,7 +875,7 @@ def extract(file, destination, is_zip64) { /** * Compresses the given path (file or directory) into the destination zip archive. - * @throws Exception if file could not be written of zip max size exceeded. + * @dies Exception if file could not be written of zip max size exceeded. * * > When an exception is thrown becase max size exceeded, some files could * > have already been compressed. In this case, the zip archive will should still diff --git a/packages/clib/clib/index.b b/packages/clib/clib/index.b index 2b040ad0..4df1831b 100644 --- a/packages/clib/clib/index.b +++ b/packages/clib/clib/index.b @@ -57,12 +57,12 @@ var _EXT = os.platform == 'windows' ? '.dll' : ( * class CLib provides an interface for interacting with C shared modules. */ class Clib { + var _ptr /** - * CLib([name: string]) - * - * The name should follow the same practice outlined in `load()`. + * @note The _name_ should follow the same practice outlined in `load()`. + * @param string? name * @constructor */ Clib(name) { @@ -80,13 +80,12 @@ class Clib { } /** - * load(name: string) - * * Loads a new C shared library pointed to by name. Name must be a * relative path, absolute path or the name of a system library. * If the system shared library extension is omitted in the name, * it will be automatically added except on Linux machines. - * @return CLib + * + * @param string name */ load(name) { if !is_string(name) @@ -100,8 +99,6 @@ class Clib { } /** - * close() - * * Closes the handle to the shared library. */ close() { @@ -110,9 +107,9 @@ class Clib { } /** - * function(name: string) - * * Retrieves the handle to a specific function in the shared library. + * + * @param string name * @return ptr */ function(name) { @@ -124,8 +121,6 @@ class Clib { } /** - * define(name: string, return_type: type, ...type) - * * Defines a new C function with the given name and return type. * - When there are no more argument, it is declared that the function * takes no argument. @@ -143,6 +138,11 @@ class Clib { * ```c * int myfunc(int a, void *b); * ``` + * + * @param string name + * @param {type} return_type + * @param {type...} types + * @return function */ define(name, return_type, ...) { if !is_string(name) @@ -164,9 +164,8 @@ class Clib { } /** - * get_pointer() + * Returns a pointer to the underlying module. * - * Returns a pointer to the underlying module * @return ptr */ get_pointer() { @@ -175,12 +174,12 @@ class Clib { } /** - * load(name: string) - * * Loads a new C shared library pointed to by name. Name must be a * relative path, absolute path or the name of a system library. * If the system shared library extension is omitted in the name, * it will be automatically added. + * + * @param string name * @return CLib */ def load(name) { @@ -188,9 +187,10 @@ def load(name) { } /** - * new(type: type, ...any) - * * Creates a new C value for the specified clib type with the given values. + * + * @param {type} type + * @param any... values * @return bytes */ def new(type, ...) { @@ -205,8 +205,6 @@ def new(type, ...) { } /** - * get(type: type, data: string | bytes) - * * Returns the data contained in a C type _type_ encoded in the data. * The data should either be an output of `clib.new()` or a call to a * function returning one of struct, union or array. @@ -215,7 +213,9 @@ def new(type, ...) { * automatically be returned with the values mapped to the names of the * structure elements. * - * @return list | dictionary + * @param {type} type + * @param {string|bytes} data + * @return {list|dictionary} */ def get(type, data) { # Ensure a valid and non void clib pointer. @@ -232,6 +232,9 @@ def get(type, data) { * Get the value at the given index of a pointer based * on the given CLib type. * + * @param ptr pointer + * @param {type} clib_type + * @param number index * @return any */ def get_ptr_index(pointer, type, index) { @@ -239,11 +242,13 @@ def get_ptr_index(pointer, type, index) { } /** - * get_ptr_index(pointer: ptr, type: clib_type, index: number, value: any) - * * Sets the value at the given index of a pointer based * on the given CLib type to the given value. * + * @param ptr pointer + * @param {type} clib_type + * @param number index + * @param any value * @return any */ def set_ptr_index(pointer, type, index, value) { @@ -251,8 +256,6 @@ def set_ptr_index(pointer, type, index, value) { } /** - * function_handle(handle: ptr, return_type: type, ...type) - * * Defines a new C function from an existing handle and return type. * - When there are no more argument, it is declared that the function * takes no argument. @@ -270,6 +273,11 @@ def set_ptr_index(pointer, type, index, value) { * ```c * int (*my_ptr)(int a, void *b); * ``` + * + * @param ptr handle + * @param {type} return_type + * @param {type...} arg_types + * @return function */ def function_handle(handle, return_type, ...) { if !reflect.is_ptr(handle) diff --git a/packages/clib/clib/types.b b/packages/clib/clib/types.b index 101b1005..c675e71a 100644 --- a/packages/clib/clib/types.b +++ b/packages/clib/clib/types.b @@ -184,8 +184,6 @@ var ptr = _clib.pointer /** - * struct(...type) - * * Returns a type that can be used to declare structs. * To create or read value for the struct you need to use the `new()` * and `get()` functions respectively. @@ -193,24 +191,23 @@ var ptr = _clib.pointer * function in the `struct` module respectively. * * @note This function can also be used to define a C union or array. + * @param any... type * @return type */ def struct(...) { if __args__.length() == 0 - die Exception('canot have an empty struct') + die Exception('cannot have an empty struct') for arg in __args__ { # Ensure a valid clib pointer. if !(reflect.is_ptr(arg) and to_string(arg).match('/clib/')) - die Exception('invalid type in struct delaration') + die Exception('invalid type in struct declaration') } return _clib.new_struct(__args__, []) } /** - * named_struct(types: dictionary) - * * Returns a type that can be used to declare structs based on the named * types. The function works well with the `get()` function because it * automatically assigns the name of the struct elements when getting the @@ -222,18 +219,19 @@ def struct(...) { * function in the `struct` module respectively. * * @note This function can also be used to define a C union or array. + * @param dictionary types * @return type */ def named_struct(types) { if !is_dict(types) die Exception('dictionary expected, ${typeof(types)} given') if types.length() == 0 - die Exception('canot have an empty struct') + die Exception('cannot have an empty struct') for key, value in types { # Ensure a valid clib pointer. if !(reflect.is_ptr(value) and to_string(value).match('/clib/')) - die Exception('invalid type in struct delaration') + die Exception('invalid type in struct declaration') } var items = types.to_list() diff --git a/packages/curl/curl/curl.b b/packages/curl/curl/curl.b index 1ceb6a21..e228eabb 100644 --- a/packages/curl/curl/curl.b +++ b/packages/curl/curl/curl.b @@ -8,6 +8,11 @@ import .infos { Info } * cURL Mime object for multipart-data forms and POST requests. */ class CurlMime { + + /** + * @pram {Curl} curl + * @constructor + */ CurlMime(curl) { if !instance_of(curl, Curl) die Exception('instance of Curl expected') @@ -15,9 +20,11 @@ class CurlMime { } /** - * add(name: string, value: any) - * * Adds a new mime part with the given name and value. + * + * @param string name + * @param any value + * @return bool */ add(name, value) { if !is_string(name) @@ -33,9 +40,11 @@ class CurlMime { } /** - * add_as(value: any, type: string) - * * Adds a new mime part with the given data and type. + * + * @param any value + * @param string type + * @return bool */ add_as(value, type) { if !is_string(type) @@ -51,9 +60,10 @@ class CurlMime { } /** - * add_data(data: any) - * * Adds a new mime part with the given data. + * + * @param any data + * @return bool */ add_data(data) { # This allows us to benefit from to_string decorators. @@ -64,9 +74,11 @@ class CurlMime { } /** - * add_file(name: string, file: string) - * * Adds a new mime part with the given name and file. + * + * @param string name + * @param {string|instance} value + * @return bool */ add_file(name, value) { if !is_string(name) @@ -82,9 +94,11 @@ class CurlMime { } /** - * add_mime(mime: CurlMime, type: string) - * * Adds a new mime subpart with the given mime. + * + * @param {CurlMime} mime + * @param string type + * @return bool */ add_mime(mime, type) { if !instance_of(mime, CurlMime) @@ -99,9 +113,9 @@ class CurlMime { } /** - * set_encoding(encoding: string) - * * Sets the encoding with which the mime will be transfered. + * + * @param string encoding */ set_encoding(encoding) { if !is_string(encoding) @@ -110,8 +124,6 @@ class CurlMime { } /** - * get_pointer() - * * Returns the raw pointer object to the underlying libcurl mime implementation. */ get_pointer() { @@ -126,7 +138,7 @@ class CurlMime { class CurlList { /** - * CurlList(items: list) + * @param list[string] items * @constrctor */ CurlList(items) { @@ -139,8 +151,6 @@ class CurlList { } /** - * close() - * * Close and disposes the pointer to the list */ close() { @@ -148,8 +158,6 @@ class CurlList { } /** - * get_pointer() - * * Returns the raw pointer object to the underlying libcurl list implementation. */ get_pointer() { @@ -164,7 +172,6 @@ class CurlList { class Curl { /** - * Curl() * @constructor */ Curl() { @@ -172,8 +179,6 @@ class Curl { } /** - * set_option(option: Option, value: any) - * * This function is used to tell `curl` how to behave. By setting the * appropriate options, the application can change `curl`'s behavior. * All options are set with an option followed by a parameter. That parameter @@ -191,6 +196,8 @@ class Curl { * * @note Strings passed to `curl` as arguments, must not exceed 8MB in size. * @note The order in which the options are set does not matter. + * @param {Option} option + * @param any value * @return boolean */ set_option(option, value) { @@ -205,39 +212,38 @@ class Curl { } /** - * get_info(info: Info) - * * Requests internal information from the `curl` session with this function. * Use this function AFTER performing a transfer if you want to get transfer * related data. - * @return string | number | list + * + * @param {Info} info + * @return {string|number|list} */ get_info(info) { return _curl.easy_getinfo(self._ptr, info) } /** - * escape(str: string) - * * This function converts the given input string to a URL encoded string and * returns that as a new allocated string. All input characters that are not * a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" * version (%NN where NN is a two-digit hexadecimal number). * + * @note This function does not accept a strings longer than 8MB. + * @param string str * @return string - * @note This function does not accept a strings longer than 8 MB. */ escape(str) { return _curl.easy_escape(self._ptr, str) } /** - * unescape(str: string) - * * This function converts the given URL encoded input string to a "plain * string" and returns that in an allocated memory area. All input characters * that are URL encoded (%XX where XX is a two-digit hexadecimal number) are * converted to their decoded versions. + * + * @param string str * @return string */ unescape(str) { @@ -245,8 +251,6 @@ class Curl { } /** - * send() - * * Performs the entire request in a blocking manner and returns when done, or * if it failed. It returns a dictionary containing the `headers` and `body` key. * @return dict @@ -254,14 +258,14 @@ class Curl { * > You must never call this function simultaneously from two places using * > the same instance. Let the function return first before invoking it * > another time. + * + * @return dictionary */ send() { return _curl.easy_perform(self._ptr) } /** - * reset() - * * Re-initializes the instace to the default values. This puts back the * instance to the same state as it was in when it was just created. * @@ -273,8 +277,6 @@ class Curl { } /** - * close() - * * Closes the current Curl instance. * * This might close all connections this instance has used and possibly has @@ -289,8 +291,6 @@ class Curl { } /** - * get_pointer() - * * Returns the raw pointer object to the underlying libcurl. */ get_pointer() { diff --git a/packages/curl/curl/index.b b/packages/curl/curl/index.b index 92602291..396755a5 100644 --- a/packages/curl/curl/index.b +++ b/packages/curl/curl/index.b @@ -15,12 +15,11 @@ import _curl /** * The libcurl version. + * @type string */ var version = _curl.version /** - * time(date_string: string) - * * Returns the number of seconds since the Epoch, January 1st 1970 00:00:00 in * the UTC time zone, for the date and time that the date_string parameter specifies. * @@ -91,6 +90,8 @@ var version = _curl.version * update in RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted * by RFC 1036) and ANSI C's asctime() format. These formats are the only ones RFC 7231 * says HTTP applications may use. + * + * @param string date_string * @return number * @static */ diff --git a/packages/json/json/encoder.b b/packages/json/json/encoder.b index b72ad124..d872a59e 100644 --- a/packages/json/json/encoder.b +++ b/packages/json/json/encoder.b @@ -25,10 +25,11 @@ class Encoder { var _is_list = false /** - * Encoder([compact: boolean = false, [max_depth: number = 1024]]) + * @param bool? compact: Default value is `false`. + * @param number? max_depth: Default value is `1024`. + * @note Depth starts from zero + * @note Set max_depth to `0` to disable max depth * @constructor - * @note that depth starts from zero - * @note set max_depth to `0` to disable max depth */ Encoder(compact, max_depth) { if max_depth { @@ -56,12 +57,9 @@ class Encoder { return '' } - /** - * _encode(value: any) - * - * encode helper method. - * @note this function calls the parent encode() method whenever the depth of the encoding increases - */ + + # Encode helper method. + # @note this function calls the parent encode() method whenever the depth of the encoding increases. _encode(value) { var spacing = self._item_spacing using typeof(value) { @@ -110,9 +108,10 @@ class Encoder { } /** - * encode(value: any) - * - * main encode method + * Encodes a value to it's corresponding JSON string. + * + * @param any value + * @return string */ encode(value) { diff --git a/packages/json/json/index.b b/packages/json/json/index.b index d4b08a45..f78c0264 100644 --- a/packages/json/json/index.b +++ b/packages/json/json/index.b @@ -62,15 +62,15 @@ import _json { _decode } /** - * encode(value: any [, compact: boolean = true [, max_depth: number = 1024]]) - * * JSON encodes the given value with a recursive depth up to `max_depth`. * * If _compact_ is `false`, the resulting json string will be * tightly packed. i.e. spaces will be trimmed from objects and arrays. Otherwise, * the JSON output will be pretty formatted. * - * @param max_depth is the maximum recursive depth for encoding, default = 1024. + * @param any value + * @param bool? compact: Default value is `true`. + * @param number? max_depth: is the maximum recursive depth for encoding, default = 1024. * @note pretty formatting use 2 spaces instead of tabs. * @return string */ @@ -80,12 +80,10 @@ def encode(value, compact, max_depth) { } /** - * decode(value: string [, allow_comments: boolean = true]) - * - * decodes the input JSON string into Blade objects + * Decodes the input JSON string into Blade objects * - * @param value is the string to decode - * @param allow_comments can be set to enable/disable C-style comments in json [default = true] + * @param string value: The string to decode + * @param bool? allow_comments: Can be set to enable/disable C-style comments in json [default = true] * @return object */ def decode(value, allow_comments) { @@ -94,9 +92,9 @@ def decode(value, allow_comments) { } /** - * parse(path: string) + * Parses a file containing json data. * - * parses a file containing json data. + * @param string path * @return object */ def parse(path) { diff --git a/packages/sqlite/sqlite/cursor.b b/packages/sqlite/sqlite/cursor.b index 876e1efd..b25ea29d 100644 --- a/packages/sqlite/sqlite/cursor.b +++ b/packages/sqlite/sqlite/cursor.b @@ -15,14 +15,10 @@ import _sqlite { */ class SQLite3Cursor { - /** - * the cursor item - */ + # the cursor item var _cursor - /** - * tracks if this cursor is still open or not - */ + # tracks if this cursor is still open or not var _is_closed /** @@ -65,9 +61,10 @@ class SQLite3Cursor { var columns = [] /** - * SQLite3Cursor(db: SQLite3, cursor: pointer) - * @constructor + * @param {SQLite3} db + * @param ptr cursor * @note SQLite3Cursor should NEVER be maually instantiated. + * @constructor */ SQLite3Cursor(db, cursor) { self.connection = db @@ -77,9 +74,8 @@ class SQLite3Cursor { } /** - * close() + * Closes the cursor and prevents further reading. * - * Closes the cursor and prevents further reading * @return bool */ close() { @@ -87,8 +83,6 @@ class SQLite3Cursor { } /** - * has_next() - * * Returns `true` if there are more rows in the result set not yet retrieved, * otherwise it returns `false`. * @@ -104,13 +98,13 @@ class SQLite3Cursor { } /** - * get(index: number | string) - * * Returns the value of the column matching the index in the current result set. * - * @note if index is a number, it returns the value in the column at the given index. - * @note that index must be lower than columns.length() in this case. - * @note if index is a string, it returns the value in the column with the given name. + * @note If index is a number, it returns the value in the column at the given index. + * @note Index must be lower than columns.length() in this case. + * @note If index is a string, it returns the value in the column with the given name. + * @param {number|string} index + * @return string * @throws SQLiteException if no matching column can be found. */ get(index) { diff --git a/packages/sqlite/sqlite/exception.b b/packages/sqlite/sqlite/exception.b index c7ad83a2..67fda4ad 100644 --- a/packages/sqlite/sqlite/exception.b +++ b/packages/sqlite/sqlite/exception.b @@ -4,13 +4,5 @@ /** * General Exception for SQLite */ -class SQLiteException < Exception { - /** - * SQLiteException(message: string) - * @constructor - */ - SQLiteException(message) { - parent(message) - } -} +class SQLiteException < Exception {} diff --git a/packages/sqlite/sqlite/index.b b/packages/sqlite/sqlite/index.b index 9035ce0b..6de85a67 100644 --- a/packages/sqlite/sqlite/index.b +++ b/packages/sqlite/sqlite/index.b @@ -194,10 +194,10 @@ import .sqlite3 { * } /** - * open([path: string]) - * * Returns an handle to a sqlite3 database. If _path_ is not given, * it will create an in-memory sqlite database. + * + * @param string? path * @return SQLite3 */ def open(path) { diff --git a/packages/sqlite/sqlite/sqlite3.b b/packages/sqlite/sqlite/sqlite3.b index 47a7adf4..40225151 100644 --- a/packages/sqlite/sqlite/sqlite3.b +++ b/packages/sqlite/sqlite/sqlite3.b @@ -21,19 +21,15 @@ class SQLite3 { */ var path = ':memory:' - /** - * pointer to sqlite3 C struct - */ + # pointer to sqlite3 C struct var _db - /** - * tracks the open/closed state of the sqlite - */ + # tracks the open/closed state of the sqlite var _is_open = false /** - * SQLite3(path: string) - * @note the database doesn't need to exist. + * @param string path + * @note The database doesn't need to exist. * @constructor */ SQLite3(path) { @@ -46,8 +42,6 @@ class SQLite3 { } /** - * open() - * * Opens the handle to a database file */ open() { @@ -60,10 +54,9 @@ class SQLite3 { } /** - * close() - * * Closes the handle to the database and return `true` if successfully * closed or `false` otherwise. + * * @return boolean */ close() { @@ -76,13 +69,13 @@ class SQLite3 { } /** - * exec(query: string [, params: list | dict]) - * * Executes a query string as is and returns `true` if the * query was executed or `false` otherwise. * * @note this method does not return a query result * @note this method takes optional params like `query()` (see below). + * @param string query + * @param {list|dict|nil} params * @return boolean * @throws SQLiteException if an error occured */ @@ -101,8 +94,6 @@ class SQLite3 { } /** - * last_insert_id() - * * The id of the last insert operation. * * Returns: @@ -125,8 +116,6 @@ class SQLite3 { * query(sql: string [, params: list | dict]) * * Executes and sql query and returns the result of the execution. - * @return SQLite3Cursor - * @throws SQLiteException if an error occured. * * 1. Pass a list as _params_ if you have unnamed parameterized queries. * @@ -146,6 +135,11 @@ class SQLite3 { * {':id': 1, ':name': 'James'} * ) * ``` + * + * @param string sql + * @param {list|dict|nil} params + * @return SQLite3Cursor + * @throws SQLiteException if an error occured. */ query(sql, params) { if params != nil { @@ -165,11 +159,12 @@ class SQLite3 { } /** - * fetch(sql: string [, params: list | dict]) - * * Runs an SQL query and returns the result as a list of dictionaries. * - * @note if the result is empty or the query is not a SELECT, it returns an empty list + * @note if the result is empty or the query is not a SELECT, it returns an empty list. + * @param string sql + * @param {list|dict|nil} params + * @return list[dictionary] */ fetch(sql, params) { var cursor = self.query(sql, params) diff --git a/packages/ssl/ssl.c b/packages/ssl/ssl.c index de129183..bba21f6e 100644 --- a/packages/ssl/ssl.c +++ b/packages/ssl/ssl.c @@ -25,6 +25,21 @@ DEFINE_SSL_PTR_CONSTANT(BIO_f_ssl) DEFINE_SSL_PTR_CONSTANT(BIO_s_connect) DEFINE_SSL_PTR_CONSTANT(BIO_s_accept) +// Adapted from https://en.wikibooks.org/wiki/OpenSSL/Error_handling +static char *ossl_err_as_string() { + BIO *bio = BIO_new(BIO_s_mem()); + ERR_print_errors(bio); + + char *buffer = NULL; + size_t length = BIO_get_mem_data(bio, &buffer); + char *ret = (char *)calloc(1, 1 + length); + if(ret) { + memcpy(ret, buffer, length); + } + BIO_free(bio); + return ret; +} + DECLARE_MODULE_METHOD(ssl_ctx) { ENFORCE_ARG_COUNT(ctx, 1); ENFORCE_ARG_TYPE(ctx, 0, IS_PTR); @@ -361,10 +376,10 @@ DECLARE_MODULE_METHOD(ssl_read) { int error = SSL_get_error(ssl, bytes); if(error == SSL_ERROR_WANT_READ) { continue; - } else if(error == SSL_ERROR_ZERO_RETURN) { + } else if(error == SSL_ERROR_ZERO_RETURN || error == SSL_ERROR_NONE) { break; } else { - RETURN_SSL_ERROR(error); + RETURN_SSL_ERROR(); } } diff --git a/packages/ssl/ssl.h b/packages/ssl/ssl.h index 704ca373..2128ac93 100644 --- a/packages/ssl/ssl.h +++ b/packages/ssl/ssl.h @@ -19,9 +19,8 @@ #define GET_SSL_CONSTANT(v) \ {#v, true, GET_MODULE_METHOD(ssl_const_##v)} -#define RETURN_SSL_ERROR(e) \ - char *err = ERR_error_string(e, NULL); \ - RETURN_ERROR("%s: %s", err, ERR_reason_error_string(e)) +#define RETURN_SSL_ERROR() \ + RETURN_ERROR("SSL Error: %s", ossl_err_as_string()) #include #include diff --git a/packages/ssl/ssl/bio.b b/packages/ssl/ssl/bio.b index cc188bbe..00356c40 100644 --- a/packages/ssl/ssl/bio.b +++ b/packages/ssl/ssl/bio.b @@ -8,7 +8,7 @@ import .constants var _close_opts = [constants.BIO_NOCLOSE, constants.BIO_CLOSE] /** - * SSL Binary Input/Output + * SSL Binary Input/Output implementation */ class BIO { @@ -16,9 +16,9 @@ class BIO { var _ssl /** - * BIO(method: ptr) + * @note Method must be a valid SSL BIO_* method + * @param ptr method * @constructor - * @note method must be a valid SSL BIO_* method */ BIO(method) { if !reflect.is_ptr(method) @@ -27,11 +27,11 @@ class BIO { } /** - * set_ssl(ssl: SSL [, option: int]) + * Sets the working SSL instance for this BIO. * - * sets the working SSL instance for this BIO - * @note option must be one of the BIO constants if given. - * @note default option = BIO_NOCLOSE + * @note Option must be one of the BIO constants if given. + * @param {SSL} ssl + * @param int? option: Default value is `BIO_NOCLOSE` */ set_ssl(ssl, option) { if !instance_of(ssl, SSL) @@ -46,9 +46,9 @@ class BIO { } /** - * set_conn_hostname(name: string) + * Sets the hostname for the current connected BIO socket. * - * sets the hostname for the current connected BIO socket + * @param string name */ set_conn_hostname(name) { if !is_string(name) @@ -57,9 +57,9 @@ class BIO { } /** - * set_accept_name(name: string) + * Sets the address name for the current accepted BIO socket. * - * sets the address name for the current accepted BIO socket + * @param string name */ set_accept_tname(name) { if !is_string(name) @@ -68,9 +68,9 @@ class BIO { } /** - * set_conn_address(address: string) + * Sets the address for the current connected BIO socket. * - * sets the address for the current connected BIO socket + * @param string address */ set_conn_address(address) { if !is_string(address) @@ -79,9 +79,9 @@ class BIO { } /** - * set_conn_port(port: int | string) + * Sets the port for the current connected BIO socket. * - * sets the port for the current connected BIO socket + * @param {int|string} port */ set_conn_port(port) { if is_int(port) port = '${port}' @@ -93,9 +93,9 @@ class BIO { } /** - * set_accept_port(port: int | string) + * Sets the port for the current accepted BIO socket. * - * sets the port for the current accepted BIO socket + * @param {int|string} port */ set_accept_port(port) { if is_int(port) port = '${port}' @@ -107,9 +107,9 @@ class BIO { } /** - * set_conn_family(family: int) + * Sets the socket family for the current connected BIO socket. * - * sets the socket family for the current connected BIO socket + * @param int family */ set_conn_family(family) { if !is_int(family) @@ -119,9 +119,9 @@ class BIO { } /** - * set_accept_family(family: int) + * Sets the socket family for the current accepted BIO socket. * - * sets the socket family for the current accepted BIO socket + * @param int family */ set_accept_family(family) { if !is_int(family) @@ -131,9 +131,8 @@ class BIO { } /** - * get_conn_hostname() + * Returns the hostname for the current connected BIO socket. * - * returns the hostname for the current connected BIO socket * @return string */ get_conn_hostname() { @@ -141,9 +140,8 @@ class BIO { } /** - * get_accept_name() + * Returns the hostname for the current accepted BIO socket. * - * returns the hostname for the current accepted BIO socket * @return string */ get_accept_name() { @@ -151,9 +149,8 @@ class BIO { } /** - * get_conn_address() + * Returns the address for the current connected BIO socket. * - * returns the address for the current connected BIO socket * @return string */ get_conn_address() { @@ -161,9 +158,8 @@ class BIO { } /** - * get_conn_port() + * Returns the port for the current connected BIO socket. * - * returns the port for the current connected BIO socket * @return string */ get_conn_port() { @@ -171,9 +167,8 @@ class BIO { } /** - * get_accept_port() + * Returns the port for the current accepted BIO socket. * - * returns the port for the current accepted BIO socket * @return string */ get_accept_port() { @@ -181,9 +176,8 @@ class BIO { } /** - * get_conn_family() + * Returns the family for the current connected BIO socket. * - * returns the family for the current connected BIO socket * @return int */ get_conn_family() { @@ -191,9 +185,8 @@ class BIO { } /** - * get_accept_family() + * Returns the family for the current accepted BIO socket. * - * returns the family for the current accepted BIO socket * @return int */ get_accept_family() { @@ -201,10 +194,9 @@ class BIO { } /** - * get_fd() - * - * returns the current socket file descriptor. + * Returns the current socket file descriptor. * It returns `-1` on failure or a positive integer on success. + * * @return number */ get_fd() { @@ -212,10 +204,10 @@ class BIO { } /** - * set_fd(fd: int [, opt: int]) + * Sets the socket file descriptor for this BIO * - * sets the socket file descriptor for this BIO - * @default opt = BIO_NOCLOSE + * @param int fd + * @param int? opt: Default value is `BIO_NOCLOSE` */ set_fd(fd, opt) { if !is_int(fd) @@ -225,53 +217,53 @@ class BIO { if !opt opt = constants.BIO_NOCLOSE - return _ssl.bio_set_fd(self._ptr, fd, opt) + _ssl.bio_set_fd(self._ptr, fd, opt) } /** - * set_non_blocking([b: bool]) - * - * converts the BIO into a non-blocking I/O stream if b is `true`, otherwise + * Converts the BIO into a non-blocking I/O stream if b is `true`, otherwise * converts it into a blocking stream. - * @default true + * + * @param bool? is_blocking: Default value is `true`. */ - set_non_blocking(b) { - if !b b = true + set_non_blocking(is_blocking) { + if !is_blocking is_blocking = true - if !is_bool(b) + if !is_bool(is_blocking) die Exception('boolean expected') - _ssl.set_nbio(self._ptr, b) + _ssl.set_nbio(self._ptr, is_blocking) } /** - * push(b: BIO) - * - * it appends b, which may be a single BIO or a chain of BIOs, + * It appends bio, which may be a single BIO or a chain of BIOs, * to the current BIO stack (unless the current pinter is `nil`). - * It then makes a control call on BIO b and returns it. + * It then makes a control call on BIO _bio_ and returns it. + * + * @param {BIO} bio + * @return self */ - push(b) { - if !instance_of(b, BIO) + push(bio) { + if !instance_of(bio, BIO) die Exception('instance of BIO expected') - if b { - _ssl.push(self._ptr, b.get_pointer()) + if bio { + _ssl.push(self._ptr, bio.get_pointer()) } return self } /** - * removes this BIO from any chain is is part of + * Removes this BIO from any chain is is part of */ pop() { _ssl.pop(self._ptr) } /** - * write(data: string | bytes) + * Writes data to the current I/O stream and returns the total bytes written. * - * writes data to the current I/O stream. - * @return int representing the total bytes written + * @param {string|bytes} data + * @return int */ write(data) { if !is_string(data) and !is_bytes(data) @@ -287,10 +279,9 @@ class BIO { } /** - * read([length: int]) + * Reads data off the I/O and returns it. * - * reads data off the I/O and returns it - * @default length = 1024 + * @param int? length: Default value is `1024` * @return string */ read(length) { @@ -307,37 +298,37 @@ class BIO { } /** - * should_retry() - * - * returns `true` if this BIO needs to retry its last operation. + * Returns `true` if this BIO needs to retry its last operation. * `false` otherwise. + * + * @return bool */ should_retry() { return _ssl.should_retry(self._ptr) } /** - * do_connect() + * Attempts to establish a connection to the host. * - * attempts to establish a connection to the host. + * @return int */ do_connect() { return _ssl.do_connect(self._ptr) } /** - * do_accept() + * Attempts to accept the connected socket. * - * attempts to accept the connected socket. + * @return int */ do_accept() { return _ssl.do_accept(self._ptr) } /** - * error([code: int]) + * Returns the last SSL error number. * - * returns the last SSL error number + * @param int? code * @return int */ error(code) { @@ -349,9 +340,8 @@ class BIO { } /** - * error_string([code: int]) + * Returns the last SSL error as string. * - * returns the last SSL error as string * @return string */ error_string() { @@ -360,18 +350,15 @@ class BIO { } /** - * free() - * - * frees this BIO and all associated resources + * Frees this BIO and all associated resources. */ free() { _ssl.free(self._ptr) } /** - * get_pointer() + * Returns the raw OpenSSl BIO pointer. * - * returns the raw OpenSSl BIO pointer * @return ptr */ get_pointer() { @@ -389,7 +376,6 @@ class BIO { class SSLBIO < BIO { /** - * ConnectBIO() * @constructor */ SSLBIO() { @@ -405,7 +391,6 @@ class SSLBIO < BIO { class ConnectBIO < BIO { /** - * ConnectBIO() * @constructor */ ConnectBIO() { @@ -422,7 +407,6 @@ class ConnectBIO < BIO { class AcceptedBIO < BIO { /** - * AcceptedBIO() * @constructor */ AcceptedBIO() { diff --git a/packages/ssl/ssl/context.b b/packages/ssl/ssl/context.b index 64da2411..94cd8212 100644 --- a/packages/ssl/ssl/context.b +++ b/packages/ssl/ssl/context.b @@ -9,9 +9,9 @@ import _ssl class SSLContext { /** - * SSLContext(method: ptr) + * @note Method must be a valid SSL method pointer. + * @param ptr method * @constructor - * @note method must be a valid SSL method pointer */ SSLContext(method) { if !reflect.is_ptr(method) @@ -21,11 +21,11 @@ class SSLContext { } /** - * set_verify(mode: int) + * Sets the verification flags for ctx to be the given mode. * - * sets the verification flags for ctx to be the given mode. * @note The verification of certificates can be controlled by a set of logically or'ed mode flags. * @note If the mode is SSL_VERIFY_NONE none of the other flags may be set. + * @param int mode */ set_verify(mode) { if !is_int(mode) @@ -34,9 +34,9 @@ class SSLContext { } /** - * set_verify_locations(locations: string) + * Sets the default locations for trusted CA certificates. * - * set default locations for trusted CA certificates + * @param string locations */ set_verify_locations(locations) { if !is_string(locations) @@ -45,9 +45,10 @@ class SSLContext { } /** - * load_certs(cert_file: string | file, private_key_file: string | file) + * Loads the given SSL/TLS certificate pairs for the given SSL/TLS context. * - * loads the given SSL/TLS certificate pairs for the given SSL/TLS context. + * @param {string|file} cert_file + * @param {string|file} private_key_file * @return bool */ load_certs(cert_file, private_key_file) { @@ -64,9 +65,9 @@ class SSLContext { } /** - * set_ciphers(ciphers: string) + * Sets the list of allowed ciphers. This list must be colon (:) separated. * - * sets the list of allowed ciphers. This list must be colon (:) separated. + * @param string ciphers * @return bool */ set_ciphers(ciphers) { @@ -76,18 +77,15 @@ class SSLContext { } /** - * free() - * - * frees this Context and all associated resources + * Frees this Context and all associated resources */ free() { _ssl.ctx_free(self._ptr) } /** - * get_pointer() + * Returns the raw OpenSSl SSL_CTX pointer. * - * returns the raw OpenSSl SSL_CTX pointer * @return ptr */ get_pointer() { @@ -105,7 +103,6 @@ import .constants class TLSContext < SSLContext { /** - * TLSContext() * @constructor */ TLSContext() { @@ -121,7 +118,6 @@ class TLSContext < SSLContext { class TLSClientContext < SSLContext { /** - * TLSClientContext() * @constructor */ TLSClientContext() { @@ -137,7 +133,6 @@ class TLSClientContext < SSLContext { class TLSServerContext < SSLContext { /** - * TLSServerContext() * @constructor */ TLSServerContext() { @@ -152,7 +147,6 @@ class TLSServerContext < SSLContext { class SSLv23Context < SSLContext { /** - * SSLv23Context() * @constructor */ SSLv23Context() { @@ -168,7 +162,6 @@ class SSLv23Context < SSLContext { class SSLv23ClientContext < SSLContext { /** - * TLSClientContext() * @constructor */ SSLv23ClientContext() { @@ -184,7 +177,6 @@ class SSLv23ClientContext < SSLContext { class SSLv23ServerContext < SSLContext { /** - * SSLv23ServerContext() * @constructor */ SSLv23ServerContext() { diff --git a/packages/ssl/ssl/index.b b/packages/ssl/ssl/index.b index e89d2d4a..07ce3798 100644 --- a/packages/ssl/ssl/index.b +++ b/packages/ssl/ssl/index.b @@ -14,12 +14,13 @@ import .socket { * } import .server { * } /** - * server(port: int, address: string) - * * Creates an new TLSServer instance. + * + * @param int port + * @param string? host * @return TLSServer * @throws Exception, SocketExcepion, HttpException */ -def server(port, address) { - return TLSServer(port, address) +def server(port, host) { + return TLSServer(port, host) } diff --git a/packages/ssl/ssl/server.b b/packages/ssl/ssl/server.b index 300e4e12..e617a86f 100644 --- a/packages/ssl/ssl/server.b +++ b/packages/ssl/ssl/server.b @@ -3,6 +3,7 @@ import http.request { HttpRequest } import http.response { HttpResponse } import http.exception { HttpException } +import http.server { HttpServer } import http.status import socket as so @@ -11,54 +12,16 @@ import .socket { TLSSocket } /** * TLS server + * * @printable */ -class TLSServer { - - /** - * The host address to which this server will be bound - * @default socket.IP_LOCAL (127.0.0.1) - */ - var host = so.IP_LOCAL - - /** - * The port to which this server will be bound to on the host. - */ - var port = 0 - - /** - * The working TLSSocket instance for the TLSServer. - */ - var socket - - /** - * A boolean value indicating whether to reuse socket addresses or not. - * @default true - */ - var resuse_address = true - - /** - * The timeout in milliseconds after which an attempt to read clients - * request data will be terminated. - * @default 2000 (2 seconds) - */ - var read_timeout = 2000 - - /** - * The timeout in milliseconds after which an attempt to write response data to - * clients will be terminated. - * - * If we cannot send response to a client after the stipulated time, it will be - * assumed such clients have disconnected and existing connections for that - * client will be closed and their respective sockets will be discarded. - * - * @default 2000 (2 seconds) - */ - var write_timeout = 2000 +class TLSServer < HttpServer { /** * The SSL/TLS ceritificate file that will be used be used by a secured server for * serving requests. + * + * @type string * @note do not set a value to it directly. Use `load_certs()` instead. */ var cert_file @@ -66,6 +29,8 @@ class TLSServer { /** * The SSL/TLS private key file that will be used be used by a secured server for * serving requests. + * + * @type string * @note do not set a value to it directly. Use `load_certs()` instead. */ var private_key_file @@ -73,24 +38,14 @@ class TLSServer { /** * This value controls whether the client certificate should be verified * or not. - * @boolean + * + * @type boolean */ var verify_certs = true - # status trackers. - var _is_listening = false - - var _ciphers = 'ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS' - - # event handler lists. - var _connect_listeners = [] - var _disconnect_listeners = [] - var _received_listeners = [] - var _sent_listeners = [] - var _error_listeners = [] - /** - * TLSServer(port: int [, host: string]) + * @param int port + * @param string? host * @constructor */ TLSServer(port, host) { @@ -107,9 +62,10 @@ class TLSServer { } /** - * load_certs(cert_file: string | file [, private_key_file: string | file]) + * Loads the given SSL/TLS certificate pairs for the given SSL/TLS context. * - * loads the given SSL/TLS certificate pairs for the given SSL/TLS context. + * @param {string|file} cert_file + * @param {string|file|nil} private_key_file * @return bool */ load_certs(cert_file, private_key_file) { @@ -129,152 +85,6 @@ class TLSServer { } /** - * close() - * - * stops the server - */ - close() { - self._is_listening = false - if !self.socket.is_closed - self.socket.close() - self.socket.get_context().free() # close the TLS socket context. - } - - /** - * on_connect(fn: function) - * - * Adds a function to be called when a new client connects. - * @note Function _fn_ MUST accept at one parameter which will be passed the client TLSSocket object. - * @note multiple `on_connect()` may be set on a single instance. - */ - on_connect(fn) { - self._connect_listeners.append(fn) - } - - /** - * on_disconnect(fn: function) - * - * Adds a function to be called when a new client disconnects. - * @note Function _fn_ MUST accept at one parameter which will be passed the client information. - * @note multiple `on_disconnect()` may be set on a single instance. - */ - on_disconnect(fn) { - self._disconnect_listeners.append(fn) - } - - /** - * on_receive(fn: function) - * - * Adds a function to be called when the server receives a message from a client. - * - * > Function _fn_ MUST accept TWO parameters. First parameter will accept the HttpRequest - * > object and the second will accept the HttpResponse object. - * - * @note multiple `on_receive()` may be set on a single instance. - */ - on_receive(fn) { - self._received_listeners.append(fn) - } - - /** - * on_reply(fn: function) - * - * Adds a function to be called when the server sends a reply to a client. - * - * > Function _fn_ MUST accept one parameter which will be passed the HttpResponse object. - * - * @note multiple `on_sent()` may be set on a single instance. - */ - on_reply(fn) { - self._sent_listeners.append(fn) - } - - /** - * on_error(fn: function) - * - * Adds a function to be called when the server encounters an error with a client. - * - * > Function _fn_ MUST accept two parameters. The first argument will be passed the - * > `Exception` object and the second will be passed the client `TLSSocket` object. - * - * @note multiple `on_error()` may be set on a single instance. - */ - on_error(fn) { - self._error_listeners.append(fn) - } - - _get_response_header_string(headers, cookies) { - var result - for x, y in headers { - result += '${x}: ${y}\r\n' - } - for x in cookies { - result += 'Set-Cookie: ${x}\r\n' - } - return result - } - - _process_received(message, client) { - if !message or !client or !client.is_connected return - - var request = HttpRequest(), - response = HttpResponse() - - if !request.parse(message, client) - response.status = status.BAD_REQUEST - - var feedback = bytes(0) - - # If we have an error in the request message itself, we don't even want to - # forward processing to callers. - # This is a server level error and should terminate immediately. - if response.status == status.OK { - - # call the received listeners on the request object. - self._received_listeners.each(@( fn, _ ) { - fn(request, response) - }) - - if response.body { - feedback += 'Content-Length: ${response.body.length()}\r\n'.to_bytes() - } - } - - # clear file buffers... - if request.files { - for f in request.files { - f.content.dispose() - } - } - - var hdrs = self._get_response_header_string(response.headers, response.cookies).to_bytes() - feedback += hdrs - hdrs.dispose() - - feedback += '\r\n'.to_bytes() - feedback += response.body - - var hdrv = ('HTTP/${response.version} ${response.status} ' + - '${status.map.get(response.status, 'UNKNOWN')}\r\n').to_bytes() - feedback = hdrv + feedback - hdrv.dispose() - - if client.is_connected { - client.send(feedback) - } - - # call the reply listeners. - self._sent_listeners.each(@( fn ) { - fn(response) - }) - - feedback.dispose() - response.body.dispose() - } - - /** - * listen() - * * Binds to the instance port and host and starts listening for incoming * connection from HTTPS clients. */ @@ -284,49 +94,7 @@ class TLSServer { if !self.private_key_file die HttpException('no private key loaded for secure server') - if !self.socket.is_listening { - self.socket.set_option(so.SO_REUSEADDR, is_bool(self.resuse_address) ? self.resuse_address : true) - self.socket.bind(self.port, self.host) - self.socket.listen() - - self._is_listening = true - var client - - while self._is_listening { - - try { - client = self.socket.accept() - - # call the connect listeners. - self._connect_listeners.each(@(fn, _) { - fn(client) - }) - - if client.is_connected { - if is_number(self.read_timeout) - client.set_option(so.SO_RCVTIMEO, self.read_timeout) - if is_number(self.write_timeout) - client.set_option(so.SO_SNDTIMEO, self.write_timeout) - } - - self._process_received(client.receive(), client) - } catch Exception e { - # call the error listeners. - self._error_listeners.each(@(fn, _) { - fn(e, client) - }) - } finally { - var client_info = client.info() - - # call the disconnect listeners. - self._disconnect_listeners.each(@(fn, _) { - fn(client_info) - }) - - client.close() - } - } - } + parent.listen() } @to_string() { diff --git a/packages/ssl/ssl/socket.b b/packages/ssl/ssl/socket.b index 93d353dc..9c8f3e24 100644 --- a/packages/ssl/ssl/socket.b +++ b/packages/ssl/ssl/socket.b @@ -246,7 +246,9 @@ class TLSSocket { # if accepted <= 0 # die Exception(ssl.error(accepted)) - return TLSSocket(s, self._context, ssl) + var client = TLSSocket(s, self._context, ssl) + client.is_connected = true + return client } /** diff --git a/packages/zlib/zlib/index.b b/packages/zlib/zlib/index.b index ab3f15ef..ac09b557 100644 --- a/packages/zlib/zlib/index.b +++ b/packages/zlib/zlib/index.b @@ -47,37 +47,46 @@ import io { # version + /** - * zLib version string + * ZLib version string. + * @type number */ var version = _zlib.Z_VERSION # compression levels + /** - * no compression level + * No compression level. + * @type number */ var NO_COMPRESSION = _zlib.Z_NO_COMPRESSION /** - * best speed compression + * Best speed compression. + * @type number */ var BEST_SPEED = _zlib.Z_BEST_SPEED /** - * best compression level + * Best compression level. + * @type number */ var BEST_COMPRESSION = _zlib.Z_BEST_COMPRESSION /** - * default compression level + * Default compression level. + * @type number */ var DEFAULT_COMPRESSION = _zlib.Z_DEFAULT_COMPRESSION # compression strategy; see compress() for details + /** - * filtered compression strategy + * Filtered compression strategy. + * @type number */ var FILTERED = _zlib.Z_FILTERED @@ -87,29 +96,35 @@ var FILTERED = _zlib.Z_FILTERED var HUFFMAN_ONLY = _zlib.Z_HUFFMAN_ONLY /** - * rle compression strategy + * Rle compression strategy. + * @type number */ var RLE = _zlib.Z_RLE /** - * fixed compression strategy + * Fixed compression strategy. + * @type number */ var FIXED = _zlib.Z_FIXED /** - * default compression strategy + * Default compression strategy. + * @type number */ var DEFAULT_STRATEGY = _zlib.Z_DEFAULT_STRATEGY # others + /** - * default memory level + * Default memory level + * @type number */ var DEFAULT_MEMORY_LEVEL = 8 /** - * maximum windows bit + * Maximum windows bit. + * @type number */ var MAX_WBITS = _zlib.MAX_WBITS @@ -121,6 +136,8 @@ var MAX_WBITS = _zlib.MAX_WBITS * return the updated checksum. * * @note An Adler-32 checksum is almost as reliable as a CRC-32 but can be computed much faster. + * @param {bytes|string} data + * @param number? intial * @return number */ def adler32(data, initial) { @@ -136,10 +153,11 @@ def adler32(data, initial) { } /** - * crc32(data: bytes | string [, initial: number]) - * * Update a running CRC-32 cheksum with the bytes buf[0..len-1] and return the * updated CRC-32 checksum. + * + * @param {bytes|string} data + * @param number? intial * @return number */ def crc32(data, initial) { @@ -155,9 +173,7 @@ def crc32(data, initial) { } /** - * compress(data: bytes | string [, level: int = Z_DEFAULT_COMPRESSION [, strategy: int = Z_DEFAULT_STRATEGY [, wbits: int = MAX_WBITS [, memory_level: int = Z_DEFAULT_MEMORY_LEVEL]]]]) - * - * compress compresses as much data as possible, and stops when the input + * Compress compresses as much data as possible, and stops when the input * buffer becomes empty or the output buffer becomes full. * * - The compression `level` must be DEFAULT_COMPRESSION, or between 0 and 9: @@ -210,6 +226,11 @@ def crc32(data, initial) { * slow and reduces compression ratio; memory_level 9 uses maximum memory for * optimal speed. The default value is 8. * + * @param {bytes|string} data + * @param int? level: Default value is `DEFAULT_COMPRESSION`. + * @param int? strategy: Default value is `DEFAULT_STRATEGY`. + * @param int? wbits: Default value is `MAX_WBITS`. + * @param int? memory_level: Default value is `DEFAULT_MEMORY_LEVEL`. * @return bytes */ def compress(data, level, strategy, wbits, memory_level) { @@ -238,9 +259,7 @@ def compress(data, level, strategy, wbits, memory_level) { } /** - * uncompress(data: bytes | string [, wbits: int = MAX_WBITS]) - * - * uncompress decompresses as much data as possible, and stops when the input + * Uncompress decompresses as much data as possible, and stops when the input * buffer becomes empty or the output buffer becomes full. * * - In this implementation, uncompress() always flushes as much output as @@ -278,6 +297,9 @@ def compress(data, level, strategy, wbits, memory_level) { * * - uncompress() can uncompress either zlib-wrapped or gzip-wrapped compress data. * If the compression uses gzip-wrapper, the correct `wbits` may need to be set. + * + * @param {bytes|string} data + * @param int? wbits: Default value is `MAX_WBITS`. * @return bytes */ def uncompress(data, wbits) { @@ -293,9 +315,9 @@ def uncompress(data, wbits) { } /** - * deflate(data: bytes | string) + * Compress data using the default options for Deflate. * - * Compress data using the default options for Deflate + * @param {bytes|string} data * @return bytes */ def deflate(data) { @@ -303,9 +325,9 @@ def deflate(data) { } /** - * undeflate(data: bytes | string) + * Uncompress a deflated data using default options. * - * uncompress a deflated data using default options + * @param {bytes|string} data * @return bytes */ def undeflate(data) { @@ -313,9 +335,9 @@ def undeflate(data) { } /** - * gzip(data: bytes | string) + * Compress data using the default options for GZip. * - * Compress data using the default options for GZip + * @param {bytes|string} data * @return bytes */ def gzip(data) { @@ -323,9 +345,9 @@ def gzip(data) { } /** - * ungzip(data: bytes | string) + * Uncompress a GZipped data using default options. * - * uncompress a GZipped data using default options + * @param {bytes|string} data * @return bytes */ def ungzip(data) { @@ -340,6 +362,9 @@ class GZ { /** * GZ(path: string [, mode: string = 'rb']) + * + * @param string path + * @param string? mode: Default value is `rb`. * @see `gzopen()` * @constructor */ @@ -354,8 +379,6 @@ class GZ { } /** - * read(length: number) - * * Reads the given number of uncompressed bytes from the compressed file. If * the input file is not in gzip format, `read()` copies the given number of * bytes into the buffer directly from the file. @@ -377,6 +400,7 @@ class GZ { * length for end of file, or -1 for error. If len is too large to fit in an integer, * then nothing is read, -1 is returned. * + * @param number length * @return bytes */ read(length) { @@ -387,12 +411,11 @@ class GZ { } /** - * write(data: bytes | string) - * * Writes the given number of uncompressed bytes into the compressed file. * write returns the number of uncompressed bytes written or 0 in case of * error. * + * @param {bytes|string} data * @return number */ write(data) { @@ -404,8 +427,6 @@ class GZ { } /** - * eof() - * * Returns `true` if the end-of-file indicator has been set while reading, * `false` otherwise. Note that the end-of-file indicator is set only if the * read tried to go past the end of the input, but came up short. Therefore, @@ -425,8 +446,6 @@ class GZ { } /** - * direct() - * * Returns `true` if file is being copied directly while reading, or `false` * if file is a gzip stream being decompressed. * @@ -449,8 +468,6 @@ class GZ { } /** - * close() - * * Flushes all pending output if necessary, closes the compressed file and * deallocates the (de)compression state. Note that once file is closed, you * cannot call gzerror with file, since its structures have been deallocated. @@ -466,12 +483,12 @@ class GZ { } /** - * set_params(level: number, strategy: number) - * * Dynamically update the compression level or strategy. See the description * of `compress()` for the meaning of these parameters. Previously provided * data is flushed before the parameter change. * + * @param number level + * @param number strategy * @return bool */ set_params(level, strategy) { @@ -483,8 +500,6 @@ class GZ { } /** - * seek(offset: int [, whence: int = SEEK_SET]) - * * Sets the starting position for the next read or write on the given * compressed file. The offset represents a number of bytes in the * uncompressed data stream. The whence parameter is defined as in `io` @@ -500,6 +515,8 @@ class GZ { * particular if the file is opened for writing and the new starting position * would be before the current position. * + * @param int offset + * @param int? whence: Default value is `SEEK_SET`. * @return number */ seek(offset, whence) { @@ -513,8 +530,6 @@ class GZ { } /** - * rewind() - * * Rewinds the given file. This function is supported only for reading. * * @note `rewind()` is equivalent to `seek(0, SEEK_SET)`. @@ -525,8 +540,6 @@ class GZ { } /** - * tell() - * * Returns the starting position for the next read or write on the given * compressed file. This position represents a number of bytes in the * uncompressed data stream, and is zero when starting. @@ -539,8 +552,6 @@ class GZ { } /** - * offset() - * * Returns the current offset in the file being read or written. This offset * includes the count of bytes that precede the gzip stream, for example when * appending. When reading, the offset does not include as yet unused buffered @@ -554,8 +565,6 @@ class GZ { } /** - * clear_error() - * * Clears the error and end-of-file flags for file. This is useful for continuing * to read a gzip file that is being written concurrently. */ @@ -565,8 +574,6 @@ class GZ { } /** - * gzopen(path: string [, mode: string = 'rb']) - * * Opens a gzip (.gz) file for reading or writing. The mode parameter is as * in `file` ("rb" or "wb") but can also include a compression level ("wb9") or * a strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman-only @@ -598,6 +605,8 @@ class GZ { * memory to allocate the gzFile state, or if an invalid mode was specified (an 'r', * 'w', or 'a' was not provided, or '+' was provided). * + * @param string path + * @param string? mode: Default value is `rb`. * @return ptr */ def gzopen(path, mode) {