From 92dec83621a0da02046f8e29313d8e6e02b2e54e Mon Sep 17 00:00:00 2001 From: "Masih H. Derkani" Date: Wed, 4 Aug 2021 16:36:26 +0100 Subject: [PATCH] Update the readme with link to examples Add examples link to the README and refine its structure. List features of CARv2. Use stronger language to encourage users to use `v2` over `v0`. --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index faec4b6..7ccf7cc 100644 --- a/README.md +++ b/README.md @@ -9,25 +9,61 @@ go-car (go!) > A library to interact with merkledags stored as a single file -This is an implementation in Go of the [CAR spec](https://ipld.io/specs/transport/car/). +This is a Go implementation of the [CAR specifications](https://ipld.io/specs/transport/car/), both [CARv1](https://ipld.io/specs/transport/car/carv1/) and [CARv2](https://ipld.io/specs/transport/car/carv2/). Note that there are two major module versions: -* [go-car/v2](v2/) is geared towards reading and writing CARv2 files, and also +* [`go-car/v2`](v2/) is geared towards reading and writing CARv2 files, and also supports consuming CARv1 files and using CAR files as an IPFS blockstore. -* go-car v0, in the root directory, just supports reading and writing CARv1 files. +* `go-car` v0, in the root directory, just supports reading and writing CARv1 files. -Most users should attempt to use v2, especially for new software. +Most users should use v2, especially for new software, since the v2 API transparently supports both CAR formats. + +## Features + +[CARv2](v2) features: +* [Generate index](https://pkg.go.dev/github.com/ipld/go-car/v2#GenerateIndex) from an existing CARv1 file +* [Wrap](https://pkg.go.dev/github.com/ipld/go-car/v2#WrapV1) CARv1 files into a CARv2 with automatic index generation. +* Random-access to blocks in a CAR file given their CID via [Read-Only blockstore](https://pkg.go.dev/github.com/ipld/go-car/v2/blockstore#NewReadOnly) API, with transparent support for both CARv1 and CARv2 +* Write CARv2 files via [Read-Write blockstore](https://pkg.go.dev/github.com/ipld/go-car/v2/blockstore#OpenReadWrite) API, with support for appending blocks to an existing CARv2 file, and resumption from a partially written CARv2 files. +* Individual access to [inner CARv1 data payload]((https://pkg.go.dev/github.com/ipld/go-car/v2#Reader.DataReader)) and [index]((https://pkg.go.dev/github.com/ipld/go-car/v2#Reader.IndexReader)) of a CARv2 file via the `Reader` API. + +## Install + +To install the latest version of `go-car/v2` module, run: +```shell script +go get github.com/ipld/go-car/v2 +``` + +Alternatively, to install the v0 module, run: +```shell script +go get github.com/ipld/go-car +``` + +## API Documentation + +See docs on [pkg.go.dev](https://pkg.go.dev/github.com/ipld/go-car). + +## Examples + +Here is a shortlist of other examples from the documentation + +* [Wrap an existing CARv1 file into an indexed CARv2 file](https://pkg.go.dev/github.com/ipld/go-car/v2#example-WrapV1File) +* [Open read-only blockstore from a CAR file](https://pkg.go.dev/github.com/ipld/go-car/v2/blockstore#example-OpenReadOnly) +* [Open read-write blockstore from a CAR file](https://pkg.go.dev/github.com/ipld/go-car/v2/blockstore#example-OpenReadWrite) +* [Read the index from an existing CARv2 file](https://pkg.go.dev/github.com/ipld/go-car/v2/index#example-ReadFrom) +* [Extract the index from a CARv2 file and store it as a separate file](https://pkg.go.dev/github.com/ipld/go-car/v2/index#example-WriteTo) ## Maintainers -[Daniel Martí](https://github.com/mvdan) and [Masih Derkani](https://github.com/masih). +* [Daniel Martí](https://github.com/mvdan) +* [Masih Derkani](https://github.com/masih) ## Contribute PRs are welcome! -Small note: If editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. +When editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. ## License -- GitLab