Skip to content

Commit

Permalink
Add extra helpers and ABI to template context
Browse files Browse the repository at this point in the history
  • Loading branch information
adisbladis committed Aug 31, 2018
1 parent 2cde490 commit b2a6d31
Show file tree
Hide file tree
Showing 21 changed files with 502 additions and 195 deletions.
104 changes: 2 additions & 102 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,104 +1,4 @@
# ABI Gen

This package allows you to generate TypeScript contract wrappers from ABI files.
It's heavily inspired by [Geth abigen](https://github.com/ethereum/go-ethereum/wiki/Native-DApps:-Go-bindings-to-Ethereum-contracts) but takes a different approach.
You can write your custom handlebars templates which will allow you to seamlessly integrate the generated code into your existing codebase with existing conventions.

[Here](https://github.com/0xProject/0x-monorepo/tree/development/packages/0x.js/contract_templates) are the templates used to generate the contract wrappers used by 0x.js.e

## Installation

`yarn add -g @0xproject/abi-gen`

## Usage

```
abi-gen
Options:
--help Show help [boolean]
--version Show version number [boolean]
--abis Glob pattern to search for ABI JSON files
[string] [required]
--output, -o, --out Folder where to put the output files [string] [required]
--partials Glob pattern for the partial template files [string]
--template Path for the main template file that will be used to
generate each contract [string] [required]
--backend The backing Ethereum library your app uses. Either 'web3'
or 'ethers'. Ethers auto-converts small ints to numbers
whereas Web3 doesn't.
[string] [choices: "web3", "ethers"] [default: "web3"]
--network-id ID of the network where contract ABIs are nested in
artifacts [number] [default: 50]
```

You're required to pass a [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) template where your abi files are located.
TL;DR - here is the example from 0x.js.

`--abis 'src/artifacts/@(Exchange|Token|TokenTransferProxy|EtherToken|TokenRegistry).json`

We could've just used `--abis 'src/artifacts/*.json` but we wanted to exclude some of the abi files.

The abi file should be either a [Truffle](http://truffleframework.com/) contract artifact (a JSON object with an abi key) or a JSON abi array.

You need to also specify the location of your main template used for every contract `--template` as well as the partial templates `--partials` that can later be used from the main one.

## How to write custom templates?

The best way to get started is to copy [0x.js templates](https://github.com/0xProject/0x-monorepo/tree/development/packages/contract_templates) and start adjusting them for your needs.
We use [handlebars](http://handlebarsjs.com/) template engine under the hood.
You need to have a master template called `contract.mustache`. it will be used to generate each contract wrapper. Although - you don't need and probably shouldn't write all your logic in a single template file. You can write [partial templates](http://handlebarsjs.com/partials.html) and as long as they are within a partials folder - they will be registered and available.

## Which data/context do I get in my templates?

For now you don't get much on top of methods abi, some useful helpers and a contract name because it was enough for our use-case, but if you need something else - create a PR.
See the [type definition](https://github.com/0xProject/0x-monorepo/tree/development/packages/abi-gen/src/types.ts) of what we pass to the render method.

## Output files

Output files will be generated within an output folder with names converted to camel case and taken from abi file names. If you already have some files in that folder they will be overwritten.

## Contributing

We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.

Please read our [contribution guidelines](../../CONTRIBUTING.md) before getting started.

### Install dependencies

If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:

```bash
yarn config set workspaces-experimental true
```

Then install dependencies

```bash
yarn install
```

### Build

To build this package and all other monorepo packages that it depends on, run the following from the monorepo root directory:

```bash
PKG=@0xproject/abi-gen yarn build
```

Or continuously rebuild on change:

```bash
PKG=@0xproject/abi-gen yarn watch
```

### Clean

```bash
yarn clean
```

### Lint

```bash
yarn lint
```
This is only a temporary fork of @0xproject/abi-gen
Do not rely on this in your projects
3 changes: 3 additions & 0 deletions lib/src/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#!/usr/bin/env node
export {};
//# sourceMappingURL=index.d.ts.map
1 change: 1 addition & 0 deletions lib/src/index.d.ts.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

182 changes: 182 additions & 0 deletions lib/src/index.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions lib/src/index.js.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

21 changes: 21 additions & 0 deletions lib/src/types.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { EventAbi, MethodAbi } from 'ethereum-types';
export declare enum ParamKind {
Input = "input",
Output = "output"
}
export declare enum ContractsBackend {
Web3 = "web3",
Ethers = "ethers"
}
export interface Method extends MethodAbi {
singleReturnValue: boolean;
hasReturnValue: boolean;
tsName: string;
functionSignature: string;
}
export interface ContextData {
contractName: string;
methods: Method[];
events: EventAbi[];
}
//# sourceMappingURL=types.d.ts.map
1 change: 1 addition & 0 deletions lib/src/types.d.ts.map

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 13 additions & 0 deletions lib/src/types.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit b2a6d31

Please sign in to comment.