feat (3.4.0): add platform option, Android and BSD platforms

README.md

@@ -21,12 +21,8 @@ npm install -g tldr
 To see tldr pages:
 
 - `tldr <command>` show examples for this command
-- `tldr <command> --os=<platform>` show command page for the given platform (`linux`, `osx`, `sunos`, `windows`)
+- `tldr <command> --platform=<android|linux|openbsd|osx|sunos|windows>` show command page for the given platform
 - `tldr --search "<query>"` search all pages for the query
-- `tldr --linux <command>` show command page for Linux
-- `tldr --osx <command>` show command page for OSX
-- `tldr --sunos <command>` show command page for SunOS
-- `tldr --windows <command>` show command page for Windows
 - `tldr --list` show all pages for current platform
 - `tldr --list-all` show all available pages
 - `tldr --random` show a page at random
@@ -91,7 +87,7 @@ you can put it in the config file:
 The default platform value can be overwritten with command-line option:
 
 ```shell
-tldr du --os=osx
+tldr du --platform=<osx>
 ```
 
 As a contributor, you can also point to your own fork containing the `tldr.zip` file. The file is just a zipped version of the entire tldr repo:
@@ -122,7 +118,7 @@ It's easiest for
 [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh)
 users, so let's start with that.
 
-```
+```zsh
 mkdir -p $ZSH_CUSTOM/plugins/tldr
 ln -s bin/completion/zsh/_tldr $ZSH_CUSTOM/plugins/tldr/_tldr
 ```
@@ -131,13 +127,13 @@ Then add tldr to your oh-my-zsh plugins,
 usually defined in `~/.zshrc`,
 resulting in something looking like this:
 
-```
+```zsh
 plugins=(git tmux tldr)
 ```
 
 Alternatively, using [zplug](https://github.com/zplug/zplug)
 
-```
+```zsh
 zplug "tldr-pages/tldr-node-client", use:bin/completion/zsh
 ```
 
@@ -147,19 +143,19 @@ Copy or symlink `bin/completion/zsh/_tldr` to
 (note the filename).
 Then add the containing directory to your fpath:
 
-```
+```zsh
 fpath=(my/completions $fpath)
 ```
 
 ### Bash
 
-```
+```zsh
 ln -s bin/completion/bash/tldr ~/.tldr-completion.bash
 ```
 
 Now add the following line to our bashrc file:
 
-```
+```zsh
 source ~/.tldr-completion.bash
 ```
 
@@ -169,15 +165,15 @@ source ~/.tldr-completion.bash
 
 - If you are trying to install as non-root user (`npm install -g tldr`) and get something like:
 
-```
+```shell
 Error: EACCES: permission denied, access '/usr/local/lib/node_modules/tldr'
 ```
 
 Then most probably your npm's default installation directory has improper permissions. You can resolve it by clicking [here](https://docs.npmjs.com/getting-started/fixing-npm-permissions)
 
 - If you are trying to install as a root user (`sudo npm install -g tldr`) and get something like:
 
-```
+```shell
 as root ->
 gyp WARN EACCES attempting to reinstall using temporary dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp"
 gyp WARN EACCES user "root" does not have permission to access the dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp/8.9.1"
@@ -187,14 +183,14 @@ You need to add the option `--unsafe-perm` to your command. This is because when
 
 - If you see an error related to `webworker-threads` like:
 
-```
+```shell
 /usr/local/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:32
     if (e.code !== 'MODULE_NOT_FOUND') throw e;
 ```
 
 Most probably you need to reinstall `node-gyp` and `webworker-threads`. Try this -
 
-```
+```shell
 sudo -H npm uninstall -g tldr
 sudo -H npm uninstall -g webworker-threads
 npm install -g node-gyp
@@ -236,10 +232,6 @@ for a few rough guidelines.
 [npm-url]: https://www.npmjs.com/package/tldr
 [npm-image]: https://img.shields.io/npm/v/tldr.svg
 [gh-actions-url]: https://github.com/tldr-pages/tldr-node-client/actions?query=workflow%3ATest+branch%3Amaster
-[gh-actions-image]: https://img.shields.io/github/actions/workflow/status/tldr-pages/tldr-node-client/test.yml?branch=master
-[dep-url]: https://david-dm.org/tldr-pages/tldr-node-client
-[dep-image]: https://david-dm.org/tldr-pages/tldr-node-client.svg?theme=shields.io
-[dev-dep-url]: https://david-dm.org/tldr-pages/tldr-node-client#info=devDependencies
-[dev-dep-image]: https://david-dm.org/tldr-pages/tldr-node-client/dev-status.svg?theme=shields.io
+[gh-actions-image]: https://img.shields.io/github/actions/workflow/status/tldr-pages/tldr-node-client/test.yml?branch=main
 [matrix-url]: https://matrix.to/#/#tldr-pages:matrix.org
 [matrix-image]: https://img.shields.io/matrix/tldr-pages:matrix.org?label=chat+on+matrix

bin/completion/bash/tldr

@@ -2,7 +2,7 @@
 
 BUILTIN_THEMES="single base16 ocean"
 
-OS_TYPES="linux osx sunos windows"
+PLATFORM_TYPES="android linux osx sunos windows"
 
 OPTIONS='-v
 --version
@@ -20,11 +20,7 @@ OPTIONS='-v
 --render
 -m
 --markdown
--o
---linux
---osx
---sunos
---windows
+-p
 -t
 --theme
 -s
@@ -56,8 +52,8 @@ function _tldr_autocomplete {
         COMPREPLY=(`compgen -f $cur`)
         ;;
 
-      -o|--os)
-        COMPREPLY=(`compgen -W "$OS_TYPES" $cur`)
+      -p|--platform)
+        COMPREPLY=(`compgen -W "$PLATFORM_TYPES" $cur`)
         ;;
 
       -t|--theme)

