# texvcinfo
[![npm version](https://badge.fury.io/js/texvcinfo.svg)](http://badge.fury.io/js/texvcinfo)
[![Build Status][1]][2]
[![Coverage Status](https://coveralls.io/repos/github/wikimedia/texvcinfo/badge.svg?branch=master)](https://coveralls.io/github/wikimedia/texvcinfo?branch=master)

Prints the texvc tokens identified by texvcjs.
Moreover, texvcinfo provides additional information on the input such as
* listing the identifiers;
* discovering if the expressions ends with a dot.

This extension is used by [mathoid](https://github.com/wikimedia/mathoid). Some information generated by texvcinfo is
available at [Wikimedia REST API](https://en.wikipedia.org/api/rest_v1/#!/Math/post_media_math_check_type).

## Installation

Node version 0.10 are tested to work.

Install the node package dependencies with:
```
npm install
```
Ensure everything works:
```
npm test
```

## Usage

```
  Usage: texvcinfo [options] <tex input>

  Options:

    -h, --help             output usage information
    -V, --version          output the version number
    -v, --verbose          Show verbose error information
    -D, --debug            Show stack trace on failure.
    -c, --compact          Do not pretty print output.
    -f, --flat             Flattens the tree for elements with only one child
    -o, --output [format]  Output the info in a specific format. Available options are:
    "list": prints all tokens as list
    "tree": prints the texvc AST
    "json": a json object that can be visualized using d3
    "identifier": prints TeX code for all identifiers
    "all": is a combination of list, tree and identifier
    "feedback": returns data to generate user feedback in a ui
```

## Visuals
To see the tree structure you can output the result to (vis/data.json).
If you want to see the texvc parse tree of the texvc expression $\frac12$ run
```
./bin/texvcinfo -j \\frac12 > ./vis/data.json
```
.
In the (/vis/index.html) is a 90° rotated version of the interactive Reingold–Tilford tree from
http://bl.ocks.org/mbostock/4339083, that displays (vis/data.json).

##Error codes
Status is one character:

- "+" : success! result is in 'output'
- "E" : Lexer exception raised
- "F" : TeX function not recognized
- "S" : Parsing error
- "-" : Generic/Default failure code. Might be an invalid argument, output file already exist, a problem with an external command ...

## Implementation Details on Identifier extraction

This section provides details on the implementation of the identifier extraction of texvcinfo.

The identifier extraction is based on the [texvc](https://github.com/wikimedia/texvcjs) AST of the input TeX string. The main component is the [extractIdentifiers](lib/identifier.js#L79) visitor, which is supported by the [extractSubscipts](lib/extractors/subscripts.js#L77) and the [getModIdent](lib/extractors/mods.js#L20) visitor. Those visitors extend the functionality of the ast objects and define new methods to transform ast. Note, that [parsed texvc input](lib/index.js#L22) might be an array or a simple string rather than an ast object. Therefore, the [identifier extractor](lib/identifier.js#L47) differentiates between those three cases.


## License

Copyright (c) 2015 Moritz Schubotz, C. Scott Ananian

Licensed under GPLv2.


[1]: https://travis-ci.org/wikimedia/texvcinfo.svg?branch=master
[2]: https://travis-ci.org/wikimedia/texvcinfo?branch=master