docs

docs/api.md

@@ -1,60 +1,158 @@
 # Meld-Build API
 
-_TODO_
-
-## Logging
-
-_TODO_
+## The Context Object (`$`)
+- `$.data[<name>]`
+	- Used to access imported Markdown table data.
+	- The `<name>` will be the previous header to the table in the note.
+	- Use `await $.log($.data);` to discover the data object.
+	- e.g. if you had a header `# My Customers` before a markdown table, `$.data.my_customers` would return an array of that table.
+- `$.blocks[]`
+	- An array of non-`meld-build` codeblocks
+	- Can be used as templates
+	- e.g. `$.blocks.at(0)` would return the first non-`meld-build` codeblock.
+- `await $.log(...params)`
+	- Along with the standard `console` functions, you can use the `$.log()` function to log things.
+- `await $.logger.set_file(filepath)`
+	- To send log messages to a file, you can first use `$.logger.set_file('Log.md');`.
+	- Note: The file will be overwritten.
+- `await $.logger.info(...params)`
+	- logs an `info` message to the console and to a file if set.
+- `await $.logger.error(...params)`
+	- logs an `error` message to the console and to a file if set.
+- `$.render( template, data )`
+	- Uses Handlebars to render the given template with the given data object.
+	- e.g. `const result = $.render( 'Hello {{name}}', {name:'World'} );`
 
 ### Examples
-````
-```js
-console.log('test logging to console');
+```js meld-build
+// console log, info, debug, error etc
+console.log('standard logging to console');
+
+// also logs to the console
+await $.log('this is $.log logging');
+
+// you can set a file to send log messages to
 await $.logger.set_file('Run Log.md');
+
+// now these log messages will be sent to the console and to 'Run log.md'
 await $.log('test logging via $.log');
-await $.logger.info('1','2',[3,4], 5);
+await $.log('1','2',[3,4], 5);
 ```
-````
 
-## UI
+## User Interaction (`$.ui`)
 
-_TODO_
+- `$.ui.notice( msg, seconds? )`
+	- Show a notice for x seconds (defaults to 5s)
+- `await $.ui.ask( question, option_list[]? )`
+	- Ask the user a question and return the result
+	- If `option_list` is provided then a dropdown is used otherwise the user can enter a short text answer
+- `await $.ui.ask( title, question, option_list[]? )`
+	- Ask a question with a title
+- `await $.ui.message( msg )`
+	- Show a message box
+- `await $.ui.message( title, msg )`
+	- Show a message box with a title
+- `await $.ui.rebuild()`
+	- Rebuild the current view, may be needed if you have an embedded note which was modified
 
 ### Examples
-````
-```js
-// Notice
+```js meld-build
+// Show a notice
 $.ui.notice('test notice');
+// Show a notice for 2 seconds
 $.ui.notice('test notice for 2s', 2);
 
-// ask
-const ans1 = await $.ui.ask( 'question 1' );
-const ans2 = await $.ui.ask( 'question 2', ['1', '2', '3'] );
+// ask for a simple text answer
+const ans1 = await $.ui.ask( "What's your age?" );
+
+// ask for an answer from a set list of options
+const ans2 = await $.ui.ask( 'Please select a number', ['1', '2', '3'] );
+
+// Titled questions
 const ans3 = await $.ui.ask( 'Title', 'question 3' );
 const ans4 = await $.ui.ask( 'Title', 'question 4', ['1', '2', '3'] );
 
-// message
+// show a message
 await $.ui.message( `Your answers were:\n\n${ans1}, ${ans2}, ${ans3}, ${ans4}` );
-// message with title
-await $.ui.message( 'A Title', 'A titled <b>message</b>' );
-// number message
-$.ui.message('Math', 13 * 67 );
 
-// reload view
+// show a message with title
+await $.ui.message( 'A Title', 'A titled <b>message</b>' );
+await $.ui.message( 'Math', 13 * 67 );
+
+// rebuild the current view, may be needed if you have an embedded note which was modified
 await $.ui.rebuild();
 ```
-````
 
