Util.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
 
/*  Util.qm Copyright 2014 - 2023 Qore Technologies, s.r.o.
 
    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/
 
// minimum Qore version
 
// do not use $ for vars, assume local var scope
 
// require type definitions everywhere
 
// enable all warnings
 
 
namespace Init {
    init();
 
};
 
namespace Util {
 
    public hashdecl UriQueryInfo {
        string method;
 
        *hash<auto> params;
 
 
        *hash<auto> path_params;
    };
 
 
     int parse_memory_size(string str, *bool use_binary);
 
 
 
     int compare_version(string lv, string rv);
 
 
 
     string normalize_dir(string path, string cwd = getcwd());
 
 
 
     string normalize_dir_unix(string path, string cwd = getcwd());
 
 
 
     string normalize_dir_windows(string path, string cwd = getcwd());
 
 
 
     string get_relative_path(string basedir, string path, string cwd = getcwd());
 
 
 
     bool absolute_path(string path);
 
 
 
     bool absolute_path_unix(string path);
 
 
 
     bool absolute_path_windows(string path);
 
 
    // private, non-exported helper function for parse_memory_size()
    int _get_size(string num, number mult);
 
 
    // private, non-exported constant hashes for scan_exp() below
    const ParenMap = (")": "(", "}": "{", "]": "[",);
    const FwdParenMap = map {$1.value: $1.key}, ParenMap.pairIterator();
 
    // private, non-exported constants for parsing
    const ET_RawString = 0;
    const ET_QuotedString = 1;
    const ET_BracketString = 2;
    const ET_CurlyBracketString = 3;
    const ET_Eq = 4;
    const ET_Comma = 5;
    const EtMap = {
        ET_RawString: "raw string",
        ET_QuotedString: "quoted string",
        ET_BracketString: "bracket expression",
        ET_CurlyBracketString: "curly bracket expression",
        ET_Eq: "=",
        ET_Comma: ",",
    };
    const Suffixes = ("th", "st", "nd", "rd", "th", "th", "th", "th", "th", "th");
 
    // private scanner for parse_to_qore_value()
    list<hash> scan_exp(string arg);
 
 
    // private, non-exported function: tries to evaluate the argument as a Qore expression/value
    hash<auto> eval_text(string arg, bool err = False);
 
 
    // private, non-exported function: tries to evaluate the argument as a Qore expression/value
    /* returns the value parsed
    */
    auto parse_to_basic_value(*string arg);
 
 
 
     auto parse_to_qore_value(string arg);
 
 
 
     string serialize_to_string(auto val);
 
 
 
     hash<UriQueryInfo> parse_uri_query(string path);
 
 
 
     string make_uri_query(hash<UriQueryInfo> h, string arg_separator = ';');
 
 
 
     string get_random_string(softint len = 15, int level = 3);
 
 
 
     string get_exception_string(hash<auto> ex);
 
 
    const StorageNames = ("Kilo", "Mega", "Giga", "Tera", "Peta", "Exa", "Zetta", "Yotta", "Bronto");
 
    const StorageAbbr = map {$1[0].lwr(): $#}, StorageNames;
 
 
     string get_byte_size(softnumber n, int decimals = 2);
 
 
 
     string get_marketing_byte_size(softnumber n, int decimals = 2);
 
 
 
     bool same(list<auto> l);
 
 
 
     list<auto> slice(list<auto> l, softlist<auto> indices);
 
 
 
     string tmp_location();
 
 
 
     bool is_int(string text, bool pure = False);
 
 
    const RE_FLOAT = ...;
 
 
 
     bool is_float(string text, bool pure = False);
 
 
    const RE_NUMBER = ...;
 
 
 
     bool is_number(string text, bool pure = False);
 
 
 
     string lpad(softstring text, int length, string padding = ' ');
 
 
 
     string rpad(softstring text, int length, string padding = ' ');
 
 
 
     string ordinal(int i);
 
 
 
     string plural(int count, string base, string singular = '', string plural = 's');
 
 
 
     string regex_escape(string text);
 
 
 
     string glob_to_regex(string pat);
 
 
 
     list<auto> flatten(softlist<auto> arg);
 
 
 
     list<int> parse_ranges(string text);
 
 
 
     list<auto> uniq(softlist<auto> arg);
 
 
 
     list<auto> zip();
 
 
 
     bool check_ip_address(string ip, bool exception = False);
 
 
 
     bool string_starts_with(string str, string substr);
 
 
 
     bool string_ends_with(string str, string substr);
 
 
    public hashdecl UrlRetrievalOptions {
        bool as_binary = False;
 
        *string default_path;
 
        *hash<auto> http_headers;
 
        *string ssh2_private_key;
 
        *string ssh2_public_key;
    };
 
 
     data get_file_from_sftp(string url, string path, *hash<UrlRetrievalOptions> options);
 
 
 
     data get_file_from_ftp(string url, string path, *hash<UrlRetrievalOptions> options);
 
 
 
     data get_file_from_http(string url, *string path, *hash<UrlRetrievalOptions> options);
 
 
 
     data get_local_file(string path, *hash<UrlRetrievalOptions> options);
 
 
 
     data get_file_from_url(string url, *hash<UrlRetrievalOptions> options);
 
 
 
     string substitute_env_vars(string str);
 
 
 
     hash<ExceptionInfo> check_exception_serializable(hash<ExceptionInfo> ex);
 
};