bin/completion/zsh/_tldr

@@ -1,8 +1,8 @@
 #compdef tldr
 
-local -a pages oses
+local -a pages platforms
 pages=$(tldr -a1)
-oses='( linux osx sunos windows )'
+platforms='( android linux osx sunos windows )'
 
 _arguments \
   '(- *)'{-h,--help}'[show help]' \
@@ -15,11 +15,7 @@ _arguments \
   '(- *)'{-e,--random-example}'[show a random example]' \
   '(- *)'{-m,--markdown}'[show the original markdown format page]' \
   '(-f --render)'{-f,--render}'[render a specific markdown file]:markdown file:_files -/' \
-  '(-o --os)'{-o,--os}"[override operating system]:os:${oses}" \
-  '--linux[override operating system with Linux]' \
-  '--osx[override operating system with OSX]' \
-  '--sunos[override operating system with SunOS]' \
-  '--windows[override operating system with Windows]' \
+  '(-p --platform)'{-p,--platform}"[override platform]:platform:(${(j:|:)platforms})" \
   '(- *)'{-u,--update}'[update local cache]' \
   '(- *)'{-c,--clear-cache}'[clear local cache]' \
   "*:page:(${(b)pages})" && return 0

bin/tldr

@@ -4,7 +4,7 @@ const program = require('commander');
 const pkg = require('../package');
 const Tldr = require('../lib/tldr');
 const config = require('../lib/config');
-const platform = require('../lib/platform');
+const platforms = require('../lib/platforms');
 const { TldrError } = require('../lib/errors');
 
 program
@@ -22,11 +22,15 @@ program
   .option('-e, --random-example', 'Show a random example')
   .option('-f, --render [file]', 'Render a specific markdown [file]')
   .option('-m, --markdown', 'Output in markdown format')
-  .option('-o, --os [type]', 'Override the operating system [linux, osx, sunos, windows]')
-  .option('--linux', 'Override the operating system with Linux')
-  .option('--osx', 'Override the operating system with OSX')
-  .option('--sunos', 'Override the operating system with SunOS')
-  .option('--windows', 'Override the operating system with Windows')
+  .option('-p, --platform [type]', `Override the current platform [${platforms.supportedPlatforms.join(', ')}]`);
+
+for (const platform of platforms.supportedPlatforms) {
+  program.option(`--${platform}`, `Override the platform with ${platform}`);
+}
+
+program
+  .alias('-o', '-p') // Alias -o to -p
+  .alias('--os', '--platform') // Alias --os to --platform
   .option('-t, --theme [theme]', 'Color theme (simple, base16, ocean)')
   .option('-s, --search [keywords]', 'Search pages using keywords')
   //
