Merge pull request #7 from ChapelR/v1.0.1-pre

v1.0.1

build.js

@@ -13,6 +13,7 @@ const scriptName = 'Harlowe Macro Framework',
     src = 'src/',
     dist = 'dist/macro.min.js',
     examples = 'examples/',
+    thirdp = 'examples/third-party/',
     binary = 'harlowe-macro-api.zip';
 
 const files = [
@@ -53,11 +54,14 @@ function build (list, path, output) {
 
 }
 
-function minifyExamples (ex) {
+function minifyExamples (ex, tp) {
     const jsFiles = jetpack.find(ex, {
         matching : '*.js',
         recursive : false
-    });
+    }).concat(jetpack.find(tp, {
+        matching : '*.js',
+        recursive : false
+    }));
 
     jsFiles.forEach( function (file) {
         const source = jetpack.read(file);
@@ -129,6 +133,6 @@ function zipUp (path, output) {
 }
 
 build(files, src, dist);
-minifyExamples(examples);
+minifyExamples(examples, thirdp);
 minifyCSS(examples);
 zipUp(dist, binary);

docs/changelog.md

@@ -1,5 +1,12 @@
 ## Release Versions
 
+### v1.0.1
+
+- **[Examples]** Added more examples:
+  - `(notify:)` A port of the CMFSC2 `<<notify>>` macro.
+  - `(macro:)` A widget-style macro passage system for Harlowe by rachek64.
+- **[Docs]** Documented example macros.
+
 ### v1.0.0
 
 - **[Update]** Changed `Harlowe.version` to `Harlowe.framework` to alleviate any confusion with `Harlowe.engine`.

docs/download/fetch.js

@@ -4,6 +4,7 @@
     var mainFile = 'https://cdn.jsdelivr.net/gh/chapelr/harlowe-macro-api@latest/dist/macro.min.js';
 
     var baseURL = 'https://cdn.jsdelivr.net/gh/chapelr/harlowe-macro-api@latest/examples/minified/';
+    var tpURL = 'https://cdn.jsdelivr.net/gh/chapelr/harlowe-macro-api@latest/examples/third-party/minified/';
     var extension = '.min.js';
     var extensionCSS = '.min.css';
 
@@ -12,11 +13,13 @@
         'Articles' : 'articles',
         'Clamp': 'clamp',
         'Dialog' : 'dialog+css',
+        'Notify' : 'notify+css',
         'Dice': 'dice',
         'Hotkeys': 'hotkeys',
         'Playtime': 'playtime',
         'Speech Box': 'speechbox+css',
-        'Textbox': 'textbox'
+        'Textbox': 'textbox',
+        'Macro Passages (by rachek64)': '~macro-passages'
     };
 
     var macros = Object.keys(fileNameMap);
@@ -35,7 +38,11 @@
                 fn = fn.split('+')[0];
                 files.push(baseURL + fn + extensionCSS);
             }
-            files.push(baseURL + fn + extension);
+            if (fn[0] === '~') {
+                files.push(tpURL + fn.substr(1) + extension);
+            } else {
+                files.push(baseURL + fn + extension); 
+            }
         });
         return [ mainFile ].concat(files);
     }

docs/examples/macro-passages.md

