# Hscpitt

hsc Project Interfering And Trashing Tool

`Hscpitt` can be used to extract and manipulate data stored in `hsc`'s project file. It lists all documents stored in the project and removes entries and corresponding files for documents.

`Hscpitt` is part of the hsc-distribution and therefor the same legal issues apply.

`Hscpitt` is dedicated to Brad Pitt.

Important: `hscpitt` should be used with caution. It assumes that the user knows what he is doing and does not ask back before performing any action. Using `hscpitt` it is rather easy to remove information within seconds that required hours being implemented.

## Options And Switches

`HELP=-h=?/S`
  Display short help message and exit.
`LICENSE/S`
  Display a short version of Copyright and exit.
`COMMAND`
  Command to be applied to project. Supported commands are:
  - `NEW` - create new project
  - `LIST` - show list of documents
  - `ADD` - add new document to project
  - `DELETE` - remove documents entries from project, but leave corresponding files intact
  - `ERASE` - remove documents entries from project andalso corresponding document and source file.
  - `EXTRACT` - show detailed list of all documents currently stored in project
  For a more detailed explanation of these commands see below.
`ARG/M`
  Arguments for command. Depends on the value of `COMMAND`.
`PRJFILE/K`
  Specifies project file to be examined/manipulated. If none given, hsc.project is used.
`QUIET/S`
  Act quietly, do not display progress and status messages.
`FORCE/S`
  Certain commands refuse to overwrite already existing data. Nevertheless with this switch enabled the will.
`-DEBUG/S`
  Enable debug mode; only useful if compiled in debug mode.

## Commands

### NEW

This command will create a new project file containing no documents. If the project file already exists, this command will refuse to overwrite it. You have to enable the switch `FORCE` to accomplish this.

### COUNT

Setting `COMMAND=COUNT` will output the number of documents currently stored in the project file.

### LIST

Setting `COMMAND=LIST` will output a short list of documents to `stdout`. Every line contains the name of an HTML object.

### ADD

Setting `COMMAND=ADD` will add a new document with it's corresponding main source to the project. The first `ARG` contains the full relative filename of the HTML object, the second `ARG` contains the name of the main hsc-source that will be used to create the document.

If the document already is part of the project, an error message will be displayed and the old document will be left untouched. To replace a document, you will have to enable the switch `FORCE` before.

### DELETE

Setting `COMMAND=DELETE` will remove the entries specified in `ARG` from the project file. The document and the corresponding source remains untouched.

### ERASE

Setting `COMMAND=ERASE` will remove the entries specified in `ARG` from the project file. Different to `COMMAND=DELETE`, it will also remove the files for document and source. This command should be used with caution.

### EXTRACT

Setting `COMMAND=EXTRACT` will output a detailed list of documents to `stdout`. This command is mend to be used if you want to utilize the information stored in the project file. Just redirect the output of `hscpitt` and scan it by your program.

All lines match the template

> identifier`="`value`"`

You must not make any assumptions about the sequence of identifiers. Your program should be able to skip unknown identifiers. At the end of data about a document, an `EOF` occurs or an empty line with another document succeeding.

Currently, possible identifers are:

`DOCUMENT`
  URI of document, relative to current directory
`SOURCE`
  Filename of main source file used to create document, relative to current directory
`INCLUDE`
  Name of a file that has been included during processing the document. This identifier can show up more then once, if multiple files have been included.

See also `hscpaltrow` to learn how you can utilize this command.

## Examples

`hscpitt HELP`
  Displays help and exits.
`hscpitt PRJFILE=sepp.project COMMAND=NEW`
  Create a new project and store data in sepp.project.
`hscpitt PRJFILE=sepp.project LIST`
  List all documents currently stored in project file sepp.project.
`hscpitt ADD ../docs/sepp.html sepp.hsc`
  Adds document sepp.html, which is created from sepp.hsc. Note that ../docs/ denotes the relative path, where the HTML objects are located. This usually is the same value you used as ```TO`'' argument to invoke `hsc`.
`hscpitt EXTRACT`
  List information about all documents currently stored in project file hsc.project.
`hscpitt COMMAND=DELETE www:index.html www:sepp/hugo.html`
  Remove entries for the documents www:index.html and www:sepp/hugo.html from the project file. The HTML object and hsc-sources for these documents will not be removed.