[[ InteractiveTutorial ]] Add load stack from resources

This patch adds the ability to load stacks from the tutorial
internal resources folder for use as a stack in the current tutorial.

Author: livecodeali

Documentation/specs/tutorial-syntax.md

@@ -63,6 +63,7 @@ The possible actions are as follows:
 	  | "go" "to" "step" <Name: STRING>
 	  | "add" "guide" <Name: STRING> "with" "rect" <Rect: RECT> "to" <Target: Object>
 	  | “interlude”
+	  | "load" ("lesson" | "stack") <Source: STRING>
 
 The highlight action causes the tutorial stack to point at the relevant
 object on the screen. If there is no highlight action, the tutorial stack
@@ -139,3 +140,13 @@ satisfied before continuing.
 	  | "the" <Property: PROPERTY> "of" <Target: Object> "is" "changed" "with" "default" <Value: STRING>
 	  | <Target: Object> "pops" "up" "answer" "dialog"
 	  | "this" "card" "is" <Card: STRING>
+
+The load action causes tutorial state to be loaded. If the "lesson" Source
+is used, the tutorial runner will find the lesson with name Source in the
+same lessons folder as the current tutorial, and run it to completion. The
+resulting stack will then be available to use in the current tutorial.
+
+If the "stack" Source is used, a stack will be loaded from the internal 
+resources folder of the tutorial (_resources/). Any `cTutorialTag` custom
+property of objects on the stack will be converted to tags for objects 
+which can subsequently be used in the current tutorial.

Toolset/libraries/revidelibrary.8.livecodescript

@@ -10367,6 +10367,10 @@ private function __fetchAndRemoveControlTags pCard
    return tTags
 end __fetchAndRemoveControlTags
 
+command revIDETutorialUpdateAndRemoveTags pStackName, @xTags
+      union xTags with __fetchAndRemoveTags(pStackName)
+end revIDETutorialUpdateAndRemoveTags
+
 on revIDETutorialLoad pCourse, pTutorial, pLesson
    local tLocation
    put __findTutorialLocation(pCourse, pTutorial, pLesson) into tLocation
@@ -10393,7 +10397,7 @@ on revIDETutorialLoad pCourse, pTutorial, pLesson
          put return & tStackName after tStackList
       end if
 
-      union tTags with __fetchAndRemoveTags(tStackName)
+      revIDETutorialUpdateAndRemoveTags tStackName, tTags
    end repeat
 
    dispatch "revTutorialResume" to stack "revTutorial" with tStackList, tTags, tLessonDataA["step"]

Toolset/palettes/tutorial/revtutorial.livecodescript

@@ -432,12 +432,20 @@ end revTutorialParseInterlude
 on revTutorialParseLoad pTokens, @rData
    local tData
    revTutorialParseLine "load lesson <token>", pTokens, tData
-   if the result is not empty then
-      return the result
+   if the result is empty then
+      put "load" into rData["type"]
+      put tData[1] into rData["lesson"]
+      return empty
    end if
-   put "load" into rData["type"]
-   put tData[1] into rData["lesson"]
-   return empty
+   
+   revTutorialParseLine "load stack <token>", pTokens, tData
+   if the result is empty then
+      put "load" into rData["type"]
+      put tData[1] into rData["stack"]
+      return empty
+   end if
+   
+   return the result
 end revTutorialParseLoad
 
 on revTutorialParseCapture pTokens, @rData
@@ -2086,18 +2094,39 @@ on revTutorialExecuteAction pActionData
          revTutorialDoCreateSet pActionData["objects"], pActionData["tag"]
          break
       case "load"
-         revTutorialDoLoad pActionData["lesson"]
+         revTutorialDoLoad pActionData
          break
    end switch
 end revTutorialExecuteAction
 
-on revTutorialDoLoad pLesson
+command revTutorialDoLoadLesson pLesson
    # Check to see if the stack from the specified lesson is complete
    local tTutorialInfo
    put revIDETutorialInProgress() into tTutorialInfo
 
    # Simply run the lesson that is to be loaded
    revTutorialRunTutorial tTutorialInfo["course"], tTutorialInfo["tutorial"], pLesson, tTutorialInfo["location"]
+end revTutorialDoLoadLesson
+
+command revTutorialDoLoadStackResource pFile
+   local tFileName, tStackName
+   put revIDETutorialInternalResource(pFile) into tFileName
+   lock screen
+   lock messages
+   go stack tFileName
+   put the name of stack tFileName into tStackName
+   set the filename of stack tStackName to empty
+   revIDETutorialUpdateAndRemoveTags tStackName, sTaggedObjects
+   unlock messages
+   unlock screen
+end revTutorialDoLoadStackResource
+
+on revTutorialDoLoad pActionData
+   if pActionData["lesson"] is not empty then
+      revTutorialDoLoadLesson pActionData["lesson"]
+   else if pActionData["stack"] is not empty then
+      revTutorialDoLoadStackResource pActionData["stack"]
+   end if
 end revTutorialDoLoad
 
 on revTutorialSetText pStep

notes/feature-tutorial_load_stack.md

@@ -0,0 +1,9 @@
+# Interactive Tutorial syntax
+The syntax `load stack <FileName>` has been added to interactive
+tutorials. This allows prepared stacks to be imported as operating
+stacks in the current tutorial.
+
+The prepared stack will be loaded from the internal resources folder 
+of the tutorial (i.e. from `_resources/<FileName>`). Any `cTutorialTag` 
+custom property of objects on the stack will be converted to tags for 
+objects which can subsequently be used in the current tutorial.