Qore Util Module Reference 2.0
Loading...
Searching...
No Matches
Util.qm.dox.h
1// -*- mode: c++; indent-tabs-mode: nil -*-
3
4/* Util.qm Copyright 2014 - 2024 Qore Technologies, s.r.o.
5
6 Permission is hereby granted, free of charge, to any person obtaining a
7 copy of this software and associated documentation files (the "Software"),
8 to deal in the Software without restriction, including without limitation
9 the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 and/or sell copies of the Software, and to permit persons to whom the
11 Software is furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in
14 all copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 DEALINGS IN THE SOFTWARE.
23*/
24
25// minimum Qore version
26
27// do not use $ for vars, assume local var scope
28
29// require type definitions everywhere
30
31// enable all warnings
32
33
34
35
36
187namespace Init {
188 init();
189
190};
191
193namespace Util {
195public hashdecl UiMessageInfo {
197 string title;
198
200 string intent;
201
203 string content;
204};
205
207public hashdecl AllowedValueInfo {
210
212 *string short_desc;
213
215 auto value;
216
218 string desc;
219
221 *string intent;
222
224 *bool disabled;
225
227 *hash<auto> metadata;
228
230 *list<hash<UiMessageInfo>> messages;
231
233 *string icon;
234
236 *string image;
237};
238
240
242public hashdecl UriQueryInfo {
244
247 string method;
248
250
258 *hash<auto> params;
259
261
263 *hash<auto> path_params;
264};
265
267
275 string get_bit_string(int i, *int min_bits);
276
277
279
296 int parse_memory_size(string str, *bool use_binary);
297
298
300
313 int compare_version(string lv, string rv);
314
315
317
335 string normalize_dir(string path, string cwd = getcwd());
336
337
339
354 string normalize_dir_unix(string path, string cwd = getcwd());
355
356
358
373 string normalize_dir_windows(string path, string cwd = getcwd());
374
375
377
390 string get_relative_path(string basedir, string path, string cwd = getcwd());
391
392
394
407 bool absolute_path(string path);
408
409
411
424 bool absolute_path_unix(string path);
425
426
428
441 bool absolute_path_windows(string path);
442
443
444// private, non-exported helper function for parse_memory_size()
445int _get_size(string num, number mult);
446
447
448// private, non-exported constant hashes for scan_exp() below
449const ParenMap = ...;
450
451const FwdParenMap = map {$1.value: $1.key}, ParenMap.pairIterator();
452
453// private, non-exported constants for parsing
454const ET_RawString = 0;
455const ET_QuotedString = 1;
456const ET_BracketString = 2;
457const ET_CurlyBracketString = 3;
458const ET_Eq = 4;
459const ET_Comma = 5;
460const ET_FileRef = 6;
461const EtMap = ...;
462
463const Suffixes = ("th", "st", "nd", "rd", "th", "th", "th", "th", "th", "th");
464
465// private scanner for parse_to_qore_value()
466list<hash> scan_exp(string arg);
467
468
469// private, non-exported function: tries to evaluate the argument as a Qore expression/value
470hash<auto> eval_text(string arg, bool err = False);
471
472
473// private, non-exported function: tries to evaluate the argument as a Qore expression/value
474/* returns the value parsed
475*/
476auto parse_to_basic_value(*string arg);
477
478
479string get_string_file_data(string loc);
480
481
482binary get_binary_file_data(string loc);
483
484
485auto get_file_ref(string type, string path);
486
487
489
596 auto parse_to_qore_value(string arg);
597
598
600
618 string serialize_to_string(auto val);
619
620
622
630 hash<UriQueryInfo> parse_uri_query(string path);
631
632
634
639 string make_uri_query(hash<UriQueryInfo> h, string arg_separator = ';');
640
641
643
659 string get_random_string(softint len = 15, int level = 3);
660
661
663
667 string get_exception_string(hash<auto> ex);
668
669
671const StorageNames = ("Kilo", "Mega", "Giga", "Tera", "Peta", "Exa", "Zetta", "Yotta", "Bronto");
672
674const StorageAbbr = map {$1[0].lwr(): $#}, StorageNames;
675
677
685 string get_byte_size(softnumber n, int decimals = 2);
686
687
689
697 string get_marketing_byte_size(softnumber n, int decimals = 2);
698
699
701
712 bool same(list<auto> l);
713
714
716
726 list<auto> slice(list<auto> l, softlist<auto> indices);
727
728
730
749 string tmp_location();
750
751
753
770 bool is_int(string text, bool pure = False);
771
772
773const RE_FLOAT = ...;
774
775
777
794 bool is_float(string text, bool pure = False);
795
796
797const RE_NUMBER = ...;
798
799
801
819 bool is_number(string text, bool pure = False);
820
821
823
838 string lpad(softstring text, int length, string padding = ' ');
839
840
842
857 string rpad(softstring text, int length, string padding = ' ');
858
859
861
872 string ordinal(int i);
873
874
876
895 string plural(int count, string base, string singular = '', string plural = 's');
896
897
899
911 string regex_escape(string text);
912
913
915
927 string glob_to_regex(string pat);
928
929
931
942 list<auto> flatten(softlist<auto> arg);
943
944
946
957 list<int> parse_ranges(string text);
958
959
961
978 list<auto> uniq(softlist<auto> arg);
979
980
982
993 list<auto> zip();
994
995
997
1011 bool check_ip_address(string ip, bool exception = False);
1012
1013
1015
1020 bool string_starts_with(string str, string substr);
1021
1022
1024
1029 bool string_ends_with(string str, string substr);
1030
1031
1033public hashdecl UrlRetrievalOptions {
1035 bool as_binary = False;
1036
1039
1041 *hash<auto> http_headers;
1042
1045
1048};
1049
1051
1059 data get_file_from_sftp(string url, string path, *hash<UrlRetrievalOptions> options);
1060
1061
1063
1071 data get_file_from_ftp(string url, string path, *hash<UrlRetrievalOptions> options);
1072
1073
1075
1081 data get_file_from_http(string url, *string path, *hash<UrlRetrievalOptions> options);
1082
1083
1085
1090 data get_local_file(string path, *hash<UrlRetrievalOptions> options);
1091
1092
1094
1101 data get_file_from_url(string url, *hash<UrlRetrievalOptions> options);
1102
1103
1105
1111 string substitute_env_vars(string str);
1112
1113
1115
1121 hash<ExceptionInfo> check_exception_serializable(hash<ExceptionInfo> ex);
1122
1123};
the Util namespace contains all the objects in the Util module
Definition Util.qm.dox.h:193
string normalize_dir_windows(string path, string cwd=getcwd())
returns a normalized Windows path name (eliminates ".", "..", and "//")
string get_byte_size(softnumber n, int decimals=2)
returns a string giving a user-friendly real storage size (ie based on 1KiB = 1024 bytes) in KiB,...
data get_file_from_http(string url, *string path, *hash< UrlRetrievalOptions > options)
Retrieves file data from an HTTP URL.
hash< ExceptionInfo > check_exception_serializable(hash< ExceptionInfo > ex)
Recursively ensure that exception arguments are serializable.
list< auto > zip()
Returns a list of lists, where the i-th list contains the i-th element from each of the argument list...
data get_file_from_ftp(string url, string path, *hash< UrlRetrievalOptions > options)
Retrieves file data from an FTP URL and a path.
string tmp_location()
Returns a path for temporary files.
list< auto > slice(list< auto > l, softlist< auto > indices)
list slice implementation
string make_uri_query(hash< UriQueryInfo > h, string arg_separator=';')
returns a serialized string for a UriQueryInfo hash
string serialize_to_string(auto val)
Serializes the given value to a string that can be deserialized with parse_to_qore_value()
bool same(list< auto > l)
checks whether given list has only unique elements
data get_local_file(string path, *hash< UrlRetrievalOptions > options)
Retrieves file data from a local file path.
string get_random_string(softint len=15, int level=3)
function that returns a random string
string ordinal(int i)
Returns string with partially textual representation of ordinal integer value.
string normalize_dir_unix(string path, string cwd=getcwd())
returns a normalized UNIX path name (starting from /, eliminates ".", "..", and "//")
string normalize_dir(string path, string cwd=getcwd())
returns a platform-specific normalized path name (starting from /, eliminates ".",...
bool is_number(string text, bool pure=False)
Checks whether string represents a (true) number value.
data get_file_from_sftp(string url, string path, *hash< UrlRetrievalOptions > options)
Retrieves file data from an SFTP URL and a path.
string lpad(softstring text, int length, string padding=' ')
Returns a string left-padded to a specified length with the specified characters.
list< auto > flatten(softlist< auto > arg)
Flattens a nested list (the nesting can be to any depth).
bool is_float(string text, bool pure=False)
Checks whether string represents a (true) float value.
auto parse_to_qore_value(string arg)
tries to convert a string (such as an argument given from the command-line) to a Qore value
bool absolute_path_windows(string path)
returns True if the argument is a Windows absolute path, False if not
string get_marketing_byte_size(softnumber n, int decimals=2)
returns a string giving a user-friendly "marketing storage" size (ie based on 1KB = 1000 bytes) in KB...
hash< UriQueryInfo > parse_uri_query(string path)
parses a URI path for a arguments and a method; where the method is the part of the path before the f...
string glob_to_regex(string pat)
Translates a shell pattern to a regular expression.
string rpad(softstring text, int length, string padding=' ')
Returns a string right-padded to a specified length with the specified characters.
data get_file_from_url(string url, *hash< UrlRetrievalOptions > options)
Retrieves file data from the given URL.
string get_exception_string(hash< auto > ex)
returns a multi-line string from the exception hash argument suitable for logging or output on the co...
string substitute_env_vars(string str)
Substitutes environment variables in a string and returns the string.
bool string_starts_with(string str, string substr)
Verifies whether a string begins with specific substring.
const StorageNames
storage names (Geop, which would normally follow Bronto, is excluded as the abbreviation would be GB/...
Definition Util.qm.dox.h:671
string get_bit_string(int i, *int min_bits)
Returns a string of the bits set in an integer.
string regex_escape(string text)
Escapes (backslashes) all non-alphanumeric characters in a string.
list< int > parse_ranges(string text)
Parses a string and returns a list of integers.
int compare_version(string lv, string rv)
compares complex versions by breaking down strings into component parts
string plural(int count, string base, string singular='', string plural='s')
Returns string with number and proper singular/plural form of noun.
bool string_ends_with(string str, string substr)
Verifies whether a string ends with specific substring.
bool absolute_path_unix(string path)
returns True if the argument is a UNIX absolute path, False if not
bool check_ip_address(string ip, bool exception=False)
verifies if a string is an IPv4 or IPv6 address
bool is_int(string text, bool pure=False)
Checks whether string represents a (true) integer value.
int parse_memory_size(string str, *bool use_binary)
Returns a size in bytes from a string where "1M" = 1048576 and so forth.
list< auto > uniq(softlist< auto > arg)
Returns a duplicate-free version of the list.
string get_relative_path(string basedir, string path, string cwd=getcwd())
returns a path as a relative path from another directory
const StorageAbbr
hash of single-letter storage name abbreviations
Definition Util.qm.dox.h:674
bool absolute_path(string path)
returns True if the argument is an absolute path, False if not
Allowed value hash.
Definition Util.qm.dox.h:207
*string short_desc
A short description in plain text for the value.
Definition Util.qm.dox.h:212
auto value
The value itself.
Definition Util.qm.dox.h:215
*bool disabled
If the value is disabled.
Definition Util.qm.dox.h:224
string desc
Description for the value.
Definition Util.qm.dox.h:218
*list< hash< UiMessageInfo > > messages
Messages related to the value.
Definition Util.qm.dox.h:230
*string icon
Any icon info for the allowed value.
Definition Util.qm.dox.h:233
*string display_name
A display name for the allowed value.
Definition Util.qm.dox.h:209
*hash< auto > metadata
Any additional data about the value.
Definition Util.qm.dox.h:227
*string intent
Any UI intent associated with the value.
Definition Util.qm.dox.h:221
*string image
Any image info for the allowed value.
Definition Util.qm.dox.h:236
Message information for display to the user.
Definition Util.qm.dox.h:195
string intent
The intent of the message.
Definition Util.qm.dox.h:200
string content
The message content itself.
Definition Util.qm.dox.h:203
string title
The title of the message.
Definition Util.qm.dox.h:197
the return value of the parse_uri_query() function
Definition Util.qm.dox.h:242
*hash< auto > params
Query parameters.
Definition Util.qm.dox.h:258
string method
The URI method.
Definition Util.qm.dox.h:247
*hash< auto > path_params
Path params; only when matching a request with a REST schema.
Definition Util.qm.dox.h:263
URL retrieval options for get_file_from_url()
Definition Util.qm.dox.h:1033
*string ssh2_private_key
SSH2 private key path.
Definition Util.qm.dox.h:1044
bool as_binary
Return the file data as binary data; if False (the default), a string will be returned.
Definition Util.qm.dox.h:1035
*hash< auto > http_headers
HTTP headers to add to any HTTP GET request.
Definition Util.qm.dox.h:1041
*string default_path
The default path for files with relative paths.
Definition Util.qm.dox.h:1038
*string ssh2_public_key
SSH2 public key path.
Definition Util.qm.dox.h:1047