flap_utils_m
FLAP utils.
Source: src/lib/flap_utils_m.f90
Dependencies
Contents
- flap_string
- count
- list_items
- list_push
- read_env
- read_line
- tokenize
- split_command_line
- write_text
- csv_split
- skill_name
- error_class
- error_exit_status
- count_substring
- to_characters
- list_count
- list_join
- replace
- replace_all
- json_string
- utf8_sequence
- json_array
- unique
- upper_case
- fish_escape
- ps_escape
- levenshtein
- suggestions
- suggestion_items
- wstrip
Variables
| Name | Type | Attributes | Description |
|---|---|---|---|
LIST_SEP | character(len=*) | parameter | Separator of the items of a stored list: v1||!||v2||!||. |
EXIT_APPLICATION | integer(kind=I4P) | parameter | Exit status of an application error. |
EXIT_USAGE | integer(kind=I4P) | parameter | Exit status of an error of the command line. |
EXIT_ENVIRONMENT | integer(kind=I4P) | parameter | Exit status of an error of a file or a variable. |
EXIT_DEFINITION | integer(kind=I4P) | parameter | Exit status of an error of the program's definitions or calls. |
Derived Types
flap_string
A string of any length. Arrays of it replace arrays of deferred-length strings in derived types: nvfortran 26.5 corrupts the heap when copying a type with a character(len=:), allocatable :: a(:) component (B33 of #125).
Components
| Name | Type | Attributes | Description |
|---|---|---|---|
s | character(len=:) | allocatable | The string. |
Interfaces
count
Overload intrinsic function count for counting substring occurences into strings.
Module procedures: count_substring
Subroutines
list_items
Return the items of a stored list, each as long as the whole list; an empty (blank) list has none.
Attributes: pure
subroutine list_items(list, items, n)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
list | character(len=*) | in | Stored list. | |
items | character(len=:) | out | allocatable | Items. |
n | integer(kind=I4P) | out | Number of items. |
Call graph
list_push
Append an item to a stored list (an unallocated list is empty).
Attributes: pure
subroutine list_push(list, item)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
list | character(len=:) | inout | allocatable | Stored list. |
item | character(len=*) | in | Item. |
Call graph
read_env
Read an environment variable, whatever the length of its value: the only environment lookup of the library.
Every lookup goes through here (step 0.D.2 of #125), so that ignore_env (F20) applies to all of them.
subroutine read_env(name, value, found, ignore)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
name | character(len=*) | in | Name of the variable. | |
value | character(len=:) | out | allocatable | Value; empty when the variable is not set. |
found | logical | out | True if the variable is set (maybe to an empty value). | |
ignore | logical | in | optional | Ignore the environment: never found (ignore_env). |
Call graph
read_line
Read a whole line of any length (non-advancing reads); a last line without line end is a line.
iostat is 0 for a line, an end-of-file code (is_iostat_end) at the end of the input, positive for a read error.
subroutine read_line(lun, line, iostat, iomsg)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
lun | integer(kind=I4P) | in | Unit. | |
line | character(len=:) | out | allocatable | Line. |
iostat | integer(kind=I4P) | out | I/O status: 0, end of file, or an error. | |
iomsg | character(len=*) | out | optional | I/O message of an error. |
Call graph
tokenize
Tokenize a string in order to parse it.
@note The dummy array containing tokens must allocatable and its character elements must have the same length of the input string. If the length of the delimiter is higher than the input string one then the output tokens array is allocated with only one element set to input string.
Attributes: pure
subroutine tokenize(strin, delimiter, toks, Nt)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
strin | character(len=*) | in | String to be tokenized. | |
delimiter | character(len=*) | in | Delimiter of tokens. | |
toks | character(len=len) | out | allocatable | Tokens. |
Nt | integer(kind=I4P) | out | optional | Number of tokens. |
Call graph
split_command_line
Split a command line string into arguments, in one pass, with shell-like quoting.
Blanks and tabs separate arguments outside quotes. Text inside '...' or "..." is taken literally (both kinds, a quote of the other kind included); a quoted part is joined to the adjacent text (ab"c d"e is abc de), and a quoted empty string is an empty argument. An unterminated quote extends to the end of the string. There are no escape characters.
Attributes: pure
subroutine split_command_line(strin, toks, Nt)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
strin | character(len=*) | in | Command line string. | |
toks | character(len=len) | out | allocatable | Arguments. |
Nt | integer(kind=I4P) | out | Number of arguments. |
Call graph
write_text
Write a text on a unit. The text is an argument, so a function building it (usage, signature) is evaluated before the write starts: nvfortran 26.5 loses the output of a write whose output list calls a function that does I/O itself.
subroutine write_text(lun, text)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
lun | integer(kind=I4P) | in | Unit. | |
text | character(len=*) | in | Text. |
Call graph
csv_split
Split one CSV record (an RFC 4180 subset), the format of list values read from the environment (F22 of #125).
The separator is ','; a field in "..." may hold commas, and "" in it is a literal "; blanks around an unquoted field are trimmed, those inside quotes kept; a quote inside an unquoted field is kept; an empty or blank record has no field. Not to be confused with tokenize, whose trailing-token behaviour the stored lists rely on.
Attributes: pure
subroutine csv_split(record, fields, nf, error)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
record | character(len=*) | in | CSV record. | |
fields | type(flap_string) | out | allocatable | Fields, with their exact length. |
nf | integer(kind=I4P) | out | Number of fields. | |
error | integer(kind=I4P) | out | 0, or 1 for an unterminated quote. |
Call graph
Functions
skill_name
Return a name valid for an Agent Skill (#129) from a program name: the base name, lower case, any other character a hyphen, no leading, trailing or repeated hyphen, at most 64 characters; 'program' if nothing is left.
Attributes: pure
Returns: character(len=:)
function skill_name(progname) result(name)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
progname | character(len=*) | in | Program name. |
Call graph
error_class
Return the class of an error code (#129), as in the table of docs/guide/errors.md: what the caller must change. '' for a status, for no error and for an unknown code.
Attributes: pure
Returns: character(len=:)
function error_class(code) result(class_name)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
code | integer(kind=I4P) | in | Error code. |
Call graph
error_exit_status
Return the exit status of an error code or a status (#129): 0 for success and for the statuses, 2 for STATUS_NO_ARGS and the usage class, 3 environment, 4 definition, 1 application. An unknown argument that the program asked to ignore (ERROR_UNKNOWN_CLAS_IGNORED) is a success.
Attributes: pure
Returns: integer(kind=I4P)
function error_exit_status(code) result(status)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
code | integer(kind=I4P) | in | Error code or status. |
Call graph
count_substring
Count the number of (non-overlapping) occurences of a substring into a string.
Attributes: elemental
Returns: integer(kind=I4P)
function count_substring(string, substring) result(No)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
string | character(len=*) | in | String. | |
substring | character(len=*) | in | Substring. |
to_characters
Return an array of strings as a character array, each element as long as the longest string.
Attributes: pure
Returns: character(len=:)
function to_characters(strings) result(chars)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
strings | type(flap_string) | in | Strings. |
Call graph
list_count
Return the number of items of a stored list; an empty (blank) list has none.
Attributes: pure
Returns: integer(kind=I4P)
function list_count(list) result(n)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
list | character(len=*) | in | Stored list. |
Call graph
list_join
Return the items of a stored list with a separator between them.
Attributes: pure
Returns: character(len=:)
function list_join(list, sep) result(joined)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
list | character(len=*) | in | Stored list. | |
sep | character(len=*) | in | Separator. |
Call graph
replace
Replace substring (only first occurrence) into a string.
Attributes: pure
Returns: character(len=:)
function replace(string, substring, restring) result(newstring)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
string | character(len=*) | in | String to be modified. | |
substring | character(len=*) | in | Substring to be replaced. | |
restring | character(len=*) | in | String to be inserted. |
replace_all
Replace substring (all occurrences) into a string.
The string is scanned once from left to right, so a replacement containing the substring is not replaced again. @note Leading and trailing white spaces are stripped out.
Attributes: pure
Returns: character(len=:)
function replace_all(string, substring, restring) result(newstring)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
string | character(len=*) | in | String to be modified. | |
substring | character(len=*) | in | Substring to be replaced. | |
restring | character(len=*) | in | String to be inserted. |
Call graph
json_string
Return a text as a JSON string, quotes included (#128): control characters are escaped, and invalid UTF-8 is replaced by U+FFFD, since command lines and environment values are bytes while a JSON document must be valid UTF-8.
Attributes: pure
Returns: character(len=:)
function json_string(text) result(quoted)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
text | character(len=*) | in | Text. |
Call graph
utf8_sequence
Return the length of the valid UTF-8 multi-byte sequence a text starts with, 0 if there is none (RFC 3629: no overlong form, no surrogate, nothing above U+10FFFF).
Attributes: pure
Returns: integer(kind=I4P)
function utf8_sequence(text) result(seq)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
text | character(len=*) | in | Text, not empty, starting with a byte above 127. |
Call graph
json_array
Return an array of strings as a JSON array, on one line.
Attributes: pure
Returns: character(len=:)
function json_array(items) result(array)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
items | type(flap_string) | in | Items. |
Call graph
unique
Reduce to one (unique) multiple (sequential) occurrences of a characters substring into a string.
For example the string ' ab-cre-cre-ab' is reduce to ' ab-cre-ab' if the substring is '-cre'. The result has the length of the input string, padded with trailing blanks.
Attributes: elemental
Returns: character(len=len)
function unique(string, substring) result(uniq)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
string | character(len=*) | in | String to be parsed. | |
substring | character(len=*) | in | Substring which multiple occurences must be reduced to one. |
Call graph
upper_case
Convert the lower case characters of a string to upper case one.
Attributes: elemental
Returns: character(len=len)
function upper_case(string)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
string | character(len=*) | in | String to be converted. |
Call graph
fish_escape
Return a text for a fish single-quoted string (F15 of #125): a backslash and a quote are escaped, new lines become blanks.
Attributes: pure
Returns: character(len=:)
function fish_escape(text) result(escaped)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
text | character(len=*) | in | Text. |
Call graph
ps_escape
Return a text for a PowerShell single-quoted string (F15 of #125): a quote is doubled, new lines become blanks.
Attributes: pure
Returns: character(len=:)
function ps_escape(text) result(escaped)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
text | character(len=*) | in | Text. |
Call graph
levenshtein
Return the Levenshtein (edit) distance of two strings: insertions, deletions and substitutions, two-row dynamic programming, O(len(a) len(b)).
Attributes: pure
Returns: integer(kind=I4P)
function levenshtein(a, b) result(d)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
a | character(len=*) | in | First string. | |
b | character(len=*) | in | Second string. |
suggestions
Return the "Did you mean" hint of an unknown token (F10 of #125): up to three candidates with similarity 1 - d/max(len) >= 0.6 (d the Levenshtein distance), most similar first (declaration order among equals), with click's wording: ' Did you mean "x"?' or ' (Did you mean one of: "x", "y"?)'; '' for none. Case-folded with case_insensitive.
Attributes: pure
Returns: character(len=:)
function suggestions(token, candidates, case_insensitive) result(hint)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
token | character(len=*) | in | Unknown token. | |
candidates | type(flap_string) | in | Candidate names. | |
case_insensitive | logical | in | Compare in any case. |
Call graph
suggestion_items
Return the candidates of the "Did you mean" hint of an unknown token (F10 of #125): up to three with similarity 1 - d/max(len) >= 0.6 (d the Levenshtein distance), most similar first (declaration order among equals).
Attributes: pure
Returns: type(flap_string)
function suggestion_items(token, candidates, case_insensitive) result(items)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
token | character(len=*) | in | Unknown token. | |
candidates | type(flap_string) | in | Candidate names. | |
case_insensitive | logical | in | Compare in any case. |
Call graph
wstrip
Strip out leading and trailing white spaces from a string.
Attributes: pure
Returns: character(len=:)
function wstrip(string) result(newstring)Arguments
| Name | Type | Intent | Attributes | Description |
|---|---|---|---|---|
string | character(len=*) | in | String to be modified. |
Call graph