Permalink
Browse files

Update docs.

  • Loading branch information...
saulpw committed Sep 4, 2017
1 parent 8a4fdb1 commit 91c31a5742c4a6516b77fd5c959e889286de5b0d
Showing with 69 additions and 51 deletions.
  1. +4 −0 CHANGELOG.md
  2. +47 −45 README.md
  3. +0 −5 ROADMAP
  4. +1 −1 docs/RELEASE.md
  5. +8 −0 docs/architecture.rst
  6. +9 −0 tests/README.md
View
@@ -8,6 +8,10 @@
- `gh` moves cursor to leftmost column (instead of leftmost non-key column)
- min_memory_mb now set to 100 by default. If `free` reports less memory, loading (or any async task) will be automatically aborted to prevent thrashing.
- theme options removed as CLI arguments (still available for .visidatarc or apps)
- fixed-column detector
- `'` appends frozen column
- renamed toplevel command() to globalCommand(); removed Sheet.command(); sheet commands now specified in Sheet.commands list of Command() objects at class level
- setter API now (sheet,col,row,value)
## 0.96 (2017-08-21)
- data can be piped through stdin
View
@@ -1,88 +1,90 @@
# VisiData v0.96 [![CircleCI](https://circleci.com/gh/saulpw/visidata/tree/stable.svg?style=svg)](https://circleci.com/gh/saulpw/visidata/tree/stable)
A terminal interface for exploring and arranging tabular data
A terminal interface for exploring and arranging tabular data.
<a href="https://github.com/saulpw/visidata/blob/develop/docs/tours.rst">![VisiData silent demo](docs/img/birdsdiet_bymass.gif)</a>
A few interesting commands:
## Dependencies
* `Shift-F` pushes a frequency analysis of the current column
* `=` creates a new column from the given Python expression (use column names to refer to their contents)
* `;` creates new columns from the match groups of the given regex
# Getting Started
## Install VisiData
- OS/X or Linux
- Python 3.3+
- other modules are required for opening particular filetypes
### from pypi (`stable` branch)
# Install
```
$ pip3 install visidata
```
### or clone from git
# Run
```
$ git clone http://github.com/saulpw/visidata.git
$ cd visidata
$ pip install -r requirements.txt
$ python setup.py install
$ vd [<options>] <input> ...
$ <command> | vd [<options>]
```
### Dependencies
Unknown filetypes are by default viewed with a text browser. Use `-f <filetype>` to force a particular filetype. VisiData supports tsv, csv, xlsx, hdf5, sqlite, ...
- Python 3.3+
- h5py and numpy (if opening .hdf5 files)
Here is the [options list]().
**Remember to install the Python3 versions of these packages with e.g. `pip3`**
VisiData supports 256-color terminals. Use [`vdcolor`](github.com/saulpw/visidata/stable/bin/vdcolor) to browse the available colors.
## Run VisiData
## Replay Script
If installed via pip3, `vd` should launch without issue.
To replay a previously [saved .vd script](https://github.com/saulpw/visidata/tree/develop/tests), which may be parameterized with `{format-field}`s:
```
$ vd [<options>] <input> ...
$ vd [<options>] < <input>
$ <command> | vd
$ vd [<options>] --play <script.vd> [--<format-field>=<value> ...]
$ vd [<options>] --play - [--<format-field>=<value> ...] < <script.vd>
```
If no inputs are given, `vd` opens the current directory.
Unknown filetypes are by default viewed with a text browser.
`<script.vd>` should be `-` if piped through stdin.
If installed via `git clone`, first set up some environment variables (on terminal):
## User Documentation
```
$ export PYTHONPATH=<visidata_dir>:$PYTHONPATH
$ export PATH=<visidata_dir>/bin:$PATH
$ man vd
$ man 2 vd
```
Further documentation is available at [readthedocs](https://visidata.readthedocs.io/).
The contents of the man page are also available at [online](https://visidata.org/man).
Here is a [quick reference of all commands](https://github.com/saulpw/visidata/blob/stable/docs/ascii-commands.txt). A few interesting ones:
## Contributing
* `Shift-F` pushes a frequency analysis of the current column
* `=` creates a new column from the given Python expression (use column names to refer to their contents)
* `;` creates new columns from the match groups of the given regex
# Developers
If something doesn't appear to be working right, please create [an issue on Github](). Include the full stack trace shown with `Ctrl-e`.
VisiData was created by Saul Pwanson `<vd@saul.pw>`.
To contribute a bugfix or a loader for another file format, fork from [develop](https://github.com/saulpw/visidata/tree/develop) and submit a [pull request](https://github.com/saulpw/visidata/pulls). Here is the [developer documentation for loaders]().
VisiData needs lots of usage and testing to help it become useful and reliable.
If you use VisiData, I would love it if you would send me a screencast!
Maybe there is an easy way to improve the tool for both of us.
Also please create a GitHub issue if anything doesn't appear to be working right.
If you get an unexpected error, please include the full stack trace that you get with `Ctrl-e`.
## Other vdtui projects
### Branch structure
The core `vdtui.py` can be used to quickly create efficient terminal workflows.
VisiData has two main branches:
* [stable](https://github.com/saulpw/visidata/tree/stable) has the last known good version of VisiData (which should be on pypi).
* [develop](https://github.com/saulpw/visidata/tree/develop) has the most up-to-date version of VisiData (which will eventually be merged to stable).
- [vgit](https://github.com/saulpw/vgit): a git interface
- [vdgalcon](https://github.com/saulpw/vdgalcon): a port of the classic game [Galactic Conquest](https://www.galcon.com)
If you wish to contribute, please fork from [develop](https://github.com/saulpw/visidata/tree/develop) and submit a [pull request](https://github.com/saulpw/visidata/pulls) against it.
Other workflows should be created as separate [apps using vdtui](docs/vdtui-dev.md). These apps can be very small; for example, see the included [viewtsv](bin/viewtsv) which is only one page of code.
A developer's guide can be found [here](http://visidata.readthedocs.io/en/stable/architecture.html).
Designs for other tools are being considered.
## Community
- [#visidata]() on freenode.net
- [r/visidata](https://www.reddit.com/r/visidata/)
- [mailing list]()
## License
The innermost core file, `vdtui.py`, is a single-file stand-alone library that provides a solid framework for building text user interface apps. It is distributed under the MIT free software license, and freely available for inclusion in other projects.
Other VisiData components, including the main `vd` application, addons, and other code in this repository, are licensed under GPLv3.
Other VisiData components, including the main `vd` application, addons, loaders, and other code in this repository, are available for reuse under licensed under GPLv3.
## Credits
VisiData was created by Saul Pwanson `<visidata@saul.pw>`. Thanks to @anjakefala for test and release support, to @databranner for documentation, and to those wonderful users who contribute feedback and in any form, for helping to make VisiData the awesome tool that it is.
View
@@ -4,13 +4,8 @@ A loose plan that is subject to change.
## v0.97
- manpage
- fixed-column detector
- SheetDiff
- `'` appends frozen column
## maybe
- vd --playerpiano
- replace sample-data with people data
## after 1.0
- Python expressions should be usable like regex for search, select, etc
View
@@ -83,4 +83,4 @@ twine upload dist/*
git tag v#.#.#
git push --tags
```
14. Announce the release and have some ice cream
14. Post the release notes on r/visidata and have some ice cream
View
@@ -20,6 +20,14 @@ closer to an RDBMS.
Constraining the data to fit within this architecture simplifies the
implementation and allows for some radical optimizations to data workflow.
The process of designing a sheet is:
1. Instantiate the sheet from a toplevel command (or other sheet);
2. Collect the rows from the sources in reload();
3. Enumerate the available columns;
4. Create commands to interact with the rows, columns, and cells.
5. Try the resulting workflow and iterate until it feels like magic.
----
One project, two licenses
View
@@ -0,0 +1,9 @@
# .vd files
`.vd` files are records of VisiData workflows, which can be run like scripts using the `--play` argument of `vd`.
To build a `.vd` file, run through a workflow and then press `Shift-D` to view the commandlog.
The commandlog can then be edited and then saved with `Ctrl-S`. Cells may be parameterized like `{foo}`, which can then be specified on the `vd --play` command-line as `--foo=value`.
This folder contains the `.vd` files which are referenced for VisiData system tests.

0 comments on commit 91c31a5

Please sign in to comment.