@@ -39,7 +43,7 @@ const help = `
   Examples:
 
     $ tldr tar
-    $ tldr du --os=linux
+    $ tldr du --platform=linux
     $ tldr --search "create symbolic link to file"
     $ tldr --list
     $ tldr --list-all
@@ -62,27 +66,15 @@ program.on('--help', () => {
 
 program.parse(process.argv);
 
-if (program.linux) {
-  program.os = 'linux';
-}
-
-if (program.osx) {
-  program.os = 'osx';
-}
-
-if (program.sunos) {
-  program.os = 'sunos';
-}
-
-if (program.windows) {
-  program.os = 'windows';
+for (const platform of platforms.supportedPlatforms) {
+  if (program[platform]) {
+    program.platform = platform;
+  }
 }
 
 let cfg = config.get();
-if (program.os) {
-  if (platform.isSupported(program.os)) {
-    cfg.platform = program.os;
-  }
+if (program.platform && platforms.isSupported(program.platform)) {
+  cfg.platform = program.platform;
 }
 
 if (program.theme) {

lib/cache.js

@@ -4,14 +4,12 @@ const fs = require('fs-extra');
 const os = require('os');
 const path = require('path');
 const remote = require('./remote');
-const platform = require('./platform');
+const platforms = require('./platforms');
 const index = require('./index');
 const utils = require('./utils');
 
 class Cache {
   constructor(config) {
-    // TODO: replace this with a private field when it reaches enough maturity
-    // https://github.com/tc39/proposal-class-fields#private-fields
     this.config = config;
     this.cacheFolder = path.join(config.cache, 'cache');
   }
@@ -21,7 +19,7 @@ class Cache {
   }
 
   getPage(page) {
-    let preferredPlatform = platform.getPreferredPlatformFolder(this.config);
+    let preferredPlatform = platforms.getPreferredPlatformFolder(this.config);
     const preferredLanguage = process.env.LANG || 'en';
     return index.findPage(page, preferredPlatform, preferredLanguage)
       .then((folder) => {

lib/config.js

@@ -4,6 +4,7 @@ const defaults = require('lodash/defaults');
 const fs = require('fs');
 const path = require('path');
 const osHomedir = require('os').homedir;
+const platforms = require('./platforms');
 
 exports.get = () => {
   const DEFAULT = path.join(__dirname, '..', 'config.json');
@@ -38,10 +39,9 @@ exports.get = () => {
   return merged;
 };
 
-function validatePlatform(os) {
-  let platform = require('./platform');
-  if (os && !platform.isSupported(os)) {
-    return 'Unsupported platform : ' + os;
+function validatePlatform(platform) {
+  if (platform && !platforms.isSupported(platform)) {
+    return 'Unsupported platform : ' + platform;
   }
   return null;
 }
@@ -101,4 +101,4 @@ function validateThemeItem(field, key) {
     return null;
   }
   return errMsg.join('\n');
-}
+}

lib/index.js

@@ -59,12 +59,12 @@ function findPage(page, preferredPlatform, preferredLanguage) {
         targetPlatform = 'common';
       } else if (targets.length > 0 && hasLang(targets, preferredLanguage)) {
         targetLanguage = preferredLanguage;
-        targetPlatform = targets[0].os;
-        console.log(`Command ${page} does not exist for the host platform. Displaying the page from ${targets[0].os} platform`);
+        targetPlatform = targets[0].platform;
+        console.log(`Command ${page} does not exist for the host platform. Displaying the page from ${targetPlatform} platform`);
       } else if (targets.length > 0 && hasLang(targets, 'en')) {
         targetLanguage = 'en';
-        targetPlatform = targets[0].os;
-        console.log(`Command ${page} does not exist for the host platform. Displaying the page from ${targets[0].os} platform`);
+        targetPlatform = targets[0].platform;
+        console.log(`Command ${page} does not exist for the host platform. Displaying the page from ${targetPlatform} platform`);
       }
 
       if (!targetLanguage && !targetPlatform) {
@@ -81,7 +81,7 @@ function findPage(page, preferredPlatform, preferredLanguage) {
 
 function hasPlatformLang(targets, preferredPlatform, preferredLanguage) {
   return targets.some((t) => {
-    return t.os === preferredPlatform && t.language === preferredLanguage;
+    return t.platform === preferredPlatform && t.language === preferredLanguage;
   });
 }
 
@@ -116,7 +116,7 @@ function commandsFor(platform) {
       let commands = Object.keys(idx)
         .filter((cmd) => {
           let targets = idx[cmd].targets;
-          let platforms = targets.map((t) => {return t.os;});
+          let platforms = targets.map((t) => {return t.platform;});
           return platforms.indexOf(platform) !== -1 || platforms.indexOf('common') !== -1;
         })
         .sort();
@@ -187,24 +187,24 @@ function buildShortPagesIndex() {
     .then((files) => {
       files = files.filter(utils.isPage);
       let reducer = (index, file) => {
-        let os = utils.parsePlatform(file);
+        let platform = utils.parsePlatform(file);
         let page = utils.parsePagename(file);
         let language = utils.parseLanguage(file);
         if (index[page]) {
           let targets = index[page].targets;
           let needsPush = true;
           for (const target of targets) {
-            if (target.platform === os && target.language === language) {
+            if (target.platform === platform && target.language === language) {
               needsPush = false;
               continue;
             }
           }
           if (needsPush) {
-            targets.push({'os': os, 'language': language});
+            targets.push({ platform, language });
             index[page].targets = targets;
           }
         } else {
-          index[page] = {targets: [{'os': os, 'language': language}]};
+          index[page] = {targets: [{ platform, language }]};
         }
 
         return index;

lib/platform.js → lib/platforms.js

@@ -5,15 +5,20 @@ const os = require('os');
 const folders = {
   'osx': 'osx',
   'darwin': 'osx',
+  'macos': 'osx',
   'linux': 'linux',
+  'openbsd': 'openbsd',
   'sunos': 'sunos',
+  'android': 'android',
   'windows': 'windows',
   'win32': 'windows'
 };
 
+const supportedPlatforms = Object.keys(folders);
+
 // Check if the platform is there in the list of platforms or not
 function isSupported(platform) {
-  return Object.prototype.hasOwnProperty.call(folders, platform);
+  return supportedPlatforms.includes(platform);
 }
 
 // If the platform given in config is present, return that.
@@ -35,5 +40,6 @@ function getPreferredPlatformFolder(config) {
 module.exports = {
   isSupported,
   getPreferredPlatform,
-  getPreferredPlatformFolder
+  getPreferredPlatformFolder,
+  supportedPlatforms
 };