Skip to content

Commit

Permalink
move go documentation to godoc
Browse files Browse the repository at this point in the history
  • Loading branch information
evanw committed Jun 11, 2020
1 parent 4a3bc51 commit 5efc19c
Show file tree
Hide file tree
Showing 5 changed files with 238 additions and 237 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ This is a JavaScript bundler and minifier. It packages up JavaScript and TypeScr
## Documentation

* [JavaScript API documentation](docs/js-api.md)
* [Go API documentation](docs/go-api.md)
* [Go API documentation](https://godoc.org/github.com/evanw/esbuild/pkg/api)
* [Architecture documentation](docs/architecture.md)
* [中文文档](http://docs.breword.com/evanw-esbuild/)

Expand Down
129 changes: 0 additions & 129 deletions docs/go-api.md

This file was deleted.

79 changes: 79 additions & 0 deletions pkg/api/api.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,82 @@
// This API exposes esbuild's two main operations: building and transforming.
// It's intended for integrating esbuild into other tools as a library.
//
// If you are just trying to run esbuild from Go without the overhead of
// creating a child process, there is also an API for the command-line
// interface itself: https://godoc.org/github.com/evanw/esbuild/pkg/cli.
//
// Build API
//
// This function runs an end-to-end build operation. It takes an array of file
// paths as entry points, parses them and all of their dependencies, and
// returns the output files to write to the file system. The available options
// roughly correspond to esbuild's command-line flags.
//
// Example usage:
//
// package main
//
// import (
// "fmt"
// "io/ioutil"
//
// "github.com/evanw/esbuild/pkg/api"
// )
//
// func main() {
// result := api.Build(api.BuildOptions{
// EntryPoints: []string{"input.js"},
// Outfile: "output.js",
// Bundle: true,
// })
//
// fmt.Printf("%d errors and %d warnings\n",
// len(result.Errors), len(result.Warnings))
//
// for _, out := range result.OutputFiles {
// ioutil.WriteFile(out.Path, out.Contents, 0644)
// }
// }
//
// Transform API
//
// This function transforms a string of source code into JavaScript. It can be
// used to minify JavaScript, convert TypeScript/JSX to JavaScript, or convert
// newer JavaScript to older JavaScript. The available options roughly
// correspond to esbuild's command-line flags.
//
// Example usage:
//
// package main
//
// import (
// "fmt"
// "os"
//
// "github.com/evanw/esbuild/pkg/api"
// )
//
// func main() {
// jsx := `
// import * as React from 'react'
// import * as ReactDOM from 'react-dom'
//
// ReactDOM.render(
// <h1>Hello, world!</h1>,
// document.getElementById('root')
// );
// `
//
// result := api.Transform(jsx, api.TransformOptions{
// Loader: api.LoaderJSX,
// })
//
// fmt.Printf("%d errors and %d warnings\n",
// len(result.Errors), len(result.Warnings))
//
// os.Stdout.Write(result.JS)
// }
//
package api

type SourceMap uint8
Expand Down
155 changes: 60 additions & 95 deletions pkg/cli/cli.go
Original file line number Diff line number Diff line change
@@ -1,106 +1,71 @@
// This API exposes the command-line interface for esbuild. It can be used to
// run esbuild from Go without the overhead of creating a child process.
//
// Example usage:
//
// package main
//
// import (
// "os"
//
// "github.com/evanw/esbuild/pkg/cli"
// )
//
// func main() {
// os.Exit(cli.Run(os.Args[1:]))
// }
//
package cli

import (
"fmt"
"io/ioutil"
"os"
"path/filepath"
"strings"

"github.com/evanw/esbuild/internal/logging"
"github.com/evanw/esbuild/pkg/api"
)

// This function invokes the esbuild CLI. It takes an array of command-line
// arguments (excluding the executable argument itself) and returns an exit
// code. There are some minor differences between this CLI and the actual
// "esbuild" executable such as the lack of auxiliary flags (e.g. "--help" and
// "--version") but it is otherwise exactly the same code.
func Run(osArgs []string) int {
buildOptions, transformOptions, err := parseOptionsForRun(osArgs)

switch {
case buildOptions != nil:
// Run the build and stop if there were errors
result := api.Build(*buildOptions)
if len(result.Errors) > 0 {
return 1
}

// Special-case writing to stdout
if buildOptions.Outfile == "" && buildOptions.Outdir == "" {
if len(result.OutputFiles) != 1 {
logging.PrintErrorToStderr(osArgs, fmt.Sprintf(
"Internal error: did not expect to generate %d files when writing to stdout", len(result.OutputFiles)))
} else if _, err := os.Stdout.Write(result.OutputFiles[0].Contents); err != nil {
logging.PrintErrorToStderr(osArgs, fmt.Sprintf(
"Failed to write to stdout: %s", err.Error()))
}
} else {
for _, outputFile := range result.OutputFiles {
if err := os.MkdirAll(filepath.Dir(outputFile.Path), 0755); err != nil {
result.Errors = append(result.Errors, api.Message{Text: fmt.Sprintf(
"Failed to create output directory: %s", err.Error())})
} else if err := ioutil.WriteFile(outputFile.Path, outputFile.Contents, 0644); err != nil {
logging.PrintErrorToStderr(osArgs, fmt.Sprintf(
"Failed to write to output file: %s", err.Error()))
}
}
}

case transformOptions != nil:
// Read the input from stdin
bytes, err := ioutil.ReadAll(os.Stdin)
if err != nil {
logging.PrintErrorToStderr(osArgs, fmt.Sprintf(
"Could not read from stdin: %s", err.Error()))
return 1
}

// Run the transform and stop if there were errors
result := api.Transform(string(bytes), *transformOptions)
if len(result.Errors) > 0 {
return 1
}

// Write the output to stdout
os.Stdout.Write(result.JS)

case err != nil:
logging.PrintErrorToStderr(osArgs, err.Error())
return 1
}

return 0
return runImpl(osArgs)
}

// This returns either BuildOptions, TransformOptions, or an error
func parseOptionsForRun(osArgs []string) (*api.BuildOptions, *api.TransformOptions, error) {
// If there's an entry point, then we're building
for _, arg := range osArgs {
if !strings.HasPrefix(arg, "-") {
options := newBuildOptions()

// Apply defaults appropriate for the CLI
options.ErrorLimit = 10
options.LogLevel = api.LogLevelInfo

err := parseOptionsImpl(osArgs, &options, nil)
if err != nil {
return nil, nil, err
}
return &options, nil, nil
}
}

// Otherwise, we're transforming
options := newTransformOptions()

// Apply defaults appropriate for the CLI
options.ErrorLimit = 10
options.LogLevel = api.LogLevelInfo
// This parses an array of strings into an options object suitable for passing
// to "api.Build()". Use this if you need to reuse the same argument parsing
// logic as the esbuild CLI.
//
// Example usage:
//
// options, err := cli.ParseBuildOptions([]string{
// "input.js",
// "--bundle",
// "--minify",
// })
//
// result := api.Build(options)
//
func ParseBuildOptions(osArgs []string) (options api.BuildOptions, err error) {
options = newBuildOptions()
err = parseOptionsImpl(osArgs, &options, nil)
return
}

err := parseOptionsImpl(osArgs, nil, &options)
if err != nil {
return nil, nil, err
}
if options.Sourcemap != api.SourceMapNone && options.Sourcemap != api.SourceMapInline {
return nil, nil, fmt.Errorf("Must use \"inline\" source map when transforming stdin")
}
return nil, &options, nil
// This parses an array of strings into an options object suitable for passing
// to "api.Transform()". Use this if you need to reuse the same argument
// parsing logic as the esbuild CLI.
//
// Example usage:
//
// options, err := cli.ParseTransformOptions([]string{
// "--minify",
// "--loader=tsx",
// "--define:DEBUG=false",
// })
//
// result := api.Transform(input, options)
//
func ParseTransformOptions(osArgs []string) (options api.TransformOptions, err error) {
options = newTransformOptions()
err = parseOptionsImpl(osArgs, nil, &options)
return
}
Loading

0 comments on commit 5efc19c

Please sign in to comment.