Expand/Shrink

decode_flags

Definition: string res = decode_flags(sequence FlagSet, atom v, string sep="+")
Description: Create a human readable string for a bit field.

FlagSet: a table of {flag,text} pairs.
v: the value to be deciphered.
sep: a separator, default "+".

Returns a string representing the bit settings of v.
pwa/p2js: Supported.
Comments: This is useful anywhere you have a bitmap field and want to show a human-readable version.
Further examples can be found in demo\arwendemo\filedump.exw

Obviously each application must define its own FlagSet(s).
The order of FlagSet determines the order things appear in the result.
If a description begins with '-', the separator(optional p3) is omitted.
A decription(s) of "" can be used to ignore/suppress specific bit settings.
The first entry in FlagSet can be eg {0,"closed"} to specify the "no bits set" meaning.
Any bits not recognised/ignored are returned as a hex value at the start.
Example 1: 
-- (these "FILE_ATTRIBUTE_XXX" flags can be found in demo\arwen\constants.e)
constant FileFlagSet = {{FILE_ATTRIBUTE_READONLY,  "R"},
                        {FILE_ATTRIBUTE_SYSTEM,    "S"},
                        {FILE_ATTRIBUTE_HIDDEN,    "H"},
                        {FILE_ATTRIBUTE_DIRECTORY, "D"}}

? decode_flags(FileFlagSet,#17,"")  -- "RSHD"
Example 2: 
constant FileFlagSet = {{FILE_ATTRIBUTE_READONLY,  "Read"},
                        {FILE_ATTRIBUTE_SYSTEM,    "System"},
                        {FILE_ATTRIBUTE_HIDDEN,    "Hidden"},
                        {FILE_ATTRIBUTE_DIRECTORY, "Directory"}}

? decode_flags(FileFlagSet,#17)     -- "Read+System+Hidden+Directory"
Example 3: 
-- Multiple bits are handled with appropriate common sense:
constant RW = {{#0003, "rw"},
                #0001, "r"},
                #0002, "w"},
                #FF00, ""}}
?decode_flags(RW,#03) -- "rw"
?decode_flags(RW,#01) -- "r"
?decode_flags(RW,#02) -- "w"
?decode_flags(RW,#102) -- "w"
-- The "rw" entry only triggers when all bits are set, whereas the
-- #FF00 triggers/ignores any bits, since length(description) is 0.
Implementation: See builtins\pdecodeflags.e (an autoinclude) for details of the actual implementation.
See also test\t71decode_flags.exw which is entirely dedicated to testing this function.