@@ -0,0 +1,75 @@
+## Macro Passages
+
+By [rachek64](https://github.com/rachek64).
+
+Allows you to run passages inline, similar to `(display:)`, but with no output and with the option of passing arguments to the passage, similar to SugarCube's widgets.
+
+> **Get the Code**
+>
+> - [Minified](https://github.com/ChapelR/harlowe-macro-api/blob/master/examples/third-party/minified/macro-passages.min.js) 
+> - [Pretty](https://github.com/ChapelR/harlowe-macro-api/blob/master/examples/third-party/macro-passages.js)
+
+### Macro: `(macro:)`
+
+Runs a macro passage, defined by adding the `macro` tag to a passage. If you add both the `macro` tag and the `auto-macro` tag, a first-class, named macro will be created.
+
+#### Syntax
+
+```
+(macro: passage [, argsList])
+```
+
+#### Arguments
+
+- `passage` ( *`string`* ) The name of a passage with the tag `macro`. The passage's code will be run with the given arguments.
+- `args` ( *`any`* ) ( optional ) Arguments to be passed on to the passage, which may be accessed as an array using the temporary variable `_args`. Just list arguments separated by commas after the passage name.
+
+#### Returns
+
+Optionally returns the value given to the `_result` temporary variable, or nothing.
+
+#### Examples
+
+```
+:: damage [macro]
+<!-- reduces the player HP by the given number -->
+(set: $player's hp to it - _args's 1st)
+(if: $player's hp <= 0)[
+	(goto: 'game over')
+]
+
+:: some passage
+The enemy attacks!
+(macro: 'damage', $enemy's attack)
+You take (print: $enemy's attack) damage and have (print: $player's hp) health remaining.
+
+:: say-hi [macro auto-macro]
+<!-- using the `auto-macro` tag makes a standalone custom macro! -->
+(set: _result to 'Hi, ' + _args's 1st + '.')
+
+:: some other passage
+(alert: (say-hi: 'Bob')) <!-- alerts "Hi, Bob." -->
+```
+
+### Additional Usage Notes
+
+* The entire macro-tagged passage should run at once (i.e., no `(prompt:)`, `(live:)`, or similar "delayed" commands) and they cannot display any output. This is suitable for code-only macros that perform complex calculations or automate repetitive tasks. If you need to print results, just return the results from the macro with `_result` and print it outside.
+* No text is displayed while running the macro passage, nor can it have any
+direct effect on the caller passage. The contents are rendered into a
+dummy screen that is never shown on the page.
+* This means you can nicely comment your macro with plain text. No need to use `{}`
+  or worry about line breaks or spacing.
+* This also means no user input is possible. If you render a link to click,
+  it will never be able to be clicked. The macro will complete assuming the link
+  wasn't clicked.
+* User input in general is not possible in macro-tagged passages, nor can you run
+asynchronous commands like (alert:) that pause the passage until you interact
+with them. No errors will happen, but the value in `_result` may not be
+picked up properly if it was changed after the delaying command was used.
+* Saving and loading from inside a macro is, in general, a terrible idea. Just don't do it.
+* Argument type checking is not possible at this time. If a macro takes arguments,
+thoroughly inspect `_args` before attempting to use them.
+* Unfortunately, errors in macro passages are handled a bit oddly. Error details
+are provided as best as possible, but so far as Harlowe is concerned the error
+occurred in the caller passage. Check the dropdown in the error bubble for the
+actual line that triggered the error.

docs/examples/main.md

@@ -15,6 +15,8 @@ The following are some example macros created by me using this framework. They'r
 - [Dialog](/examples/dialog.md)
 - [Clamp](/examples/clamp.md)
 - [Achievements](/examples/achievements.md)
+- [Notify](/examples/notify.md)
+- [Macro Passages](/examples/macro-passages.md) (by [rachek64](https://github.com/rachek64))
 
 ## Installation
 

docs/examples/notify.md

@@ -0,0 +1,47 @@
+## Notify
+
+Creates a quick user notification that rolls out from the top right of the screen, hangs for a minute, and rolls back in, useful for a quick note about status updates, achievements, or whatever else when a dialog box is a bit too much. Ported over from the similar CMFSC2 macro.
+
+> - **Get the Code**
+>
+>   - [Minified](https://github.com/ChapelR/harlowe-macro-api/blob/master/examples/minified/notify.min.js) 
+>   - [Pretty](https://github.com/ChapelR/harlowe-macro-api/blob/master/examples/notify.js)
+> - **Required CSS**
+>   - [Minified](https://github.com/ChapelR/harlowe-macro-api/blob/master/examples/minified/notify.min.css) 
+>   - [Pretty](https://github.com/ChapelR/harlowe-macro-api/blob/master/examples/notify.css)
+
+### Macro: `(notify:)`
+
+Creates and displays a quick notification and renders the content of the associated hook into it.
+
+#### Syntax
+
+```
+(notify: [delay] [, classList])[ ... ]
+```
+
+#### Arguments
+
+- `delay` ( *`time`* ) ( optional ) A CSS-style time value (e.g., `5s`, `500ms`) for controlling how long the notification should remain. A short animation plays before and after this delay. Defaults to two seconds.
+- `classList` ( *`string`* | *`string array`* ) ( optional ) You may pass a single string of space separated class names (e.g. `"my-class another-class a-third-class"`), an array of strings, or simply list several different strings as arguments to the macro to have them added to the `#notify` element for styling. You must include a delay time to add classes
+
+#### Returns
+
+Nothing.
+
+#### Examples
+
+```
+<!-- a two second, basic notification -->
+(notify:)[Inventory updated.]
+
+<!-- a ten second long notification with a custom class -->
+(notify: '10s', 'my-class')[Achievement unlocked.]
+
+<!-- a five second notification -->
+(notify: '5000ms')[Gold earned.]
+```
+
+#### Note
+
+Giving the player unlimited control over these notifications, or trying to show several at once or right after each other will cause them to trip over themselves as they try to animate, so try to keep them spaced out, and don't assign them to links or buttons you expect the player to press repeatedly.