split readPage to allow reading LS directly from a string, as well as…

… from a file

doc/LAYOUTSCRIPT.md

@@ -112,7 +112,7 @@ terminate called after throwing an instance of 'std::runtime_error'
 ```
 as you can see, the tokeniser has correctly identified my syntax error, and shows precisely where in the original `widgets_demo.sls` file it occurred, along with a preview.
 
-when a parsing exception like this occurs, you may catch it in order to show an error message to the user and exit gracefully, but the return value of `readPage` will be `nullptr`, so don't try to access anything on it.
+when a parsing exception like this occurs, you may catch it in order to show an error message to the user and exit gracefully, but the return value of `readPageFromFile` will be `nullptr`, so don't try to access anything on it.
 
 there are lots of different types of errors which can be thrown, so below is a table of all of them, what stage they happen, and what the message actually means in a little more detail.
 

doc/TODO.md

@@ -1,10 +1,10 @@
 # To-Dos
 
 - [ ] add editable text area component
+- [ ] fix actual_offset in tree view
 
 # v0.4
 - [ ] documentation and examples for LayoutScript
-- [ ] fix actual_offset in tree view
 - [x] better handling of object deletion within pages
 - [x] implement LayoutScript reading from file
 - [x] correct consistency of '*'s at end of comments

examples/compiler_tool_ls.cpp

@@ -246,7 +246,7 @@ int main()
     Terminal::configure("compiler tool", 1.0f);
 
     LayoutReader reader;
-    main_page = reader.readPage("examples/layoutscripts/compiler_tool.sls");
+    main_page = reader.readPageFromFile("examples/layoutscripts/compiler_tool.sls");
     selected_input_files = main_page->get<ListView>("selected_input_files");
     output_file = main_page->get<TextInputBox>("output_file");
     compiler_selection = main_page->get<RadioButton>("compiler_selection");

examples/page_usage_ls.cpp

@@ -29,7 +29,7 @@ int main()
 
     LayoutReader reader;
 
-    Page* page = reader.readPage("examples/layoutscripts/page_usage.sls");
+    Page* page = reader.readPageFromFile("examples/layoutscripts/page_usage.sls");
     text_widget = page->get<Label>("text_widget");
     text_field = page->get<TextInputBox>("text_field");
     text_field->callback = textBoxCallback;

examples/script_demo.cpp

@@ -9,7 +9,7 @@ int main()
     Terminal::configure("script test", 0.5f);
 
     LayoutReader reader;
-    Page* pg = reader.readPage("demo.sls");
+    Page* pg = reader.readPageFromFile("demo.sls");
     if (!pg) return 1;
 
     pg->get<ProgressBar>("progress_bar")->fraction = 0.99f;

examples/widgets_demo_ls.cpp

@@ -15,7 +15,7 @@ int main(int argc, char** argv)
     stui::Terminal::configure();
 
     stui::LayoutReader reader;
-    stui::Page* page = reader.readPage("examples/layoutscripts/widgets_demo.sls");
+    stui::Page* page = reader.readPageFromFile("examples/layoutscripts/widgets_demo.sls");
 
     stui::Label* t1 = page->get<stui::Label>("t1");
     stui::Spinner* s1 = page->get<stui::Spinner>("s1");

inc/stui_script.h

@@ -848,7 +848,23 @@ class LayoutReader
      * @returns a `Page` fully constructed with all of the components
      * specified in the file, or `nullptr` if the file was not readable
      */
-    Page* readPage(string file);
+    Page* readPageFromFile(string file);
+
+    /**
+     * @brief reads a `Page` of STUI LayoutScript from a raw block of
+     * LayoutScript code.
+     * 
+     * since the `Component`s in the page are constructed using `new`
+     * at runtime, you **MUST** call `destroyAllComponents` on the
+     * page when you're done using it.
+     * 
+     * throws an exception if a syntax error is found.
+     * 
+     * @param content LayoutScript code to translate into a `Page`
+     * @returns a `Page` fully constructed with all of the components
+     * specified in the content, or `nullptr`
+     */
+    Page* readPage(string content);
 
     ~LayoutReader();
 
@@ -1080,7 +1096,7 @@ void LayoutReader::registerBuilder(ComponentBuilder* builder)
     builders.emplace(name, builder);
 }
 
-Page* LayoutReader::readPage(string file)
+Page* LayoutReader::readPageFromFile(string file)
 {
     ifstream file_data(file, ifstream::ate);
     if (!file_data.is_open())
@@ -1099,10 +1115,15 @@ Page* LayoutReader::readPage(string file)
 
     DEBUG_LOG("loaded " + to_string(file_content.size()) + " chars of script from " + file);
 
+    return readPage(file_content);
+}
+
+Page* LayoutReader::readPage(string content)
+{
     vector<Token> tokens;
     try
     {
-        tokens = tokenise(file_content);
+        tokens = tokenise(content);
     }
     catch (const runtime_error& e)
     {
@@ -1121,19 +1142,19 @@ Page* LayoutReader::readPage(string file)
 
     if (pruned_tokens.size() < 3)
     {
-        reportError("the LayoutScript file must contain at least one complete Component", 0, file_content);
+        reportError("the LayoutScript file must contain at least one complete Component", 0, content);
     }
 
     if (pruned_tokens[0].type != TokenType::TEXT)
     {
-        reportError("the LayoutScript file must begin with a Component definition", 0, file_content);
+        reportError("the LayoutScript file must begin with a Component definition", 0, content);
     }
 
     Page* page = new Page();
 
     try
     {
-        Component* root = parseComponent(pruned_tokens, 0, file_content, page);
+        Component* root = parseComponent(pruned_tokens, 0, content, page);
         page->setRoot(root);
     }
     catch (const runtime_error& e)
@@ -1144,7 +1165,7 @@ Page* LayoutReader::readPage(string file)
         throw runtime_error(e.what());
     }
 
-    DEBUG_LOG("successfully built a UI tree of " + to_string(page->getAllComponents().size()) + " components from file " + file);
+    DEBUG_LOG("successfully built a UI tree of " + to_string(page->getAllComponents().size()) + " components");
 
     return page;
 }