js-cfb/README.md

155 lines
4.7 KiB
Markdown
Raw Normal View History

# Compound File Binary Format
2013-09-05 18:55:36 +00:00
2017-09-14 21:14:22 +00:00
Pure-JS implementation of MS-CFB: Compound File Binary File Format, a container
format used in many Microsoft file types (XLS, DOC, VBA blobs in XLSX and XLSB)
2013-09-05 18:55:36 +00:00
2017-09-14 21:14:22 +00:00
[![Build Status](https://travis-ci.org/SheetJS/js-cfb.svg?branch=master)](https://travis-ci.org/SheetJS/js-cfb)
[![Coverage Status](http://img.shields.io/coveralls/SheetJS/js-cfb/master.svg)](https://coveralls.io/r/SheetJS/js-cfb?branch=master)
[![Dependencies Status](https://david-dm.org/sheetjs/js-cfb/status.svg)](https://david-dm.org/sheetjs/js-cfb)
[![NPM Downloads](https://img.shields.io/npm/dt/cfb.svg)](https://npmjs.org/package/cfb)
[![ghit.me](https://ghit.me/badge.svg?repo=sheetjs/js-xlsx)](https://ghit.me/repo/sheetjs/js-xlsx)
[![Analytics](https://ga-beacon.appspot.com/UA-36810333-1/SheetJS/js-cfb?pixel)](https://github.com/SheetJS/js-cfb)
## Installation
In the browser:
```html
<script src="dist/cfb.min.js" type="text/javascript"></script>
```
2013-09-05 18:55:36 +00:00
With [npm](https://www.npmjs.org/package/cfb):
2013-09-05 18:55:36 +00:00
```bash
2017-09-14 21:14:22 +00:00
$ npm install cfb
2013-09-05 18:55:36 +00:00
```
2017-09-14 21:14:22 +00:00
The `xlscfb.js` file is designed to be embedded in [js-xlsx](http://git.io/xlsx)
2017-09-14 21:14:22 +00:00
## Library Usage
In node:
```js
var CFB = require('cfb');
```
For example, to get the Workbook content from an XLS file:
```js
var cfb = CFB.read(filename, {type: 'file'});
2017-09-14 21:14:22 +00:00
var workbook = CFB.find(cfb, 'Workbook');
var data = workbook.content;
```
2017-09-14 21:14:22 +00:00
## Command-Line Utility Usage
It is preferable to install the library globally with npm:
2017-09-14 21:14:22 +00:00
```bash
$ npm install -g cfb
```
The global installation adds a command `cfb` which can work with existing files:
- `cfb file` will extract the contents of the file to the current directory.
It will make the corresponding subdirectories.
- `cfb --list-files file` will show a listing of the contained files.
The format follows the `unzip -l` "short format".
- `cfb --repair file` will attempt to repair by reading and re-writing the file.
This fixes some issues with files generated by non-standard tools.
## JS API
TypeScript definitions are maintained in `types/index.d.ts`.
The CFB object exposes the following methods and properties:
`CFB.parse(blob)` takes a nodejs Buffer or an array of bytes and returns an
parsed representation of the data.
2017-09-14 21:14:22 +00:00
`CFB.read(blob, opts)` wraps `parse`. `opts.type` controls the behavior:
2017-09-14 21:14:22 +00:00
- `file`: `blob` is interpreted as a file name that will be read
- `base64`: `blob` is interpreted as base64 string
- `binary`: `blob` is interpreted as binary string
- default: `blob` is interpreted as nodejs buffer or array of bytes
`CFB.find(cfb, path)` performs a case-insensitive match for the path (or file
name, if there are no slashes) and returns an entry object or null if not found.
2017-09-14 21:14:22 +00:00
`CFB.write(cfb, opts)` generates a file based on the container. `opts.type`
controls the behavior:
- `base64`: returns a base64 string
- `binary`: returns a binary string
- default: returns a nodejs buffer or array of bytes
`CFB.writeFile(cfb, filename, opts)` creates a file with the specified name.
## Utility Functions
The utility functions are available in the `CFB.utils` object. Functions that
accept a `name` argument strictly deal with absolute file names:
2017-09-14 21:14:22 +00:00
- `.cfb_new(?opts)` creates a new container object.
- `.cfb_add(cfb, name, ?content, ?opts)` adds a new file to the `cfb`.
- `.cfb_del(cfb, name)` deletes the specified file
- `.cfb_mov(cfb, old_name, new_name)` moves the old file to new path and name
2017-09-14 21:14:22 +00:00
## Container Object Description
The objects returned by `parse` and `read` have the following properties:
- `.FullPaths` is an array of the names of all of the streams (files) and
storages (directories) in the container. The paths are properly prefixed from
the root entry (so the entries are unique)
- `.FullPathDir` is an object whose keys are entries in `.FullPaths` and whose
values are objects with metadata and content (described below)
- `.FileIndex` is an array of the objects from `.FullPathDir`, in the same order
as `.FullPaths`.
- `.raw` contains the raw header and sectors
2017-09-14 21:14:22 +00:00
## Entry Object Description
The entry objects are available from `FullPathDir` and `FileIndex` elements of
2017-09-14 21:14:22 +00:00
the container object:
```typescript
interface CFBEntry {
name: string; /** Case-sensitive internal name */
type: number; /** 1 = dir, 2 = file, 5 = root ; see [MS-CFB] 2.6.1 */
content: Buffer | number[] | Uint8Array; /** Raw Content */
ct?: Date; /** Creation Time */
mt?: Date; /** Modification Time */
}
```
2017-09-14 21:14:22 +00:00
## License
2013-09-05 18:55:36 +00:00
2017-09-14 21:14:22 +00:00
Please consult the attached LICENSE file for details. All rights not explicitly
granted by the Apache 2.0 License are reserved by the Original Author.
2013-09-05 18:55:36 +00:00
2017-09-14 21:14:22 +00:00
## References
2017-09-14 21:14:22 +00:00
<details>
<summary><b>OSP-covered Specifications</b> (click to show)</summary>
2017-09-14 21:14:22 +00:00
- [MS-CFB]: Compound File Binary File Format
2017-09-14 21:14:22 +00:00
</details>