From 6e3c54256ccc2d9f684ee0aaa04a7ba0a158f121 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 8 Aug 2019 10:21:37 +1000 Subject: [PATCH] Re-organize ractool's usage as a doc comment --- cmd/ractool/main.go | 99 +++++++++++++++++++++++++++++--------------- doc/spec/rac-spec.md | 7 +++- 2 files changed, 72 insertions(+), 34 deletions(-) diff --git a/cmd/ractool/main.go b/cmd/ractool/main.go index a3373b0b..136a1ed2 100644 --- a/cmd/ractool/main.go +++ b/cmd/ractool/main.go @@ -14,7 +14,65 @@ // ---------------- -// ractool manipulates Random Access Compression (RAC) files. +/* +ractool manipulates Random Access Compression (RAC) files. + +Usage: + +ractool [flags] [input_filename] + +If no input_filename is given, stdin is used. Either way, output is written to +stdout. + +The flags should include exactly one of -decode or -encode. + +When encoding, the input is partitioned into chunks and each chunk is +compressed independently. You can specify the target chunk size in terms of +either its compressed size or decompressed size. By default (if both +-cchunksize and -dchunksize are zero), a 64KiB -cchunksize is used. + +You can also specify a -cpagesize, which is similar to but not exactly the same +concept as alignment. If non-zero, padding is inserted into the output to +minimize the number of pages that each chunk occupies. Look for "CPageSize" in +the "package rac" documentation for more details: +https://godoc.org/github.com/google/wuffs/lib/rac + +A RAC file consists of an index and the chunks. The index may be either at the +start or at the end of the file. See the RAC specification for more details: +https://github.com/google/wuffs/blob/master/doc/spec/rac-spec.md + +Examples: + + ractool -decode foo.rac | sha256sum + ractool -decode -drange=400:500 foo.rac + ractool -encode foo.dat > foo.rac + ractool -encode -codec=zlib -dchunksize=256 foo.dat > foo.raczlib + +General Flags: + +-decode + whether to decode the input +-encode + whether to encode the input + +Decode-Related Flags: + +-drange + the "i:j" range to decompress, ":8" means the first 8 bytes + +Encode-Related Flags: + +-cchunksize + the chunk size (in CSpace) +-codec + the compression codec (default "zlib") +-cpagesize + the page size (in CSpace) +-dchunksize + the chunk size (in DSpace) +-indexlocation + the index location, "start" or "end" (default "start") +*/ package main import ( @@ -39,44 +97,19 @@ var ( // Decode-related flags. drangeFlag = flag.String("drange", ":", - "when decoding, the \"i:j\" range to decompress, \":8\" means the first 8 bytes") + "the \"i:j\" range to decompress, \":8\" means the first 8 bytes") // Encode-related flags. - codecFlag = flag.String("codec", "zlib", "when encoding, the compression codec") - cpagesizeFlag = flag.Uint64("cpagesize", 0, "when encoding, the page size (in CSpace)") - cchunksizeFlag = flag.Uint64("cchunksize", 0, "when encoding, the chunk size (in CSpace)") - dchunksizeFlag = flag.Uint64("dchunksize", 0, "when encoding, the chunk size (in DSpace)") + codecFlag = flag.String("codec", "zlib", "the compression codec") + cpagesizeFlag = flag.Uint64("cpagesize", 0, "the page size (in CSpace)") + cchunksizeFlag = flag.Uint64("cchunksize", 0, "the chunk size (in CSpace)") + dchunksizeFlag = flag.Uint64("dchunksize", 0, "the chunk size (in DSpace)") indexlocationFlag = flag.String("indexlocation", "start", - "when encoding, the index location, \"start\" or \"end\"") + "the index location, \"start\" or \"end\"") ) -const usageStr = `usage: ractool [flags] [input_filename] - -If no input_filename is given, stdin is used. Either way, output is written to -stdout. - -The flags should include exactly one of -decode or -encode. - -When encoding, the input is partitioned into chunks and each chunk is -compressed independently. You can specify the target chunk size in terms of -either its compressed size or decompressed size. By default (if both --cchunksize and -dchunksize are zero), a 64KiB -cchunksize is used. - -You can also specify a -cpagesize, which is similar to but not exactly the same -concept as alignment. If non-zero, padding is inserted into the output to -minimize the number of pages that each chunk occupies. Look for "CPageSize" in -the "package rac" documentation for more details. - -A RAC file consists of an index and the chunks. The index may be either at the -start or at the end of the file. See the RAC specification for more details: - -https://github.com/google/wuffs/blob/master/doc/spec/rac-spec.md - -` - func usage() { - fmt.Fprintf(os.Stderr, usageStr) - flag.PrintDefaults() + // TODO: fmt.Fprintf(os.Stderr, usageStr) } func main() { diff --git a/doc/spec/rac-spec.md b/doc/spec/rac-spec.md index aecdec6d..e61e367d 100644 --- a/doc/spec/rac-spec.md +++ b/doc/spec/rac-spec.md @@ -656,11 +656,16 @@ and `0x00`, which means that they are both `CBiasing Branch Node`s. # Reference Implementation -In the Go programming language: +Go programming language libraries: - [RAC](https://godoc.org/github.com/google/wuffs/lib/rac) - [RAC + Zlib](https://godoc.org/github.com/google/wuffs/lib/raczlib) +Command line tool, installable via `go get +github.com/google/wuffs/cmd/ractool`: + + - [ractool](https://godoc.org/github.com/google/wuffs/cmd/ractool) + # Acknowledgements