time-to-botec

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

README.md (3923B)

      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 # Resolve Parent Path
     22 
     23 > Resolve a path by walking parent directories.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var resolveParentPath = require( '@stdlib/fs/resolve-parent-path' );
     31 ```
     32 
     33 <a name="resolve-parent-path"></a>
     34 
     35 #### resolveParentPath( path\[, options], clbk )
     36 
     37 Asynchronously resolves a path by walking parent directories.
     38 
     39 ```javascript
     40 resolveParentPath( 'package.json', onPath );
     41 
     42 function onPath( error, path ) {
     43     if ( error ) {
     44         throw error;
     45     }
     46     console.log( path );
     47     // => '...'
     48 }
     49 ```
     50 
     51 The function accepts the following `options`:
     52 
     53 -   **dir**: base directory from which to begin walking. May be either an absolute path or a path relative to the current working directory.
     54 
     55 By default, the function begins walking from the current working directory. To specify an alternative directory, set the `dir` option.
     56 
     57 ```javascript
     58 var opts = {
     59     'dir': __dirname
     60 };
     61 resolveParentPath( 'package.json', opts, onPath );
     62 
     63 function onPath( error, path ) {
     64     if ( error ) {
     65         throw error;
     66     }
     67     console.log( path );
     68     // => '...'
     69 }
     70 ```
     71 
     72 #### resolveParentPath.sync( path\[, options] )
     73 
     74 Synchronously resolves a path by walking parent directories.
     75 
     76 ```javascript
     77 var path = resolveParentPath.sync( 'package.json' );
     78 // returns '...'
     79 ```
     80 
     81 The function accepts the same `options` as [`resolveParentPath()`](#resolve-parent-path).
     82 
     83 </section>
     84 
     85 <!-- /.usage -->
     86 
     87 <section class="notes">
     88 
     89 ## Notes
     90 
     91 -   If unable to resolve a path, both functions return `null`.
     92 -   This implementation is **not** similar in functionality to core [`path.resolve`][node-core-path-resolve]. The latter performs string manipulation to generate a full path. This implementation walks parent directories to perform a **search**, thereby touching the file system. Accordingly, this implementation resolves a _real_ absolute file path and is intended for use when a target's location in a parent directory is unknown relative to a child directory; e.g., when wanting to find a package root from deep within a package directory. 
     93 
     94 </section>
     95 
     96 <!-- /.notes -->
     97 
     98 <section class="examples">
     99 
    100 ## Examples
    101 
    102 <!-- eslint no-undef: "error" -->
    103 
    104 ```javascript
    105 var resolveParentPath = require( '@stdlib/fs/resolve-parent-path' );
    106 
    107 var opts = {
    108     'dir': __dirname
    109 };
    110 
    111 /* Sync */
    112 
    113 var out = resolveParentPath.sync( 'package.json', opts );
    114 // returns '...'
    115 
    116 out = resolveParentPath.sync( 'non_existent_basename' );
    117 // returns null
    118 
    119 /* Async */
    120 
    121 resolveParentPath( 'package.json', opts, onPath );
    122 resolveParentPath( './../non_existent_path', onPath );
    123 
    124 function onPath( error, path ) {
    125     if ( error ) {
    126         throw error;
    127     }
    128     console.log( path );
    129 }
    130 ```
    131 
    132 </section>
    133 
    134 <!-- /.examples -->
    135 
    136 * * *
    137 
    138 <section class="cli">
    139 
    140 ## CLI
    141 
    142 <section class="usage">
    143 
    144 ### Usage
    145 
    146 ```text
    147 Usage: resolve-parent-path [options] <path>
    148 
    149 Options:
    150 
    151   -h,    --help                Print this message.
    152   -V,    --version             Print the package version.
    153          --dir dir             Base search directory.
    154 ```
    155 
    156 </section>
    157 
    158 <!-- /.usage -->
    159 
    160 <section class="examples">
    161 
    162 ### Examples
    163 
    164 ```bash
    165 $ resolve-parent-path package.json
    166 ```
    167 
    168 </section>
    169 
    170 <!-- /.examples -->
    171 
    172 </section>
    173 
    174 <!-- /.cli -->
    175 
    176 <section class="links">
    177 
    178 [node-core-path-resolve]: https://nodejs.org/api/path.html#path_path_resolve_paths
    179 
    180 </section>
    181 
    182 <!-- /.links -->