Add support for "looping" a presentation

Author: kgryte

lib/node_modules/@stdlib/repl/data/help.csv

@@ -24,7 +24,7 @@ load,"\nload( fpath )\n    Loads and evaluates a JavaScript file, such as a REPL
 loadWorkspace,"\nloadWorkspace( name[, options] )\n    Loads variables from a specified workspace into the current workspace.\n\n    Parameters\n    ----------\n    name: string\n        Workspace name.\n\n    options: Object (optional)\n    	Options.\n\n    options.include: RegExp|ArrayLikeObject (optional)\n    	Variable name inclusion filter.\n\n    options.exclude: RegExp|ArrayLikeObject (optional)\n    	Variable name exclusion filter.\n\n    options.override: boolean (optional)\n    	Boolean indicating whether to override existing workspace variables.\n        Default: true.\n\n    Examples\n    --------\n    > workspace( 'foobar' );\n    > var x = 3.14;\n    > workspace( 'barfoo' );\n    > typeof x\n    > loadWorkspace( 'foobar' );\n    > x\n\n    See Also\n    --------\n    vars, varsWorkspace, workspace, workspaces\n\n"
 logStart,"\nlogStart( fpath )\n    Starts logging commands and printed output to a specified file path.\n\n    Parameters\n    ----------\n    fpath: string\n        File path.\n\n    Returns\n    -------\n    id: number\n        Record identifier.\n\n    Examples\n    --------\n    > var id = logStart( './path/to/file.txt' );\n    > 1 + 1\n    2\n    > 'foo'\n    'foo'\n    > logStop( id );\n\n    See Also\n    --------\n    logStop\n\n"
 logStop,"\nlogStop( id )\n    Stops logging commands and printed output to a file path associated with a\n    specified record identifier.\n\n    Parameters\n    ----------\n    id: number\n        Record identifier.\n\n    Returns\n    -------\n    bool: boolean\n        Boolean indicating whether the REPL successfully stopped logging\n        evaluated commands.\n\n    Examples\n    --------\n    > var id = logStart( './path/to/file.txt' );\n    > 1 + 1\n    2\n    > 'foo'\n    'foo'\n    > logStop( id );\n\n    See Also\n    --------\n    logfileStart\n\n"
