Changeset 489d3ba for doc

Timestamp:

Nov 15, 2024, 5:48:11 PM (5 weeks ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

master

Children:

e255902b

Parents:

2325b57

Message:

change how latex code generated from sharing-demo.cfa

Location:

doc/theses/mike_brooks_MMath

Files:

• Makefile (modified) (5 diffs)
• programs/sharectx.run.cfa (moved) (moved from doc/theses/mike_brooks_MMath/programs/sharectx-demo.cfa)
• programs/sharing-demo.cfa (modified) (24 diffs)
• string.tex (modified) (9 diffs)

doc/theses/mike_brooks_MMath/Makefile

@@ -10 +10 @@
 TeXSRC = ${wildcard *.tex}
 PicSRC = ${notdir ${wildcard ${Pictures}/*.png}}
-DemoSRC = ${notdir ${wildcard ${Programs}/*-demo.cfa}}
+DemoPgmSRC = ${notdir ${wildcard ${Programs}/*-demo.cfa}}
 PgmSRC = ${notdir ${wildcard ${Programs}/*}}
 RunPgmSRC = ${notdir ${wildcard ${Programs}/*.run.*}}
@@ -24 +24 @@
 BASE = ${basename ${DOCUMENT}}                  # remove suffix
 
-DemoTex = ${DemoSRC:%.cfa=${Build}/%.tex} 
 RunPgmExe = ${addprefix ${Build}/,${basename ${basename ${RunPgmSRC}}}}
 RunPgmOut = ${RunPgmExe:%=%.out}
+DemoPgmExe = ${addprefix ${Build}/,${basename ${basename ${DemoPgmSRC}}}}
+DemoPgmOut = ${DemoPgmExe:%=%.out}
 
 # Commands
@@ -38 +39 @@
 # Rules and Recipes
 
-.PHONY : all fragments_ran clean                        # not file names
-.PRECIOUS : ${Build}/% ${Build}/%-demo      # don't delete intermediates
+.PHONY : all clean                              # not file names
+.SECONDARY:
+#.PRECIOUS : ${Build}/%                         # don't delete intermediates
 .ONESHELL :
 
-all : fragments_ran ${DOCUMENT}
-
-fragments_ran : $(RunPgmOut)
+all : ${DOCUMENT}
 
 clean :
@@ -51 +51 @@
 # File Dependencies
 
-%.pdf : ${TeXSRC} ${DemoTex} ${PicSRC} ${PgmSRC} ${BibSRC} ${BibRep}/pl.bib ${LaTMac}/common.tex Makefile | ${Build}
+%.pdf : ${TeXSRC} $(RunPgmOut) ${DemoPgmOut} ${PicSRC} ${BibSRC} ${BibRep}/pl.bib ${LaTMac}/common.tex Makefile | ${Build}
         ${LaTeX} ${BASE}
         ${BibTeX} ${Build}/${BASE}
@@ -64 +64 @@
         mkdir -p $@
 
-%-demo.tex: %-demo | ${Build}
-        $< > $@
+${Build}/%-demo: ${Programs}/%-demo.cfa | ${Build}
+        ${CFA} $< -o $@
 
-${Build}/%-demo: ${Programs}/%-demo.cfa | ${Build}
+${Build}/%: ${Programs}/%-demo.cfa | ${Build}
         ${CFA} $< -o $@
 

doc/theses/mike_brooks_MMath/programs/sharing-demo.cfa

@@ -5 +5 @@
 #define str(s) #s
 
+ofstream outfile;
+
 void demo1() {
         sout | sepOff;
-        sout | "Consider two strings @s1@ and @s1a@ that are in an aliasing relationship, and a third, @s2@, made by a simple copy from @s1@.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
+//      sout | "Consider two strings @s1@ and @s1a@ that are in an aliasing relationship, and a third, @s2@, made by a simple copy from @s1@.";
 
         #define S1 string s1  = "abc"
@@ -21 +20 @@
         assert( s1a == "abc" );
         assert( s2 == "abc" );
-        sout | xstr(S1) | "\t\\\\";
-        sout | xstr(S1A) | "\t\\\\";
-        sout | xstr(S2) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2;
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "Aliasing (@`shareEdits@) means that changes flow in both directions; with a simple copy, they do not.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
-        sout | "\t\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+
+        open( outfile, "build/sharing1.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{@{}llll@{}}";
+        outfile | "\t\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
+        outfile | xstr(S1) | "\t\\\\";
+        outfile | xstr(S1A) | "\t\\\\";
+        outfile | xstr(S2) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2;
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "Aliasing (@`shareEdits@) means that changes flow in both directions; with a simple copy, they do not.";
+        open( outfile, "build/sharing2.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{@{}llll@{}}";
+        outfile | "\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
+        outfile | "\\multicolumn{1}{r}{initial} & " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1s1 s1 [1] = '+'
         S1s1;
         assert( s1 == "a+c" );
-        sout | xstr(S1s1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S1s1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1As1 s1a[1] = '-'
         S1As1;
         assert( s1a == "a-c" );
-        sout | xstr(S1As1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S1As1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S2s1 s2 [1] = '|'
         S2s1;
         assert( s2 == "a|c" );
-        sout | xstr(S2s1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2;
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "Assignment of a value is just a modificiation."
-                   "\nThe aliasing relationship is established at construction and is unaffected by assignment of a value.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
-        sout | "\t\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S2s1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2;
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "Assignment of a value is just a modificiation."
+//                 "\nThe aliasing relationship is established at construction and is unaffected by assignment of a value.";
+        open( outfile, "build/sharing3.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{llll}";
+        outfile | "\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
+        outfile | "\\multicolumn{1}{r}{initial} & " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1qrs s1  = "qrs"
         S1qrs;
         assert( s1 == "qrs" );
-        sout | xstr(S1qrs) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S1qrs) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1Atuv s1a = "tuv"
         S1Atuv;
         assert( s1a == "tuv" );
-        sout | xstr(S1Atuv) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S1Atuv) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S2wxy s2  = "wxy"
         S2wxy;
         assert( s2 == "wxy" );
-        sout | xstr(S2wxy) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2;
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "Assignment from a string is just assignment of a value."
-                   "\nWhether of not the RHS participates in aliasing is irrelevant.  Any aliasing of the LHS is unaffected.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
-        sout | "\t\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S2wxy) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2;
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "Assignment from a string is just assignment of a value."
+//                 "\nWhether of not the RHS participates in aliasing is irrelevant.  Any aliasing of the LHS is unaffected.";
+        open( outfile, "build/sharing4.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{llll}";
+        outfile | "\t\t& @s1@\t& @s1a@\t& @s2@\t\\\\";
+        outfile | "\\multicolumn{1}{r}{initial} & " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1S2 s1  = s2
@@ -86 +96 @@
         assert( s1a == "wxy" );
         assert( s2 == "wxy" );
-        sout | xstr(S1S2) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S1S2) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1aaa s1  = "aaa"
@@ -93 +103 @@
         assert( s1a == "aaa" );
         assert( s2 == "wxy" );
-        sout | xstr(S1aaa) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S1aaa) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S2S1 s2  = s1
@@ -100 +110 @@
         assert( s1a == "aaa" );
         assert( s2 == "aaa" );
-        sout | xstr(S2S1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S2S1) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S2bbb s2  = "bbb"
@@ -107 +117 @@
         assert( s1a == "aaa" );
         assert( s2 == "bbb" );
-        sout | xstr(S2bbb) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S2bbb) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S2S1a s2  = s1a
@@ -114 +124 @@
         assert( s1a == "aaa" );
         assert( s2 == "aaa" );
-        sout | xstr(S2S1a) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S2S1a) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S2ccc s2  = "ccc"
@@ -121 +131 @@
         assert( s1a == "aaa" );
         assert( s2 == "ccc" );
-        sout | xstr(S2ccc) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(S2ccc) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
 
         #define S1xxx s1  = "xxx"
@@ -128 +138 @@
         assert( s1a == "xxx" );
         assert( s2 == "ccc" );
-        sout | xstr(S1xxx) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par";
+        outfile | xstr(S1xxx) | "\t& " | s1 | "\t& " | s1a | "\t& " | s2 | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
 }
 
 
 void demo2() {
-        sout | "Consider new strings @s1_mid@ being an alias for a run in the middle of @s1@, along with @s2@, made by a simple copy from the middle of @s1@.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t\t\t& @s1@\t& @s1_mid@\t& @s2@\t\\\\";
+//      sout | "Consider new strings @s1_mid@ being an alias for a run in the middle of @s1@, along with @s2@, made by a simple copy from the middle of @s1@.";
+        open( outfile, "build/sharing5.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{llll}";
+        outfile | "\t\t\t\t& @s1@\t& @s1_mid@\t& @s2@\t\\\\";
 
         #define D2_s1_abcd string s1     = "abcd"
         D2_s1_abcd;
-        sout | xstr(D2_s1_abcd) | "\t\\\\";
+        outfile | xstr(D2_s1_abcd) | "\t\\\\";
 
         #define D2_s1mid_s1 string s1_mid = s1(1,2)`shareEdits
         D2_s1mid_s1;
-        sout | xstr(D2_s1mid_s1) | "\t\\\\";
+        outfile | xstr(D2_s1mid_s1) | "\t\\\\";
 
         #define D2_s2_s1 string s2     = s1(1,2)
@@ -153 +165 @@
         assert( s1_mid == "bc" );
         assert( s2 == "bc" );
-        sout | xstr(D2_s2_s1) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "Again, @`shareEdits@ passes changes in both directions; copy does not.  Note the difference in index values, with the \\emph{b} position being 1 in the longer string and 0 in the shorter strings.  In the case of s1 aliasing with @s1_mid@, the very same character is being accessed by different postitions.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t\t\t& @s1@\t& @s1_mid@\t& @s2@\t\\\\";
-        sout | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(D2_s2_s1) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "Again, @`shareEdits@ passes changes in both directions; copy does not.  Note the difference in index values, with the \\emph{b} position being 1 in the longer string and 0 in the shorter strings.  In the case of s1 aliasing with @s1_mid@, the very same character is being accessed by different postitions.";
+        open( outfile, "build/sharing6.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{llll}";
+        outfile | "\t\t\t\t& @s1@\t& @s1_mid@\t& @s2@\t\\\\";
+        outfile | "\\multicolumn{1}{r}{initial} & " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
 
         #define D2_s1_plus s1    [1] = '+'
@@ -168 +182 @@
         assert( s1_mid == "+c" );
         assert( s2 == "bc" );
-        sout | xstr(D2_s1_plus) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(D2_s1_plus) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
 
         #define D2_s1mid_minus s1_mid[0] = '-'
@@ -175 +189 @@
         assert( s1_mid == "-c" );
         assert( s2 == "bc" );
-        sout | xstr(D2_s1mid_minus) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(D2_s1mid_minus) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
 
         #define D2_s2_pipe s2    [0] = '|'
@@ -182 +196 @@
         assert( s1_mid == "-c" );
         assert( s2 == "|c" );
-        sout | xstr(D2_s2_pipe) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "Once again, assignment of a value is a modificiation that flows through the aliasing relationship, without affecting its structure.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llll}";
-        sout | "\t\t\t\t& @s1@\t& @s1_mid@\t& @s2@\t\\\\";
-        sout | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(D2_s2_pipe) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "Once again, assignment of a value is a modificiation that flows through the aliasing relationship, without affecting its structure.";
+        open( outfile, "build/sharing7.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{llll}";
+        outfile | "\t\t\t\t& @s1@\t& @s1_mid@\t& @s2@\t\\\\";
+        outfile | "\\multicolumn{1}{r}{initial} & " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
 
         #define D2_s1mid_ff s1_mid = "ff"
@@ -197 +213 @@
         assert( s1_mid == "ff" );
         assert( s2 == "|c" );
-        sout | xstr(D2_s1mid_ff) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | xstr(D2_s1mid_ff) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
 
         #define D2_s2_gg s2     = "gg"
@@ -204 +220 @@
         assert( s1_mid == "ff" );
         assert( s2 == "gg" );
-        sout | xstr(D2_s2_gg) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "In the \\emph{ff} step, which is a positive example of flow across an aliasing relationship, the result is straightforward to accept because the flow direction is from contained (small) to containing (large).  The following rules for edits through aliasing substrings will guide how to flow in the opposite direction.";
-        sout | "\\par";
-
-
-        sout | "Growth and shrinkage are natural extensions.  An empty substring is a real thing, at a well-defined location, whose meaning is extrapolated from the examples so far.  The intended metaphor is to operating a GUI text editor.  Having an aliasing substring is like using the mouse to select a few words.  Assigning onto an aliasign substring is like typing from having a few words selected:  depending how much you type, the file being edited can get shorter or longer.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{lll}";
-        sout | "\t\t\t\t& @s1@\t& @s1_mid@\t\\\\";
-        sout | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
+        outfile | xstr(D2_s2_gg) | "\t& " | s1 | "\t& " | s1_mid | "\t& " | s2 | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "In the \\emph{ff} step, which is a positive example of flow across an aliasing relationship, the result is straightforward to accept because the flow direction is from contained (small) to containing (large).  The following rules for edits through aliasing substrings will guide how to flow in the opposite direction.";
+//      sout | "\\par";
+
+
+//      sout | "Growth and shrinkage are natural extensions.  An empty substring is a real thing, at a well-defined location, whose meaning is extrapolated from the examples so far.  The intended metaphor is to operating a GUI text editor.  Having an aliasing substring is like using the mouse to select a few words.  Assigning onto an aliasign substring is like typing from having a few words selected:  depending how much you type, the file being edited can get shorter or longer.";
+        open( outfile, "build/sharing8.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{lll}";
+        outfile | "\t\t\t\t& @s1@\t& @s1_mid@\t\\\\";
+        outfile | "\\multicolumn{1}{r}{initial} & " | s1 | "\t& " | s1_mid | "\t\\\\";
 
         assert( s1 == "affd" );
 //      assert( s1_mid == "fc" );                                                                                                        // ????????? bug?
-        sout | xstr(D2_s2_gg) | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
+        outfile | xstr(D2_s2_gg) | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
 
         #define D2_s1mid_hhhh s1_mid = "hhhh"
@@ -226 +244 @@
         assert( s1 == "ahhhhd" );
         assert( s1_mid == "hhhh" );
-        sout  | xstr(D2_s1mid_hhhh)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
+        outfile  | xstr(D2_s1mid_hhhh)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
 
         #define D2_s1mid_i s1_mid = "i"
@@ -232 +250 @@
         assert( s1 == "aid" );
         assert( s1_mid == "i" );
-        sout  | xstr(D2_s1mid_i)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
+        outfile  | xstr(D2_s1mid_i)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
 
         #define D2_s1mid_empty s1_mid = ""
@@ -238 +256 @@
         assert( s1 == "ad" );
         // assert( s1_mid == "" );    ------ Should be so, but fails
-        sout  | xstr(D2_s1mid_empty)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
+        outfile  | xstr(D2_s1mid_empty)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
 
         #define D2_s1mid_jj s1_mid = "jj"
@@ -244 +262 @@
         assert( s1 == "ajjd" );
         assert( s1_mid == "jj" );
-        sout  | xstr(D2_s1mid_jj)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "Multiple portions can be aliased.  When there are several aliasing substrings at once, the text editor analogy becomes an online multi-user editor.  I should be able to edit a paragraph in one place (changing the document's length), without my edits affecting which letters are within a mouse-selection that you had made previously, somewhere else.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{lllll}";
-        sout | "\t\t\t\t& @s1@\t& @s1_bgn@\t& @s1_mid@\t& @s1_end@\t\\\\";
+        outfile  | xstr(D2_s1mid_jj)  | "\t& " | s1 | "\t& " | s1_mid | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "Multiple portions can be aliased.  When there are several aliasing substrings at once, the text editor analogy becomes an online multi-user editor.  I should be able to edit a paragraph in one place (changing the document's length), without my edits affecting which letters are within a mouse-selection that you had made previously, somewhere else.";
+        open( outfile, "build/sharing9.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{lllll}";
+        outfile | "\t\t\t\t& @s1@\t& @s1_bgn@\t& @s1_mid@\t& @s1_end@\t\\\\";
 
         #define D2_s1bgn_s1     string s1_bgn = s1(0, 1)`shareEdits
         D2_s1bgn_s1;
-        sout  | xstr(D2_s1bgn_s1)  | "\t\\\\";
+        outfile  | xstr(D2_s1bgn_s1)  | "\t\\\\";
 
         #define D2_s1end_s1 string s1_end = s1(3, 1)`shareEdits
@@ -263 +283 @@
         assert( s1_mid == "jj" );
         assert( s1_end == "d" );
-        sout  | xstr(D2_s1end_s1)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
+        outfile  | xstr(D2_s1end_s1)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
 
         #define D1_s1bgn_zzz s1_bgn = "zzzz"
@@ -271 +291 @@
         assert( s1_mid == "jj" );
         assert( s1_end == "d" );
-        sout  | xstr(D1_s1bgn_zzz)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-
-        sout | "When an edit happens on an aliasing substring that overlaps another, an effect is unavoidable.  Here, the passive party sees its selection shortened, to exclude the characters that were not part of the original selection.";
-        sout | "\\par\\noindent";
-        sout | "\\begin{tabular}{llllll}";
-        sout | "\t\t\t\t& @s1@\t& @s1_bgn@\t& @s1_crs@\t& @s1_mid@\t& @s1_end@\t\\\\";
+        outfile  | xstr(D1_s1bgn_zzz)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
+
+//      sout | "When an edit happens on an aliasing substring that overlaps another, an effect is unavoidable.  Here, the passive party sees its selection shortened, to exclude the characters that were not part of the original selection.";
+        open( outfile, "build/sharing10.tex" );
+        outfile | "\\begin{cquote}";
+        outfile | "\\begin{tabular}{llllll}";
+        outfile | "\t\t\t\t& @s1@\t& @s1_bgn@\t& @s1_crs@\t& @s1_mid@\t& @s1_end@\t\\\\";
 
         #define D2_s1crs_s1 string s1_crs = s1(3, 2)`shareEdits
@@ -287 +309 @@
         assert( s1_mid == "jj" );
         assert( s1_end == "d" );
-        sout  | xstr(D2_s1crs_s1)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_crs | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
+        outfile  | xstr(D2_s1crs_s1)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_crs | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
 
         #define D2_s1crs_ppp s1_crs = "+++"
@@ -296 +318 @@
         assert( s1_mid == "j" );
         assert( s1_end == "d" );
-        sout  | xstr(D2_s1crs_ppp)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_crs | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
-        sout | "\\end{tabular}";
-        sout | "\\par\\noindent";
-        sout | "TODO: finish typesetting the demo";
+        outfile  | xstr(D2_s1crs_ppp)  | "\t& " | s1 | "\t& " | s1_bgn | "\t& " | s1_crs | "\t& " | s1_mid | "\t& " | s1_end | "\t\\\\";
+        outfile | "\\end{tabular}";
+        outfile | "\\end{cquote}";
+        close( outfile );
 
         // "This shortening behaviour means that a modification has to occur entirely inside a substring, to show up in that substring.  Sharing changes through the intersection of partially overlapping aliases is still possible, so long as the receiver's boundary is not inside the edit."
@@ -379 +401 @@
         demo1();
         demo2();
-        printf("%% %s done running\n", argv[0]);
+//      printf("%% %s done running\n", argv[0]);
 }

doc/theses/mike_brooks_MMath/string.tex

@@ -67 +67 @@
 \CFA provides a dynamic mechanism to indicate mutable or immutable as an assignment attribute: @`shareEdits@.
 
-\input{sharing-demo.tex}
-
 Consider two strings @s1@ and @s1a@ that are in an aliasing relationship, and a third, @s2@, made by a simple copy from @s1@.
-\par\noindent
-\begin{tabular}{llll}
-                                & @s1@  & @s1a@ & @s2@  \\
-%\input{sharing-demo1.tex}
-\end{tabular}
-\par\noindent
+Aliasing (@`shareEdits@) means that changes flow in both directions; with a simple copy, they do not.
+\input{sharing1.tex}
+
+Aliasing (@`shareEdits@) means that changes flow in both directions; with a simple copy, they do not.
+\input{sharing2.tex}
+
+Assignment of a value is just a modification.
+The aliasing relationship is established at construction and is unaffected by assignment of a value.
+\input{sharing3.tex}
+
+Assignment from a string is just assignment of a value.
+Whether of not the RHS participates in aliasing is irrelevant.  Any aliasing of the LHS is unaffected.
+\input{sharing4.tex}
+
+Consider new strings @s1_mid@ being an alias for a run in the middle of @s1@, along with @s2@, made by a simple copy from the middle of @s1@.
+\input{sharing5.tex}
+
+Again, @`shareEdits@ passes changes in both directions; copy does not.
+Note the difference in index values, with the \emph{b} position being 1 in the longer string and 0 in the shorter strings.
+In the case of s1 aliasing with @s1_mid@, the very same character is being accessed by different positions.
+\input{sharing6.tex}
+
+Once again, assignment of a value is a modification that flows through the aliasing relationship, without affecting its structure.
+\input{sharing7.tex}
+
+In the \emph{ff} step, which is a positive example of flow across an aliasing relationship, the result is straightforward to accept because the flow direction is from contained (small) to containing (large).
+The following rules for edits through aliasing substrings will guide how to flow in the opposite direction.
+
+Growth and shrinkage are natural extensions.
+An empty substring is a real thing, at a well-defined location, whose meaning is extrapolated from the examples so far.
+The intended metaphor is to operating a GUI text editor.
+Having an aliasing substring is like using the mouse to select a few words.
+Assigning onto an aliasing substring is like typing from having a few words selected: depending how much you type, the file being edited can get shorter or longer.
+\input{sharing8.tex}
+
+Multiple portions can be aliased.
+When there are several aliasing substrings at once, the text editor analogy becomes an online multi-user editor.
+I should be able to edit a paragraph in one place (changing the document's length), without my edits affecting which letters are within a mouse-selection that you had made previously, somewhere else.
+\input{sharing9.tex}
+
+When an edit happens on an aliasing substring that overlaps another, an effect is unavoidable.
+Here, the passive party sees its selection shortened, to exclude the characters that were not part of the original selection.
+\input{sharing10.tex}
+
+TODO: finish typesetting the demo
+
+%\input{sharing-demo.tex}
 
 
 \subsection{RAII limitations}
 
-Earlier work on \CFA [to cite Schluntz] implemented the feature of constructors and destructors.  A constructor is a user-defined function that runs implicitly, when control passes an object's declaration, while a destructor runs at the exit of the declaration's lexical scope.  The feature allows programmers to assume that, whenever a runtime object of a certain type is accessible, the system called one of the programmer's constructor functions on that object, and a matching destructor call will happen in the future.  The feature helps programmers know that their programs' invariants obtain.
-
-The purposes of such invariants go beyond ensuring authentic values for the bits inside the object.   These invariants can track occurrences of the managed objects in other data structures.  Reference counting is a typical application of the latter invariant type.  With a reference-counting smart pointer, the constructor and destructor \emph{of the pointer type} track the life cycles of occurrences of these pointers, by incrementing and decrementing a counter (usually) on the referent object, that is, they maintain a that is state separate from the objects to whose life cycles they are attached.  Both the \CC and \CFA RAII systems ares powerful enough to achieve such reference counting.
-
-The \CC RAII system supports a more advanced application.  A life cycle function has access to the object under management, by location; constructors and destructors receive a @this@ parameter providing its memory address.  A lifecycle-function implementation can then add its objects to a collection upon creation, and remove them at destruction.  A module that provides such objects, by using and encapsulating such a collection, can traverse the collection at relevant times, to keep the objects ``good.''  Then, if you are the user of such an module, declaring an object of its type means not only receiving an authentically ``good'' value at initialization, but receiving a subscription to a service that will keep the value ``good'' until you are done with it.
-
-In many cases, the relationship between memory location and lifecycle is simple.  But with stack-allocated objects being used as parameters and returns, there is a sender version in one stack frame and a receiver version in another.  \CC is able to treat those versions as distinct objects and guarantee a copy-constructor call for communicating the value from one to the other.  This ability has implications on the language's calling convention.  Consider an ordinary function @void f( Vehicle x )@, which receives an aggregate by value.  If the type @Vehicle@ has custom lifecycle functions, then a call to a user-provided copy constructor occurs, after the caller evaluates its argument expression, after the callee's stack frame exists, with room for its variable @x@ (which is the location that the copy-constructor must target), but before the user-provided body of @f@ begins executing.  \CC achieves this ordering by changing the function signature, in the compiled form, to pass-by-reference and having the callee invoke the copy constructor in its preamble.  On the other hand, if @Vehicle@ is a simple structure then the C calling convention is applied as the code originally appeared, that is, the call-site implementation code performs a bitwise copy from the caller's expression result, into the callee's x.
+Earlier work on \CFA~\cite[ch.~2]{Schluntz17} implemented object constructors and destructors for all types (basic and user defined).
+A constructor is a user-defined function run implicitly \emph{after} an object's declaration-storage is created, and a destructor is a user-defined function run \emph{before} an object's declaration-storage is deleted.
+This feature guarantees pre invariants for users before accessing an object and post invariants for the programming environment after an object terminates.
+
+The purposes of these invariants goes beyond ensuring authentic values inside an object.
+Invariants can also track occurrences of the managed objects in other data structures.
+For example, reference counting is a typical application of an invariant outside of the data values.
+With a reference-counting smart-pointer, the constructor and destructor \emph{of a pointer type} tracks the life cycle of the object it points to.
+Both \CC and \CFA RAII systems are powerful enough to achieve reference counting.
+
+In general, a lifecycle function has access to an object by location, \ie constructors and destructors receive a @this@ parameter providing an object's memory address.
+The lifecycle implementation can then add this object to a collection upon creation and remove it at destruction.
+A module that provides such objects, by using and encapsulating such a collection, can traverse the collection at relevant times, to keep the objects ``good.''.
+Hence, declaring such an object not only ensures ``good'' authentic at initialization, but also an implicit subscription to a service that keeps the value ``good'' across its lifetime.
+
+In many cases, the relationship between memory location and lifecycle is simple.
+But with stack-allocated objects being used as parameters and returns, there is a sender version in one stack frame and a receiver version in another.
+\CC is able to treat those versions as distinct objects and guarantee a copy-constructor call for communicating the value from one to the other.
+This ability has implications on the language's calling convention.
+Consider an ordinary function @void f( Vehicle x )@, which receives an aggregate by value.
+If the type @Vehicle@ has custom lifecycle functions, then a call to a user-provided copy constructor occurs, after the caller evaluates its argument expression, after the callee's stack frame exists, with room for its variable @x@ (which is the location that the copy-constructor must target), but before the user-provided body of @f@ begins executing.
+\CC achieves this ordering by changing the function signature, in the compiled form, to pass-by-reference and having the callee invoke the copy constructor in its preamble.
+On the other hand, if @Vehicle@ is a simple structure then the C calling convention is applied as the code originally appeared, that is, the call-site implementation code performs a bitwise copy from the caller's expression result, into the callee's x.
 
 TODO: learn correction to fix inconsistency: this discussion says the callee invokes the copy constructor, but only the caller knows which copy constructor to use!
@@ -149 +204 @@
 
 The \CFA sting library provides the @string_sharectx@ type to control an ambient sharing context for the current thread.  It allows two adjustments: to opt out of sharing entirely, or to begin sharing within a private context.  Either way, the chosen mode applies to the current thread, for the duration of the lifetime of the created  @string_sharectx@ object, up to being suspended by child lifetimes of different contexts.  The indented use is with stack-managed lifetimes, in which the established context lasts until the current function returns, and affects all functions called that don't create their own contexts.
-\lstinputlisting[language=CFA, firstline=20, lastline=34]{sharectx-demo.cfa}
+\lstinputlisting[language=CFA, firstline=20, lastline=34]{sharectx.run.cfa}
 In this example, the single-letter functions are called in alphabetic order.  The functions @a@ and @d@ share string character ranges within themselves, but not with each other.  The functions @b@, @c@ and @e@ never share anything.
 
@@ -169 +224 @@
 \subsection{Performance assessment}
 
-I assessed the CFA string library's speed and memory usage.  I present these results in even equivalent cases, due to either micro-optimizations foregone, or fundamental costs of the added functionality.  They also show the benefits and tradeoffs, as >100\% effects, of switching to CFA, with the tradeoff points quantified.  The final test shows the overall win of the CFA text-sharing mechanism.  It exercises several operations together, showing CFA enabling clean user code to achieve performance that STL requires less-clean user code to achieve.
-
-To discuss: general goal of ... while STL makes you think about memory management, all the time, and if you do your performance can be great ... CFA sacrifices this advantage modestly in exchange for big wins when you're not thinking about memory management.  [Does this position cover all of it?]
+I assessed the \CFA string library's speed and memory usage.  I present these results in even equivalent cases, due to either micro-optimizations foregone, or fundamental costs of the added functionality.  They also show the benefits and tradeoffs, as >100\% effects, of switching to \CFA, with the tradeoff points quantified.  The final test shows the overall win of the \CFA text-sharing mechanism.  It exercises several operations together, showing \CFA enabling clean user code to achieve performance that STL requires less-clean user code to achieve.
+
+To discuss: general goal of ... while STL makes you think about memory management, all the time, and if you do your performance can be great ... \CFA sacrifices this advantage modestly in exchange for big wins when you're not thinking about memory management.  [Does this position cover all of it?]
 
 To discuss: revisit HL v LL APIs
@@ -196 +251 @@
 \subsubsection{Test: Append}
 
-This test measures the speed of appending fragments of text onto a growing string.  Its subcases include both CFA being similar to STL, and their designs offering a tradeoff.
+This test measures the speed of appending fragments of text onto a growing string.  Its subcases include both \CFA being similar to STL, and their designs offering a tradeoff.
 
 One experimental variable is the user's operation being @a = a + b@ vs. @a += b@.  While experienced programmers expect the latter to be ``what you obviously should do,'' controlling the penalty of the former both helps the API be accessible to beginners and also helps offer confidence that when a user tries to compose operations, the forms that are most natural to the user's composition are viable.
@@ -210 +265 @@
     @ } @                                      & @ } @
 \end{tabular}\\
-These benchmark drivers have an outer loop for ``until a sample-worthy amount of execution has happened'' and an inner loop for ``build up the desired-length string.''  It is sensible to doubt that a user should have to care about this difference, yet the STL performs differently in these cases.  Concretely, both cases incur the cost of copying characters into the target string, but only the allocation-fresh case incurs a further reallocation cost, which is generally paid at points of doubling the length.  For the STL, this cost includes obtaining a fresh buffer from the memory allocator and copying older characters into the new buffer, while CFA-sharing hides such a cost entirely.  The reuse-vs-fresh distinction is only relevant in the current \emph{append} tests.
+These benchmark drivers have an outer loop for ``until a sample-worthy amount of execution has happened'' and an inner loop for ``build up the desired-length string.''  It is sensible to doubt that a user should have to care about this difference, yet the STL performs differently in these cases.  Concretely, both cases incur the cost of copying characters into the target string, but only the allocation-fresh case incurs a further reallocation cost, which is generally paid at points of doubling the length.  For the STL, this cost includes obtaining a fresh buffer from the memory allocator and copying older characters into the new buffer, while \CFA-sharing hides such a cost entirely.  The reuse-vs-fresh distinction is only relevant in the current \emph{append} tests.
 
 The \emph{append} tests use the varying-from-1 corpus construction; that is they do not assume away the STL's advantage from small-string optimization.
@@ -230 +285 @@
 \end{figure}
 
-In sharing mode, \CFA makes the fresh/reuse difference disappear, as shown in Figure \ref{fig:string-graph-peq-sharing}.  At append lengths 5 and above, CFA not only splits the two baseline STL cases, but its slowdown of 16\% over (STL with user-managed reuse) is close to the \CFA-v-STL implementation difference seen with \CFA in STL-emulation mode.
+In sharing mode, \CFA makes the fresh/reuse difference disappear, as shown in Figure \ref{fig:string-graph-peq-sharing}.  At append lengths 5 and above, \CFA not only splits the two baseline STL cases, but its slowdown of 16\% over (STL with user-managed reuse) is close to the \CFA-v-STL implementation difference seen with \CFA in STL-emulation mode.
 
 \begin{figure}
@@ -238 +293 @@
 \end{figure}
 
-When the user takes a further step beyond the STL's optimal zone, by running @x = x + y@, as in Figure \ref{fig:string-graph-pta-sharing}, the STL's penalty is above $15 \times$ while CFA's (with sharing) is under $2 \times$, averaged across the cases shown here.  Moreover, the STL's gap increases with string size, while \CFA's converges.
+When the user takes a further step beyond the STL's optimal zone, by running @x = x + y@, as in Figure \ref{fig:string-graph-pta-sharing}, the STL's penalty is above $15 \times$ while \CFA's (with sharing) is under $2 \times$, averaged across the cases shown here.  Moreover, the STL's gap increases with string size, while \CFA's converges.
 
 \subsubsection{Test: Pass argument}
@@ -275 +330 @@
 \begin{figure}
     \includegraphics[width=\textwidth]{string-graph-allocn.png}
-    \caption{Space and time performance, under varying fraction-live targets, for the five string lengths shown, at (\emph{Fixed-size} corpus construction.  [MISSING] The identified clusters are for the default fraction-live target, which is 30\%.  MISSING: STL results, typically just below the 0.5--0.9 CFA segment.  All runs keep an average of 836 strings live, and the median string lifetime is ?? allocations.}
+    \caption{Space and time performance, under varying fraction-live targets, for the five string lengths shown, at (\emph{Fixed-size} corpus construction.  [MISSING] The identified clusters are for the default fraction-live target, which is 30\%.  MISSING: STL results, typically just below the 0.5--0.9 \CFA segment.  All runs keep an average of 836 strings live, and the median string lifetime is ?? allocations.}
     \label{fig:string-graph-allocn}
 \end{figure}
@@ -285 +340 @@
 \subsubsection{Test: Normalize}
 
-This test is more applied than the earlier ones.  It combines the effects of several operations.  It also demonstrates a case of the CFA API allowing user code to perform well, while being written without overt memory management, while achieving similar performance in STL requires adding memory-management complexity.
+This test is more applied than the earlier ones.  It combines the effects of several operations.  It also demonstrates a case of the \CFA API allowing user code to perform well, while being written without overt memory management, while achieving similar performance in STL requires adding memory-management complexity.
 
 To motivate: edits being rare