pcsolnX.ax.txt - eXpanded comments for phonecode solution axioms

This file is a reference for the "Phonecode in Axiomatic Language" paper.
The lines below are the paper Table 1 source lines with the addition of
4 comment blocks for each of the 4 application-specific phonecode axioms.
These comment blocks describe the utility functions and the intermediate
stack states.
  - See paper for a listing of the used utility functions.
  - See /util/...ax.txt files for the utility predicate definitions.
Note:
  _val represents an expression value of a certain type or purpose
  _val_ in a sequence represents a string of >=0 of those value expression

The lines below are the paper Table 1 source lines with the added comment
blocks: 
----+----|----+----|----+----|----+----|----+----|----+----|----+----|----+----8

! phonecode - encode phone numbers with words from a dictionary
!/
  A letter>digit map is applied to a dictionary file of words, one-per-line,
  to produce a matching of digit strings to words.  Each word has >0
  upper/lowercase letters.  Phone numbers from a text file, one-per-line,
  are encoded as a string of words whose digit strings combine to form
  the number, with single phone number digits inserted where there is no
  matching word starting with that digit (but no consecutive digits allowed).
  Phone number-code pairs are written to an output file, one-per-line:
     phnum: d|[d ]word{[ d] word}[ d]    - code words/digits (& blanks)
  Words and phone numbers can have special characters, which are ignored in
  the encoding but included in the output.  A phone number may have >=0 codes.
!\

1 (Prog: ^(e jnq rwx dsy ft am civ bku lop ghz) digs>wd ph#enc pcfmt).
        !  0  1   2   3  4  5   6   7   8   9   - digit for each uc/lc letter
  ! -> (Program _dic _ph#s _outf)  - generated Program valid exprs
!/
  The "top-level" 'Prog:' axiom generates the 'Program' valid expressions
  which hold instances of the dictionary and phonenum input files and the
  corresponding output file.  The Prog: expression gives a function
  composition with the letter>digit map expression and three application-
  specific sub-functions, each defined as a utility function composition:
    digs>wd - create digits>word map from ltr>dig map and dictionary,
    ph#enc - compute phone number encodings from digits>word map,
    pcfmt - format ph#-code pairs for output lines.
!\ 

! Supporting functions and stack states (arguments numbered 0..):
    !stk:      _dic    _ph#s     - initial stack w input text files
! ^(e jnq ... ghz)     - "constant fn" pushes ltr>dig map expr onto stack
    !stk:    (e jnq ... ghz)   _dic   _ph#s

2 (: digs>wd *sel1 x>d ltr> *&>{^ *rev).  ! get digits>word map
!/
  The digs>wd function uses the composition of the following utilities:
  *se11 - select elem 1 of the ltr>dig map symbols to get char string seq
   - sel1 on a symbol (` "jnq") gets char string "jnq" for that symbol
   - * prefix applies this function to all symbols in the ltr>dig expr seq:
    stk:   ("e" "jnq" ... "ghz")  _dic  _p#s
  x>d - number char strs 0..9, then make map of str chars to those digits:
    stk:  (('e' '0') ('j' '1') ('n' '1') ... ('z' '9'))  _dic  _p#s
  ltr> - generalizes a letter map to both cases:
    stk:  (('e' '0') .. ('z' '9') ('E' '0') .. ('Z' '9'))  _dic  _p#s
  *&>{^ - apply ltr>dig map to dic words to get word>digits map
   - >{ map-filter function applies ltr>dig map to each word seq to
     create a digit seq.  (Non-letters are ignored by the filter.)
     The ^ suffix moves the ltr>dig map from stack arg0 into the >{
     parameter position, so the "instanced" function expr (>{ _ltr>dig)
     acts on new stack arg0 _dic.
   - & prefix for a function means that the >{ input arg (a word char seq) is
     included in a sequence with the fn result (a digit seq):  (word digits)
   - * prefix means to apply (&>{ ltr>dig) to every word in the dictionary:
    stk:     _word>digits   _p#s 
  *rev - This reverses the word>digits map to get the digits>word map
     (Note that this "map" is not a true function since the same digit
     string can map to more than one word (that differ, say, by case.):
!\
    !stk:     _digs>wd   _ph#s   - digs>wd map is seq of (digstr word) pairs

3 (: ph#enc dup1 (1 1*dig?{ *eat1^ *~cnsc?dig?{) *join).   ! get codes
!/
  The ph#enc fn applies the digs>wd map to get all the codes for each ph#:
  dup1 - duplicate stack arg1 (the phone numbers), inserting the copy
     at the front of the stack:
    stk:   _p#s    _digs>wd   _p#s
  (1 ... - this higher-order form applies a function composition to the
      stack suffix starting at _digs>wd (arg1)
   1*dig?{ - filter ph# non-digits from arg1 of stk suffix (arg2 of orig stk) 
    - dig? Boolean function returns true/false if char expr is a digit
    - the filter function dig?{ keeps only the digit chars of each phone num
     stk:   _p#s    _digs>wd   _p#ds    - last stack arg is seq of digit-ph#s
   *eat1^ - apply digs>wd map to "eat" each ph# digit seq to get outp word seq
      But if a "bite" is not possible at some point, 1 ph# digit is copied
      to the output seq.  (At this point we do not check for consecutive
      digits, so some resulting code sequences may be invalid.)  All possible
      codes (for all possible bites) are produced for each ph# digit seq.)
     stk:   _p#s    _p#codesX    - [possibly invalid] codes grouped by ph# 
   *~cnsc?dig?{ - for each ph#, filter out invalid codes (w consecutive digits)
    - cnsc?Bfn? - tests if seq has consecutive elems w Boolean fn Bfn? true
      (The merged symbol is itself a Boolean function.)
      ~cnsc?dig?{ filter keeps sequences that do NOT have consecutive digits
      This filter is applied for each phone number.  (The codes are grouped
      by phone number.)
     stk:   _p#s    _p#codes     - ph# codes are now valid (still grouped)
   ) - end of (1 ...) function composition
  *join - join each phone num w its corresponding seq of (valid) codes
!\
    !stk:    (.. (_ph# _ph#codes) ..)   - each phnum and its seq of codes

4 (: pcfmt *./join cat* (*ins1 ": ") (*:2ins_ ' ') *chxcat).  !format p-c pairs
!/
  The pcfmt function formats the ph#-codes seq into outp line ph#-code pairs:
  *./join - pair each ph# with each of its codes, w pairs grouped by ph#
   - /join - join a phone# w each of its codes giving seq of ph#-code pairs
   - . prefix indicates that 2-arg /join fn get its inputs from a seq
    stk:    (.. (.. (p# p#code) ..) ..)   - ph#-code pairs grouped by ph#
  cat* - this catenates the groups of ph#-code pairs into flat seq of pairs:
    stk:    (.. (p# code) ..)     - ph#-code pairs w/o grouping
  (*ins1 ": ") - inserts param expr ": " before elem 1 of all (p# code) seqs
    stk:    (.. (p# ": " code) ..)
  (*:2ins_ ' ') - inserts param ' ' between elems of elem 2 (code) seq
   - :fn says arg0 sequence is a "sub-stack" in which to apply fn
   - 2fn says to apply fn to cur stack suffix starting at arg 2
    stk:    (.. (p# ": " codeB) ..)    - codeB is code w inserted blanks   
  *chxcat - flatten each (p# ": " codeB) char expr into a char string
    stk:    (.. "..phnum..: ..code_elem_char_str.." ..)  - seq of output lines
!\  
    !stk:      _outf    - output text file w formated ph#-code pairs