Skip to content

Commit

Permalink
v0.4.0
Browse files Browse the repository at this point in the history 
  * [potentially breaking change] `typex` now accepts options _after_ operands
      as well (except after `--`), and now also accepts long option names.
  * [doc] `typex` now has a man page (if manually installed, use `typex --man`);
      `typex -h` now just prints concise usage information.
  * [doc] Read-me improved.
  * [fix] Various fixes and stability improvements.
  * [dev] Installation of sourcing (with `-i`) no longer uses `ed` so as to
      work on a wider range of platforms, notably Fedora.
  * [dev] Tests improved, additional tests added.
  • Loading branch information
@mklement0
mklement0 committed Sep 21, 2015
1 parent 0496775 commit a5d7d4a
Show file tree
Hide file tree
Showing 19 changed files with 1,426 additions and 432 deletions.
11 changes: 11 additions & 0 deletions CHANGELOG.md
View file
Expand Up @@ -4,6 +4,17 @@ Versioning complies with [semantic versioning (semver)](http://semver.org/).

<!-- NOTE: An entry template is automatically added each time `make version` is called. Fill in changes afterwards. -->

* **[v0.4.0](https://github.com/mklement0/typex/compare/v0.3.3...v0.4.0)** (2015-09-21):
* [potentially breaking change] `typex` now accepts options _after_ operands
as well (except after `--`), and now also accepts long option names.
* [doc] `typex` now has a man page (if manually installed, use `typex --man`);
`typex -h` now just prints concise usage information.
* [doc] Read-me improved.
* [fix] Various fixes and stability improvements.
* [dev] Installation of sourcing (with `-i`) no longer uses `ed` so as to
work on a wider range of platforms, notably Fedora.
* [dev] Tests improved, additional tests added.

* **[v0.3.3](https://github.com/mklement0/typex/compare/v0.3.2...v0.3.3)** (2015-09-15):
* [dev] Makefile improvements; various other behind-the-scenes tweaks.

Expand Down
2 changes: 1 addition & 1 deletion Makefile
View file
Expand Up @@ -201,7 +201,7 @@ update-man:
# If man-page creation is turned on: recreate the man page and view it with `man`.
.PHONY: view-man
view-man: update-man
@manfile=`json -f package.json man` || { echo "ERROR: No `man` property found in 'package.json'." >&2; exit 2; }; \
@manfile=`json -f package.json man`; [[ -n $$manfile ]] || { echo "ERROR: No 'man' property found in 'package.json'." >&2; exit 2; }; \
man "$$manfile"

# Toggles inclusion of an auto-updating TOC in README.md via doctoc.
Expand Down
240 changes: 67 additions & 173 deletions README.md
View file
Expand Up @@ -5,25 +5,26 @@

**Contents**

- [typex &mdash; Introduction](#typex-&mdash-introduction)
- [Examples](#examples)
- [Installation](#installation)
- [From the npm registry](#from-the-npm-registry)
- [Manual installation](#manual-installation)
- [Usage](#usage)
- [License](#license)
- [Acknowledgements](#acknowledgements)
- [npm dependencies](#npm-dependencies)
- [Changelog](#changelog)
- [typex &mdash; introduction](#typex-&mdash-introduction)
- [Examples](#examples)
- [Installation](#installation)
- [Installation from the npm registry](#installation-from-the-npm-registry)
- [Manual installation](#manual-installation)
- [Usage](#usage)
- [License](#license)
- [Acknowledgements](#acknowledgements)
- [npm dependencies](#npm-dependencies)
- [Changelog](#changelog)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# typex &mdash; Introduction
# typex &mdash; introduction

`typex` is an extended version of the `type` Unix shell builtin that incorporates features from the `which` and `file` utilities:
By default, it provides information about the current shell.
Given a name, it indicates how the current shell would interpret that name as a command, and provides information about each command form found.
Given a filesystem path, it provides information such as file type and the canonical path.
`typex` is an enhanced version of the `type` Unix shell builtin that
incorporates features from the `which` and `file` utilities:
By default, it provides information about the current shell.
Given a name, it indicates how the current shell would interpret that name as a command, and provides information about each command form found.
Given a filesystem path, it provides information such as file type and canonical path.

`typex` extends `type` as follows:

Expand All @@ -37,11 +38,12 @@ Given a filesystem path, it provides information such as file type and the canon
Note: `typex` is designed for interactive use, to provide humans with concise, salient information about a command or filesystem object.
As such, its output is geared toward readability by humans, and should not be relied on for programmatic parsing.

See the [Usage](#usage) chapter for details.
See the examples below, concise [usage information](#usage) further below,
or read the [manual](doc/typex.md).

For supported platforms and shells, see the [Installation](#installation) chapter.

## Examples
# Examples

```shell
# Print information about the current shell.
Expand All @@ -59,9 +61,9 @@ $ typex nawk
BINARY: /usr/bin/nawk@ -> /etc/alternatives/nawk@ -> /usr/bin/gawk [GNU Awk 4.0.1]

# Print information about executable script 'npm';
# note the interpreter information ('js script').
# note the interpreter information ('POSIX shell script').
$ typex npm
SCRIPT: /usr/bin/npm@ -> /usr/lib/node_modules/npm/bin/npm-cli.js (js script) [1.4.28]
SCRIPT: /usr/bin/npm@ -> /usr/lib/node_modules/npm/bin/npm-cli.js (POSIX shell script) [2.11.3]

# Print information about an alias:
$ alias lsx='ls -FAhl'
Expand All @@ -77,10 +79,9 @@ DIRECTORY: /etc/apache2 -> /private/etc/apache2
$ typex -v /dev/null
FILE: /dev/null (character special )
crw-rw-rw- 1 root root 1, 3 Feb 1 19:43

```

## Installation
# Installation

**Supported platforms**

Expand All @@ -89,16 +90,20 @@ FILE: /dev/null (character special )

**Supported shells**

For this utility to detect the current shell's aliases, keywords, (non-exported) shell functions, and builtins, it must be *sourced*, which is supported in the following shells:
For this utility to detect the current shell's aliases, keywords, functions, and builtins, it must be *sourced*, which is supported in the following shells:

* **bash**, **ksh**, and **zsh**
* **Bash**, **Ksh**, and **Zsh**

`typex` can still be useful in unsupported shells when invoked standalone (in which case it runs in `bash`), albeit in limited form:

* only executable *files* and filesystem objects will be detected - no other command forms.
* a warning to that effect is printed; you can suppress it with `-p`

### From the npm registry
Simply put, non-sourced use of `typex` amounts to an enhanced version of the `which` utility.

## Installation from the npm registry

<sup>Note: Even if you don't use Node.js, its package manager, `npm`, works across platforms and is easy to install; try [`curl -L http://git.io/n-install | bash`](https://github.com/mklement0/n-install)</sup>

With [Node.js](http://nodejs.org/) or [io.js](https://iojs.org/) installed, install [the package](https://www.npmjs.com/package/typex) as follows:

Expand All @@ -112,7 +117,7 @@ With [Node.js](http://nodejs.org/) or [io.js](https://iojs.org/) installed, inst
**IMPORTANT**: After installation, run `typex -i` to add sourcing of `typex` to the per-user initialization file of all supported shells that are present (e.g., `~/.bashrc`).
To remove these sourcing commands later, run `typex -u`.

### Manual installation
## Manual installation

* Download [this `bash` script](https://raw.githubusercontent.com/mklement0/typex/stable/bin/typex) as `typex`.
* Make it executable with `chmod +x typex`.
Expand All @@ -121,189 +126,78 @@ To remove these sourcing commands later, run `typex -u`.
**IMPORTANT**: After installation, run `typex -i` to add sourcing of `typex` to the per-user initialization file of all supported shells that are present (e.g., `~/.bashrc`).
To remove these sourcing commands later, run `typex -u`.

## Usage
# Usage

Find concise usage information below; for complete documentation, read the [manual online](doc/typex.md), or, once installed, run `man typex` (`typex --man` if installed manually).

<!-- DO NOT EDIT THE FENCED CODE BLOCK and RETAIN THIS COMMENT: The fenced code block below is updated by `make update-readme/release` with CLI usage information. -->

```nohighlight
$ typex --help
SYNOPSIS
typex [-p] [-V] [-v] [name ...]
typex -i|-u
DESCRIPTION
An extended version of the `type` utility that incorporates elements
of the `which` and `file` utilities.
Determines if NAME refers to one or more of the following command forms:
alias, shell keyword, shell function, builtin, or
executable file in the PATH
Provides more information than `type -a`, notably executable
type, symlink chains, and version information.
Alternatively, NAME may be a *filesystem path* rather than a mere (file)name,
in which case information about that path is reported.
Not specying any NAME prints information about the current shell.
NOTE: For this utility to detect the current shell's aliases, keywords,
(non-exported) shell functions, and builtins, it must be
*sourced*, which is supported in the following shells:
bash, ksh, zsh
Sourcing this utility without arguments in your shell's per-user
initialization file will define a function of the same name that
will be available throughout the session.
- typex -i installs this sourcing for all supported shells,
- typex -u uninstalls it.
Ad-hoc and in scripts, you can source and invoke at the same time;
e.g.:
. typex read
If you instead invoke this utility directly:
- only executable *files* will be detected - no other command forms;
- a warning to that effect is printed; suppress it with -p.
-p
Only looks for (executable) *files* (ignores aliases, keywords, functions,
and builtins). This option applies implicity if NAME is a filesystem path
rather than a mere command name.
-V
Suppresses the attempt to obtain version information from executable
files. Helpful if you know that the target file doesn't support --version,
or you're wary of what invocation with --version might do.
-v
Verbose mode: prints additional information - see below.
Note that, unless you specified a filesystem path, ALL defined forms of a
given command name are reported, in order of precedence (highest first).
bash, zsh: alias > shell keyword > shell function > builtin > executable
ksh: shell keyword > alias > shell function > builtin > executable
All output starts with a headword identifying the command form / path type,
as in the description below.
Output for each command form is single-line, except for the optional
information added by -v; the latter is indented with 2 spaces.
The exit code is 0 if all NAMEs were found, the number of non-existent
NAMES otherwise.
ALIAS:
Prints the alias's definition. If the first token of the alias'
definition is itself a command, information about that command is
printed as well, in indented form, potentially recursively.
No attempt is made to detect additional commands inside the alias
definition.
-v is never applied to the recursive calls.
KEYWORD:
A shell-language keyword, such as `while`; the name is printed.
FUNCTION:
Prints the function name, followed by '()'; e.g., 'foo()'.
In bash, if the function is also exported, ' # -x' is appended.
With -v specified:
The function definition (its source code) is printed, too.
BUILTIN:
Prints the builtin's name.
BINARY / SCRIPT / DIRECTORY / FILE:
Prints files' full path, and, in the case of a symlink, the *entire
symlink chain to the ultimate target file*, using full paths.
If the file is not itself a symlink, but has symlink components
(directories) in its *path*, the input path is printed as well
as the canonical path with all symlinks resolved.
If the file is an executable script, interpreter information is
appended in parentheses; e.g., '(bash script)'.
If the file is non-executable, file-type information obtained with
`file` is appended in parentheses; e.g., '(ASCII text)'.
If the file is a special file such as /dev/null, its type is also
appended in parentheses; e.g., '(character special)'.
Unless -V was specified, an attempt is made to obtain version information
through invocation of the executable file with --version.
If -V was specified, or if no version information was found, the
last-modified timestamp of the (ultimate target) file is used.
Whatever information is available is appended in square brackets; e.g.,
'[ls (GNU coreutils) 8.21]' or '[2014-09-09]'
With -v specified:
File statistics (permissions, owner, ...) are printed, using `ls -l`.
For symlinks, this happens for every file in the symlink chain.
Additional information printed for executables:
- binaries: file-type information obtained with `file`.
- scripts: the shebang line.
COMPATIBILITY
Platforms supported in principle:
OSX, Linux, BSD (with bash installed)
Among those, sourcing the script (recommmended) works in the following
shells:
bash, ksh, zsh
EXAMPLES
# Print info about the current shell.
$ typex
BINARY: /bin/bash [GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin14)]
# Print info about utility 'awk' and its symlink chain:
$ typex awk
BINARY: /usr/bin/awk@ -> /etc/alternatives/awk -> /usr/bin/gawk [GNU Awk 4.0.1]
# Print information about command forms named 'printf' in order of
# precedence:
$ typex printf
BUILTIN: printf
BINARY: /usr/bin/printf [printf (GNU coreutils) 8.21]
# Print information about script 'npm':
$ typex -p npm
SCRIPT: /usr/local/bin/npm (node script) [2.1.7]
# Print information about executables 'nawk' and 'mawk':
$ typex -p nawk mawk
BINARY: /usr/bin/nawk@ -> /etc/alternatives/nawk@ -> /usr/bin/gawk [GNU Awk 4.0.1]
BINARY: /usr/bin/mawk [2014-03-24]
# Define an alias and print information about it.
$ alias lsx='ls -FAhl'; typex lsx
ALIAS: lsx='ls -FAhl'
BINARY: /bin/ls [ls (GNU coreutils) 8.21]
Reports salient information about available commands, programs, and
filesystem items, such as command or file type, (ultimate) location,
and version.
typex [-p] [-V] [-v] [<nameOrPath>...]
-p look for files only (ignore shell aliases, keywords, functions,
builtins)
-V skip attempt to obtain executable version information
-v verbose mode: report additional information
Install / uninstall sourcing via shell-initialization files (required
to detect aliases, functions, shell builtins - supported in
Bash, Ksh, Zsh):
typex -i
typex -u
```

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'LICENSE.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

## License
# License

Copyright (c) 2015 Michael Klement <mklement0@gmail.com> (http://same2u.net), released under the [MIT license](https://spdx.org/licenses/MIT#licenseText).

### Acknowledgements
## Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

[npm](https://www.npmjs.com/) dependencies below have optional suffixes denoting the type of dependency; the _absence_ of a suffix denotes a required _run-time_ dependency: `(D)` denotes a _development-time-only_ dependency, `(O)` an _optional_ dependency, and `(P)` a _peer_ dependency.

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the dependencies from 'package.json'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

### npm dependencies
## npm dependencies

* [doctoc (D)](https://github.com/thlorenz/doctoc)
* [json (D)](https://github.com/trentm/json)
* [marked-man (D)](https://github.com/kapouer/marked-man#readme)
* [replace (D)](https://github.com/harthur/replace)
* [semver (D)](https://github.com/npm/node-semver#readme)
* [shall (D)](https://github.com/mklement0/shall)
* [urchin (D)](https://github.com/tlevine/urchin)

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'CHANGELOG.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

## Changelog
# Changelog

Versioning complies with [semantic versioning (semver)](http://semver.org/).

<!-- NOTE: An entry template is automatically added each time `make version` is called. Fill in changes afterwards. -->

* **[v0.4.0](https://github.com/mklement0/typex/compare/v0.3.3...v0.4.0)** (2015-09-21):
* [potentially breaking change] `typex` now accepts options _after_ operands
as well (except after `--`), and now also accepts long option names.
* [doc] `typex` now has a man page (if manually installed, use `typex --man`);
`typex -h` now just prints concise usage information.
* [doc] Read-me improved.
* [fix] Various fixes and stability improvements.
* [dev] Installation of sourcing (with `-i`) no longer uses `ed` so as to
work on a wider range of platforms, notably Fedora.
* [dev] Tests improved, additional tests added.

* **[v0.3.3](https://github.com/mklement0/typex/compare/v0.3.2...v0.3.3)** (2015-09-15):
* [dev] Makefile improvements; various other behind-the-scenes tweaks.

Expand Down
4 changes: 2 additions & 2 deletions TODO.md
View file
@@ -1,8 +1,8 @@

* Fix the following scenario to truly report all intermediary targets

/Users/mklement/bin/fls@ -> /Users/mklement/lib/node_modules/fls/bin/fls
/Users/mklement/lib/node_modules/fls@ -> /Users/mklement/Documents/Projects/OSS/fls
/Users/mklement/bin/fls@ -> /Users/mklement/lib/node_modules/fls/bin/fls
/Users/mklement/lib/node_modules/fls@ -> /Users/mklement/Documents/Projects/OSS/fls

That is, the symlink points to file inside a symlinked *directory*.
Currently, we only report the start- and endpoints of such a chain.
Expand Down

0 comments on commit a5d7d4a

Please sign in to comment.