Annotation of src/usr.bin/awk/README.md, Revision 1.7
1.7 ! millert 1: $OpenBSD: README.md,v 1.6 2022/01/27 16:58:37 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
! 33: double-quote (`"`) characters, fields may contain embedded newlines.
! 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
![[BACK]](/icons/back.gif){kind=icon}
Return to README.md CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / awk