-presentationStart,"\npresentationStart( [text, ][options] )\n    Starts a REPL presentation.\n\n    When not provided presentation text, an options argument must specify a\n    presentation file to load.\n\n    If a specified workspace already exists, the workspace is silently cleared\n    and a new presentation bound. In order to preserve an existing workspace,\n    specify an alternative presentation workspace name.\n\n    Parameters\n    ----------\n    text: string (optional)\n        Presentation text.\n\n    options: Object (optional)\n        Presentation options.\n\n    options.borderTop: string (optional)\n        Top border character sequence. Default: '*'.\n\n    options.borderBottom: string (optional)\n        Bottom border character sequence. Default: '*'.\n\n    options.borderLeft: string (optional)\n        Left border character sequence. Default: '* '.\n\n    options.borderRight: string (optional)\n        Right border character sequence. Default: ' *'.\n\n    options.counter: string|boolean (optional)\n        Slide counter. If `true`, each slide displays a slide counter. If set to\n        'progress', each slide displays a progress counter. If `false`, no\n        counter is displayed. Default: false.\n\n    options.width: integer|null (optional)\n        Presentation width. If `null`, the presentation width is either computed\n        based on the screen size (if a REPL output stream is TTY) or set to `80`\n        characters. Default: null.\n\n    options.height: integer|null (optional)\n        Presentation height. If `null`, the presentation height is either\n        computed based on the screen size (if a REPL output stream is TTY) or\n        set to `25` rows. Default: null.\n\n    options.workspace: string (optional)\n        REPL workspace name. A presentation adds commands to the specified\n        workspace, thus allowing presentation navigation and interaction.\n        Default: `'presentation-<n>'`, where `n` is an assigned presentation\n        identifier.\n\n    options.load: string (optional)\n        File path specifying a presentation file to load. If presentation text\n        is provided, this option is ignored. Otherwise, this option is required.\n\n    options.watch: boolean (optional)\n        Boolean indicating whether to watch a presentation source file for\n        changes. This option is only applicable if not provided presentation\n        text and the options object specifies a presentation file to load.\n        Default: false.\n\n    options.autoClear: boolean (optional)\n        Boolean indicating whether to automatically clear the screen before\n        writing a rendered slide to the REPL. Default: true.\n\n    Returns\n    -------\n    id: integer\n        Presentation identifier.\n\n    Examples\n    --------\n    > var id = presentationStart( 'beep\n---boop\n' );\n\n    See Also\n    --------\n    presentationStop, workspace, workspaces\n\n"
+presentationStart,"\npresentationStart( [text, ][options] )\n    Starts a REPL presentation.\n\n    When not provided presentation text, an options argument must specify a\n    presentation file to load.\n\n    If a specified workspace already exists, the workspace is silently cleared\n    and a new presentation bound. In order to preserve an existing workspace,\n    specify an alternative presentation workspace name.\n\n    Parameters\n    ----------\n    text: string (optional)\n        Presentation text.\n\n    options: Object (optional)\n        Presentation options.\n\n    options.borderTop: string (optional)\n        Top border character sequence. Default: '*'.\n\n    options.borderBottom: string (optional)\n        Bottom border character sequence. Default: '*'.\n\n    options.borderLeft: string (optional)\n        Left border character sequence. Default: '* '.\n\n    options.borderRight: string (optional)\n        Right border character sequence. Default: ' *'.\n\n    options.counter: string|boolean (optional)\n        Slide counter. If `true`, each slide displays a slide counter. If set to\n        'progress', each slide displays a progress counter. If `false`, no\n        counter is displayed. Default: false.\n\n    options.width: integer|null (optional)\n        Presentation width. If `null`, the presentation width is either computed\n        based on the screen size (if a REPL output stream is TTY) or set to `80`\n        characters. Default: null.\n\n    options.height: integer|null (optional)\n        Presentation height. If `null`, the presentation height is either\n        computed based on the screen size (if a REPL output stream is TTY) or\n        set to `25` rows. Default: null.\n\n    options.workspace: string (optional)\n        REPL workspace name. A presentation adds commands to the specified\n        workspace, thus allowing presentation navigation and interaction.\n        Default: `'presentation-<n>'`, where `n` is an assigned presentation\n        identifier.\n\n    options.load: string (optional)\n        File path specifying a presentation file to load. If presentation text\n        is provided, this option is ignored. Otherwise, this option is required.\n\n    options.watch: boolean (optional)\n        Boolean indicating whether to watch a presentation source file for\n        changes. This option is only applicable if not provided presentation\n        text and the options object specifies a presentation file to load.\n        Default: false.\n\n    options.autoClear: boolean (optional)\n        Boolean indicating whether to automatically clear the screen before\n        writing a rendered slide to the REPL. Default: true.\n\n    options.loop: boolean (optional)\n        Boolean indicating whether to \"loop\" a presentation. Default: false.\n\n    Returns\n    -------\n    id: integer\n        Presentation identifier.\n\n    Examples\n    --------\n    > var id = presentationStart( 'beep\n---boop\n' );\n\n    See Also\n    --------\n    presentationStop, workspace, workspaces\n\n"
 presentationStop,"\npresentationStop( [id] )\n    Stops a REPL presentation.\n\n    If provided a presentation identifier, the corresponding presentation is\n    stopped. Otherwise, assuming the command is invoked in a presentation\n    workspace, the current presentation is stopped.\n\n    When stopping a REPL presentation, the presentation's REPL workspace is\n    both cleared and deleted.\n\n    Parameters\n    ----------\n    id: number|string (optional)\n        Presentation identifier. Must be provided if not currently in a\n        presentation workspace.\n\n    Returns\n    -------\n    bool: boolean\n        Boolean indicating whether the REPL successfully stopped a REPL\n        presentation.\n\n    Examples\n    --------\n    > var id = presentationStart( 'beep\n---\nboop\n' );\n    > presentationStop();\n\n    See Also\n    --------\n    presentationStart, workspace, workspaces\n\n"
 quit,"\nquit()\n    Exits the REPL.\n\n    Examples\n    --------\n    > quit()\n\n    See Also\n    --------\n    clear, save\n\n"
 renameWorkspace,"\nrenameWorkspace( oldName, newName )\n    Renames a workspace.\n\n    The new workspace name must not already exist. The only exception is when\n    the old name and the new name are the same; in which case, invoking this\n    function is a non-operation.\n\n    As a 'base' workspace must always exist, when renaming the 'base' workspace,\n    variables from the 'base' workspace are simply copied to a new workspace and\n    the 'base' workspace cleared of user-defined variables.\n\n    Parameters\n    ----------\n    oldName: string\n        Name of workspace to rename.\n\n    newName: string\n        New workspace name.\n\n    Examples\n    --------\n    // Create a new workspace:\n    > workspace( 'foobar' );\n    > var x = 3.14;\n\n    // List current workspaces:\n    > workspaces()\n\n    // Switch to another workspace:\n    > workspace( 'barfoo' );\n\n    // List current workspaces:\n    > workspaces()\n\n    // Rename the first workspace:\n    > renameWorkspace( 'foobar', 'beepboop' );\n\n    // Check the updated list of workspaces:\n    > workspaces()\n\n    // Switch to the renamed workspace:\n    > workspace( 'beepboop' );\n\n    // Confirm that workspace contains previously defined variables:\n    > x\n\n\n    See Also\n    --------\n    currentWorkspace, deleteWorkspace, loadWorkspace, workspace, workspaces\n\n"

