[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, array-iface, updated. 52c4d6df2661e9ebdd
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, array-iface, updated. 52c4d6df2661e9ebdde8fcc0ea2e9308f37efd2e |
|
Date: |
Sun, 16 Dec 2012 15:34:21 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, array-iface has been updated
via 52c4d6df2661e9ebdde8fcc0ea2e9308f37efd2e (commit)
via b68a7db5669521f4c56dc690a12588422548fa53 (commit)
via 9f87da605cc746045f1bd6a697e10a766ce26ad5 (commit)
from 287b218ce09459ba4d66dd0c4ad6f1c48f525c82 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=52c4d6df2661e9ebdde8fcc0ea2e9308f37efd2e
commit 52c4d6df2661e9ebdde8fcc0ea2e9308f37efd2e
Merge: 287b218 b68a7db
Author: Arnold D. Robbins <address@hidden>
Date: Sun Dec 16 17:10:48 2012 +0200
Merge branch 'master' into array-iface
diff --cc doc/gawk.info
index 2483836,b3c7a69..693d2dc
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@@ -636,8 -631,13 +631,13 @@@ texts being (a) (see below), and with t
`git' repository.
* Future Extensions:: New features that may be implemented
one day.
-* Implementation Limitations:: Some limitations of the
- implementation.
+* Implementation Limitations:: Some limitations of the
implementation.
+* Old Extension Mechansim:: Some compatibility for old extensions.
+ * Extension Design:: Design notes about the extension API.
+ * Old Extension Problems:: Problems with the old mechanism.
+ * Extension New Mechanism Goals:: Goals for the new mechanism.
+ * Extension Other Design Decisions:: Some other design decisions.
+ * Extension Future Growth:: Some room for future growth.
* Basic High Level:: The high level view.
* Basic Data Typing:: A very quick intro to data types.
@@@ -26497,7 -26287,7 +26287,8 @@@ and maintainers of `gawk'. Everything
* Additions:: Making Additions To `gawk'.
* Future Extensions:: New features that may be implemented one day.
* Implementation Limitations:: Some limitations of the implementation.
+* Old Extension Mechansim:: Some compatibility for old extensions.
+ * Extension Design:: Design notes about the extension API.
File: gawk.info, Node: Compatibility Mode, Next: Additions, Up: Notes
@@@ -26992,45 -26782,220 +26783,259 @@@ Size of a literal string `MAX_INT
Size of a printf string `MAX_INT '
- File: gawk.info, Node: Old Extension Mechansim, Prev: Implementation
Limitations, Up: Notes
-File: gawk.info, Node: Extension Design, Prev: Implementation Limitations,
Up: Notes
++File: gawk.info, Node: Old Extension Mechansim, Next: Extension Design,
Prev: Implementation Limitations, Up: Notes
-C.5 Extension API Design
+C.5 Compatibility For Old Extensions
+====================================
+
+*note Dynamic Extensions::, describes the supported API and mechanisms
+for writing extensions for `gawk'. This API was introduced in *FIXME:
+VERSION*. However, for many years `gawk' provided an extension
+mechanism that required knowledge of `gawk' internals and that was not
+as well designed.
+
+ In order to provide a transition period, `gawk' version *FIXME:
+VERSION* continues to support the original extension mechanism. This
+will be true for the life of exactly one major release. This support
+will be withdrawn, and removed from the source code, at the next major
+release.
+
+ Briefly, original-style extensions should be compiled by including
+the `awk.h' header file in the extension source code. Additionally, you
+must define the identifier `GAWK' when building (use `-DGAWK' with
+Unix-style compilers). Otherwise, the definitions in `gawkapi.h' will
+cause conflicts with those in `awk.h' and your extension will not
+compile.
+
+ Just as in previous versions, you load an old-style extension with
+the `extension()' built-in function (which is not otherwise documented).
+This function in turn finds and loads the shared object file containing
+the extension and calls its `dl_load()' C routine.
+
+ Because original-style and new-style extensions use different
+initialiation routines (`dl_load()' versus `dlload()'), they may safely
+be installed in the same directory (to be found by `AWKLIBPATH')
+without conflict.
+
+ The `gawk' development team strongly recommends that you convert any
+old extensions that you may have to use the new API described in *note
+Dynamic Extensions::.
+
+
++File: gawk.info, Node: Extension Design, Prev: Old Extension Mechansim,
Up: Notes
++
++C.6 Extension API Design
+ ========================
+
+ This minor node documents the design of the extension API, including a
+ discussion of some of the history and problems that needed to be solved.
+
+ The first version of extensions for `gawk' was developed in the
+ mid-1990s and released with `gawk' 3.1 in the late 1990s. The basic
+ mechanisms and design remained unchanged for close to 15 years, until
+ 2012.
+
+ The old extension mechanism used data types and functions from
+ `gawk' itself, with a "clever hack" to install extension functions.
+
+ `gawk' included some sample extensions, of which a few were really
+ useful. However, it was clear from the outset that the extension
+ mechanism was bolted onto the side and was not really thought out.
+
+ * Menu:
+
+ * Old Extension Problems:: Problems with the old mechanism.
+ * Extension New Mechanism Goals:: Goals for the new mechanism.
+ * Extension Other Design Decisions:: Some other design decisions.
+ * Extension Future Growth:: Some room for future growth.
+
+
+ File: gawk.info, Node: Old Extension Problems, Next: Extension New
Mechanism Goals, Up: Extension Design
+
-C.5.1 Problems With The Old Mechanism
++C.6.1 Problems With The Old Mechanism
+ -------------------------------------
+
+ The old extension mechanism had several problems:
+
+ * It depended heavily upon `gawk' internals. Any time the `NODE'
+ structure(1) changed, an extension would have to be recompiled.
+ Furthermore, to really write extensions required understanding
+ something about `gawk''s internal functions. There was some
+ documentation in this Info file, but it was quite minimal.
+
+ * Being able to call into `gawk' from an extension required linker
+ facilities that are common on Unix-derived systems but that did
+ not work on Windows systems; users wanting extensions on Windows
+ had to statically link them into `gawk', even though Windows
+ supports dynamic loading of shared objects.
+
+ * The API would change occasionally as `gawk' changed; no
+ compatibility between versions was ever offered or planned for.
+
+ Despite the drawbacks, the `xgawk' project developers forked `gawk'
+ and developed several significant extensions. They also enhanced
+ `gawk''s facilities relating to file inclusion and shared object access.
+
+ A new API was desired for a long time, but only in 2012 did the
+ `gawk' maintainer and the `xgawk' developers finally start working on
+ it together. More information about the `xgawk' project is provided in
+ *note gawkextlib::.
+
+ ---------- Footnotes ----------
+
+ (1) A critical central data structure inside `gawk'.
+
+
+ File: gawk.info, Node: Extension New Mechanism Goals, Next: Extension Other
Design Decisions, Prev: Old Extension Problems, Up: Extension Design
+
-C.5.2 Goals For A New Mechanism
++C.6.2 Goals For A New Mechanism
+ -------------------------------
+
+ Some goals for the new API were:
+
+ * The API should be independent of `gawk' internals. Changes in
+ `gawk' internals should not be visible to the writer of an
+ extension function.
+
+ * The API should provide _binary_ compatibility across `gawk'
+ releases as long as the API itself does not change.
+
+ * The API should enable extensions written in C to have roughly the
+ same "appearance" to `awk'-level code as `awk' functions do. This
+ means that extensions should have:
+
+ - The ability to access function parameters.
+
+ - The ability to turn an undefined parameter into an array
+ (call by reference).
+
+ - The ability to create, access and update global variables.
+
+ - Easy access to all the elements of an array at once ("array
+ flattening") in order to loop over all the element in an easy
+ fashion for C code.
+
+ - The ability to create arrays (including `gawk''s true
+ multi-dimensional arrays).
+
+ Some additional important goals were:
+
+ * The API should use only features in ISO C 90, so that extensions
+ can be written using the widest range of C and C++ compilers. The
+ header should include the appropriate `#ifdef __cplusplus' and
+ `extern "C"' magic so that a C++ compiler could be used. (If
+ using C++, the runtime system has to be smart enough to call any
+ constructors and destructors, as `gawk' is a C program. As of this
+ writing, this has not been tested.)
+
+ * The API mechanism should not require access to `gawk''s symbols(1)
+ by the compile-time or dynamic linker, in order to enable creation
+ of extensions that also work on Windows.
+
+ During development, it became clear that there were other features
+ that should be available to extensions, which were also subsequently
+ provided:
+
+ * Extensions should have the ability to hook into `gawk''s I/O
+ redirection mechanism. In particular, the `xgawk' developers
+ provided a so-called "open hook" to take over reading records.
+ During development, this was generalized to allow extensions to
+ hook into input processing, output processing, and two-way I/O.
+
+ * An extension should be able to provide a "call back" function to
+ perform clean up actions when `gawk' exits.
+
+ * An extension should be able to provide a version string so that
+ `gawk''s `--version' option can provide information about
+ extensions as well.
+
+ The requirement to avoid access to `gawk''s symbols is, at first
+ glance, a difficult one to meet.
+
+ One design, apparently used by Perl and Ruby and maybe others, would
+ be to make the mainline `gawk' code into a library, with the `gawk'
+ utility a small C `main()' function linked against the library.
+
+ This seemed like the tail wagging the dog, complicating build and
+ installation and making a simple copy of the `gawk' executable from one
+ system to another (or one place to another on the same system!) into a
+ chancy operation.
+
+ Pat Rankin suggested the solution that was adopted. *Note Extension
+ Mechanism Outline::, for the details.
+
+ ---------- Footnotes ----------
+
+ (1) The "symbols" are the variables and functions defined inside
+ `gawk'. Access to these symbols by code external to `gawk' loaded
+ dynamically at runtime is problematic on Windows.
+
+
+ File: gawk.info, Node: Extension Other Design Decisions, Next: Extension
Future Growth, Prev: Extension New Mechanism Goals, Up: Extension Design
+
-C.5.3 Other Design Decisions
++C.6.3 Other Design Decisions
+ ----------------------------
+
+ As an arbitrary design decision, extensions can read the values of
+ built-in variables and arrays (such as `ARGV' and `FS'), but cannot
+ change them, with the exception of `PROCINFO'.
+
+ The reason for this is to prevent an extension function from
+ affecting the flow of an `awk' program outside its control. While a
+ real `awk' function can do what it likes, that is at the discretion of
+ the programmer. An extension function should provide a service or make
+ a C API available for use within `awk', and not mess with `FS' or
+ `ARGC' and `ARGV'.
+
+ In addition, it becomes easy to start down a slippery slope. How
+ much access to `gawk' facilities do extensions need? Do they need
+ `getline'? What about calling `gsub()' or compiling regular
+ expressions? What about calling into `awk' functions? (_That_ would be
+ messy.)
+
+ In order to avoid these issues, the `gawk' developers chose to start
+ with the simplest, most basic features that are still truly useful.
+
+ Another decision is that although `gawk' provides nice things like
+ MPFR, and arrays indexed internally by integers, these features are not
+ being brought out to the API in order to keep things simple and close to
+ traditional `awk' semantics. (In fact, arrays indexed internally by
+ integers are so transparent that they aren't even documented!)
+
+ Additionally, all functions in the API check that their pointer
+ input parameters are not `NULL'. If they are, they return an error.
+ (It is a good idea for extension code to verify that pointers received
+ from `gawk' are not `NULL'. Such a thing should not happen, but the
+ `gawk' developers are only human, and they have been known to
+ occasionally make mistakes.)
+
+ With time, the API will undoubtedly evolve; the `gawk' developers
+ expect this to be driven by user needs. For now, the current API seems
+ to provide a minimal yet powerful set of features for creating
+ extensions.
+
+
+ File: gawk.info, Node: Extension Future Growth, Prev: Extension Other
Design Decisions, Up: Extension Design
+
-C.5.4 Room For Future Growth
++C.6.4 Room For Future Growth
+ ----------------------------
+
+ The API can later be expanded, in two ways:
+
+ * `gawk' passes an "extension id" into the extension when it first
+ loads the extension. The extension then passes this id back to
+ `gawk' with each function call. This mechanism allows `gawk' to
+ identify the extension calling into it, should it need to know.
+
+ * Similarly, the extension passes a "name space" into `gawk' when it
+ registers each extension function. This allows a future mechanism
+ for grouping extension functions and possibly avoiding name
+ conflicts.
+
+ Of course, as of this writing, no decisions have been made with
+ respect to any of the above.
+
+
File: gawk.info, Node: Basic Concepts, Next: Glossary, Prev: Notes, Up:
Top
Appendix D Basic Programming Concepts
@@@ -31820,517 -31785,516 +31825,517 @@@ Inde
Tag Table:
Node: Top1352
-Node: Foreword40178
-Node: Preface44523
-Ref: Preface-Footnote-147576
-Ref: Preface-Footnote-247682
-Node: History47914
-Node: Names50305
-Ref: Names-Footnote-151782
-Node: This Manual51854
-Ref: This Manual-Footnote-157760
-Node: Conventions57860
-Node: Manual History59994
-Ref: Manual History-Footnote-163264
-Ref: Manual History-Footnote-263305
-Node: How To Contribute63379
-Node: Acknowledgments64523
-Node: Getting Started69019
-Node: Running gawk71398
-Node: One-shot72584
-Node: Read Terminal73809
-Ref: Read Terminal-Footnote-175459
-Ref: Read Terminal-Footnote-275735
-Node: Long75906
-Node: Executable Scripts77282
-Ref: Executable Scripts-Footnote-179151
-Ref: Executable Scripts-Footnote-279253
-Node: Comments79800
-Node: Quoting82267
-Node: DOS Quoting86890
-Node: Sample Data Files87565
-Node: Very Simple90597
-Node: Two Rules95196
-Node: More Complex97343
-Ref: More Complex-Footnote-1100273
-Node: Statements/Lines100358
-Ref: Statements/Lines-Footnote-1104820
-Node: Other Features105085
-Node: When106013
-Node: Invoking Gawk108160
-Node: Command Line109621
-Node: Options110404
-Ref: Options-Footnote-1125802
-Node: Other Arguments125827
-Node: Naming Standard Input128485
-Node: Environment Variables129579
-Node: AWKPATH Variable130137
-Ref: AWKPATH Variable-Footnote-1132895
-Node: AWKLIBPATH Variable133155
-Node: Other Environment Variables133752
-Node: Exit Status136247
-Node: Include Files136922
-Node: Loading Shared Libraries140491
-Node: Obsolete141716
-Node: Undocumented142413
-Node: Regexp142656
-Node: Regexp Usage144045
-Node: Escape Sequences146071
-Node: Regexp Operators151834
-Ref: Regexp Operators-Footnote-1159214
-Ref: Regexp Operators-Footnote-2159361
-Node: Bracket Expressions159459
-Ref: table-char-classes161349
-Node: GNU Regexp Operators163872
-Node: Case-sensitivity167595
-Ref: Case-sensitivity-Footnote-1170563
-Ref: Case-sensitivity-Footnote-2170798
-Node: Leftmost Longest170906
-Node: Computed Regexps172107
-Node: Reading Files175517
-Node: Records177520
-Ref: Records-Footnote-1186444
-Node: Fields186481
-Ref: Fields-Footnote-1189514
-Node: Nonconstant Fields189600
-Node: Changing Fields191802
-Node: Field Separators197783
-Node: Default Field Splitting200412
-Node: Regexp Field Splitting201529
-Node: Single Character Fields204871
-Node: Command Line Field Separator205930
-Node: Field Splitting Summary209371
-Ref: Field Splitting Summary-Footnote-1212563
-Node: Constant Size212664
-Node: Splitting By Content217248
-Ref: Splitting By Content-Footnote-1220974
-Node: Multiple Line221014
-Ref: Multiple Line-Footnote-1226861
-Node: Getline227040
-Node: Plain Getline229256
-Node: Getline/Variable231345
-Node: Getline/File232486
-Node: Getline/Variable/File233808
-Ref: Getline/Variable/File-Footnote-1235407
-Node: Getline/Pipe235494
-Node: Getline/Variable/Pipe238054
-Node: Getline/Coprocess239161
-Node: Getline/Variable/Coprocess240404
-Node: Getline Notes241118
-Node: Getline Summary243905
-Ref: table-getline-variants244313
-Node: Read Timeout245171
-Ref: Read Timeout-Footnote-1248916
-Node: Command line directories248973
-Node: Printing249603
-Node: Print251234
-Node: Print Examples252571
-Node: Output Separators255355
-Node: OFMT257115
-Node: Printf258473
-Node: Basic Printf259379
-Node: Control Letters260918
-Node: Format Modifiers264730
-Node: Printf Examples270739
-Node: Redirection273454
-Node: Special Files280438
-Node: Special FD280971
-Ref: Special FD-Footnote-1284596
-Node: Special Network284670
-Node: Special Caveats285520
-Node: Close Files And Pipes286316
-Ref: Close Files And Pipes-Footnote-1293339
-Ref: Close Files And Pipes-Footnote-2293487
-Node: Expressions293637
-Node: Values294769
-Node: Constants295445
-Node: Scalar Constants296125
-Ref: Scalar Constants-Footnote-1296984
-Node: Nondecimal-numbers297166
-Node: Regexp Constants300225
-Node: Using Constant Regexps300700
-Node: Variables303755
-Node: Using Variables304410
-Node: Assignment Options306134
-Node: Conversion308006
-Ref: table-locale-affects313382
-Ref: Conversion-Footnote-1314006
-Node: All Operators314115
-Node: Arithmetic Ops314745
-Node: Concatenation317250
-Ref: Concatenation-Footnote-1320043
-Node: Assignment Ops320163
-Ref: table-assign-ops325151
-Node: Increment Ops326559
-Node: Truth Values and Conditions330029
-Node: Truth Values331112
-Node: Typing and Comparison332161
-Node: Variable Typing332950
-Ref: Variable Typing-Footnote-1336847
-Node: Comparison Operators336969
-Ref: table-relational-ops337379
-Node: POSIX String Comparison340928
-Ref: POSIX String Comparison-Footnote-1341884
-Node: Boolean Ops342022
-Ref: Boolean Ops-Footnote-1346100
-Node: Conditional Exp346191
-Node: Function Calls347923
-Node: Precedence351517
-Node: Locales355186
-Node: Patterns and Actions356275
-Node: Pattern Overview357329
-Node: Regexp Patterns358998
-Node: Expression Patterns359541
-Node: Ranges363226
-Node: BEGIN/END366192
-Node: Using BEGIN/END366954
-Ref: Using BEGIN/END-Footnote-1369685
-Node: I/O And BEGIN/END369791
-Node: BEGINFILE/ENDFILE372073
-Node: Empty374977
-Node: Using Shell Variables375293
-Node: Action Overview377578
-Node: Statements379935
-Node: If Statement381789
-Node: While Statement383288
-Node: Do Statement385332
-Node: For Statement386488
-Node: Switch Statement389640
-Node: Break Statement391737
-Node: Continue Statement393727
-Node: Next Statement395520
-Node: Nextfile Statement397910
-Node: Exit Statement400551
-Node: Built-in Variables402967
-Node: User-modified404062
-Ref: User-modified-Footnote-1412417
-Node: Auto-set412479
-Ref: Auto-set-Footnote-1424830
-Ref: Auto-set-Footnote-2425035
-Node: ARGC and ARGV425091
-Node: Arrays428942
-Node: Array Basics430447
-Node: Array Intro431273
-Node: Reference to Elements435591
-Node: Assigning Elements437861
-Node: Array Example438352
-Node: Scanning an Array440084
-Node: Controlling Scanning442398
-Ref: Controlling Scanning-Footnote-1447331
-Node: Delete447647
-Ref: Delete-Footnote-1450412
-Node: Numeric Array Subscripts450469
-Node: Uninitialized Subscripts452652
-Node: Multi-dimensional454280
-Node: Multi-scanning457374
-Node: Arrays of Arrays458965
-Node: Functions463610
-Node: Built-in464429
-Node: Calling Built-in465507
-Node: Numeric Functions467495
-Ref: Numeric Functions-Footnote-1471327
-Ref: Numeric Functions-Footnote-2471684
-Ref: Numeric Functions-Footnote-3471732
-Node: String Functions472001
-Ref: String Functions-Footnote-1495498
-Ref: String Functions-Footnote-2495627
-Ref: String Functions-Footnote-3495875
-Node: Gory Details495962
-Ref: table-sub-escapes497641
-Ref: table-sub-posix-92498995
-Ref: table-sub-proposed500346
-Ref: table-posix-sub501700
-Ref: table-gensub-escapes503245
-Ref: Gory Details-Footnote-1504452
-Ref: Gory Details-Footnote-2504503
-Node: I/O Functions504654
-Ref: I/O Functions-Footnote-1511759
-Node: Time Functions511906
-Ref: Time Functions-Footnote-1522798
-Ref: Time Functions-Footnote-2522866
-Ref: Time Functions-Footnote-3523024
-Ref: Time Functions-Footnote-4523135
-Ref: Time Functions-Footnote-5523247
-Ref: Time Functions-Footnote-6523474
-Node: Bitwise Functions523740
-Ref: table-bitwise-ops524298
-Ref: Bitwise Functions-Footnote-1528519
-Node: Type Functions528703
-Node: I18N Functions529173
-Node: User-defined530800
-Node: Definition Syntax531604
-Ref: Definition Syntax-Footnote-1536514
-Node: Function Example536583
-Node: Function Caveats539177
-Node: Calling A Function539598
-Node: Variable Scope540713
-Node: Pass By Value/Reference543676
-Node: Return Statement547116
-Node: Dynamic Typing550097
-Node: Indirect Calls550832
-Node: Library Functions560517
-Ref: Library Functions-Footnote-1563516
-Node: Library Names563687
-Ref: Library Names-Footnote-1567158
-Ref: Library Names-Footnote-2567378
-Node: General Functions567464
-Node: Strtonum Function568417
-Node: Assert Function571347
-Node: Round Function574673
-Node: Cliff Random Function576216
-Node: Ordinal Functions577232
-Ref: Ordinal Functions-Footnote-1580302
-Ref: Ordinal Functions-Footnote-2580554
-Node: Join Function580763
-Ref: Join Function-Footnote-1582534
-Node: Getlocaltime Function582734
-Node: Data File Management586449
-Node: Filetrans Function587081
-Node: Rewind Function591220
-Node: File Checking592607
-Node: Empty Files593701
-Node: Ignoring Assigns595931
-Node: Getopt Function597484
-Ref: Getopt Function-Footnote-1608788
-Node: Passwd Functions608991
-Ref: Passwd Functions-Footnote-1617966
-Node: Group Functions618054
-Node: Walking Arrays626138
-Node: Sample Programs627707
-Node: Running Examples628384
-Node: Clones629112
-Node: Cut Program630336
-Node: Egrep Program640181
-Ref: Egrep Program-Footnote-1647954
-Node: Id Program648064
-Node: Split Program651680
-Ref: Split Program-Footnote-1655199
-Node: Tee Program655327
-Node: Uniq Program658130
-Node: Wc Program665559
-Ref: Wc Program-Footnote-1669825
-Ref: Wc Program-Footnote-2670025
-Node: Miscellaneous Programs670117
-Node: Dupword Program671305
-Node: Alarm Program673336
-Node: Translate Program678085
-Ref: Translate Program-Footnote-1682472
-Ref: Translate Program-Footnote-2682700
-Node: Labels Program682834
-Ref: Labels Program-Footnote-1686205
-Node: Word Sorting686289
-Node: History Sorting690173
-Node: Extract Program692012
-Ref: Extract Program-Footnote-1699495
-Node: Simple Sed699623
-Node: Igawk Program702685
-Ref: Igawk Program-Footnote-1717842
-Ref: Igawk Program-Footnote-2718043
-Node: Anagram Program718181
-Node: Signature Program721249
-Node: Internationalization722349
-Node: I18N and L10N723781
-Node: Explaining gettext724467
-Ref: Explaining gettext-Footnote-1729533
-Ref: Explaining gettext-Footnote-2729717
-Node: Programmer i18n729882
-Node: Translator i18n734082
-Node: String Extraction734875
-Ref: String Extraction-Footnote-1735836
-Node: Printf Ordering735922
-Ref: Printf Ordering-Footnote-1738706
-Node: I18N Portability738770
-Ref: I18N Portability-Footnote-1741219
-Node: I18N Example741282
-Ref: I18N Example-Footnote-1743917
-Node: Gawk I18N743989
-Node: Advanced Features744606
-Node: Nondecimal Data746110
-Node: Array Sorting747693
-Node: Controlling Array Traversal748390
-Node: Array Sorting Functions756628
-Ref: Array Sorting Functions-Footnote-1760302
-Ref: Array Sorting Functions-Footnote-2760395
-Node: Two-way I/O760589
-Ref: Two-way I/O-Footnote-1766021
-Node: TCP/IP Networking766091
-Node: Profiling768935
-Node: Debugger776389
-Node: Debugging777357
-Node: Debugging Concepts777790
-Node: Debugging Terms779646
-Node: Awk Debugging782243
-Node: Sample Debugging Session783135
-Node: Debugger Invocation783655
-Node: Finding The Bug784984
-Node: List of Debugger Commands791472
-Node: Breakpoint Control792806
-Node: Debugger Execution Control796470
-Node: Viewing And Changing Data799830
-Node: Execution Stack803186
-Node: Debugger Info804653
-Node: Miscellaneous Debugger Commands808634
-Node: Readline Support814079
-Node: Limitations814910
-Node: Arbitrary Precision Arithmetic817162
-Ref: Arbitrary Precision Arithmetic-Footnote-1818804
-Node: General Arithmetic818952
-Node: Floating Point Issues820672
-Node: String Conversion Precision821553
-Ref: String Conversion Precision-Footnote-1823259
-Node: Unexpected Results823368
-Node: POSIX Floating Point Problems825521
-Ref: POSIX Floating Point Problems-Footnote-1829346
-Node: Integer Programming829384
-Node: Floating-point Programming831137
-Ref: Floating-point Programming-Footnote-1837446
-Node: Floating-point Representation837710
-Node: Floating-point Context838875
-Ref: table-ieee-formats839717
-Node: Rounding Mode841101
-Ref: table-rounding-modes841580
-Ref: Rounding Mode-Footnote-1844584
-Node: Gawk and MPFR844765
-Node: Arbitrary Precision Floats846007
-Ref: Arbitrary Precision Floats-Footnote-1848436
-Node: Setting Precision848747
-Node: Setting Rounding Mode851480
-Ref: table-gawk-rounding-modes851884
-Node: Floating-point Constants853064
-Node: Changing Precision854488
-Ref: Changing Precision-Footnote-1855888
-Node: Exact Arithmetic856062
-Node: Arbitrary Precision Integers859170
-Ref: Arbitrary Precision Integers-Footnote-1862170
-Node: Dynamic Extensions862317
-Node: Extension Intro863694
-Node: Plugin License864902
-Node: Extension Mechanism Outline865587
-Ref: load-extension866004
-Ref: load-new-function867482
-Ref: call-new-function868463
-Node: Extension API Description870457
-Node: Extension API Functions Introduction871796
-Node: General Data Types876574
-Ref: General Data Types-Footnote-1882176
-Node: Requesting Values882475
-Ref: table-value-types-returned883206
-Node: Constructor Functions884160
-Node: Registration Functions887156
-Node: Extension Functions887841
-Node: Exit Callback Functions890015
-Node: Extension Version String891258
-Node: Input Parsers891908
-Node: Output Wrappers900495
-Node: Two-way processors904911
-Node: Printing Messages907041
-Ref: Printing Messages-Footnote-1908118
-Node: Updating `ERRNO'908270
-Node: Accessing Parameters909009
-Node: Symbol Table Access910239
-Node: Symbol table by name910751
-Ref: Symbol table by name-Footnote-1912921
-Node: Symbol table by cookie913001
-Ref: Symbol table by cookie-Footnote-1917130
-Node: Cached values917193
-Ref: Cached values-Footnote-1920636
-Node: Array Manipulation920727
-Ref: Array Manipulation-Footnote-1921825
-Node: Array Data Types921864
-Ref: Array Data Types-Footnote-1924567
-Node: Array Functions924659
-Node: Flattening Arrays928425
-Node: Creating Arrays935264
-Node: Extension API Variables940059
-Node: Extension Versioning940695
-Node: Extension API Informational Variables942596
-Node: Extension API Boilerplate943682
-Node: Finding Extensions947513
-Node: Extension Example948060
-Node: Internal File Description948798
-Node: Internal File Ops952486
-Ref: Internal File Ops-Footnote-1963933
-Node: Using Internal File Ops964073
-Ref: Using Internal File Ops-Footnote-1966426
-Node: Extension Samples966692
-Node: Extension Sample File Functions968135
-Node: Extension Sample Fnmatch976608
-Node: Extension Sample Fork978334
-Node: Extension Sample Ord979548
-Node: Extension Sample Readdir980324
-Node: Extension Sample Revout981828
-Node: Extension Sample Rev2way982421
-Node: Extension Sample Read write array983111
-Node: Extension Sample Readfile984994
-Node: Extension Sample API Tests985749
-Node: Extension Sample Time986274
-Node: gawkextlib987581
-Node: Language History989962
-Node: V7/SVR3.1991484
-Node: SVR4993805
-Node: POSIX995247
-Node: BTL996255
-Node: POSIX/GNU997060
-Node: Common Extensions1002595
-Node: Ranges and Locales1003654
-Ref: Ranges and Locales-Footnote-11008272
-Ref: Ranges and Locales-Footnote-21008299
-Ref: Ranges and Locales-Footnote-31008559
-Node: Contributors1008780
-Node: Installation1013076
-Node: Gawk Distribution1013970
-Node: Getting1014454
-Node: Extracting1015280
-Node: Distribution contents1016972
-Node: Unix Installation1022233
-Node: Quick Installation1022850
-Node: Additional Configuration Options1024812
-Node: Configuration Philosophy1026289
-Node: Non-Unix Installation1028631
-Node: PC Installation1029089
-Node: PC Binary Installation1030388
-Node: PC Compiling1032236
-Node: PC Testing1035180
-Node: PC Using1036356
-Node: Cygwin1040541
-Node: MSYS1041541
-Node: VMS Installation1042055
-Node: VMS Compilation1042658
-Ref: VMS Compilation-Footnote-11043665
-Node: VMS Installation Details1043723
-Node: VMS Running1045358
-Node: VMS Old Gawk1046965
-Node: Bugs1047439
-Node: Other Versions1051291
-Node: Notes1056606
-Node: Compatibility Mode1057335
-Node: Additions1058118
-Node: Accessing The Source1059045
-Node: Adding Code1060648
-Node: New Ports1066690
-Node: Derived Files1070825
-Ref: Derived Files-Footnote-11076146
-Ref: Derived Files-Footnote-21076180
-Ref: Derived Files-Footnote-31076780
-Node: Future Extensions1076878
-Node: Implementation Limitations1077459
-Node: Extension Design1078711
-Node: Old Extension Problems1079828
-Ref: Old Extension Problems-Footnote-11081336
-Node: Extension New Mechanism Goals1081393
-Ref: Extension New Mechanism Goals-Footnote-11084752
-Node: Extension Other Design Decisions1084938
-Node: Extension Future Growth1087044
-Node: Basic Concepts1087865
-Node: Basic High Level1088546
-Ref: figure-general-flow1088817
-Ref: figure-process-flow1089416
-Ref: Basic High Level-Footnote-11092645
-Node: Basic Data Typing1092830
-Node: Glossary1096185
-Node: Copying1121496
-Node: GNU Free Documentation License1159053
-Node: Index1184190
+Node: Foreword40217
+Node: Preface44562
+Ref: Preface-Footnote-147615
+Ref: Preface-Footnote-247721
+Node: History47953
+Node: Names50344
+Ref: Names-Footnote-151821
+Node: This Manual51893
+Ref: This Manual-Footnote-157799
+Node: Conventions57899
+Node: Manual History60033
+Ref: Manual History-Footnote-163303
+Ref: Manual History-Footnote-263344
+Node: How To Contribute63418
+Node: Acknowledgments64562
+Node: Getting Started69058
+Node: Running gawk71437
+Node: One-shot72623
+Node: Read Terminal73848
+Ref: Read Terminal-Footnote-175498
+Ref: Read Terminal-Footnote-275774
+Node: Long75945
+Node: Executable Scripts77321
+Ref: Executable Scripts-Footnote-179190
+Ref: Executable Scripts-Footnote-279292
+Node: Comments79839
+Node: Quoting82306
+Node: DOS Quoting86929
+Node: Sample Data Files87604
+Node: Very Simple90636
+Node: Two Rules95235
+Node: More Complex97382
+Ref: More Complex-Footnote-1100312
+Node: Statements/Lines100397
+Ref: Statements/Lines-Footnote-1104859
+Node: Other Features105124
+Node: When106052
+Node: Invoking Gawk108199
+Node: Command Line109660
+Node: Options110443
+Ref: Options-Footnote-1125841
+Node: Other Arguments125866
+Node: Naming Standard Input128524
+Node: Environment Variables129618
+Node: AWKPATH Variable130176
+Ref: AWKPATH Variable-Footnote-1132934
+Node: AWKLIBPATH Variable133194
+Node: Other Environment Variables133791
+Node: Exit Status136286
+Node: Include Files136961
+Node: Loading Shared Libraries140530
+Node: Obsolete141755
+Node: Undocumented142452
+Node: Regexp142695
+Node: Regexp Usage144084
+Node: Escape Sequences146110
+Node: Regexp Operators151873
+Ref: Regexp Operators-Footnote-1159253
+Ref: Regexp Operators-Footnote-2159400
+Node: Bracket Expressions159498
+Ref: table-char-classes161388
+Node: GNU Regexp Operators163911
+Node: Case-sensitivity167634
+Ref: Case-sensitivity-Footnote-1170602
+Ref: Case-sensitivity-Footnote-2170837
+Node: Leftmost Longest170945
+Node: Computed Regexps172146
+Node: Reading Files175556
+Node: Records177559
+Ref: Records-Footnote-1186483
+Node: Fields186520
+Ref: Fields-Footnote-1189553
+Node: Nonconstant Fields189639
+Node: Changing Fields191841
+Node: Field Separators197822
+Node: Default Field Splitting200451
+Node: Regexp Field Splitting201568
+Node: Single Character Fields204910
+Node: Command Line Field Separator205969
+Node: Field Splitting Summary209410
+Ref: Field Splitting Summary-Footnote-1212602
+Node: Constant Size212703
+Node: Splitting By Content217287
+Ref: Splitting By Content-Footnote-1221013
+Node: Multiple Line221053
+Ref: Multiple Line-Footnote-1226900
+Node: Getline227079
+Node: Plain Getline229295
+Node: Getline/Variable231384
+Node: Getline/File232525
+Node: Getline/Variable/File233847
+Ref: Getline/Variable/File-Footnote-1235446
+Node: Getline/Pipe235533
+Node: Getline/Variable/Pipe238093
+Node: Getline/Coprocess239200
+Node: Getline/Variable/Coprocess240443
+Node: Getline Notes241157
+Node: Getline Summary243944
+Ref: table-getline-variants244352
+Node: Read Timeout245210
+Ref: Read Timeout-Footnote-1248955
+Node: Command line directories249012
+Node: Printing249642
+Node: Print251273
+Node: Print Examples252610
+Node: Output Separators255394
+Node: OFMT257154
+Node: Printf258512
+Node: Basic Printf259418
+Node: Control Letters260957
+Node: Format Modifiers264769
+Node: Printf Examples270778
+Node: Redirection273493
+Node: Special Files280477
+Node: Special FD281010
+Ref: Special FD-Footnote-1284635
+Node: Special Network284709
+Node: Special Caveats285559
+Node: Close Files And Pipes286355
+Ref: Close Files And Pipes-Footnote-1293378
+Ref: Close Files And Pipes-Footnote-2293526
+Node: Expressions293676
+Node: Values294808
+Node: Constants295484
+Node: Scalar Constants296164
+Ref: Scalar Constants-Footnote-1297023
+Node: Nondecimal-numbers297205
+Node: Regexp Constants300264
+Node: Using Constant Regexps300739
+Node: Variables303794
+Node: Using Variables304449
+Node: Assignment Options306173
+Node: Conversion308045
+Ref: table-locale-affects313421
+Ref: Conversion-Footnote-1314045
+Node: All Operators314154
+Node: Arithmetic Ops314784
+Node: Concatenation317289
+Ref: Concatenation-Footnote-1320082
+Node: Assignment Ops320202
+Ref: table-assign-ops325190
+Node: Increment Ops326598
+Node: Truth Values and Conditions330068
+Node: Truth Values331151
+Node: Typing and Comparison332200
+Node: Variable Typing332989
+Ref: Variable Typing-Footnote-1336886
+Node: Comparison Operators337008
+Ref: table-relational-ops337418
+Node: POSIX String Comparison340967
+Ref: POSIX String Comparison-Footnote-1341923
+Node: Boolean Ops342061
+Ref: Boolean Ops-Footnote-1346139
+Node: Conditional Exp346230
+Node: Function Calls347962
+Node: Precedence351556
+Node: Locales355225
+Node: Patterns and Actions356314
+Node: Pattern Overview357368
+Node: Regexp Patterns359037
+Node: Expression Patterns359580
+Node: Ranges363265
+Node: BEGIN/END366231
+Node: Using BEGIN/END366993
+Ref: Using BEGIN/END-Footnote-1369724
+Node: I/O And BEGIN/END369830
+Node: BEGINFILE/ENDFILE372112
+Node: Empty375016
+Node: Using Shell Variables375332
+Node: Action Overview377617
+Node: Statements379974
+Node: If Statement381828
+Node: While Statement383327
+Node: Do Statement385371
+Node: For Statement386527
+Node: Switch Statement389679
+Node: Break Statement391776
+Node: Continue Statement393766
+Node: Next Statement395559
+Node: Nextfile Statement397949
+Node: Exit Statement400590
+Node: Built-in Variables403006
+Node: User-modified404101
+Ref: User-modified-Footnote-1412456
+Node: Auto-set412518
+Ref: Auto-set-Footnote-1424869
+Ref: Auto-set-Footnote-2425074
+Node: ARGC and ARGV425130
+Node: Arrays428981
+Node: Array Basics430486
+Node: Array Intro431312
+Node: Reference to Elements435630
+Node: Assigning Elements437900
+Node: Array Example438391
+Node: Scanning an Array440123
+Node: Controlling Scanning442437
+Ref: Controlling Scanning-Footnote-1447370
+Node: Delete447686
+Ref: Delete-Footnote-1450451
+Node: Numeric Array Subscripts450508
+Node: Uninitialized Subscripts452691
+Node: Multi-dimensional454319
+Node: Multi-scanning457413
+Node: Arrays of Arrays459004
+Node: Functions463649
+Node: Built-in464468
+Node: Calling Built-in465546
+Node: Numeric Functions467534
+Ref: Numeric Functions-Footnote-1471366
+Ref: Numeric Functions-Footnote-2471723
+Ref: Numeric Functions-Footnote-3471771
+Node: String Functions472040
+Ref: String Functions-Footnote-1495537
+Ref: String Functions-Footnote-2495666
+Ref: String Functions-Footnote-3495914
+Node: Gory Details496001
+Ref: table-sub-escapes497680
+Ref: table-sub-posix-92499034
+Ref: table-sub-proposed500385
+Ref: table-posix-sub501739
+Ref: table-gensub-escapes503284
+Ref: Gory Details-Footnote-1504491
+Ref: Gory Details-Footnote-2504542
+Node: I/O Functions504693
+Ref: I/O Functions-Footnote-1511798
+Node: Time Functions511945
+Ref: Time Functions-Footnote-1522837
+Ref: Time Functions-Footnote-2522905
+Ref: Time Functions-Footnote-3523063
+Ref: Time Functions-Footnote-4523174
+Ref: Time Functions-Footnote-5523286
+Ref: Time Functions-Footnote-6523513
+Node: Bitwise Functions523779
+Ref: table-bitwise-ops524337
+Ref: Bitwise Functions-Footnote-1528558
+Node: Type Functions528742
+Node: I18N Functions529212
+Node: User-defined530839
+Node: Definition Syntax531643
+Ref: Definition Syntax-Footnote-1536553
+Node: Function Example536622
+Node: Function Caveats539216
+Node: Calling A Function539637
+Node: Variable Scope540752
+Node: Pass By Value/Reference543715
+Node: Return Statement547155
+Node: Dynamic Typing550136
+Node: Indirect Calls550871
+Node: Library Functions560556
+Ref: Library Functions-Footnote-1563555
+Node: Library Names563726
+Ref: Library Names-Footnote-1567197
+Ref: Library Names-Footnote-2567417
+Node: General Functions567503
+Node: Strtonum Function568456
+Node: Assert Function571386
+Node: Round Function574712
+Node: Cliff Random Function576255
+Node: Ordinal Functions577271
+Ref: Ordinal Functions-Footnote-1580341
+Ref: Ordinal Functions-Footnote-2580593
+Node: Join Function580802
+Ref: Join Function-Footnote-1582573
+Node: Getlocaltime Function582773
+Node: Data File Management586488
+Node: Filetrans Function587120
+Node: Rewind Function591259
+Node: File Checking592646
+Node: Empty Files593740
+Node: Ignoring Assigns595970
+Node: Getopt Function597523
+Ref: Getopt Function-Footnote-1608827
+Node: Passwd Functions609030
+Ref: Passwd Functions-Footnote-1618005
+Node: Group Functions618093
+Node: Walking Arrays626177
+Node: Sample Programs627746
+Node: Running Examples628423
+Node: Clones629151
+Node: Cut Program630375
+Node: Egrep Program640220
+Ref: Egrep Program-Footnote-1647993
+Node: Id Program648103
+Node: Split Program651719
+Ref: Split Program-Footnote-1655238
+Node: Tee Program655366
+Node: Uniq Program658169
+Node: Wc Program665598
+Ref: Wc Program-Footnote-1669864
+Ref: Wc Program-Footnote-2670064
+Node: Miscellaneous Programs670156
+Node: Dupword Program671344
+Node: Alarm Program673375
+Node: Translate Program678124
+Ref: Translate Program-Footnote-1682511
+Ref: Translate Program-Footnote-2682739
+Node: Labels Program682873
+Ref: Labels Program-Footnote-1686244
+Node: Word Sorting686328
+Node: History Sorting690212
+Node: Extract Program692051
+Ref: Extract Program-Footnote-1699534
+Node: Simple Sed699662
+Node: Igawk Program702724
+Ref: Igawk Program-Footnote-1717881
+Ref: Igawk Program-Footnote-2718082
+Node: Anagram Program718220
+Node: Signature Program721288
+Node: Internationalization722388
+Node: I18N and L10N723820
+Node: Explaining gettext724506
+Ref: Explaining gettext-Footnote-1729572
+Ref: Explaining gettext-Footnote-2729756
+Node: Programmer i18n729921
+Node: Translator i18n734121
+Node: String Extraction734914
+Ref: String Extraction-Footnote-1735875
+Node: Printf Ordering735961
+Ref: Printf Ordering-Footnote-1738745
+Node: I18N Portability738809
+Ref: I18N Portability-Footnote-1741258
+Node: I18N Example741321
+Ref: I18N Example-Footnote-1743956
+Node: Gawk I18N744028
+Node: Advanced Features744645
+Node: Nondecimal Data746149
+Node: Array Sorting747732
+Node: Controlling Array Traversal748429
+Node: Array Sorting Functions756667
+Ref: Array Sorting Functions-Footnote-1760341
+Ref: Array Sorting Functions-Footnote-2760434
+Node: Two-way I/O760628
+Ref: Two-way I/O-Footnote-1766060
+Node: TCP/IP Networking766130
+Node: Profiling768974
+Node: Debugger776428
+Node: Debugging777396
+Node: Debugging Concepts777829
+Node: Debugging Terms779685
+Node: Awk Debugging782282
+Node: Sample Debugging Session783174
+Node: Debugger Invocation783694
+Node: Finding The Bug785023
+Node: List of Debugger Commands791511
+Node: Breakpoint Control792845
+Node: Debugger Execution Control796509
+Node: Viewing And Changing Data799869
+Node: Execution Stack803225
+Node: Debugger Info804692
+Node: Miscellaneous Debugger Commands808673
+Node: Readline Support814118
+Node: Limitations814949
+Node: Arbitrary Precision Arithmetic817201
+Ref: Arbitrary Precision Arithmetic-Footnote-1818843
+Node: General Arithmetic818991
+Node: Floating Point Issues820711
+Node: String Conversion Precision821592
+Ref: String Conversion Precision-Footnote-1823298
+Node: Unexpected Results823407
+Node: POSIX Floating Point Problems825560
+Ref: POSIX Floating Point Problems-Footnote-1829385
+Node: Integer Programming829423
+Node: Floating-point Programming831176
+Ref: Floating-point Programming-Footnote-1837485
+Node: Floating-point Representation837749
+Node: Floating-point Context838914
+Ref: table-ieee-formats839756
+Node: Rounding Mode841140
+Ref: table-rounding-modes841619
+Ref: Rounding Mode-Footnote-1844623
+Node: Gawk and MPFR844804
+Node: Arbitrary Precision Floats846046
+Ref: Arbitrary Precision Floats-Footnote-1848475
+Node: Setting Precision848786
+Node: Setting Rounding Mode851519
+Ref: table-gawk-rounding-modes851923
+Node: Floating-point Constants853103
+Node: Changing Precision854527
+Ref: Changing Precision-Footnote-1855927
+Node: Exact Arithmetic856101
+Node: Arbitrary Precision Integers859209
+Ref: Arbitrary Precision Integers-Footnote-1862209
+Node: Dynamic Extensions862356
- Node: Extension Intro863742
- Node: Plugin License864950
- Node: Extension Design865624
- Node: Old Extension Problems866695
- Ref: Old Extension Problems-Footnote-1868205
- Node: Extension New Mechanism Goals868262
- Ref: Extension New Mechanism Goals-Footnote-1870974
- Node: Extension Other Design Decisions871160
- Node: Extension Mechanism Outline873272
- Ref: load-extension874297
- Ref: load-new-function875775
- Ref: call-new-function876756
- Node: Extension Future Growth878750
- Node: Extension API Description879568
- Node: Extension API Functions Introduction880896
- Node: General Data Types885674
- Ref: General Data Types-Footnote-1891276
- Node: Requesting Values891575
- Ref: table-value-types-returned892306
- Node: Constructor Functions893260
- Node: Registration Functions896256
- Node: Extension Functions896941
- Node: Exit Callback Functions899115
- Node: Extension Version String900358
- Node: Input Parsers901008
- Node: Output Wrappers909595
- Node: Two-way processors914011
- Node: Printing Messages916141
- Ref: Printing Messages-Footnote-1917218
- Node: Updating `ERRNO'917370
- Node: Accessing Parameters918109
- Node: Symbol Table Access919339
- Node: Symbol table by name919851
- Ref: Symbol table by name-Footnote-1922021
- Node: Symbol table by cookie922101
- Ref: Symbol table by cookie-Footnote-1926230
- Node: Cached values926293
- Ref: Cached values-Footnote-1929736
- Node: Array Manipulation929827
- Ref: Array Manipulation-Footnote-1930925
- Node: Array Data Types930964
- Ref: Array Data Types-Footnote-1933667
- Node: Array Functions933759
- Node: Flattening Arrays937525
- Node: Creating Arrays944358
- Node: Extension API Variables949153
- Node: Extension Versioning949789
- Node: Extension API Informational Variables951690
- Node: Extension API Boilerplate952776
- Node: Finding Extensions956607
- Node: Extension Example957154
- Node: Internal File Description957892
- Node: Internal File Ops961580
- Ref: Internal File Ops-Footnote-1973027
- Node: Using Internal File Ops973167
- Ref: Using Internal File Ops-Footnote-1975520
- Node: Extension Samples975786
- Node: Extension Sample File Functions977229
- Node: Extension Sample Fnmatch985702
- Node: Extension Sample Fork987428
- Node: Extension Sample Ord988642
- Node: Extension Sample Readdir989418
- Node: Extension Sample Revout990922
- Node: Extension Sample Rev2way991515
- Node: Extension Sample Read write array992205
- Node: Extension Sample Readfile994088
- Node: Extension Sample API Tests994843
- Node: Extension Sample Time995368
- Node: gawkextlib996675
- Node: Language History999056
- Node: V7/SVR3.11000578
- Node: SVR41002899
- Node: POSIX1004341
- Node: BTL1005349
- Node: POSIX/GNU1006154
- Node: Common Extensions1011689
- Node: Ranges and Locales1012748
- Ref: Ranges and Locales-Footnote-11017366
- Ref: Ranges and Locales-Footnote-21017393
- Ref: Ranges and Locales-Footnote-31017653
- Node: Contributors1017874
- Node: Installation1022170
- Node: Gawk Distribution1023064
- Node: Getting1023548
- Node: Extracting1024374
- Node: Distribution contents1026066
- Node: Unix Installation1031327
- Node: Quick Installation1031944
- Node: Additional Configuration Options1033906
- Node: Configuration Philosophy1035383
- Node: Non-Unix Installation1037725
- Node: PC Installation1038183
- Node: PC Binary Installation1039482
- Node: PC Compiling1041330
- Node: PC Testing1044274
- Node: PC Using1045450
- Node: Cygwin1049635
- Node: MSYS1050635
- Node: VMS Installation1051149
- Node: VMS Compilation1051752
- Ref: VMS Compilation-Footnote-11052759
- Node: VMS Installation Details1052817
- Node: VMS Running1054452
- Node: VMS Old Gawk1056059
- Node: Bugs1056533
- Node: Other Versions1060385
- Node: Notes1065700
- Node: Compatibility Mode1066430
- Node: Additions1067213
- Node: Accessing The Source1068140
- Node: Adding Code1069743
- Node: New Ports1075785
- Node: Derived Files1079920
- Ref: Derived Files-Footnote-11085228
- Ref: Derived Files-Footnote-21085262
- Ref: Derived Files-Footnote-31085862
- Node: Future Extensions1085960
- Node: Implementation Limitations1086541
- Node: Old Extension Mechansim1087800
- Node: Basic Concepts1089567
- Node: Basic High Level1090248
- Ref: figure-general-flow1090519
- Ref: figure-process-flow1091118
- Ref: Basic High Level-Footnote-11094347
- Node: Basic Data Typing1094532
- Node: Glossary1097887
- Node: Copying1123198
- Node: GNU Free Documentation License1160755
- Node: Index1185892
++Node: Extension Intro863733
++Node: Plugin License864941
++Node: Extension Mechanism Outline865626
++Ref: load-extension866043
++Ref: load-new-function867521
++Ref: call-new-function868502
++Node: Extension API Description870496
++Node: Extension API Functions Introduction871835
++Node: General Data Types876613
++Ref: General Data Types-Footnote-1882215
++Node: Requesting Values882514
++Ref: table-value-types-returned883245
++Node: Constructor Functions884199
++Node: Registration Functions887195
++Node: Extension Functions887880
++Node: Exit Callback Functions890054
++Node: Extension Version String891297
++Node: Input Parsers891947
++Node: Output Wrappers900534
++Node: Two-way processors904950
++Node: Printing Messages907080
++Ref: Printing Messages-Footnote-1908157
++Node: Updating `ERRNO'908309
++Node: Accessing Parameters909048
++Node: Symbol Table Access910278
++Node: Symbol table by name910790
++Ref: Symbol table by name-Footnote-1912960
++Node: Symbol table by cookie913040
++Ref: Symbol table by cookie-Footnote-1917169
++Node: Cached values917232
++Ref: Cached values-Footnote-1920675
++Node: Array Manipulation920766
++Ref: Array Manipulation-Footnote-1921864
++Node: Array Data Types921903
++Ref: Array Data Types-Footnote-1924606
++Node: Array Functions924698
++Node: Flattening Arrays928464
++Node: Creating Arrays935303
++Node: Extension API Variables940098
++Node: Extension Versioning940734
++Node: Extension API Informational Variables942635
++Node: Extension API Boilerplate943721
++Node: Finding Extensions947552
++Node: Extension Example948099
++Node: Internal File Description948837
++Node: Internal File Ops952525
++Ref: Internal File Ops-Footnote-1963972
++Node: Using Internal File Ops964112
++Ref: Using Internal File Ops-Footnote-1966465
++Node: Extension Samples966731
++Node: Extension Sample File Functions968174
++Node: Extension Sample Fnmatch976647
++Node: Extension Sample Fork978373
++Node: Extension Sample Ord979587
++Node: Extension Sample Readdir980363
++Node: Extension Sample Revout981867
++Node: Extension Sample Rev2way982460
++Node: Extension Sample Read write array983150
++Node: Extension Sample Readfile985033
++Node: Extension Sample API Tests985788
++Node: Extension Sample Time986313
++Node: gawkextlib987620
++Node: Language History990001
++Node: V7/SVR3.1991523
++Node: SVR4993844
++Node: POSIX995286
++Node: BTL996294
++Node: POSIX/GNU997099
++Node: Common Extensions1002634
++Node: Ranges and Locales1003693
++Ref: Ranges and Locales-Footnote-11008311
++Ref: Ranges and Locales-Footnote-21008338
++Ref: Ranges and Locales-Footnote-31008598
++Node: Contributors1008819
++Node: Installation1013115
++Node: Gawk Distribution1014009
++Node: Getting1014493
++Node: Extracting1015319
++Node: Distribution contents1017011
++Node: Unix Installation1022272
++Node: Quick Installation1022889
++Node: Additional Configuration Options1024851
++Node: Configuration Philosophy1026328
++Node: Non-Unix Installation1028670
++Node: PC Installation1029128
++Node: PC Binary Installation1030427
++Node: PC Compiling1032275
++Node: PC Testing1035219
++Node: PC Using1036395
++Node: Cygwin1040580
++Node: MSYS1041580
++Node: VMS Installation1042094
++Node: VMS Compilation1042697
++Ref: VMS Compilation-Footnote-11043704
++Node: VMS Installation Details1043762
++Node: VMS Running1045397
++Node: VMS Old Gawk1047004
++Node: Bugs1047478
++Node: Other Versions1051330
++Node: Notes1056645
++Node: Compatibility Mode1057445
++Node: Additions1058228
++Node: Accessing The Source1059155
++Node: Adding Code1060758
++Node: New Ports1066800
++Node: Derived Files1070935
++Ref: Derived Files-Footnote-11076256
++Ref: Derived Files-Footnote-21076290
++Ref: Derived Files-Footnote-31076890
++Node: Future Extensions1076988
++Node: Implementation Limitations1077569
++Node: Old Extension Mechansim1078828
++Node: Extension Design1080620
++Node: Old Extension Problems1081734
++Ref: Old Extension Problems-Footnote-11083242
++Node: Extension New Mechanism Goals1083299
++Ref: Extension New Mechanism Goals-Footnote-11086658
++Node: Extension Other Design Decisions1086844
++Node: Extension Future Growth1088950
++Node: Basic Concepts1089771
++Node: Basic High Level1090452
++Ref: figure-general-flow1090723
++Ref: figure-process-flow1091322
++Ref: Basic High Level-Footnote-11094551
++Node: Basic Data Typing1094736
++Node: Glossary1098091
++Node: Copying1123402
++Node: GNU Free Documentation License1160959
++Node: Index1186096
End Tag Table
diff --cc doc/gawk.texi
index fca7ceb,60fb794..15b4303
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@@ -844,8 -839,13 +839,13 @@@ particular records in a file and perfor
@command{git} repository.
* Future Extensions:: New features that may be implemented
one day.
-* Implementation Limitations:: Some limitations of the
- implementation.
+* Implementation Limitations:: Some limitations of the
implementation.
+* Old Extension Mechansim:: Some compatibility for old extensions.
+ * Extension Design:: Design notes about the extension API.
+ * Old Extension Problems:: Problems with the old mechanism.
+ * Extension New Mechanism Goals:: Goals for the new mechanism.
+ * Extension Other Design Decisions:: Some other design decisions.
+ * Extension Future Growth:: Some room for future growth.
* Basic High Level:: The high level view.
* Basic Data Typing:: A very quick intro to data types.
@end detailmenu
@@@ -34304,7 -34084,7 +34084,8 @@@ maintainers of @command{gawk}. Everyth
* Additions:: Making Additions To @command{gawk}.
* Future Extensions:: New features that may be implemented one day.
* Implementation Limitations:: Some limitations of the implementation.
+* Old Extension Mechansim:: Some compatibility for old extensions.
+ * Extension Design:: Design notes about the extension API.
@end menu
@node Compatibility Mode
@@@ -34935,42 -34715,234 +34716,269 @@@ different limits
@item Size of a printf string @tab @code{MAX_INT }
@end multitable
address@hidden Old Extension Mechansim
address@hidden Compatibility For Old Extensions
+
address@hidden Extensions}, describes the supported API and mechanisms
+for writing extensions for @command{gawk}. This API was introduced
+in @strong{FIXME: VERSION}. However, for many years @command{gawk}
+provided an extension mechanism that required knowledge of @command{gawk}
+internals and that was not as well designed.
+
+In order to provide a transition period, @command{gawk} version
address@hidden: VERSION} continues to support the original extension mechanism.
+This will be true for the life of exactly one major release. This support
+will be withdrawn, and removed from the source code, at the next major
+release.
+
+Briefly, original-style extensions should be compiled by including the
address@hidden header file in the extension source code. Additionally,
+you must define the identifier @samp{GAWK} when building (use
address@hidden with Unix-style compilers). Otherwise, the definitions
+in @file{gawkapi.h} will cause conflicts with those in @file{awk.h}
+and your extension will not compile.
+
+Just as in previous versions, you load an old-style extension with the
address@hidden()} built-in function (which is not otherwise documented).
+This function in turn finds and loads the shared object file containing
+the extension and calls its @code{dl_load()} C routine.
+
+Because original-style and new-style extensions use different initialiation
+routines (@code{dl_load()} versus @code{dlload()}), they may safely
+be installed in the same directory (to be found by @env{AWKLIBPATH})
+without conflict.
+
+The @command{gawk} development team strongly recommends that you
+convert any old extensions that you may have to use the new API
+described in @ref{Dynamic Extensions}.
+
+ @node Extension Design
+ @appendixsec Extension API Design
+
+ This @value{SECTION} documents the design of the extension API,
+ including a discussion of some of the history and problems that needed
+ to be solved.
+
+ The first version of extensions for @command{gawk} was developed in
+ the mid-1990s and released with @command{gawk} 3.1 in the late 1990s.
+ The basic mechanisms and design remained unchanged for close to 15 years,
+ until 2012.
+
+ The old extension mechanism used data types and functions from
+ @command{gawk} itself, with a ``clever hack'' to install extension
+ functions.
+
+ @command{gawk} included some sample extensions, of which a few were
+ really useful. However, it was clear from the outset that the extension
+ mechanism was bolted onto the side and was not really thought out.
+
+ @menu
+ * Old Extension Problems:: Problems with the old mechanism.
+ * Extension New Mechanism Goals:: Goals for the new mechanism.
+ * Extension Other Design Decisions:: Some other design decisions.
+ * Extension Future Growth:: Some room for future growth.
+ @end menu
+
+ @node Old Extension Problems
+ @appendixsubsec Problems With The Old Mechanism
+
+ The old extension mechanism had several problems:
+
+ @itemize @bullet
+ @item
+ It depended heavily upon @command{gawk} internals. Any time the
+ @code{NODE} address@hidden critical central data structure
+ inside @command{gawk}.} changed, an extension would have to be
+ recompiled. Furthermore, to really write extensions required understanding
+ something about @command{gawk}'s internal functions. There was some
+ documentation in this @value{DOCUMENT}, but it was quite minimal.
+
+ @item
+ Being able to call into @command{gawk} from an extension required linker
+ facilities that are common on Unix-derived systems but that did
+ not work on Windows systems; users wanting extensions on Windows
+ had to statically link them into @command{gawk}, even though Windows supports
+ dynamic loading of shared objects.
+
+ @item
+ The API would change occasionally as @command{gawk} changed; no compatibility
+ between versions was ever offered or planned for.
+ @end itemize
+
+ Despite the drawbacks, the @command{xgawk} project developers forked
+ @command{gawk} and developed several significant extensions. They also
+ enhanced @command{gawk}'s facilities relating to file inclusion and
+ shared object access.
+
+ A new API was desired for a long time, but only in 2012 did the
+ @command{gawk} maintainer and the @command{xgawk} developers finally
+ start working on it together. More information about the @command{xgawk}
+ project is provided in @ref{gawkextlib}.
+
+ @node Extension New Mechanism Goals
+ @appendixsubsec Goals For A New Mechanism
+
+ Some goals for the new API were:
+
+ @itemize @bullet
+ @item
+ The API should be independent of @command{gawk} internals. Changes in
+ @command{gawk} internals should not be visible to the writer of an
+ extension function.
+
+ @item
+ The API should provide @emph{binary} compatibility across @command{gawk}
+ releases as long as the API itself does not change.
+
+ @item
+ The API should enable extensions written in C to have roughly the
+ same ``appearance'' to @command{awk}-level code as @command{awk}
+ functions do. This means that extensions should have:
+
+ @itemize @minus
+ @item
+ The ability to access function parameters.
+
+ @item
+ The ability to turn an undefined parameter into an array (call by reference).
+
+ @item
+ The ability to create, access and update global variables.
+
+ @item
+ Easy access to all the elements of an array at once (``array flattening'')
+ in order to loop over all the element in an easy fashion for C code.
+
+ @item
+ The ability to create arrays (including @command{gawk}'s true
+ multi-dimensional arrays).
+ @end itemize
+ @end itemize
+
+ Some additional important goals were:
+
+ @itemize @bullet
+ @item
+ The API should use only features in ISO C 90, so that extensions
+ can be written using the widest range of C and C++ compilers. The header
+ should include the appropriate @samp{#ifdef __cplusplus} and @samp{extern "C"}
+ magic so that a C++ compiler could be used. (If using C++, the runtime
+ system has to be smart enough to call any constructors and destructors,
+ as @command{gawk} is a C program. As of this writing, this has not been
+ tested.)
+
+ @item
+ The API mechanism should not require access to @command{gawk}'s
+ address@hidden @dfn{symbols} are the variables and functions
+ defined inside @command{gawk}. Access to these symbols by code
+ external to @command{gawk} loaded dynamically at runtime is
+ problematic on Windows.} by the compile-time or dynamic linker,
+ in order to enable creation of extensions that also work on Windows.
+ @end itemize
+
+ During development, it became clear that there were other features
+ that should be available to extensions, which were also subsequently
+ provided:
+
+ @itemize @bullet
+ @item
+ Extensions should have the ability to hook into @command{gawk}'s
+ I/O redirection mechanism. In particular, the @command{xgawk}
+ developers provided a so-called ``open hook'' to take over reading
+ records. During development, this was generalized to allow
+ extensions to hook into input processing, output processing, and
+ two-way I/O.
+
+ @item
+ An extension should be able to provide a ``call back'' function
+ to perform clean up actions when @command{gawk} exits.
+
+ @item
+ An extension should be able to provide a version string so that
+ @command{gawk}'s @option{--version} option can provide information
+ about extensions as well.
+ @end itemize
+
+ The requirement to avoid access to @command{gawk}'s symbols is, at first
+ glance, a difficult one to meet.
+
+ One design, apparently used by Perl and Ruby and maybe others, would
+ be to make the mainline @command{gawk} code into a library, with the
+ @command{gawk} utility a small C @code{main()} function linked against
+ the library.
+
+ This seemed like the tail wagging the dog, complicating build and
+ installation and making a simple copy of the @command{gawk} executable
+ from one system to another (or one place to another on the same
+ system!) into a chancy operation.
+
+ Pat Rankin suggested the solution that was adopted.
+ @xref{Extension Mechanism Outline}, for the details.
+
+ @node Extension Other Design Decisions
+ @appendixsubsec Other Design Decisions
+
+ As an arbitrary design decision, extensions can read the values of
+ built-in variables and arrays (such as @code{ARGV} and @code{FS}), but cannot
+ change them, with the exception of @code{PROCINFO}.
+
+ The reason for this is to prevent an extension function from affecting
+ the flow of an @command{awk} program outside its control. While a real
+ @command{awk} function can do what it likes, that is at the discretion
+ of the programmer. An extension function should provide a service or
+ make a C API available for use within @command{awk}, and not mess with
+ @code{FS} or @code{ARGC} and @code{ARGV}.
+
+ In addition, it becomes easy to start down a slippery slope. How
+ much access to @command{gawk} facilities do extensions need?
+ Do they need @code{getline}? What about calling @code{gsub()} or
+ compiling regular expressions? What about calling into @command{awk}
+ functions? (@emph{That} would be messy.)
+
+ In order to avoid these issues, the @command{gawk} developers chose
+ to start with the simplest, most basic features that are still truly useful.
+
+ Another decision is that although @command{gawk} provides nice things like
+ MPFR, and arrays indexed internally by integers, these features are not
+ being brought out to the API in order to keep things simple and close to
+ traditional @command{awk} semantics. (In fact, arrays indexed internally
+ by integers are so transparent that they aren't even documented!)
+
+ Additionally, all functions in the API check that their pointer
+ input parameters are not @code{NULL}. If they are, they return an error.
+ (It is a good idea for extension code to verify that
+ pointers received from @command{gawk} are not @code{NULL}.
+ Such a thing should not happen, but the @command{gawk} developers
+ are only human, and they have been known to occasionally make
+ mistakes.)
+
+ With time, the API will undoubtedly evolve; the @command{gawk} developers
+ expect this to be driven by user needs. For now, the current API seems
+ to provide a minimal yet powerful set of features for creating extensions.
+
+ @node Extension Future Growth
+ @appendixsubsec Room For Future Growth
+
+ The API can later be expanded, in two ways:
+
+ @itemize @bullet
+ @item
+ @command{gawk} passes an ``extension id'' into the extension when it
+ first loads the extension. The extension then passes this id back
+ to @command{gawk} with each function call. This mechanism allows
+ @command{gawk} to identify the extension calling into it, should it need
+ to know.
+
+ @item
+ Similarly, the extension passes a ``name space'' into @command{gawk}
+ when it registers each extension function. This allows a future
+ mechanism for grouping extension functions and possibly avoiding name
+ conflicts.
+ @end itemize
+
+ Of course, as of this writing, no decisions have been made with respect
+ to any of the above.
+
-
@c ENDOFRANGE impis
@c ENDOFRANGE gawii
-----------------------------------------------------------------------
Summary of changes:
doc/ChangeLog | 5 +
doc/gawk.info | 735 +++++++++++++++++++++++++++++----------------------------
doc/gawk.texi | 476 +++++++++++++++++++------------------
3 files changed, 617 insertions(+), 599 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, array-iface, updated. 52c4d6df2661e9ebdde8fcc0ea2e9308f37efd2e,
Arnold Robbins <=