CustomFunctionsSuite.xml

<fmxmlsnippet type="FMObjectList"><CustomFunction id="4" functionArity="3" visible="True" parameters="dict;key;value" name="DictAfterKeyValue"><Calculation><![CDATA[// DictAfterKeyValue ( dict; key; value )
// version 1.0, Daniel A. Shockley

// Returns part of the specified dictionary that occurs after (and including) the specified key/value pair. If not found, returns empty string.

Let( [
  kvPair = DictItem( key; value)
 ; kvPos = Position( dict; kvPair; 1; 1 )  // will be 0 if not within dict
];


If( kvPos 
  ; Right( dict; Length( dict ) - kvPos + 1 ) 
  ; ""
  )

)]]></Calculation></CustomFunction><CustomFunction id="5" functionArity="2" visible="True" parameters="dict;name" name="DictContains"><Calculation><![CDATA[// DictContains( dict; name )
// version 1.1, Daniel A. Shockley

// Simple test for whether a dictionary includes a specified key.

/*
VERSION HISTORY:
1.1 - Use DictEscape instead of hard-coded Substitute within function.
*/

Let(
 pattern = "<:" & DictEscape( name ) & ":=";
 Position( dict; pattern; 1; 1 ) > 0
)]]></Calculation></CustomFunction><CustomFunction id="6" functionArity="2" visible="True" parameters="dict;name" name="DictCount"><Calculation><![CDATA[// DictCount ( dict; name )
// version 1.1, Daniel A. Shockley

// Counts number of name key-value pairs. Useful if you have a "non-standard" dictionary (a standard associative array has only ONE occurrence of a given key-value pair).


/*
VERSION HISTORY:
1.1 - Use DictEscape instead of hard-coded Substitute within function.
*/


Let(
 pattern = "<:" & DictEscape( name ) & ":=";
 PatternCount( dict; pattern )
)]]></Calculation></CustomFunction><CustomFunction id="7" functionArity="1" visible="True" parameters="input" name="DictEscape"><Calculation><![CDATA[// DictEscape ( input )
// version 1.0, SixFriedRice.com

// Escapes a string (key or value) so it can be used in a SixFriedRice.com-style dictionary.

Substitute( input; ["="; "/="]; [":"; "/:"] ; [">"; "/>"]; ["<" ; "/<"]   )]]></Calculation></CustomFunction><CustomFunction id="8" functionArity="1" visible="True" parameters="dict" name="DictFirst"><Calculation><![CDATA[// DictFirst( dict )
// version 1.2, Daniel A. Shockley

// Gets the NAME of the first key-value pair from a Dictionary object. 

/*
VERSION HISTORY:
1.2 - Reformatted to match standards.
1.1 - Properly unescapes the name of the item, since returning the escaped name is wrong. 
*/

Let( [
   startValue = "<:"
 ; endValue = ":="
 ; positionOfStartValue = Position( dict ; startValue ; 1 ; 1 )
 ; endOfStartValue = If( positionOfStartValue > 0 ; positionOfStartValue  + Length( startvalue ); -1 )
 ; beginningOfEndValue = Position( dict; endValue; endOfStartValue; 1 )
 ; found = If( beginningOfEndValue > -1 and endOfStartValue > -1 ; True; False )
 ; lengthFoundValue = beginningOfEndValue - endOfStartValue
 ; foundValue = Middle( dict; endOfStartValue ; lengthFoundValue )
];

   If( found ; DictUnescape( foundValue ) ; "" )
)]]></Calculation></CustomFunction><CustomFunction id="9" functionArity="2" visible="True" parameters="dict;name" name="DictGet"><Calculation><![CDATA[// DictGet ( dict; name )
// version 1.1, SixFriedRice.com

// Gets the specified key name's value from a SixFriedRice.com-style dictionary.

/*
VERSION HISTORY:
1.1 - Reformatted calc to fit standards. Still uses hard-coded escape/unescape so it can stand alone. 
*/


Let( [
   match ="<:" & Substitute( name ; ["="; "/="]; [":"; "/:"] ; [">"; "/>"]; ["<" ; "/<"]   ) & ":="
 ; pstart = Position( dict; match; 1; 1 )
 ; start = pstart + Length( match )
 ; end = Position( dict ; ":>"; start; 1 )
 ; len = If( end = 0; 999999999; end - start )
];

If ( pstart = 0
   ; ""
   ; Substitute( Middle( dict; start; len); ["/:"; ":"]; ["/="; "="] ; ["/>"; ">"] ; ["/<" ; "<" ] )
   )
)]]></Calculation></CustomFunction><CustomFunction id="23" functionArity="3" visible="True" parameters="dict;pairName;pairIndex" name="DictGetByKeyWithIndex"><Calculation><![CDATA[// DictGetByKeyWithIndex ( dict; pairName; pairIndex )
// version 1.1, Daniel A. Shockley

// For a given SixFriedRice.com-style dictionary that has multiple name-value pairs with the same name, return the value of the pair found at the specified index. 

/*
VERSION HISTORY:
1.1 - Reformatted calc to fit standards. 
*/



Let( [ 
   match="<:" & DictEscape( pairName ) & ":="
 ; pstart = Position( dict; match; 1; pairIndex )
 ; start = pstart + Length( match )
 ; end = Position( dict ; ":>"; start; 1)
 ; len = If( end = 0; 999999999; end - start ) 
];

If ( pstart = 0
   ; ""
   ; DictUnescape( Middle( dict; start; len ) ) 
   )
)]]></Calculation></CustomFunction><CustomFunction id="10" functionArity="2" visible="True" parameters="name;value" name="DictItem"><Calculation><![CDATA[// DictItem ( name; value )
// version 1.0, SixFriedRice.com

// Creates a name/value (aka key/value) pair for a SixFriedRice.com-style dictionary.

"<:" 
& DictEscape( name ) 
& ":=" 
& DictEscape( value ) 
& ":>"]]></Calculation></CustomFunction><CustomFunction id="11" functionArity="1" visible="True" parameters="dict" name="DictListKeys"><Calculation><![CDATA[// DictListKeys( dict )
// version 1.1, Daniel A. Shockley

// Lists all of the keys present in a dictionary object (as used by SixFriedRice.com).


/*
VERSION HISTORY:
1.1 - Reformatted calc to fit standards. 
*/

Let( [
   firstKeyName = DictFirst( dict )
 // Need to get next key so that we know whether to put in the line return (if no next, don't put in the separator)
 ; nextKeyName = If( Length( firstKeyName ) > 0; DictFirst( DictRemove( dict; firstKeyName ) ); "" )
];

If( Length( firstKeyName ) > 0
  ; firstKeyName & If( Length( nextKeyName ) = 0; ""; "¶" & DictListKeys( DictRemove( dict; firstKeyName ) ) )
  ; ""
  )

)]]></Calculation></CustomFunction><CustomFunction id="22" functionArity="2" visible="True" parameters="dict;nodePath" name="DictNode"><Calculation><![CDATA[// DictNode( dict; nodePath )
// version 1.0, Daniel A. Shockley

/* Obtains the value of a specific node from a SixFriedRice.com-style Dictionary using the specified path. Somewhat like the XPath function for XML data.


SYNTAX for the nodePath is: 
-----------------------
      KeyA/KeyB[2]/…/KeyX
-----------------------

Note that there can be an index in square brackets if there are multiple keys with same name at a level ( KeyB[2] in the example above ).
Note also that while this syntax looks like an XML XPath, it behaves differently. It selects only the first node, not all nodes with a given name, when no index is specified.

VERSION HISTORY:
1.0 - initial version.

EXAMPLE USE: 
If the some dictionary is set to the following calc: 
-----------------------
     #( "FirstName"; "Bob" ) 
   & #( "LastName"; "Smith" ) 
   &  #( "PhoneList"
         ; #( "Phone"
              ; #( "Label"; "Home" ) & #( "Value"; "212-123-4567" )
              )
       & #( "Phone"
              ; #( "Label"; "Cell" ) & #( "Value"; "212-999-9876" )
              )
       )
-----------------------
Searching for the nodePath "PhoneList/Phone[2]/Label" will return: "Cell"
-----------------------

*/

Let( [
   nodeDelim = "/"
 ; delimPos = Position( nodePath; nodeDelim; 1; 1 )
 ; firstNode = If( delimPos = 0
     ; nodePath
     ; Left( nodePath; Position( nodePath; nodeDelim; 1; 1 ) - 1 ) 
     ) 
 ; bracketOpenPos = Position( firstNode; "["; 1; PatternCount( firstNode; "[" ) )
 ; bracketClosePos = Position( firstNode; "]"; bracketOpenPos; 1 )
 ; bracketVal = 
    Case( 
       bracketOpenPos = 0 or bracketClosePos = 0; ""   // no index specified, so use first
       ;
       Middle( firstNode; bracketOpenPos+1; bracketClosePos - bracketOpenPos )
       )
 ; bracketValAsNum = GetAsNumber( bracketVal )
 ; nodeIndex = If( bracketValAsNum > 0 and bracketValAsNum = Truncate( bracketValAsNum; 0 )
       ; bracketValAsNum
       ; ""
       )
 ; firstNodeName = If( IsEmpty( nodeIndex ); firstNode; Left( firstNode; bracketOpenPos - 1 ) )

 ; nodeValue =  If( IsEmpty( nodeIndex ); DictGet( dict; firstNodeName ); DictGetByKeyWithIndex( dict; firstNodeName; nodeIndex ) )

 ; nodeFinalResult = If( PatternCount( nodePath; nodeDelim ) = 0
        ; nodeValue  // final node of the path, so just return its value
        ; DictNode( nodeValue; Right( nodePath; Length( nodePath ) - delimPos + 1 - Length( nodeDelim ) ) ) 
        )

]; 


nodeFinalResult



/* DEBUGGING CODE:
If( firstNodeName = "PhoneList"
  ; Let([
       $$DEBUG_34546576867_1 = "part 1"
     ; $$DEBUG_34546576867_2 = "dict = " & dict
     ];
     nodeFinalResult
     )
  ; nodeFinalResult
)
*/

)]]></Calculation></CustomFunction><CustomFunction id="12" functionArity="2" visible="True" parameters="dict;name" name="DictRemove"><Calculation><![CDATA[// DictRemove( dict; name )
// version 1.1, SixFriedRice.com

// Removes a name/value (aka key/value) pair from a SixFriedRice.com-style dictionary.


/*
VERSION HISTORY:
1.1 - Reformatted calc to fit standards. 
*/


Let([
   pattern = "<:" & DictEscape( name ) & ":="
 ; entry_start = Position( dict ; pattern ; 1 ; 1)
 ; entry_end = Position( dict ; ":>" ; entry_start + 1; 1)
 ; dict_beginning = If( entry_start > 0 ; Left ( dict ; entry_start - 1 ) )
 ; rest_of_dict = Middle( dict ; entry_end + 2 ; Length( dict ) )
 ; new_dict = dict_beginning & rest_of_dict
];

If( entry_start > 0 
  ; new_dict 
  ; dict 
  )

)]]></Calculation></CustomFunction><CustomFunction id="13" functionArity="3" visible="True" parameters="dict;name;newValue" name="DictReplace"><Calculation><![CDATA[// DictReplace( dict; name; newValue )
// version 1.1, SixFriedRice.com

// Replaces (the first occurrence of) a key-value pair in a SixFriedRice.com-style Dictionary with a new specified value.

/*
VERSION HISTORY:
1.1 - Changed the order - new key/value pair is before the remaining original dictionary. Reason: If the dictionary contains multiple pairs named with same key, then the one that is "replaced" will be the first one, but the old method would then put the new one at the end. Putting it FIRST in the result means it will appear at the same location as the one it is replacing if the values were extracted for all of the specified (multiple) pairs. Nothing should have relied on the previous behavior, but this new behavior is more consistent with what the function's name implies. 
*/

DictItem( name; newValue ) & DictRemove( dict; name )]]></Calculation></CustomFunction><CustomFunction id="21" functionArity="2" visible="True" parameters="dict;subLevel" name="DictToCalcString"><Calculation><![CDATA[// DictToCalcString( dict; subLevel )
// version 1.1, Daniel A. Shockley

/* Displays a SixFriedRice.com-style Dictionary as the calculation that would be needed to create it. 


VERSION HISTORY:
1.1 - fixed a bug where there would be a trailing comma.
1.0 - initial version.

EXAMPLE USE: 
If the variable $someDictionary is set to the following calc: 
-----------------------
   #( "FirstName"; "Bob" ) 
   & #( "LastName"; "Smith" ) 
   &  #( "PhoneList"
         ; #( "Phone"
              ; #( "Label"; "Home" ) & #( "Value"; "212-123-4567" )
              )
       & #( "Phone"
              ; #( "Label"; "Cell" ) & #( "Value"; "212-999-9876" )
              )
       )
-----------------------
and thus $someDictionary looks like this in the debugger:
-----------------------
<:FirstName:=Bob:><:LastName:=Smith:><:PhoneList:=/</:Phone/:/=//<//:Label//://=Home//://>//<//:Value//://=212-123-4567//://>/:/>/</:Phone/:/=//<//:Label//://=Cell//://>//<//:Value//://=212-999-9876//://>/:/>:>
-----------------------

Using DictToCalcString( $someDictionary; "" ) will give back a string that looks just like the calculation above:
-----------------------

*/

Let( [
   
   indentPattern = "   "   // character(s) to use as prefix for each level of indentation
 ; subLevel = If( IsEmpty( subLevel ); 0; subLevel )  // identifies what is current level of indent
 ; firstKey  = DictFirst ( dict ) 
]; 

If( IsEmpty( firstKey ) 
  ; ""
  ; Let( [
         rawData = DictGet( dict; firstKey )  
        // if the value of this key is ITSELF a dictionary, need to handle that and recurse: 
        ; valueAsDict = If( IsEmpty( DictFirst( rawData ) ) ; ""; "# ( " & Substitute( DictToCalcString( rawData; subLevel + 1 ); "¶"; "¶" & indentPattern ) ) 
        ; rest = DictRemove( dict ; firstKey ) 
        ];

       If( subLevel = 0; "#( " )
       & If( IsEmpty( valueAsDict )
           ; Quote( firstKey ) & "; " & Quote( rawData ) & " ) "
           ; Quote( firstKey ) & "; ¶" & indentPattern & valueAsDict & "¶" & ") "
           )
       & Case( not IsEmpty( DictFirst( rest ) ) 
          ; " ¶&¶# ( " & DictToCalcString( rest; subLevel + 1 )
          ; ""
          )
       & If( subLevel = 0; "" )
       )
  )
)]]></Calculation></CustomFunction><CustomFunction id="14" functionArity="3" visible="True" parameters="dict;keys;outdelimiter" name="DictToDelimitedList"><Calculation><![CDATA[// DictToDelimitedList( dict; keys; outdelimiter )
// version 1.1, NYHTC

// Grabs the values from a dictionary object (as used by SixFriedRice.com) that belong to the key(s) (return-delimited) listed, separating each by the delimiter specified. If there are multiple ocurrences of a key, EACH value will be returned.


/*
VERSION HISTORY:
1.1 - Reformatted calc to match standards. 
*/


Let( [
  firstKeyName = DictFirst( dict )
]; 

If( Length( firstKeyName ) = 0
  ; ""
  ; Let( [
          firstKeyIsWanted = ValueIsInList( keys; firstKeyName )
        ; restOfDict = DictRemove( dict; firstKeyName )
        ];

        Case( 
            firstKeyIsWanted
            ; AppendWithSeparator ( DictGet( dict; firstKeyName ) ; DictToDelimitedList ( restOfDict; keys; outdelimiter ) ; outdelimiter )
            ; DictToDelimitedList ( restOfDict; keys; outdelimiter )
            )
       )
  )
)]]></Calculation></CustomFunction><CustomFunction id="15" functionArity="2" visible="True" parameters="dict;subLevel" name="DictToJSON"><Calculation><![CDATA[// DictToJSON( dict; subLevel )
// version 1.1, Daniel A. Shockley

/* Displays a SixFriedRice.com-style Dictionary as JSON to make it easier to read by a human. 


VERSION HISTORY:
1.1 - fixed a bug where there would be a trailing comma.
1.0 - initial version.

EXAMPLE USE: 
If the variable $someDictionary is set to: 
-----------------------
   #( "FirstName"; "Bob" ) 
& #( "LastName"; "Smith" ) 
&  #( "PhoneList"
       ; #( "Phone"
              ; #( "Label"; "Home" ) & #( "Value"; "212-123-4567" )
              )
       & #( "Phone"
              ; #( "Label"; "Cell" ) & #( "Value"; "212-999-9876" )
              )
       )
-----------------------
and thus $someDictionary looks like this in the debugger:
-----------------------
<:FirstName:=Bob:><:LastName:=Smith:><:PhoneList:=/</:Phone/:/=//<//:Label//://=Home//://>//<//:Value//://=212-123-4567//://>/:/>/</:Phone/:/=//<//:Label//://=Cell//://>//<//:Value//://=212-999-9876//://>/:/>:>
-----------------------

Using DictToJSON( $someDictionary; "" ) will give the much-easier-to-read display:
-----------------------
{
    "FirstName": "Bob", 
    "LastName": "Smith", 
    "PhoneList": 
    {
        "Phone": 
        {
            "Label": "Home", 
            "Value": "212-123-4567"
        }, 
        "Phone": 
        {
            "Label": "Cell", 
            "Value": "212-999-9876"
        }
    }
}
-----------------------

*/

Let( [
   
   indentPattern = "    "   // character(s) to use as prefix for each level of indentation
 ; subLevel = If( IsEmpty( subLevel ); 0; subLevel )  // identifies what is current level of indent
 ; firstKey  = DictFirst ( dict ) 
]; 

If( IsEmpty( firstKey ) 
  ; ""
  ; Let( [
         rawData = DictGet( dict; firstKey ) 
        ; valueAsDict = If( IsEmpty( DictFirst( rawData ) ) ; ""; "¶" & indentPattern & Substitute( DictToJSON( rawData; subLevel + 1 ); "¶"; "¶" & indentPattern ) ) 
        ; rest = DictRemove( dict ; firstKey ) 
        ];

       If( subLevel = 0; "{¶" )
       & indentPattern 
       & If( IsEmpty( valueAsDict )
           ; Quote( firstKey ) & ": " & Quote( rawData )
           ; Quote( firstKey ) & ": ¶" & indentPattern & "{" & valueAsDict & "¶" & indentPattern & "}"
           )
       & Case( not IsEmpty( DictFirst( rest ) ) 
          ; ", ¶" & DictToJSON( rest; subLevel + 1 )
          ; ""
          )
       & If( subLevel = 0; "¶}" )
       )
  )
)]]></Calculation></CustomFunction><CustomFunction id="16" functionArity="1" visible="True" parameters="dict" name="DictToVariables"><Calculation><![CDATA[// DictToVariables( dict )
// version 1.1, Daniel A. Shockley, NYHTC, based on code examples from SixFriedRice.com blog comments.

// Converts a dictionary object (as used by SixFriedRice.com) into script variables (single $), scoped to exist within the script that calls this function. Returns a list of the variable names created.


/*
VERSION HISTORY:
1.1 - Reformatted to match standards.
*/

Let( [
   firstKeyName = DictFirst( dict )
 ; makeVar = "Let( $" 
                     & firstKeyName
                     & " = " 
                     & Quote( DictGet( dict; firstKeyName ) ) 
                     & "; \"$" 
                     & firstKeyName 
                     & "\" )"
 ; nextKeyName = If( Length( firstKeyName ) > 0; DictFirst( DictRemove( dict; firstKeyName ) ); "" )
];

If( Length( firstKeyName ) > 0
  ; Evaluate( makeVar ) 
    & If( Length( nextKeyName ) = 0
          ; ""
          ; "¶" & DictToVariables( DictRemove( dict; firstKeyName ) ) 
          )
  ; ""
  )

)]]></Calculation></CustomFunction><CustomFunction id="17" functionArity="1" visible="True" parameters="input" name="DictUnescape"><Calculation><![CDATA[// DictUnescape ( input )
// version 1.0, SixFriedRice.com

// Unescapes a name/value (aka key/value) string extracted from a SixFriedRice.com-style dictionary.

Substitute( input; ["/:"; ":"]; ["/="; "="] ; ["/>"; ">"] ; ["/<" ; "<" ] )]]></Calculation></CustomFunction></fmxmlsnippet>