-## IO
+## Input/Output (`$.io`)
+
+Read and write vault files.
+
+- `const success = await $.io.import( path )`
+	- Import data and blocks from another file
+- `const content = await $.io.load( path )`
+	- Return the contents of a file
+- `const data = await $.io.load_data( path, name? )`
+	- Load any tables from another file and add it to `$.data[]`
+	- The loaded data is also returned
+- `const dataurl = await $.io.load_data_url( path, mimetype? )`
+	- Encode the contents of a file into a dataurl for use in a template
+	- Optionaly specify the mime type.
+	- Auto mime type mappings are available for the following file extensions: `.jpg`, `.png`, `.gif`, `.svg`, `.css`
+- `await $.io.output( file, content, open? )`
+	- (Over)Writes the `file` with given `content`
+	- Tries to open the `file` if `open` is true (false by default)
+	> WARNING: be careful with `$.io.output` which will overwrite your files.
+- `await $.io.open( linktext )`
+	- Tries to open `linktext`
+- `await $.io.delete( file )`
+	- Sends the `file` to the trash
+	> WARNING: be careful with `$.io.delete`, although the deleted file is sent to the trash so it _might_ be recoverable.
 
-_TODO_
 
 ### Examples
-````
-```js
-await $.io.import('some other file.md')
-const dataurl = await $.io.load_data_url('logo.png');
-$.log(dataurl.length);
-```
-````
+```js meld-build
+// import data and blocks from another file
+const success = await $.io.import('some other file.md');
 
+// load the contents of a file into a variable
+const fileContents = await $.load('my-template.html');
+
+// encode the contents of a file to a dataurl for use in a template
+const logo_dataurl = await $.io.load_data_url('logo.png');
+const css_dataurl = await $.io.load_data_url('styles.css');
+
+// save data to a file
+await $.io.output( 'My Dynamic Note.md', '# Title\n- 1\n- 2\n- 3\n' );
+// save data to a file and open it
+await $.io.output( 'My Basic Note.md', '# Title\nHello there', true );
+
+// open a file
+await $.io.open( 'output/index.html' );
+
+// send a file to the trash
+await $.io.delete( 'output/index.html' );
+```
+
+## Assert (`$.assert`)
+
+You can use `$.assert` to stop the run and show a message if a test fails.
+
+- `await $.assert.isDefined( value, label? )`;
+	- Stop the run and show a message if value is `undefined` or `null`
+	- Label is an optional short label to include with a fail message
+- `await $.assert.isTrue( value, label? )`;
+	- Stop the run and show a message if value is `falsy`
+- `await $.assert.isFalse( value, label? )`;
+	- Stop the run and show a message if value is `truthy`
+- `await $.assert.eq( expected, actual, label? )`;
+	- Stop the run and show a message if `expected` is not equal to `actual`
+- `await $.assert.neq( expected, actual, label? )`;
+	- Stop the run and show a message if `expected` is equal to `actual`
+
+### Examples
+```js meld-build
+const template = $.blocks.at(1);
+// will stop with a message if there is no 2nd block
+await $.assert.isDefined( template, 'template' );
+
+```

docs/user-guide.md

@@ -1,6 +1,6 @@
 # User Guide
 
-The Meld-Build plugin can be used to turn a note into a small, simple, application.
+The Meld-Build plugin can be used to turn a note into a small, simple, runnable thing.
 
 For example, here is a JavaScript codeblock which will display a message box with the result of a simple calculation:
 ````md

src/run-context.ts

@@ -49,9 +49,9 @@ export type TIoRunContext = {
 }
 
 export type TAssertRunContext = {
-	isDefined( value:any, label?:string  ) : Promise<void>;
-	isTrue( value:any, label?:string  ) : Promise<void>;
-	isFalse( value:any, label?:string  ) : Promise<void>;
+	isDefined( value:any, label?:string ) : Promise<void>;
+	isTrue( value:any, label?:string ) : Promise<void>;
+	isFalse( value:any, label?:string ) : Promise<void>;
 	eq( expected:any, actual:any, label?:string ) : Promise<void>;
 	neq( expected:any, actual:any, label?:string ) : Promise<void>;
 }