Annotation of src/usr.bin/awk/README.md, Revision 1.8
1.8 ! millert 1: $OpenBSD: README.md,v 1.7 2023/09/17 14:49:44 millert Exp $
1.1 millert 2:
3: # The One True Awk
4:
5: This is the version of `awk` described in _The AWK Programming Language_,
1.7 millert 6: Second Edition, by Al Aho, Brian Kernighan, and Peter Weinberger
7: (Addison-Wesley, 2024, ISBN-13 978-0138269722, ISBN-10 0138269726).
8:
9: ## What's New? ##
10:
11: This version of Awk handles UTF-8 and comma-separated values (CSV) input.
12:
13: ### Strings ###
14:
15: Functions that process strings now count Unicode code points, not bytes;
16: this affects `length`, `substr`, `index`, `match`, `split`,
17: `sub`, `gsub`, and others. Note that code
18: points are not necessarily characters.
19:
20: UTF-8 sequences may appear in literal strings and regular expressions.
21: Aribtrary characters may be included with `\u` followed by 1 to 8 hexadecimal digits.
22:
23: ### Regular expressions ###
24:
25: Regular expressions may include UTF-8 code points, including `\u`.
26: Character classes are likely to be limited to about 256 characters
27: when expanded.
28:
29: ### CSV ###
30:
31: The option `--csv` turns on CSV processing of input:
32: fields are separated by commas, fields may be quoted with
1.8 ! millert 33: double-quote (`"`) characters, quoted fields may contain embedded newlines.
1.7 millert 34: In CSV mode, `FS` is ignored.
35:
36: If no explicit separator argument is provided,
37: field-splitting in `split` is determined by CSV mode.
1.1 millert 38:
39: ## Copyright
40:
41: Copyright (C) Lucent Technologies 1997<br/>
42: All Rights Reserved
43:
44: Permission to use, copy, modify, and distribute this software and
45: its documentation for any purpose and without fee is hereby
46: granted, provided that the above copyright notice appear in all
47: copies and that both that the copyright notice and this
48: permission notice and warranty disclaimer appear in supporting
49: documentation, and that the name Lucent Technologies or any of
50: its entities not be used in advertising or publicity pertaining
51: to distribution of the software without specific, written prior
52: permission.
53:
54: LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
55: INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
56: IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY
57: SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
58: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
59: IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
60: ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
61: THIS SOFTWARE.
62:
63: ## Distribution and Reporting Problems
64:
65: Changes, mostly bug fixes and occasional enhancements, are listed
66: in `FIXES`. If you distribute this code further, please please please
67: distribute `FIXES` with it.
68:
69: If you find errors, please report them
1.6 millert 70: to the current maintainer, ozan.yigit@gmail.com.
1.1 millert 71: Please _also_ open an issue in the GitHub issue tracker, to make
72: it easy to track issues.
73: Thanks.
74:
75: ## Submitting Pull Requests
76:
1.2 millert 77: Pull requests are welcome. Some guidelines:
78:
79: * Please do not use functions or facilities that are not standard (e.g.,
80: `strlcpy()`, `fpurge()`).
81:
82: * Please run the test suite and make sure that your changes pass before
83: posting the pull request. To do so:
84:
85: 1. Save the previous version of `awk` somewhere in your path. Call it `nawk` (for example).
86: 1. Run `oldawk=nawk make check > check.out 2>&1`.
87: 1. Search for `BAD` or `error` in the result. In general, look over it manually to make sure there are no errors.
88:
89: * Please create the pull request with a request
1.1 millert 90: to merge into the `staging` branch instead of into the `master` branch.
91: This allows us to do testing, and to make any additional edits or changes
92: after the merge but before merging to `master`.
93:
94: ## Building
95:
96: The program itself is created by
97:
98: make
99:
100: which should produce a sequence of messages roughly like this:
101:
1.7 millert 102: bison -d awkgram.y
103: awkgram.y: warning: 44 shift/reduce conflicts [-Wconflicts-sr]
104: awkgram.y: warning: 85 reduce/reduce conflicts [-Wconflicts-rr]
105: awkgram.y: note: rerun with option '-Wcounterexamples' to generate conflict counterexamples
106: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o awkgram.tab.o awkgram.tab.c
107: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o b.o b.c
108: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o main.o main.c
109: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o parse.o parse.c
110: gcc -g -Wall -pedantic -Wcast-qual -O2 maketab.c -o maketab
111: ./maketab awkgram.tab.h >proctab.c
112: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o proctab.o proctab.c
113: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o tran.o tran.c
114: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o lib.o lib.c
115: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o run.o run.c
116: gcc -g -Wall -pedantic -Wcast-qual -O2 -c -o lex.o lex.c
117: gcc -g -Wall -pedantic -Wcast-qual -O2 awkgram.tab.o b.o main.o parse.o proctab.o tran.o lib.o run.o lex.o -lm
1.1 millert 118:
119: This produces an executable `a.out`; you will eventually want to
120: move this to some place like `/usr/bin/awk`.
121:
122: If your system does not have `yacc` or `bison` (the GNU
123: equivalent), you need to install one of them first.
124:
1.6 millert 125: NOTE: This version uses ISO/IEC C99, as you should also. We have
1.1 millert 126: compiled this without any changes using `gcc -Wall` and/or local C
127: compilers on a variety of systems, but new systems or compilers
128: may raise some new complaint; reports of difficulties are
129: welcome.
130:
131: This compiles without change on Macintosh OS X using `gcc` and
132: the standard developer tools.
133:
1.4 millert 134: You can also use `make CC=g++` to build with the GNU C++ compiler,
135: should you choose to do so.
136:
1.5 millert 137: ## A Note About Releases
138:
1.7 millert 139: We don't usually do releases.
1.5 millert 140:
1.3 millert 141: ## A Note About Maintenance
142:
1.5 millert 143: NOTICE! Maintenance of this program is on a ''best effort''
1.3 millert 144: basis. We try to get to issues and pull requests as quickly
145: as we can. Unfortunately, however, keeping this program going
146: is not at the top of our priority list.
147:
1.1 millert 148: #### Last Updated
1.4 millert 149:
1.7 millert 150: Sun Sep 3 09:26:43 EDT 2023