lib/node_modules/@stdlib/repl/data/help.json

@@ -64,6 +64,9 @@ presentationStart( [text, ][options] )
         Boolean indicating whether to automatically clear the screen before
         writing a rendered slide to the REPL. Default: true.
 
+    options.loop: boolean (optional)
+        Boolean indicating whether to "loop" a presentation. Default: false.
+
     Returns
     -------
     id: integer

lib/node_modules/@stdlib/repl/docs/commands/presentation_start.txt

@@ -305,6 +305,7 @@ The function accepts the following `options`:
 -   **workspace**: [REPL][@stdlib/repl] workspace name. A presentation instance adds presentation commands to the specified workspace, thus allowing presentation navigation and interaction. Default: `'presentation'`.
 -   **load**: file path specifying a presentation file to load. If a presentation `text` is provided, this option is **ignored**.
 -   **autoClear**: `boolean` indicating whether to automatically clear the screen before writing a rendered slide to the [REPL][@stdlib/repl]. Default: `true`.
+-   **loop**: `boolean` indicating whether to "loop" a presentation (i.e., proceed to the first slide after the last slide and have the last slide precede the first slide). Default: `false`.
 
 To initialize a presentation upon instantiating a `Presentation` instance, **either** provide a `string` as the first argument containing the presentation text to render **or** set the `load` option to specify a presentation file to load.
 
@@ -1449,6 +1450,7 @@ Options:
       --timeout <timeout>       Milliseconds before terminating a command.
       --quiet                   Disable printing of REPL logs and diagnostics.
       --no-autoclear            Disable automatic clearing when rendering.
