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

README.md

@@ -21,12 +21,19 @@ 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 --search "<query>"` search all pages for the query
+- `tldr <command> --platform=<osx, darwin, macos, freebsd, linux, netbsd, openbsd, sunos, android, windows, win32>` show command page for the given platform
+- `tldr --android <command>` show command page for Android
+- `tldr --darwin <command>` show command page for darwin (macOS)
+- `tldr --freebsd <command>` show command page for FreeBSD
 - `tldr --linux <command>` show command page for Linux
-- `tldr --osx <command>` show command page for OSX
+- `tldr --macos <command>` show command page for macOS
+- `tldr --netbsd <command>` show command page for NetBSD
+- `tldr --openbsd <command>` show command page for OpenBSD
+- `tldr --osx <command>` show command page for osx (macOS)
 - `tldr --sunos <command>` show command page for SunOS
+- `tldr --win32 <command>` show command page for win32 (Windows)
 - `tldr --windows <command>` show command page for Windows
+- `tldr --search "<query>"` search all pages for the query
 - `tldr --list` show all pages for current platform
 - `tldr --list-all` show all available pages
 - `tldr --random` show a page at random
@@ -91,7 +98,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 +129,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 +138,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,37 +154,37 @@ 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
 
-```
+```bash
 ln -s bin/completion/bash/tldr ~/.tldr-completion.bash
 ```
 
 Now add the following line to our bashrc file:
 
-```
+```bash
 source ~/.tldr-completion.bash
 ```
 
 ## FAQ
 
-#### Installation Issues
+### Installation Issues
 
 - If you are trying to install as non-root user (`npm install -g tldr`) and get something like:
 
-```
+```text
 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 +194,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:
 
-```
+```text
 /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 +243,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 freebsd linux netbsd openbsd osx sunos windows"
 
 OPTIONS='-v
 --version
@@ -20,10 +20,17 @@ OPTIONS='-v
 --render
 -m
 --markdown
--o
+-p
+--android
+--darwin
+--freebsd
 --linux
+--macos
+--netbsd
+--openbsd
 --osx
 --sunos
+--win32
 --windows
 -t
 --theme
@@ -56,8 +63,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 freebsd linux netbsd openbsd osx sunos windows )'
 
 _arguments \
   '(- *)'{-h,--help}'[show help]' \
@@ -15,11 +15,18 @@ _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}" \
+  '(-p --platform)'{-p,--platform}"[override platform]:platform:(${(j:|:)platforms})" \
+  '(- *)'{-u,--update}'[update local cache]' \
+  '--android[override operating system with Android]' \
+  '--darwin[override operating system with macOS]' \
+  '--freebsd[override operating system with FreeBSD]' \
   '--linux[override operating system with Linux]' \
-  '--osx[override operating system with OSX]' \
+  '--macos[override operating system with macOS]' \
+  '--netbsd[override operating system with NetBSD]' \
+  '--openbsd[override operating system with OpenBSD]' \
+  '--osx[override operating system with macOS]' \
   '--sunos[override operating system with SunOS]' \
+  '--win32[override operating system with Windows]' \
   '--windows[override operating system with Windows]' \
-  '(- *)'{-u,--update}'[update local cache]' \
   '(- *)'{-c,--clear-cache}'[clear local cache]' \
   "*:page:(${(b)pages})" && return 0

bin/tldr

@@ -4,9 +4,11 @@ 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');
 
+pkg.version = `v${pkg.version}\nClient Specification: 2.0`;
+
 program
   .version(pkg.version, '-v, --version', 'Display version')
   .helpOption('-h, --help', 'Show this help message')
@@ -22,11 +24,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 +45,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 +68,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

@@ -5,6 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const utils = require('./utils');
 const osHomedir = require('os').homedir;
+const platforms = require('./platforms');
 
 exports.get = () => {
   const DEFAULT = path.join(__dirname, '..', 'config.json');
@@ -55,10 +56,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;
 }
@@ -118,4 +118,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;