### Example: list installed packages Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/pkgs/installed/README.md Complete example that requires the module and lists installed packages using the default options. ```javascript var pkgs = require( '@stdlib/_tools/pkgs/installed' ); pkgs( onPkgs ); function onPkgs( error, list ) { if ( error ) { throw error; } console.dir( list ); } ``` -------------------------------- ### Example: Run dmax examples Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of running examples for the moved dmax package. ```bash make examples EXAMPLES_FILTER=".*/stats/strided/dmax/.*" ``` -------------------------------- ### Run examples Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Run the package's examples using the examples filter. Replace path/to/new/package with the new package path. ```bash make examples EXAMPLES_FILTER=".*/path/to/new/package/.*" ``` -------------------------------- ### Example: Compile and run dmax C examples Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of compiling and running C examples for the moved dmax package. ```bash make examples-c EXAMPLES_FILTER=".*/stats/strided/dmax/.*" ``` -------------------------------- ### Example: Run dmax benchmarks Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of running benchmarks for the moved dmax package. ```bash make benchmark BENCHMARKS_FILTER=".*/stats/strided/dmax/.*" ``` -------------------------------- ### CLI example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/info/README.md Example command to get info for 'base.sin'. ```bash $ stdlib-alias-info 'base.sin' ``` -------------------------------- ### Install dependencies with make install Source: https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md Run this command to install project dependencies. It is part of the initial setup for contributing to stdlib. ```bash $ make install ``` -------------------------------- ### Examples section with single-line input Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/repl_text.md Template for the Examples section demonstrating essential behavior with single-line user input and expected output. ```text foo( str ) A short description. Parameters ---------- str: string An input value. Returns ------- out: string An output value. Examples -------- > var out = foo( 'beep' ) 'boop' ... ``` -------------------------------- ### Example: Compile dmax addon Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of compiling the dmax addon after moving to stats/strided. ```bash make install-node-addons NODE_ADDONS_PATTERN="stats/strided/dmax" ``` -------------------------------- ### Example: Compile and run dmax C benchmarks Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of compiling and running C benchmarks for the moved dmax package. ```bash make benchmark-c BENCHMARKS_FILTER=".*/stats/strided/dmax/.*" ``` -------------------------------- ### Compile and run C examples Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md If the package contains C examples, compile and run them using this command. Replace path/to/new/package with the new package path. ```bash make examples-c EXAMPLES_FILTER=".*/path/to/new/package/.*" ``` -------------------------------- ### Example: Run dmax unit tests Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of running unit tests for the moved dmax package. ```bash make test TESTS_FILTER=".*/stats/strided/dmax/.*" ``` -------------------------------- ### Get byteOffset of Complex128Array Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/complex128/docs/repl.txt Shows how to get the byte offset of the array from the start of its underlying ArrayBuffer. The example demonstrates both a default offset of 0 and a custom offset of 128 when constructed with a buffer. ```javascript > var arr = new {{alias}}( 10 ) > var offset = arr.byteOffset 0 > var buf = new {{alias:@stdlib/array/buffer}}( 480 ); > arr = new {{alias}}( buf, 128 ) > offset = arr.byteOffset 128 ``` -------------------------------- ### Example: create database with options Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/docs/www/readme-database/README.md Full example that sets 'dir' and 'ignore' options before creating the database. ```javascript var create = require( '@stdlib/_tools/docs/www/readme-database' ); var opts = { 'dir': './lib/node_modules', 'ignore': [ 'benchmark/**', 'bin/**', 'build/**', 'docs/**', 'etc/**', 'examples/**', 'reports/**', 'scripts/**', 'test/**' ] }; create( opts, done ); function done( error, db ) { if ( error ) { throw error; } console.log( JSON.stringify( db ) ); } ``` -------------------------------- ### Access DataView.prototype.byteOffset Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/dataview/README.md Get the byte offset from the DataView to the start of the underlying buffer. The example creates a DataView with a byteOffset of 3. ```javascript var ArrayBuffer = require( '@stdlib/array/buffer' ); var buf = new ArrayBuffer( 5 ); var dv = new DataView( buf, 3 ); var byteOffset = dv.byteOffset; // returns 3 ``` -------------------------------- ### Get shape of a normalized multi-slice with {{alias}} Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/slice/base/shape/docs/repl.txt Returns the shape of a normalized multi-slice object. The example creates a slice with start 1, stop 10, and step 1, then a multi-slice containing two such slices, and calls {{alias}} to get the shape [9, 9]. ```javascript > var s = new {{alias:@stdlib/slice/ctor}}( 1, 10, 1 ); > var ms = new {{alias:@stdlib/slice/multi}}( s, s ); > {{alias}}( ms ) [ 9, 9 ] ``` -------------------------------- ### tutorial( [name, [options]] ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/README.md Starts a tutorial. When not provided a tutorial name, prints a list of available tutorials. Accepts options for customizing the tutorial presentation. ```APIDOC ## tutorial( [name, [options]] ) ### Description Starts a tutorial. When not provided a tutorial `name`, the function prints a list of available tutorials. If a specified workspace already exists, the workspace is silently cleared and a new tutorial presentation bound. In order to preserve an existing workspace, specify an alternative tutorial workspace name. ### Parameters - **name** (string) - Optional - The tutorial name. - **options** (Object) - Optional - Options for the tutorial. - **borderTop** (string) - Optional - Top border character sequence. Default: `'*'`. - **borderBottom** (string) - Optional - Bottom border character sequence. Default: `'*'`. - **borderLeft** (string) - Optional - Left border character sequence. Default: `'* '`. - **borderRight** (string) - Optional - Right border character sequence. Default: `' *'`. - **counter** (boolean|string) - Optional - Slide counter. Can either be `true`, `false`, or `'progress'`. Default: `progress`. - **workspace** (string) - Optional - REPL workspace name. Default: `'tutorial--'`, where `name` is the tutorial `name` and `n` is an assigned tutorial presentation identifier. - **autoClear** (boolean) - Optional - Whether to automatically clear the screen before writing a rendered tutorial slide to the REPL. Default: `true`. ### Request Example ```text In [1]: var id = tutorial( 'repl' ); ``` ``` -------------------------------- ### CLI example with arguments Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/pkgs/browser-entry-points/README.md Runs pkg-browser-entry-points with package names as arguments. Output is shown as placeholder objects. ```bash $ pkg-browser-entry-points tape browserify {...} {...} ``` -------------------------------- ### Call {{alias}}() to get familiar American-English words Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/dale-chall-new/docs/repl.txt Returns a list of familiar American-English words as an array of strings. The example shows the output starts with 'a', 'able', 'aboard', and so on. ```javascript > var list = {{alias}}() [ 'a', 'able', 'aboard', 'about', 'above', ... ] ``` -------------------------------- ### Get byteOffset property Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/fixed-endian-factory/README.md Read-only property that returns the offset in bytes from the start of the ArrayBuffer. The example creates a Float64ArrayFE with 5 elements and outputs 0. ```javascript var Float64ArrayFE = fixedEndianFactory( 'float64' ); var arr = new Float64ArrayFE( 'little-endian', 5 ); var byteOffset = arr.byteOffset; // returns 0 ``` -------------------------------- ### tutorial( [name, [options]] ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/tutorial.txt Starts a tutorial in the REPL. When no tutorial name is provided, it prints a list of available tutorials. If a specified workspace already exists, it is silently cleared and a new tutorial presentation is bound. ```APIDOC ## tutorial( [name, [options]] ) ### Description Starts a tutorial. When not provided a tutorial name, the function prints a list of available tutorials. If a specified workspace already exists, the workspace is silently cleared and a new tutorial presentation bound. ### Method Function call ### Signature `tutorial( [name, [options]] )` ### Parameters #### name (string, optional) Tutorial name. #### options (Object, optional) Tutorial options. - **options.borderTop** (string, optional) - Top border character sequence. Default: `'*'`. - **options.borderBottom** (string, optional) - Bottom border character sequence. Default: `'*'`. - **options.borderLeft** (string, optional) - Left border character sequence. Default: `'* '`. - **options.borderRight** (string, optional) - Right border character sequence. Default: `' *'`. - **options.counter** (string|boolean, optional) - Slide counter. If `true`, each tutorial slide displays a slide counter. If set to `'progress'`, each tutorial slide displays a progress counter. If `false`, no counter is displayed. Default: `'progress'`. - **options.workspace** (string, optional) - REPL workspace name. A tutorial presentation adds commands to the specified workspace, thus allowing tutorial navigation and interaction. Default: `'tutorial--'`, where `name` is the tutorial name and `n` is an assigned tutorial presentation identifier. - **options.autoClear** (boolean, optional) - Boolean indicating whether to automatically clear the screen before writing a rendered tutorial slide to the REPL. Default: `true`. ### Returns - **out** (integer|void) - Tutorial presentation identifier. ### Request Example ```javascript > var id = tutorial( 'repl' ); ``` ### See Also presentationStart, presentationStop, workspace, workspaces ``` -------------------------------- ### make install-all Source: https://github.com/stdlib-js/stdlib/blob/develop/tools/make/lib/install/README.md Runs the project's full install sequence. Warning: only run if absolutely necessary; most development does not require a full installation. ```bash $ make install-all ``` -------------------------------- ### Create and iterate a step iterator Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/iter/step/docs/repl.txt Creates an iterator that returns numbers starting at 0 with an increment of 2 for 10 values. The example shows calling next() to get values 0 and 2. ```javascript > var it = {{alias}}( 0, 2, 10 ); > var v = it.next().value 0 > v = it.next().value 2 ``` -------------------------------- ### Setup code with before option Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/utils/timeit/README.md Provides setup code via the 'before' option to initialize variables used in the timed snippet. ```javascript var setup = 'var randu = require( \'@stdlib/random/base/randu\' );'; setup += 'var pow = require( \'@stdlib/math/base/special/pow\' );'; var code = 'var x = pow( randu(), 3 );'; code += 'if ( x !== x ) {'; code += 'throw new Error( \'Something went wrong.\' );'; code += '}'; var opts = { 'before': setup }; timeit( code, opts, done ); function done( error, results ) { if ( error ) { throw error; } console.dir( results ); } ``` -------------------------------- ### Get English stop words list Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/stopwords-en/docs/repl.txt Returns an array of English stop words. The example shows the expected output format, a list starting with 'a', 'about', 'above', 'across', and so on. ```javascript var list = {{alias}}() ``` ```text [ 'a', 'about', 'above', 'across', ... ] ``` -------------------------------- ### CLI: basic example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/docs/www/readme-database/README.md Runs the CLI with default settings. ```bash $ readme-database ``` -------------------------------- ### Uint32Array.prototype.reduce without initial value Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/uint32/README.md Applies a function against an accumulator and each element, starting with the first element as the initial accumulator. The example sums squares of elements [2,1,3] to get 12. ```javascript function fcn( acc, v ) { return acc + ( v*v ); } var arr = new Uint32Array( [ 2, 1, 3 ] ); var v = arr.reduce( fcn ); // returns 12 ``` -------------------------------- ### Start a tutorial with tutorial( 'repl' ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/tutorial.txt Starts the 'repl' tutorial and returns a tutorial presentation identifier. The workspace is silently cleared if it already exists unless an alternative workspace name is specified. ```javascript > var id = tutorial( 'repl' ); ``` -------------------------------- ### Get byteOffset property Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/little-endian-factory/README.md Returns the offset in bytes from the start of the ArrayBuffer. The byteOffset property is read-only. The example creates a Float64ArrayLE with 5 elements and outputs 0. ```javascript var Float64ArrayLE = littleEndianFactory( 'float64' ); var arr = new Float64ArrayLE( 5 ); var byteOffset = arr.byteOffset; // returns 0 ``` -------------------------------- ### Examples section with comment headings for distinct behavior Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/repl_text.md Template for delineating examples of conceptually distinct behavior using comment headings and empty lines. ```text foo( str ) A short description. Parameters ---------- str: string|number An input value. Returns ------- out: string An output value. Examples -------- // String inputs: > var out = foo( 'beep' ) 'boop' // Number inputs: > var x = 3.14; > out = foo( x ) 10.0 ... ``` -------------------------------- ### example( instance ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/example.txt Runs examples for a provided class instance. Only direct instances of documented built-in constructors are supported. ```APIDOC ## example( instance ) ### Description Runs examples for a provided class instance. Only direct instances of documented built-in constructors are supported. ### Parameters - **instance** (any) - Required - Class instance. ### Request Example ```javascript > example( new Float64Array( 10 ) ) ``` ### See Also - help - info ``` -------------------------------- ### Create subarray view with begin index Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/float64/README.md Creates a subarray view starting at a specified begin index (inclusive). The example uses begin=1 to get elements from index 1 onward, sharing the same buffer. ```javascript var arr1 = new Float64Array( [ 1.0, 2.0, 3.0 ] ); var arr2 = arr1.subarray( 1 ); // returns [ 2.0, 3.0 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` -------------------------------- ### Create subarray view with begin index Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/float32/README.md Creates a subarray view starting from a specified begin index (inclusive). The example uses begin=1 to get elements from index 1 onward. ```javascript var arr1 = new Float32Array( [ 1.0, 2.0, 3.0 ] ); var arr2 = arr1.subarray( 1 ); // returns [ 2.0, 3.0 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` -------------------------------- ### Get view offset via .byteOffset Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/dataview/docs/repl.txt Read-only property returning the offset (in bytes) of the view to the start of the underlying array buffer. The example creates a view with a byteOffset of 2, resulting in a byteLength of 3. ```javascript > var buf = new {{alias:@stdlib/array/buffer}}( 5 ); > var dv = new {{alias}}( buf, 2 ); > dv.byteLength 3 > dv.byteOffset 2 ``` -------------------------------- ### Create subarray with begin index Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/uint8c/README.md Creates a subarray starting from a specified begin index (inclusive). The example uses `subarray(1)` to get elements from index 1 onward, and confirms the buffer is shared. ```javascript var arr1 = new Uint8ClampedArray( [ 1, 2, 3 ] ); var arr2 = arr1.subarray( 1 ); // returns [ 2, 3 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` -------------------------------- ### bundle-pkg-list help command Source: https://github.com/stdlib-js/stdlib/blob/develop/README.md Print help documentation for the `bundle-pkg-list` CLI command. Run from the local installation directory after following the development guide. ```bash $ NODE_PATH=./lib/node_modules node ./bin/cli bundle-pkg-list -- -h ``` -------------------------------- ### tutorial( name ) - Start a tutorial Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/README.md Starts a tutorial. The function accepts options such as borderTop, borderBottom, borderLeft, borderRight, counter, workspace, and autoClear. When not provided a tutorial name, it prints a list of available tutorials. ```text In [1]: var id = tutorial( 'repl' ); ``` -------------------------------- ### Launch Static File Server with python -m SimpleHttpServer Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/bundle/pkg-list/examples/multiple-bundles/README.md Start a simple HTTP server to serve the example files. Replace with the desired port (e.g., 7331). ```bash $ python -m SimpleHttpServer ``` -------------------------------- ### Create subarray with negative indices Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/uint8c/README.md Creates a subarray using negative indices, which are relative to the last element. The example uses `subarray(-arr1.length, -1)` to get elements from the start up to the second-to-last, and confirms the buffer is shared. ```javascript var arr1 = new Uint8ClampedArray( [ 1, 2, 3 ] ); var arr2 = arr1.subarray( -arr1.length, -1 ); // returns [ 1, 2 ] var bool = ( arr1.buffer === arr2.buffer ); // returns true ``` -------------------------------- ### Run examples Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md Runs example files matching the specified pattern. ```bash $ make EXAMPLES_FILTER=".*//.*" examples ``` -------------------------------- ### View Example in Browser Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/bundle/pkg-list/examples/multiple-bundles/README.md Navigate to the local server address to view the example in a web browser. ```text http://127.0.0.1: ``` -------------------------------- ### CLI example for base.sin Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/code-blocks/README.md Runs the CLI command to get an example for the 'base.sin' alias. ```bash $ stdlib-alias-example 'base.sin' ``` -------------------------------- ### Run examples for a class instance: example( new Float64Array( 10 ) ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/example.txt Runs examples for a provided class instance. Only direct instances of documented built-in constructors are supported. ```repl > example( new Float64Array( 10 ) ) ``` -------------------------------- ### Get example for alias base.sin Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/code-blocks/README.md Returns a string containing an example for the given alias. ```javascript var out = example( 'base.sin' ); // returns ``` -------------------------------- ### Set array elements with Complex128Array.prototype.set Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/complex128/docs/repl.txt Sets one or more elements starting at index i (default 0). Accepts a complex number or array-like of complex numbers/interleaved components. Example shows setting at index 0 and index 1, then reading with get. ```javascript > var arr = new {{alias}}( 2 ) > arr.set( new {{alias:@stdlib/complex/float64/ctor}}( 1.0, -1.0 ) ); > var z = arr.get( 0 ) [ 1.0, -1.0 ] > arr.set( new {{alias:@stdlib/complex/float64/ctor}}( 2.0, -2.0 ), 1 ); > z = arr.get( 1 ) [ 2.0, -2.0 ] ``` -------------------------------- ### Set a single element at default index 0 Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/complex128/README.md Sets the first element of a Complex128Array to a new Complex128 value. The method starts at index 0 by default. The example shows getting the element before and after setting to verify the change. ```javascript var Complex128 = require( '@stdlib/complex/float64/ctor' ); var arr = new Complex128Array( 10 ); // Get the first element: var z = arr.get( 0 ); // returns [ 0.0, 0.0 ] // Set the first element: arr.set( new Complex128( 1.0, -1.0 ) ); // Get the first element: z = arr.get( 0 ); // returns [ 1.0, -1.0 ] ``` -------------------------------- ### %makeinstall with bindir override Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/spam-assassin/data/easy-ham-2/01263.3bb6affa5c6c572955280dd0d5ae8ae7.txt Shows how to override bindir in %makeinstall, typically to point to the buildroot. ```spec %makeinstall bindir=%{buildroot}%{_sbindir} ``` -------------------------------- ### dznrm2.ndarray with offset parameter Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/blas/base/wasm/dznrm2/docs/repl.txt Uses the offset parameter to start indexing from a specific element. The example starts at index 1 and returns exactly 3.0. ```javascript > x = new {{alias:@stdlib/array/complex128}}( [ 3.0, 2.0, 3.0, 0.0 ] ); > out = {{alias}}.ndarray( 1, x, 1, 1 ) 3.0 ``` -------------------------------- ### Run example code with example() Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/tutorials/read_eval_print_loop.txt Run the example code found in the documentation for the sin function. ```javascript example( '{{alias:@stdlib/math/base/special/sin}}' ) ``` -------------------------------- ### example( property ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/example.txt Runs examples for a specified property. The property can be provided as an object path string or a reference. ```APIDOC ## example( property ) ### Description Runs examples for a specified property. ### Parameters - **property** (any) - Required - Alias property (an object path string or reference). ### Request Example ```javascript > example( isString.isPrimitive ) > example( 'isString.isPrimitive' ) ``` ``` -------------------------------- ### Negative begin index Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/to-view-iterator/README.md When begin is negative, the starting index is resolved relative to the last element. This example uses -3 to start from index 1, same as the previous example. ```javascript var it = arrayview2iterator( [ 1, 2, 3, 4 ], -3 ); // returns var v = it.next().value; // returns 2 v = it.next().value; // returns 3 v = it.next().value; // returns 4 var bool = it.next().done; // returns true ``` -------------------------------- ### GitHub Actions workflow to run examples Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/scripts/templates/workflow_examples.yml.txt Defines a GitHub Actions workflow named 'examples' that runs on manual dispatch. It checks out the repository, installs Node.js 20, installs dependencies with retries, and runs 'npm run examples'. Actions are pinned to specific commit SHAs. ```yaml #/ # @license Apache-2.0 # # Copyright (c) 2021 The Stdlib Authors. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. #/ # Workflow name: name: examples # Workflow triggers: on: # Allow the workflow to be manually run: workflow_dispatch: # Workflow jobs: jobs: # Define a job to run the package examples... examples: # Define display name: name: 'Run examples' # Define the type of virtual host machine on which to run the job: runs-on: ubuntu-latest # Define the sequence of job steps... steps: # Checkout repository: - name: 'Checkout repository' # Pin action to full length commit SHA uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 # Install Node.js: - name: 'Install Node.js' # Pin action to full length commit SHA uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 with: node-version: 20 timeout-minutes: 5 # Install dependencies: - name: 'Install production and development dependencies' run: | npm install || npm install || npm install timeout-minutes: 15 # Run examples: - name: 'Run examples' run: | npm run examples ``` -------------------------------- ### CLI example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/benchmarks/html/README.md Run the CLI with a bundle URL. ```bash $ benchmarks-html /foo/bar/beep.js ``` -------------------------------- ### CLI example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/signature/README.md Example command to get the signature for `'base.sin'`. ```bash $ stdlib-alias-signature 'base.sin' ``` -------------------------------- ### Navigate to Example Directory Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/bundle/pkg-list/examples/multiple-bundles/README.md Change to the example directory before running the bundle generation commands. ```bash $ cd /path/to/this/directory ``` -------------------------------- ### CLI example command Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/modules/import-require-tree/README.md Shows an example command to run the CLI on the ./examples directory, with a TODO placeholder for expected output. ```bash $ import-require-tree ./examples TODO ``` -------------------------------- ### Call {{alias}}() to get US state capitals Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/us-states-capitals/docs/repl.txt Returns a list of US state capitals in alphabetical order according to state name. The output is an array of strings, with an example result starting with 'Montgomery', 'Juneau', 'Phoenix'. ```javascript > var list = {{alias}}() ``` ```text [ 'Montgomery', 'Juneau', 'Phoenix', ... ] ``` -------------------------------- ### example( alias ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/example.txt Runs examples for a specified alias. The alias can be provided as an object path string or a reference. ```APIDOC ## example( alias ) ### Description Runs examples for a specified alias. ### Parameters - **alias** (any) - Required - Alias (an object path string or reference). ### Request Example ```javascript > example( base.sin ) > example( 'base.sin' ) ``` ``` -------------------------------- ### Example: deepGet with dynamic keys Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/object/deep-get/README.md A complete example that generates random data and retrieves nested values using an array path with a dynamic index. ```javascript var randu = require( '@stdlib/random/base/randu' ); var deepGet = require( '@stdlib/object/deep-get' ); var data; var keys; var val; var i; data = new Array( 100 ); for ( i = 0; i < data.length; i++ ) { data[ i ] = { 'x': Date.now(), 'y': [ randu(), randu(), i ] }; } keys = [ 0, 'y', 2 ]; for ( i = 0; i < data.length; i++ ) { keys[ 0 ] = i; val = deepGet( data, keys ); console.log( val ); } ``` -------------------------------- ### List all example files Source: https://github.com/stdlib-js/stdlib/blob/develop/tools/make/README.md Lists all example files. ```bash $ make list-examples ``` -------------------------------- ### Run examples for an alias: example( base.sin ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/example.txt Runs examples for a specified alias, which can be an object path string or a reference. The first call uses a reference, the second uses a string path. ```repl > example( base.sin ) ``` ```repl > example( 'base.sin' ) ``` -------------------------------- ### CLI Example: Get maximum finite value for float16 Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/utils/real-max/README.md Example command to get the maximum finite value for float16, which outputs 65504.0. ```bash $ realmax float16 65504.0 ``` -------------------------------- ### Full example with sync and async Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/fs/read-dir/README.md Demonstrates both sync and async usage, including error handling for ENOENT. ```javascript var isError = require( '@stdlib/assert/is-error' ); var readDir = require( '@stdlib/fs/read-dir' ); /* Sync */ var out = readDir.sync( __dirname ); // returns console.log( isError( out ) ); // => false out = readDir.sync( 'beepboop' ); // returns console.log( isError( out ) ); // => true /* Async */ readDir( __dirname, onRead ); readDir( 'beepboop', onRead ); function onRead( error, data ) { if ( error ) { if ( error.code === 'ENOENT' ) { console.error( 'Directory does not exist.' ); } else { throw error; } } else { console.log( data ); } } ``` -------------------------------- ### rpmbuild -bi --short-circuit command Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/spam-assassin/data/easy-ham-2/01235.3a679e506c7f862dda03736804009e92.txt Use this command to skip RPM build steps up to the %install section, starting from there. It requires that all previous build steps have been completed and will not produce any RPM files, but can help verify if the build can finish successfully. ```bash rpmbuild -bi --short-circuit ``` -------------------------------- ### Multiple header file example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/lint/license-header-glob/README.md Shows how to provide multiple license headers with file extension prefixes using multiple --header options. ```bash $ lint-license-header-glob --header='awk:./beep.txt' --header='js:./boop.txt' --header='default:./foo.txt' ``` -------------------------------- ### Get list of common female first names Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/female-first-names-en/docs/repl.txt Returns an array of common female first names in English speaking countries. The example shows the output starts with 'Aaren', 'Aarika', 'Abagael', 'Abagail', and continues with more names. ```javascript var list = {{alias}}() ``` ```text [ 'Aaren', 'Aarika', 'Abagael', 'Abagail', ... ] ``` -------------------------------- ### Use zswap.Module.prototype.ndarray with alternative indexing Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/blas/base/wasm/zswap/README.md Similar to main() but uses ndarray() with additional starting index parameters ox and oy, both set to 0. The setup and output are identical to the main() example, demonstrating alternative indexing semantics. ```javascript var Memory = require( '@stdlib/wasm/memory' ); var oneTo = require( '@stdlib/array/one-to' ); var zeros = require( '@stdlib/array/zeros' ); var bytesPerElement = require( '@stdlib/ndarray/base/bytes-per-element' ); var Complex128Array = require( '@stdlib/array/complex128' ); var reinterpretComplex128 = require( '@stdlib/strided/base/reinterpret-complex128' ); var zswap = require( '@stdlib/blas/base/wasm/zswap' ); // Create a new memory instance with an initial size of 10 pages (320KiB) and a maximum size of 100 pages (6.4MiB): var mem = new Memory({ 'initial': 10, 'maximum': 100 }); // Create a BLAS routine: var mod = new zswap.Module( mem ); // returns // Initialize the routine: mod.initializeSync(); // Define a vector data type: var dtype = 'complex128'; // Specify a vector length: var N = 5; // Define pointers (i.e., byte offsets) for storing input vectors: var xptr = 0; var yptr = N * bytesPerElement( dtype ); // Write vector values to module memory: var xbuf = oneTo( N*2, 'float64' ); var x = new Complex128Array( xbuf.buffer ); mod.write( xptr, x ); var ybuf = zeros( N*2, 'float64' ); var y = new Complex128Array( ybuf.buffer ); mod.write( yptr, y ); // Perform computation: mod.ndarray( N, xptr, 1, 0, yptr, 1, 0 ); // Read out the results: var viewX = zeros( N, dtype ); var viewY = zeros( N, dtype ); mod.read( xptr, viewX ); mod.read( yptr, viewY ); console.log( reinterpretComplex128( viewX, 0 ) ); // => [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] console.log( reinterpretComplex128( viewY, 0 ) ); // => [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 ] ``` -------------------------------- ### CLI basic usage examples Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/string/starts-with/README.md Shows basic command-line usage of starts-with with direct arguments and standard stream input. The first example returns true for 'beep' starting with 'be'; the second returns true for 'boop' starting with 'bo'. ```bash $ starts-with --search=be beep true ``` ```bash $ echo -n 'boop' | starts-with --search=bo true ``` -------------------------------- ### Run examples, benchmarks, and tests with make filters Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/packages.md Use these make commands during package development to run examples, benchmarks, and tests filtered to your package. Replace the pattern in each filter with a regex matching your package path. Run them from the project root. ```bash $ make EXAMPLES_FILTER=".*/pattern/to/identify/your/package/.*" examples ``` ```bash $ make BENCHMARKS_FILTER=".*/pattern/to/identify/your/package/.*" benchmark ``` ```bash $ make TESTS_FILTER=".*/pattern/to/identify/your/package/.*" test ``` -------------------------------- ### Full example: build with options and directory creation Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/README.md Creates the output directory if it does not exist, then builds the file tree with the specified options. The callback logs 'Finished!' on success. ```javascript var mkdir = require( 'fs' ).mkdirSync; var resolve = require( 'path' ).resolve; var exists = require( '@stdlib/fs/exists' ).sync; var build = require( '@stdlib/_tools/docs/www/readme-fragment-file-tree' ); var dpath = resolve( __dirname, 'build' ); var opts = { 'dir': './lib/node_modules', 'ignore': [ 'benchmark/**', 'bin/**', 'build/**', 'docs/**', 'etc/**', 'examples/**', 'reports/**', 'scripts/**', 'test/**' ] }; if ( !exists( dpath ) ) { mkdir( dpath ); } build( dpath, opts, done ); function done( error ) { if ( error ) { throw error; } console.log( 'Finished!' ); } ``` -------------------------------- ### General REPL text format template Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/repl_text.md Provides the canonical structure for a REPL text document, including placeholders for the alias, parameters, descriptions, parameter/return sections, examples, references, and see-also sections. Use this as a starting template when writing new REPL texts. ```text {{alias}}( param1, param2, ... ) A short description. A longer description, including notes explaining special cases and use cases. Parameters ---------- param1: Parameter description. param2: Parameter description. Returns ------- out: Return value description. Examples -------- > var out = {{alias}}() References ---------- - Nadler, Boaz. 2006. "Design Flaws in the Implementation of the Ziggurat and Monty Python methods (and some remarks on MATLAB randn)." *arXiv* abs/math/0603058 (March). See Also -------- ``` -------------------------------- ### Get example for unrecognized alias Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/code-blocks/README.md Returns null when the alias is not recognized. ```javascript var out = example( 'unrecognized_alias_beep_boop_bop_bip' ); // returns null ``` -------------------------------- ### Run examples for a property: example( isString.isPrimitive ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/example.txt Runs examples for a specified alias property, which can be an object path string or a reference. The first call uses a reference, the second uses a string path. ```repl > example( isString.isPrimitive ) ``` ```repl > example( 'isString.isPrimitive' ) ``` -------------------------------- ### Example: Copy dmax package Source: https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/moving_packages.md Example of copying the dmax package from stats/base to stats/strided. ```bash cp -R lib/node_modules/@stdlib/stats/base/dmax lib/node_modules/@stdlib/stats/strided/dmax ``` -------------------------------- ### Get example for alias Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/code-blocks/docs/repl.txt Returns an example associated with a provided alias. The alias is a string, and the return value is a string or null if no example exists. ```javascript > var txt = {{alias}}( '{{alias:@stdlib/math/base/special/sin}}' ) ``` -------------------------------- ### Run the REPL with stdlib repl Source: https://github.com/stdlib-js/stdlib/blob/develop/README.md After global installation, use the stdlib command to run the REPL. ```bash $ stdlib repl ``` -------------------------------- ### %configure with --bindir override Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/spam-assassin/data/easy-ham-2/01263.3bb6affa5c6c572955280dd0d5ae8ae7.txt Shows how to override the --bindir switch in %configure. The last occurrence is believed to take precedence. ```spec %configure --bindir=%{_sbindir} ``` -------------------------------- ### dgetrans.ndarray with starting indices Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/lapack/base/dge-trans/README.md Demonstrates offset parameters for starting indices. The example uses a 2x2 matrix with input starting at index 1 and output starting at index 2. ```javascript var Float64Array = require( '@stdlib/array/float64' ); var A = new Float64Array( [ 0.0, 1.0, 2.0, 3.0, 4.0 ] ); var out = new Float64Array( [ 0.0, 0.0, 11.0, 312.0, 53.0, 412.0 ] ); dgetrans.ndarray( 2, 2, A, 2, 1, 1, out, 2, 1, 2 ); // out => [ 0.0, 0.0, 1.0, 3.0, 2.0, 4.0 ] ``` -------------------------------- ### Slice with start index Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/array/complex128/README.md Copies a portion of the array starting from a specified start index (inclusive). The example starts at index 1 and shows the resulting array and length. ```javascript var arr = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); var out = arr.slice( 1 ); // returns [ 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] var len = out.length; // returns 3 ``` -------------------------------- ### Full example: create HTTP server with options and request listener Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/net/http-server/README.md Complete example showing how to create an HTTP server with options and a request listener, then make a request. ```javascript var proc = require( 'process' ); var http = require( 'http' ); var httpServerFactory = require( '@stdlib/net/http-server' ); function done( error, server ) { if ( error ) { throw error; } http.get( 'http://127.0.0.1:7331/beep/boop', onResponse ); } function onResponse() { console.log( 'Success!' ); proc.exit( 0 ); } function onRequest( request, response ) { console.log( request.url ); response.end( 'OK' ); } // Specify server options... var opts = { 'port': 7331, 'maxport': 9999, 'hostname': 'localhost' }; // Create a function for creating an HTTP server... var httpServer = httpServerFactory( opts, onRequest ); // Create a server: httpServer( done ); ``` -------------------------------- ### CLI example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/typed-signature/README.md Example command to get the typed signature for 'base.sin'. ```bash $ stdlib-alias-typed-signature 'base.sin' ``` -------------------------------- ### openURL example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/presentation/examples/presentation.txt Opens the stdlib GitHub repository in a browser. ```javascript openURL( 'https://github.com/stdlib-js/stdlib' ); ``` -------------------------------- ### logStart example: start logging and stop Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/commands/log_start.txt Starts logging commands and printed output to a file path, returns a record identifier, and stops logging with logStop. The example shows the command sequence and expected output. ```javascript > var id = logStart( './path/to/file.txt' ); > 1 + 1 2 > 'foo' 'foo' > logStop( id ); ``` -------------------------------- ### CLI example with multiple ignore patterns Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/pkgs/browser-compatible/README.md Shows how to provide multiple exclusion glob patterns using multiple --ignore options. ```bash $ stdlib-browser-compatible-pkgs --ignore=node_modules/** --ignore=build/** --ignore=reports/** ``` -------------------------------- ### clogspace ndarray example Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/blas/ext/base/ndarray/clogspace/README.md Example usage of clogspace to fill a Complex64Vector with complex numbers spaced logarithmically between start and stop values. It creates scalar ndarrays for base, start, stop, and endpoint, then calls clogspace with the vector and these scalars. The example logs the vector before and after the operation. ```javascript var Complex64Vector = require( '@stdlib/ndarray/vector/complex64' ); var Complex64 = require( '@stdlib/complex/float32/ctor' ); var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' ); var ndarray2array = require( '@stdlib/ndarray/to-array' ); var ndarraylike2scalar = require( '@stdlib/ndarray/ndarraylike2scalar' ); var clogspace = require( '@stdlib/blas/ext/base/ndarray/clogspace' ); var x = new Complex64Vector( 10 ); console.log( ndarray2array( x ) ); var base = scalar2ndarray( 10.0, { 'dtype': 'float32' }); console.log( 'Base: %d', ndarraylike2scalar( base ) ); var strt = scalar2ndarray( new Complex64( 0.0, 0.0 ), { 'dtype': 'complex64' }); console.log( 'Start: %s', ndarraylike2scalar( strt ) ); var stp = scalar2ndarray( new Complex64( 9.0, 1.0 ), { 'dtype': 'complex64' }); console.log( 'Stop: %s', ndarraylike2scalar( stp ) ); var endpoint = scalar2ndarray( true, { 'dtype': 'bool' }); console.log( 'Endpoint: %s', ndarraylike2scalar( endpoint ) ); clogspace( [ x, base, strt, stp, endpoint ] ); console.log( ndarray2array( x ) ); ``` -------------------------------- ### example( arg ) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/README.md Runs examples for a specified alias, property, or class instance. Only direct instances of documented built-in constructors are supported. ```APIDOC ## example( arg ) ### Description Runs examples for a specified alias, property, or class instance. ### Method Function call ### Parameters - **arg** (alias|property|class instance) - Required - The alias, property, or class instance for which to run examples. ### Notes - Only direct instances of documented built-in constructors are supported. ### Example ```text In [1]: example( base.sin ) ``` ``` -------------------------------- ### example: run examples for an alias Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/README.md Runs examples for a specified alias, property, or class instance. Only direct instances of documented built-in constructors are supported. ```text In [1]: example( base.sin ) ``` -------------------------------- ### Install Dependencies (make install) Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/_tools/scripts/templates/Makefile.txt Runs the project's install sequence by invoking the npm install command. ```makefile install: $(NPM) install .PHONY: install ``` -------------------------------- ### Install RPM package with rpm -i Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/spam-assassin/data/easy-ham-1/01070.6e34c1053a1840779780a315fb083057.txt Attempts to install an RPM package. In this example, the command fails with the error 'package already installed'. ```bash rpm -i [rpm package] ``` -------------------------------- ### Example: load and log image buffer Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/datasets/img-french-alpine-landscape/README.md Complete example that imports the module, calls image(), and logs the resulting buffer to the console. ```javascript var image = require( '@stdlib/datasets/img-french-alpine-landscape' ); var img = image(); console.log( img ); ``` -------------------------------- ### make examples - Run examples Source: https://github.com/stdlib-js/stdlib/blob/develop/tools/make/lib/examples/README.md Runs examples. Supports the EXAMPLES_FILTER environment variable to filter files by path pattern. Alias for examples-javascript. ```bash $ make examples ``` -------------------------------- ### Run example code with example() using variable reference Source: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/repl/docs/tutorials/read_eval_print_loop.txt Provide a variable reference to again run the example code for the sin function. ```javascript example( {{alias:@stdlib/math/base/special/sin}} ) ```