Add multi-inline extension script to tutorial

It's useful to have an example of an extension script that handles
multiple types of things.  It's also good to show that scripts can
handle data types other than strings, and can chase an address to
format data items elsewhere in the code.

This required updating the tutorial binary, adding the new script,
and updating the tutorial text and associated screen shots.

SourceGen/Examples/Tutorial/InlineL1String.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections.Generic;
-
 using PluginCommon;
 
 namespace ExtensionScriptSample {
@@ -15,7 +14,7 @@ namespace ExtensionScriptSample {
         private IApplication mAppRef;
         private byte[] mFileData;
 
-        // Only one call.
+        // Only one label.
         private const string CALL_LABEL = "PrintInlineL1String";
         private int mInlineL1StringAddr;      // jsr
 
@@ -62,7 +61,7 @@ namespace ExtensionScriptSample {
             if (offset + 3 >= mFileData.Length) {
                 return;     // length byte is off end
             }
-            int len = mFileData[3];     // first byte past JSR
+            int len = mFileData[offset + 3];     // first byte past JSR
             if (offset + 4 + len > mFileData.Length) {
                 mAppRef.DebugLog("L1 string ran off end of file at +" +
                     (offset + 4).ToString("x6"));

SourceGen/Examples/Tutorial/InlineMulti.cs

@@ -0,0 +1,153 @@
+// Copyright 2021 faddenSoft. All Rights Reserved.
+// See the LICENSE.txt file for distribution terms (Apache 2.0).
+
+using System;
+using System.Collections.Generic;
+using PluginCommon;
+
+namespace ExtensionScriptSample {
+    /// <summary>
+    /// Formats three different kinds of inline functions:
+    ///
+    ///   PrintInlineL1String: format following data as L1 string
+    ///   PrintInlineNullString*: format following data as null-term string.
+    ///   PrintInlineAddrString*: format following data as 16-bit pointer to null-term string.
+    /// </summary>
+    public class InlineMultiData : MarshalByRefObject, IPlugin, IPlugin_SymbolList,
+            IPlugin_InlineJsr {
+        private IApplication mAppRef;
+        private byte[] mFileData;
+        private AddressTranslate mAddrTrans;
+
+        private const string L1STR_NAME = "PrintInlineL1String";
+        private const string NULLSTR_PREFIX = "PrintInlineNullString";
+        private const string ADDRSTR_PREFIX = "PrintInlineAddrString";
+        private enum InlineKind { Unknown = 0, L1Str, NullStr, AddrStr };
+
+        private Dictionary<int, InlineKind> mInlineLabels = new Dictionary<int, InlineKind>();
+
+        public string Identifier {
+            get {
+                return "Inline multi-data formatter";
+            }
+        }
+
+        public void Prepare(IApplication appRef, byte[] fileData, AddressTranslate addrTrans) {
+            mAppRef = appRef;
+            mFileData = fileData;
+            mAddrTrans = addrTrans;
+
+            mAppRef.DebugLog("InlineMultiData(id=" +
+                AppDomain.CurrentDomain.Id + "): prepare()");
+        }
+
+        public void Unprepare() {
+            mAppRef = null;
+            mFileData = null;
+            mAddrTrans = null;
+        }
+
+        public void UpdateSymbolList(List<PlSymbol> plSyms) {
+            mInlineLabels.Clear();
+
+            // Find matching symbols.  Save the symbol's value (its address) and the type.
+            // We want an exact match on L1STR_NAME, and prefix matches on the other two.
+            foreach (PlSymbol sym in plSyms) {
+                if (sym.Label.Equals(L1STR_NAME)) {
+                    mInlineLabels.Add(sym.Value, InlineKind.L1Str);
+                } else if (sym.Label.StartsWith(NULLSTR_PREFIX)) {
+                    mInlineLabels.Add(sym.Value, InlineKind.NullStr);
+                } else if (sym.Label.StartsWith(ADDRSTR_PREFIX)) {
+                    mInlineLabels.Add(sym.Value, InlineKind.AddrStr);
+                }
+            }
+            mAppRef.DebugLog("Found matches for " + mInlineLabels.Count + " labels");
+        }
+
+        public bool IsLabelSignificant(string beforeLabel, string afterLabel) {
+            return DoesLabelMatch(beforeLabel) || DoesLabelMatch(afterLabel);
+        }
+        private static bool DoesLabelMatch(string label) {
+            return (label.Equals(L1STR_NAME) ||
+                label.StartsWith(NULLSTR_PREFIX) ||
+                label.StartsWith(ADDRSTR_PREFIX));
+        }
+
+        public void CheckJsr(int offset, int operand, out bool noContinue) {
+            noContinue = false;
+
+            InlineKind kind;
+            if (!mInlineLabels.TryGetValue(operand, out kind)) {
+                return;
+            }
+
+            switch (kind) {
+                case InlineKind.L1Str:
+                    // Length-delimited ASCII string
+                    FormatL1String(offset + 3);
+                    break;
+                case InlineKind.NullStr:
+                    // Null-terminated ASCII string.
+                    FormatNullTermString(offset + 3);
+                    break;
+                case InlineKind.AddrStr:
+                    // Pointer to data.  Format as address.  Start by confirming next two
+                    // bytes are inside the file bounds.
+                    if (!Util.IsInBounds(mFileData, offset + 3, 2)) {
+                        return;
+                    }
+                    // Format 16-bit value as an address.
+                    mAppRef.SetInlineDataFormat(offset + 3, 2,
+                        DataType.NumericLE, DataSubType.Address, null);
+
+                    // Now format the string that the address points to.  Extract the
+                    // address from the operand.
+                    int strAddr = Util.GetWord(mFileData, offset + 3, 2, false);
+                    // Convert the address to a file offset.  Returns -1 if not in file bounds.
+                    int strOff = mAddrTrans.AddressToOffset(offset, strAddr);
+                    // Format it if it's in bounds.
+                    FormatNullTermString(strOff);
+                    break;
+            }
+        }
+
+        private void FormatL1String(int offset) {
+            if (offset < 0 || offset >= mFileData.Length) {
+                return;     // length byte is not inside file
+            }
+            int len = mFileData[offset];
+            if (offset + 1 + len > mFileData.Length) {
+                mAppRef.DebugLog("L1 string ran off end of file at +" +
+                    (offset + 1).ToString("x6"));
+                return;
+            }
+
+            // Assuming ASCII.
+            mAppRef.SetInlineDataFormat(offset, len + 1,
+                DataType.StringL8, DataSubType.Ascii, null);
+        }
+
+        private void FormatNullTermString(int offset) {
+            if (offset < 0 || offset >= mFileData.Length) {
+                return;     // start is not inside file
+            }
+            // search for the terminating null byte
+            int nullOff = offset;
+            while (nullOff < mFileData.Length) {
+                if (mFileData[nullOff] == 0x00) {
+                    break;
+                }
+                nullOff++;
+            }
+            if (nullOff == mFileData.Length) {
+                mAppRef.DebugLog("Unable to find end of null-terminated string at +" +
+                    offset.ToString("x6"));
+                return;
+            }
+
+            // Assuming ASCII.
+            mAppRef.SetInlineDataFormat(offset, nullOff - offset + 1,
+                DataType.StringNullTerm, DataSubType.Ascii, null);
+        }
+    }
+}

SourceGen/Examples/Tutorial/InlineNullTermString.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections.Generic;
-
 using PluginCommon;
 
 namespace ExtensionScriptSample {
@@ -41,6 +40,7 @@ namespace ExtensionScriptSample {
         public void UpdateSymbolList(List<PlSymbol> plSyms) {
             mNullStringAddrs.Clear();
 
+            // Find matching symbols.
             foreach (PlSymbol sym in plSyms) {
                 if (sym.Label.StartsWith(LABEL_PREFIX)) {
                     mNullStringAddrs.Add(sym.Value, sym);
@@ -61,7 +61,7 @@ namespace ExtensionScriptSample {
             // search for the terminating null byte
             int nullOff = offset + 3;
             while (nullOff < mFileData.Length) {
-                if (mFileData[nullOff] == 0) {
+                if (mFileData[nullOff] == 0x00) {
                     break;
                 }
                 nullOff++;

SourceGen/Examples/Tutorial/Source/Tutorial4.S

@@ -13,11 +13,18 @@
 
         jsr     PrintInlineZString2
         asc     'Test two',00
+
+        jsr     PrintInlineAddr
+        dw      test_three
         rts
 
+test_three asc  'Test three',00
+
 PrintInlineL1String
         rts
 PrintInlineZString1
         rts
 PrintInlineZString2
         rts
+PrintInlineAddr
+        rts