From 93a39dbd3c28db811b1c7bf0f5f8c6db08790523 Mon Sep 17 00:00:00 2001 From: micovery Date: Wed, 22 Oct 2014 01:56:51 -0700 Subject: [PATCH] update stats.sqf library with support for merge, keys, and count operations --- persistence/sock/stats.sqf | 283 +++++++++++++++++++++++++++++++++---- 1 file changed, 255 insertions(+), 28 deletions(-) diff --git a/persistence/sock/stats.sqf b/persistence/sock/stats.sqf index a13d3bc45..13840ba5b 100644 --- a/persistence/sock/stats.sqf +++ b/persistence/sock/stats.sqf @@ -87,7 +87,7 @@ stats_build_params = { * e.g. * * //set the value for "key1" in "scope1" -* stats_set("scope1", "key1", "value1"); +* ["scope1", "key1", "value1"] call stats_set; * * @param {String} _scope Name of the scope to use * @param {String} _key Name of the key to set @@ -103,7 +103,7 @@ stats_build_params = { * e.g. * * //set values for "key1", and "key2" in "scope1" - * stats_set("scope1", ["key1", "value1"], ["key2", "value2"]); + * ["scope1", ["key1", "value1"], ["key2", "value2"])] call stats_set; * * * @param {String} _scope Name of the scope to use @@ -126,7 +126,7 @@ stats_set = { * e.g. * * //push the value into the array at "key1" within "scope1" -* stats_push("scope1", "key1", "value1"); +* ["scope1", "key1", "value1"] call stats_push; * * @param {String} _scope Name of the scope to use * @param {String} _key Name of the key to push into @@ -142,7 +142,7 @@ stats_set = { * e.g. * * //push values into arrays at "key1", and "key2" within "scope1" - * stats_push("scope1", ["key1", "value1"], ["key2", "value2"]); + * ["scope1", ["key1", "value1"], ["key2", "value2"]] call stats_push; * * * @param {String} _scope Name of the scope to use @@ -163,7 +163,7 @@ stats_push = { * e.g. * * //unshift the value into the array at "key1" within "scope1" -* stats_unshift("scope1", "key1", "value1"); +* ["scope1", "key1", "value1"] call stats_unshift; * * @param {String} _scope Name of the scope to use * @param {String} _key Name of the key to unshift into @@ -179,7 +179,7 @@ stats_push = { * e.g. * * //unshift values into arrays at "key1", and "key2" within "scope1" - * stats_unshift("scope1", ["key1", "value1"], ["key2", "value2"]); + * ["scope1", ["key1", "value1"], ["key2", "value2"]] call stats_unshift; * * * @param {String} _scope Name of the scope to use @@ -194,6 +194,60 @@ stats_unshift = { (["unshift", _this] call stats_write) }; +/** +* This function merges the given {@code _value} with the existing value at the specified {@code _key}, and within the given scope {@code _scope} +* +* e.g. +* +* //merges the _hash into the existing value at "key1" +* private["_hash"]; +* _hash = [ +* ["child1", "val1"], +* ["child2", "val2"] +* ] call sock_hash; +* +* ["scope1", "key1", _hash] call stats_merge; +* +* @param {String} _scope Name of the scope to use +* @param {String} _key Name of the key to merge into +* @param {*} _value Value to merge +* +* @returns {boolean} true on success, false on failure +*/ + + +/** + * This function merges one or more values into the existing values at the specified keys within the given {@code _scope} + * + * e.g. + * + * private["_hash1", "_hash2"]; + * _hash1 = [ + * ["child1", "val1"], + * ["child2", "val2"] + * ] call sock_hash; + * + * _hash12= [ + * ["child1", "val1"], + * ["child2", "val2"] + * ] call sock_hash; + * + * //merges _hash1 into the value at "key1", and _hash2 into the value at "key2" + * ["scope1", ["key1", _hash1], ["key2", _hash2]] call stats_merge; + * + * + * @param {String} _scope Name of the scope to use + * @param {...Array} _pair Key-value pair + * @param {String} _pair[0] Name of the key to merge into + * @param {*} _pair[1] Value to merge + * + * @returns true on success, false on failure + * + */ + +stats_merge = { + (["merge", _this] call stats_write) +}; stats_write = { if (isNil "_this") exitWith {false}; @@ -238,7 +292,7 @@ stats_write = { * stats_get("scope", "key1"); * * //get the value for "key1", or use "default1" if not found -* stats_get("scope", "key1", "default1") +* ["scope", "key1", "default1"] call stats_get; * * @param {String} _scope Name of the scope to use * @param {String} _key Name of the key to set @@ -255,12 +309,12 @@ stats_write = { * e.g. * * //get the values for all keys within "scope1" -* stats_get("scope1") +* ["scope1"] call stats_get; * * //get the values for "key1", "key2", and "key3" -* stats_get("scope1", ["key1", "default1"], [key2, "default2"], ["key3"]) +* ["scope1", ["key1", "default1"], [key2, "default2"], ["key3"]] call stats_get; +* * - * @param {Strnig} _scope Name of the scope to use * @param {...Array} [_pair] One or more key-value pairs to retrieve * @param {String} [_pair[0]] Name of the key @@ -273,7 +327,7 @@ stats_write = { * * [["key1","value1"],["key2", "value2"],...] * -* On failure, returns null +* On failure, returns nil * */ @@ -289,10 +343,10 @@ stats_get = { * e.g. * * //pop the value for array at "key1" -* stats_pop("scope", "key1"); +* ["scope", "key1"] call stats_pop; * * //pop the value for array at "key1", or use "default1" if not found -* stats_pop("scope", "key1", "default1") +* ["scope", "key1", "default1"] call stats_pop; * * @param {String} _scope Name of the scope to use * @param {String} _key Name of the key to pop value off @@ -310,7 +364,7 @@ stats_get = { * * * //pop the values for arrays at "key1", "key2", and "key3" -* stats_pop("scope1", ["key1", "default1"], [key2, "default2"], ["key3"]) +* ["scope1", ["key1", "default1"], [key2, "default2"], ["key3"]] call stats_pop; * * @param {Strnig} _scope Name of the scope to use @@ -325,7 +379,7 @@ stats_get = { * * [["key1","value1"],["key2", "value2"],...] * -* On failure, returns null +* On failure, returns nil * */ @@ -340,10 +394,10 @@ stats_pop = { * e.g. * * //shift the value for array at "key1" -* stats_shift("scope", "key1"); +* ["scope", "key1"] call stats_shift; * * //shift the value for array at "key1", or use "default1" if not found -* stats_shift("scope", "key1", "default1") +* ["scope", "key1", "default1"] call stats_shift; * * @param {String} _scope Name of the scope to use * @param {String} _key Name of the key to shift value out @@ -361,9 +415,9 @@ stats_pop = { * * * //shift the values for arrays at "key1", "key2", and "key3" -* stats_shift("scope1", ["key1", "default1"], [key2, "default2"], ["key3"]) +* ["scope1", ["key1", "default1"], [key2, "default2"], ["key3"]] call stats_shift; +* * - * @param {Strnig} _scope Name of the scope to use * @param {...Array} [_pair] One or more key-value pairs to retrieve * @param {String} [_pair[0]] Name of the key to shift value out @@ -376,13 +430,159 @@ stats_pop = { * * [["key1","value1"],["key2", "value2"],...] * -* On failure, returns null +* On failure, returns nil * */ stats_shift = { (["shift", _this] call stats_read) }; +/** +* This function counts the child keys within the given {@code _scope} +* +* e.g. +* +* //count child keys at "scope1" +* ["scope"] call stats_count; +* +* +* @param {String} _scope Name of the scope to use +* +* @return +* +* The count of child keys at the specified {@code _scope} +* +*/ + +/** +* This function counts the child keys at the specified {@code _key}, within the given {@code _scope} +* +* e.g. +* +* //count child keys at "key1" +* ["scope", "key1"] call stats_count; +* +* //count the child keys at "key1", or use -1 if not found +* ["scope", "key1", -1] call stats_count; +* +* @param {String} _scope Name of the scope to use +* @param {String} _key Name of the key where child keys will be counted +* @param {*} [_default] Default value to use if {@code _key} does not exist +* @return +* +* The count of child keys at the specified {@code _key} +* +*/ + +/** +* This function counts the child keys for one or more of the specified keys, within the given {@code _scope} +* +* e.g. +* +* +* //count the child keys at "key1", "key2", and "key3" +* ["scope1", ["key1", -1], [key2, -1], ["key3", -1]] call stats_count; +* +* +* @param {Strnig} _scope Name of the scope to use +* @param {...Array} [_pair] One or more key-value pairs +* @param {String} [_pair[0]] Name of the key where child keys will be counted +* @param {*} [_pair[1]] Default value to use, if key is not found +* +* @return +* +* On success, returns array containing the key-value pairs. +* e.g. +* +* [["key1", 0],["key2", 2], ["key3", -1], ...] +* +* On failure, returns nil +* +*/ +stats_count = { + (["count", _this] call stats_read) +}; + + + +/** +* This function retrieves the names of child keys within the given {@code _scope} +* +* e.g. +* +* //retrieve the names of child keys at "scope1" +* ["scope"] call stats_keys; +* +* +* @param {String} _scope Name of the scope to use +* +* @return +* +* Array containing the names of child keys +* +* e.g. +* +* ["key1", "key2", "key3", ...] +* +* +*/ + +/** +* This function retrievs the names of child keys at the specified {@code _key}, within the given {@code _scope} +* +* e.g. +* +* //retrieve the names of child keys at "key1" +* ["scope", "key1"] call stats_keys; +* +* //retrieve the names of child keys at "key1", or use nil if not found +* ["scope", "key1", nil] call stats_keys; +* +* @param {String} _scope Name of the scope to use +* @param {String} _key Name of the key where the names of child keys will be retrieved +* @param {*} [_default] Default value to use if {@code _key} does not exist +* @return +* +* On success returns an array with the names of the child keys within specified {@code _key} +* +* e.g. +* +* [ "a", "b", "c"] +* +* On failure, or if the key is not found, returns the default value +* +*/ + +/** +* This function retrieves the names of child keys for one or more of the specified keys, within the given {@code _scope} +* +* e.g. +* +* +* //retrieve the names of child keys at "key1", "key2", and "key3" +* ["scope1", ["key1", nil], ["key2", []], ["key3", nil]] call stats_keys; +* +* +* @param {Strnig} _scope Name of the scope to use +* @param {...Array} [_pair] One or more key-value pairs +* @param {String} [_pair[0]] Name of the key where the names of chikd keys will be retreived +* @param {*} [_pair[1]] Default value to use, if key is not found +* +* @return +* +* On success, returns array containing the key-value pairs. +* e.g. +* +* [["key1", ["a", "b", "c"]],["key2", []], ["key3", nil], ...] +* +* On failure, returns nil +* +*/ + +stats_keys = { + (["keys", _this] call stats_read) +}; + stats_read = { if (isNil "_this") exitWith {}; @@ -398,26 +598,53 @@ stats_read = { def(_result); _result = [_method, _params] call sock_rpc; - //get(scope, key, default) - Expect anything - if (isSTRING(xGet(_params,1))) exitWith { + + /* For single result operations, - Expect anything + * get(scope, key, default) + * shift(scope, key default) + * pop(scope, key, default) + * count(scope) + * keys(scope) + * Expect anything as the result + */ + if (isSTRING(xGet(_params,1)) || { + ((["keys","count"] find _method) >= 0 && { undefined(xGet(_params,1))}) + }) exitWith { OR(_result,nil) }; - //get(scope) or get(scope, pair, ...) - Expect [["k", "v"],["k", "v"],...] - _result = OR(_result,false); + /* For multi result operations, + * get(scope) + * get(scope, [k,v],...) + * pop(scope, [k,v],...) + * shift(scope, [k,v],...) + * keys(scope, [k,v],...) + * count(scope, [k,v],...) + * Expect as result + * + * A code {[["k", "v"],["k", "v"],...]} for a sucessful response + * A string result might indicate an error message + * A nil result is an outright failure + */ + + + if (undefined(_result)) exitWith { + format["was expecting _result of typeName %1, but instead got nil during %2 operation", typeName {}, _method] call stats_log_severe; + nil + }; + //an error must have occurred if (isSTRING(_result)) exitWith { _result call stats_log_severe; - false + nil }; if (not(isCODE(_result))) exitWith { - format["was expecting _result of typeName %1, but instead got typeName %2", typeName {}, typeName _result] call stats_log_severe; - false + format["was expecting _result of typeName %1, but instead got typeName %2 during %3 operation", typeName {}, typeName _result, _method] call stats_log_severe; + nil }; (call _result) - }; /**