{"dist":{"shasum":"ad6546f1eb97367038988df41ae4fef4d64baedc","tarball":"https://registry.npmjs.org/flavored-path/-/flavored-path-0.0.2.tgz","integrity":"sha512-6IUdOyeK4jhKgBuP+ea1xb/59QtfVV4xwmcjJegtlOUIvRmcHaNNxAKl1FQwYlB7mw2oa9Y3GFYitaz59Mb/gw==","signatures":[{"sig":"MEUCIQDTrLpNZNRAZhOLV0no6dtTxcRoIOedGugXgPAScJAJEAIgSAYyRZ014U+8L/YFUWWr3LO7rKrPHXRxVsM6lY8x4yA=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"flavored-path","name":"flavored-path","author":{"name":"Gabriel Llamas","email":"gaglekas@gmail.com"},"readme":"flavored-path\r\n=============\r\n\r\n_Node.js project_\r\n\r\n#### \"path\" module revisited with backward compatibility and additional features ####\r\n\r\nVersion: 0.0.2\r\n\r\nThe goal of this module is to fix the current working directory issue, provide backward compatibility to the `path.normalize()` function (it's terribly bugged on Windows), provide forward compatibility with the `path.sep` alias and add additional useful methods.\r\n\r\nThis module uses [meta-path](https://github.com/Gagle/Node-MetaPath) to guarantee the backward compatibility. See its documentation to understand the problems and the fixes.\r\n\r\nThe primary intention is to use `flavored-path` as a complete replacement for the `path` built-in module.\r\n\r\nWhen dealing with built-in functions and relative paths there are two ways to adapt a path, with the `fix()` function and with `resolve()` (see documentation for each one). the first one fixes the current working directory issue. The second one can be used to resolve Linux home paths. Both functions should be used to pass a relative path to a `fs` built-in function, if the path is relative and starts with `~/` then use resolve, if not use fix. Instead of doing this check by yourself, there's a convenient function called `get()`.\r\n\r\n```javascript\r\nvar path = require (\"flavored-path\");\r\n```\r\n\r\n#### Installation ####\r\n\r\n```\r\nnpm install flavored-path\r\n```\r\n\r\n#### Example ####\r\n\r\n```javascript\r\nvar fs = require (\"fs\");\r\nvar path = require (\"flavored-path\");\r\n\r\n/*\r\npath.get (\".\") is equivalent to __dirname but get() can be used with any type\r\nof path, e.g.: Linux home paths (~/a/b).\r\n\r\nOn Linux, home paths are resolved to absolute files, so this snippet prints\r\nall the entries in the user's home path.\r\n\r\nOn Windows, home paths are processed like regular relative paths, that is,\r\nget() will return something like this: <cwd>/~/, so don't use ~ on Windows.\r\n\r\nThe Node.js built-in functions work the same way, for them ~ are not processed\r\nas relative home paths.\r\n*/\r\n\r\nfs.readdir (path.get (\"~/\"), function (error, files){\r\n\tif (error) return console.log (error);\r\n\tconsole.log (files);\r\n});\r\n```\r\n\r\n#### Methods and Properties ####\r\n\r\n__path.basename(p)__  \r\nSame Node.js built-in function ([path.basename()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.basename)).\r\n\r\n__path.dirname(p)__  \r\nSame Node.js built-in function ([path.dirname()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.dirname)).\r\n\r\n__path.extname(p[, ext])__  \r\nSame Node.js built-in function ([path.extname()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.extname)).\r\n\r\n__path.fix(p)__  \r\nFixes the current working directory issue. See [meta-path](https://github.com/Gagle/Node-MetaPath) documentation for extended information. The function only applies to relative paths except Linux home paths (`~/a/b`).\r\n\r\nIf the path is not relative returns the given path. If the path is a candidate to be fixed the returned path is normalized (using the normalize function provided by this module).\r\n\r\nIf the Node.js script is executed from a different directory from where the main script it's run, e.g. `node a/app.js`, the returned path will be fixed. Example:\r\n\r\n```\r\n$ pwd\r\n/home/gll\r\n$ node a/app.js\r\na/app.js\r\n```\r\n\r\n```javascript\r\n//app.js\r\nvar path = require (\"flavored-path\");\r\nconsole.log (path.fix (\"app.js\"));\r\n```\r\n\r\nIf `flavored-path` it's used within a global module it makes no sense to try to fix a relative path because it's not needed. In this case the function only normalizes the path and returns it.\r\n\r\nThis function provides the same funcionality than the `__dirname` approach but also works in third-party modules whereas `__dirname` cannot be used in a public module.\r\n\r\nThe recommended use of this function is to use it only when you need to call a built-in function that receives a path and use unfixed paths in all your application. Example:\r\n\r\n```javascript\r\nvar p = \"a/b\";\r\ndoSomething (path.dirname (p));\r\nfs.exists (path.fix (p), function (exists){\r\n  if (exists){\r\n\t\tdoMoreStuff (path.basename (p));\r\n\t}\r\n});\r\n```\r\n\r\nIf you follow this simple rule your code will never break if you execute your application from different directories:\r\n\r\n```\r\nnode a/b/app.js\r\nnode app.js\r\nnode ../app.js\r\n...\r\n```\r\n\r\nBecause the function prefixes a relative fix every time you call it, if you fix a path multiple times you'll end with an invalid path.\r\n\r\n```javascript\r\nvar p = \"a\";\r\np = path.fix (p);\r\n```\r\n\r\nThe path will be fixed but it's very easy to forget that it's already fixed and use it as an unfixed path.\r\n\r\nDon't do this, never. The function cannot check if a path has been fixed previously.\r\n\r\n```javascript\r\npath.fix (path.fix (\"a\"));\r\n```\r\n\r\n__path.get(p)__  \r\nReturns a path suitable for using with a `fs` built-in function. You could use `fix()` if the path is relative or `resolve()` if it's a home path but for your convenience you can use `get()`. In fact, `get()`'s implementation is the following:\r\n\r\n```javascript\r\nif (!path.isRelative (p)) return path.normalize (p);\r\nif (!WIN && path.isHome (p)){\r\n\treturn path.resolve (p);\r\n}\r\nreturn path.fix (p);\r\n```\r\n\r\nAs you can see, home paths are not resolved to an absolute path on Windows, they are processed like regular relative paths (the fix function is aware of won't fix anything, home paths are not fixed on any operating system).\r\n\r\nThe resolve function can also be used to fix the current working directory issue, it returns the absolute path:\r\n\r\n```javascript\r\nconsole.log (path.resolve (\"b\")); //Prints: /home/gll/a/b\r\nconsole.log (path.fix (\"b\")); //Prints a/b\r\n```\r\n\r\nBoth paths are valid but I recommend to use `get()` whenever possible.\r\n\r\nThe intended use of this function is when you need to pass a path to a `fs` built-in function:\r\n\r\n```javascript\r\nfs.exists (path.get (\"a\"), cb);\r\n```\r\n\r\nYou can pass any type of path. It will be normalized, fixed, resolved, whatever modification to convert the given path to a valid path for using with any `fs` built-in function.\r\n\r\n__path.isAbsolute(p)__  \r\nChecks whether the path it's absolute. An absolute path begins with `/` or `\\` (the prefix is skipped, e.g.: `D:`), this means that network paths are also absolute. The given path doesn't need to be normalized. Returns true if is absolute, false otherwise.\r\n\r\n__path.isHome(p)__  \r\nChecks whether the path it's relative from the user's home directory. A home path path begins with `~/` or `~\\` (cannot contains a prefix), this means that home paths are also relative. The given path doesn't need to be normalized. Returns true if is a home path, false otherwise.\r\n\r\n__path.isNetwork(p)__  \r\nChecks whether the path it's a network resource (on Windows world this is called a UNC path). A network path begins with `//` or `\\\\\\\\` (the prefix is skipped, e.g.: `smb:`). The given path doesn't need to be normalized. Returns true if is a network resource, false otherwise.\r\n\r\n__path.isRelative(p)__  \r\nChecks whether the path it's relative. A relative  path begins with any character different from `/` or `\\` (the prefix is skipped, e.g.: `D:`), this means that Linux home paths (e.g.: `~/a/b`) are also relative but not candidates for the fix process. The given path doesn't need to be normalized. Returns true if is relative, false otherwise.\r\n\r\n__path.isRoot(p)__  \r\nChecks whether the path it's a root. A root path it's equal to `/`, `\\`, `//` or `\\\\` (the prefix is skipped, e.g.: `D:`). The given path doesn't need to be normalized. Returns true if is a root path, false otherwise.\r\n\r\n__path.join(path1, path2[, ...][, withoutPrefix])__  \r\nSame Node.js built-in function ([path.join()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.join)).\r\n\r\nUses the normalize function provided by this module so, the joined path is normalized correctly.\r\n\r\nA new parameter has been added, `withoutPrefix`. If true, returns the path without a possible prefix.\r\n\r\n```javascript\r\nconsole.log (path.join (\"smb://a//b\", \"c/\")); //Prints: smb://a/b/c/\r\n```\r\n\r\n__path.normalize(p[, withoutPrefix])__  \r\nSame Node.js built-in function ([path.normalize()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.normalize)).\r\n\r\nTakes care all of the bugs found in the built-in normalize function explained in the [meta-path](https://github.com/Gagle/Node-MetaPath) module.\r\n\r\nA new parameter has been added, `withoutPrefix`. If true, returns the path without a possible prefix.\r\n\r\n__path.prefix(p)__  \r\nReturns the prefix. The prefix is the string before `:` (included).\r\n\r\n__path.relative(from, to)__  \r\nSame Node.js built-in function ([path.relative()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.relative)).\r\n\r\n__path.resolve([from], to)__  \r\nSame Node.js built-in function ([path.resolve()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.resolve)).\r\n\r\nThe absolute path that is returned fixes the current working directory issue. As explained in the fix function description, the resolve function cannot check if the path has already been fixed so don't call it multiples times. Don't do this, never:\r\n\r\n```javascript\r\npath.resolve (path.resolve (\"a\"));\r\n```\r\n\r\nIn addition, the Linux relative home paths are resolved to its absolute path (only on Linux). The resolve built-in function doesn't provide this functionality. The file system built-in function don't expand `~` to the user's home path, so when you deal with home paths you must convert it first to an absolute path:\r\n\r\n```javascript\r\nfs.exists (path.resolve (\"~/a\"), cb);\r\n```\r\n\r\nResource paths (paths that begin with `//`) are also resolved correctly, they are processed like absolute paths.\r\n\r\nSome examples:\r\n\r\n```\r\n$ pwd\r\n/home/gll\r\n$ node a/resolve.js\r\n```\r\n\r\n```javascript\r\n//resolve.js\r\nconsole.log (path.resolve (\"b\", \"c\")); //Prints: /home/gll/a/b/c\r\nconsole.log (path.resolve (\"s\", \"~/a\")); //Prints: /home/gll/a\r\nconsole.log (path.resolve (\"s\", \"/a\", \"b\")); //Prints: /a/b\r\nconsole.log (path.resolve (\"s\", \"//a\", \"b\")); //Prints: //a/b\r\n```\r\n\r\n__path.sep__  \r\nSame Node.js built-in property ([path.sep()](http://nodemanual.org/latest/nodejs_ref_guide/path.html#path.sep)).","engines":{"node":"*"},"_npmUser":{"name":"Gagle","email":"gaglekas@gmail.com"},"keywords":["path","backward","compatibility","flavored"],"licenses":[{"url":"http://www.opensource.org/licenses/mit-license.html","type":"MIT"}],"deprecated":"use rwd","repository":{"url":"git://github.com/Gagle/Node-FlavoredPath.git","type":"git"},"_npmVersion":"1.1.66","description":"path module revisited with backward compatibility and additional features","directories":{},"maintainers":[{"name":"Gagle","email":"gaglekas@gmail.com"}],"dependencies":{"meta-path":"*"},"readmeFilename":"README.md","_id":"flavored-path@0.0.2","version":"0.0.2"}