+      --loop                    Loop a presentation.
       --watch                   Watch the source presentation file for changes.
 ```
 

lib/node_modules/@stdlib/repl/presentation/README.md

@@ -130,6 +130,9 @@ function main() {
 	if ( flags.autoclear === false ) {
 		opts2.autoClear = flags.autoclear;
 	}
+	if ( flags.loop ) {
+		opts2.loop = flags.loop;
+	}
 	// Check if we are receiving data from `stdin`...
 	if ( !process.stdin.isTTY ) {
 		if ( IS_WINDOWS ) {

lib/node_modules/@stdlib/repl/presentation/bin/cli

@@ -21,5 +21,6 @@ Options:
       --timeout <timeout>       Milliseconds before terminating a command.
       --quiet                   Disable printing of REPL logs and diagnostics.
       --no-autoclear            Disable automatic clearing when rendering.
+      --loop                    Loop a presentation.
       --watch                   Watch the source presentation file for changes.
 

lib/node_modules/@stdlib/repl/presentation/docs/usage.txt

@@ -20,6 +20,7 @@
 		"version",
 		"quiet",
 		"no-autoclear",
+		"loop",
 		"watch"
 	],
 	"alias": {

lib/node_modules/@stdlib/repl/presentation/etc/cli_opts.json

@@ -38,7 +38,8 @@ function defaults() {
 		'height': null,
 		'counter': false,
 		'workspace': 'presentation',
-		'autoClear': true
+		'autoClear': true,
+		'loop': false
 	};
 	return options;
 }

lib/node_modules/@stdlib/repl/presentation/lib/defaults.js

@@ -33,6 +33,7 @@ var setNonEnumerableReadOnly = require( '@stdlib/utils/define-nonenumerable-read
 var setNonEnumerableReadOnlyAccessor = require( '@stdlib/utils/define-nonenumerable-read-only-accessor' ); // eslint-disable-line id-length
 var setNonEnumerable = require( '@stdlib/utils/define-nonenumerable-property' );
 var clamp = require( '@stdlib/math/base/special/clamp' );
+var wrap = require( '@stdlib/math/base/special/wrap' );
 var readFile = require( '@stdlib/fs/read-file' ).sync;
 var repeat = require( '@stdlib/string/repeat' );
 var constructorName = require( '@stdlib/utils/constructor-name' );
@@ -76,6 +77,7 @@ var DEFAULT_HEIGHT = 25;
 * @param {string} [options.workspace="presentation"] - REPL workspace name
 * @param {string} [options.load] - file path specifying a presentation file to load
 * @param {boolean} [options.autoClear=true] - boolean indicating whether to automatically clear the screen before writing a rendered slide to the REPL
+* @param {boolean} [options.loop=false] - boolean indicating whether to "loop" a presentation
 * @throws {Error} must provide a REPL instance
 * @throws {TypeError} presentation text argument must be a string
 * @throws {TypeError} REPL argument must be a REPL instance
@@ -243,9 +245,13 @@ setNonEnumerableReadOnly( Presentation.prototype, '_select', function select( n,
 	var fc;
 	var N;
 
-	// Limit the slide cursor range to one position before/after the first/last slide in order to avoid multiple previous/next calls moving the cursors indefinitely away from the slide deck...
+	// Limit the slide cursor range in order to avoid multiple previous/next calls moving the cursors indefinitely away from the slide deck...
 	N = this.length;
-	sc = clamp( n, -1, N );
+	if ( this._opts.loop ) {
+		sc = wrap( n, 0, N );
+	} else {
+		sc = clamp( n, -1, N );
+	}
 	if ( sc === -1 || sc === N ) {
 		debug( 'Unable to select slide. Slide cursor out-of-range.' );
 		this._slide = null;

lib/node_modules/@stdlib/repl/presentation/lib/main.js

@@ -45,6 +45,7 @@ var isPositiveInteger = require( '@stdlib/assert/is-positive-integer' ).isPrimit
 * @param {string} [options.workspace] - REPL workspace name
 * @param {string} [options.load] - file path specifying a presentation file to load
 * @param {boolean} [options.autoClear] - boolean indicating whether to automatically clear the screen before writing a rendered slide to the REPL
+* @param {boolean} [options.loop] - boolean indicating whether to "loop" a presentation
 * @throws {Error} must provide valid options
 * @returns {(Error|null)} error or null
 *
@@ -122,6 +123,12 @@ function validate( opts, options ) {
 			return new TypeError( 'invalid option. `autoClear` option must be a boolean. Option: `' + options.autoClear + '`.' );
 		}
 	}
+	if ( hasOwnProp( options, 'loop' ) ) {
+		opts.loop = options.loop;
+		if ( !isBoolean( options.loop ) ) {
+			return new TypeError( 'invalid option. `loop` option must be a boolean. Option: `' + options.loop + '`.' );
+		}
+	}
 	return null;
 }