time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (3645B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2018 The Stdlib Authors.
      6 
      7 Licensed under the Apache License, Version 2.0 (the "License");
      8 you may not use this file except in compliance with the License.
      9 You may obtain a copy of the License at
     10 
     11    http://www.apache.org/licenses/LICENSE-2.0
     12 
     13 Unless required by applicable law or agreed to in writing, software
     14 distributed under the License is distributed on an "AS IS" BASIS,
     15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     16 See the License for the specific language governing permissions and
     17 limitations under the License.
     18 
     19 -->
     20 
     21 # Read Directory
     22 
     23 > Read the contents of a directory.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var readDir = require( '@stdlib/fs/read-dir' );
     31 ```
     32 
     33 #### readDir( path, clbk )
     34 
     35 Asynchronously reads the contents of a directory.
     36 
     37 ```javascript
     38 readDir( __dirname, onRead );
     39 
     40 function onRead( error, data ) {
     41     if ( error ) {
     42         console.error( error );
     43     } else {
     44         console.log( data );
     45         // => [...]
     46     }
     47 }
     48 ```
     49 
     50 #### readDir.sync( path )
     51 
     52 Synchronously reads the contents of a directory.
     53 
     54 ```javascript
     55 var out = readDir.sync( __dirname );
     56 if ( out instanceof Error ) {
     57     throw out;
     58 }
     59 console.log( out );
     60 // => [...]
     61 ```
     62 
     63 </section>
     64 
     65 <!-- /.usage -->
     66 
     67 <section class="notes">
     68 
     69 ## Notes
     70 
     71 -   The difference between this module and [`fs.readdirSync()`][fs] is that [`fs.readdirSync()`][fs] will throw if an `error` is encountered (e.g., if given a non-existent `path`) and this module will return an `error`. Hence, the following anti-pattern
     72 
     73     ```javascript
     74     var fs = require( 'fs' );
     75 
     76     var dir = '/path/to/dir';
     77 
     78     // Check for existence to prevent an error being thrown...
     79     if ( fs.existsSync( dir ) ) {
     80         dir = fs.readdirSync( dir );
     81     }
     82     ```
     83 
     84     can be replaced by an approach which addresses existence via `error` handling.
     85 
     86     ```javascript
     87     var readDir = require( '@stdlib/fs/read-dir' );
     88 
     89     var dir = '/path/to/dir';
     90 
     91     // Explicitly handle the error...
     92     dir = readDir.sync( dir );
     93     if ( dir instanceof Error ) {
     94         // You choose what to do...
     95         throw dir;
     96     }
     97     ```
     98 
     99 </section>
    100 
    101 <!-- /.notes -->
    102 
    103 <section class="examples">
    104 
    105 ## Examples
    106 
    107 <!-- eslint no-undef: "error" -->
    108 
    109 ```javascript
    110 var readDir = require( '@stdlib/fs/read-dir' );
    111 
    112 /* Sync */
    113 
    114 var out = readDir.sync( __dirname );
    115 // returns <Array>
    116 
    117 console.log( out instanceof Error );
    118 // => false
    119 
    120 out = readDir.sync( 'beepboop' );
    121 // returns <Error>
    122 
    123 console.log( out instanceof Error );
    124 // => true
    125 
    126 /* Async */
    127 
    128 readDir( __dirname, onRead );
    129 readDir( 'beepboop', onRead );
    130 
    131 function onRead( error, data ) {
    132     if ( error ) {
    133         if ( error.code === 'ENOENT' ) {
    134             console.error( 'Directory does not exist.' );
    135         } else {
    136             throw error;
    137         }
    138     } else {
    139         console.log( data );
    140     }
    141 }
    142 ```
    143 
    144 </section>
    145 
    146 <!-- /.examples -->
    147 
    148 * * *
    149 
    150 <section class="cli">
    151 
    152 ## CLI
    153 
    154 <section class="usage">
    155 
    156 ### Usage
    157 
    158 ```text
    159 Usage: read-dir [options] <dirpath>
    160 
    161 Options:
    162 
    163   -h,    --help                Print this message.
    164   -V,    --version             Print the package version.
    165 ```
    166 
    167 </section>
    168 
    169 <!-- /.usage -->
    170 
    171 <section class="notes">
    172 
    173 ### Notes
    174 
    175 -   Relative paths are resolved relative to the current working directory.
    176 -   Errors are written to `stderr`.
    177 -   Directory contents are written to `stdout`.
    178 
    179 </section>
    180 
    181 <!-- /.notes -->
    182 
    183 <section class="examples">
    184 
    185 ### Examples
    186 
    187 ```bash
    188 $ read-dir ./../
    189 ...
    190 ...
    191 ```
    192 
    193 </section>
    194 
    195 <!-- /.examples -->
    196 
    197 </section>
    198 
    199 <!-- /.cli -->
    200 
    201 <section class="links">
    202 
    203 [fs]: https://nodejs.org/api/fs.html
    204 
    205 </section>
    206 
    207 <!-- /.links -->