github.com/benhoyt/goawk@v1.8.1/README.md (about)

     1  # GoAWK: an AWK interpreter written in Go
     2  
     3  [![Documentation](https://pkg.go.dev/badge/github.com/benhoyt/goawk)](https://pkg.go.dev/github.com/benhoyt/goawk)
     4  [![GitHub Actions Build](https://github.com/benhoyt/goawk/workflows/Go/badge.svg)](https://github.com/benhoyt/goawk/actions?query=workflow%3AGo)
     5  
     6  
     7  AWK is a fascinating text-processing language, and somehow after reading the delightfully-terse [*The AWK Programming Language*](https://ia802309.us.archive.org/25/items/pdfy-MgN0H1joIoDVoIC7/The_AWK_Programming_Language.pdf) I was inspired to write an interpreter for it in Go. So here it is, feature-complete and tested against "the one true AWK" test suite.
     8  
     9  [**Read more about how GoAWK works and performs here.**](https://benhoyt.com/writings/goawk/)
    10  
    11  ## Basic usage
    12  
    13  To use the command-line version, simply use `go install` to install it, and then run it using `goawk` (assuming `$GOPATH/bin` is in your `PATH`):
    14  
    15  ```shell
    16  $ go install github.com/benhoyt/goawk@latest
    17  $ goawk 'BEGIN { print "foo", 42 }'
    18  foo 42
    19  $ echo 1 2 3 | goawk '{ print $1 + $3 }'
    20  4
    21  ```
    22  
    23  On Windows, `"` is the shell quoting character, so use `"` around the entire AWK program on the command line, and use `'` around AWK strings -- this is a non-POSIX extension to make GoAWK easier to use on Windows:
    24  
    25  ```powershell
    26  C:\> goawk "BEGIN { print 'foo', 42 }"
    27  foo 42
    28  ```
    29  
    30  To use it in your Go programs, you can call `interp.Exec()` directly for simple needs:
    31  
    32  ```go
    33  input := bytes.NewReader([]byte("foo bar\n\nbaz buz"))
    34  err := interp.Exec("$0 { print $1 }", " ", input, nil)
    35  if err != nil {
    36      fmt.Println(err)
    37      return
    38  }
    39  // Output:
    40  // foo
    41  // baz
    42  ```
    43  
    44  Or you can use the `parser` module and then `interp.ExecProgram()` to control execution, set variables, etc:
    45  
    46  ```go
    47  src := "{ print NR, tolower($0) }"
    48  input := "A\naB\nAbC"
    49  
    50  prog, err := parser.ParseProgram([]byte(src), nil)
    51  if err != nil {
    52      fmt.Println(err)
    53      return
    54  }
    55  config := &interp.Config{
    56      Stdin: bytes.NewReader([]byte(input)),
    57      Vars:  []string{"OFS", ":"},
    58  }
    59  _, err = interp.ExecProgram(prog, config)
    60  if err != nil {
    61      fmt.Println(err)
    62      return
    63  }
    64  // Output:
    65  // 1:a
    66  // 2:ab
    67  // 3:abc
    68  ```
    69  
    70  Read the [documentation](https://pkg.go.dev/github.com/benhoyt/goawk) for more details.
    71  
    72  ## Differences from AWK
    73  
    74  The intention is for GoAWK to conform to `awk`'s behavior and to the [POSIX AWK spec](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/awk.html), but this section describes some areas where it's different.
    75  
    76  Additional features GoAWK has over AWK:
    77  
    78  * It's embeddable in your Go programs! You can even call custom Go functions from your AWK scripts.
    79  * I/O-bound AWK scripts (which is most of them) are significantly faster than `awk`, and on a par with `gawk` and `mawk`.
    80  * The parser supports `'single-quoted strings'` in addition to `"double-quoted strings"`, primarily to make Windows one-liners easier (the Windows `cmd.exe` shell uses `"` as the quote character).
    81  
    82  Things AWK has over GoAWK:
    83  
    84  * CPU-bound AWK scripts are slightly slower than `awk`, and about twice as slow as `gawk` and `mawk`.
    85  * AWK is written by Brian Kernighan.
    86  
    87  ## Stability
    88  
    89  This project has a good suite of tests, and I've used it a bunch personally, but it's certainly not battle-tested or heavily used, so please use at your own risk. I intend not to change the Go API in a breaking way.
    90  
    91  ## License
    92  
    93  GoAWK is licensed under an open source [MIT license](https://github.com/benhoyt/goawk/blob/master/LICENSE.txt).
    94  
    95  ## The end
    96  
    97  Have fun, and please [contact me](https://benhoyt.com/) if you're using GoAWK or have any feedback!