[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, feature/namespaces, created. gawk-4.1.0-
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, feature/namespaces, created. gawk-4.1.0-2570-gc5788a1 |
|
Date: |
Tue, 30 May 2017 07:04:16 -0400 (EDT) |
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, feature/namespaces has been created
at c5788a173624edc1d3e7396d71c868e30a37e809 (commit)
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=c5788a173624edc1d3e7396d71c868e30a37e809
commit c5788a173624edc1d3e7396d71c868e30a37e809
Author: Arnold D. Robbins <address@hidden>
Date: Tue May 30 14:03:35 2017 +0300
More namespace doc. Make -e require full syntactic units.
diff --git a/ChangeLog b/ChangeLog
index c4a1a1a..1257afb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
2017-05-30 Arnold D. Robbins <address@hidden>
+ * awkgram.y (nextc): Force -e chunks to be syntactic units.
+ Needed for namespaces to work correctly.
+
+2017-05-30 Arnold D. Robbins <address@hidden>
+
* NEWS: Mention PROCINFO["argv"].
2017-05-24 Andrew J. Schorr <address@hidden>
diff --git a/awkgram.c b/awkgram.c
index 4325e77..0e9a8d7 100644
--- a/awkgram.c
+++ b/awkgram.c
@@ -5514,6 +5514,9 @@ check_bad_char(int c)
/* nextc --- get the next input character */
+// For namespaces, -e chunks must be syntactic units.
+#define NO_CONTINUE_SOURCE_STRINGS 1
+
static int
nextc(bool check_for_bad)
{
@@ -5601,6 +5604,7 @@ again:
return END_SRC;
}
}
+#undef NO_CONTINUE_SOURCE_STRINGS
/* pushback --- push a character back on the input */
diff --git a/awkgram.y b/awkgram.y
index e4f5bab..37acf28 100644
--- a/awkgram.y
+++ b/awkgram.y
@@ -3094,6 +3094,9 @@ check_bad_char(int c)
/* nextc --- get the next input character */
+// For namespaces, -e chunks must be syntactic units.
+#define NO_CONTINUE_SOURCE_STRINGS 1
+
static int
nextc(bool check_for_bad)
{
@@ -3181,6 +3184,7 @@ again:
return END_SRC;
}
}
+#undef NO_CONTINUE_SOURCE_STRINGS
/* pushback --- push a character back on the input */
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 2efa50b..9dc07ed 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -2,6 +2,7 @@
* gawktexi.in: Initial doc on namespaces. Serves as a design
right now.
+ * gawktexi.in: More doc added.
2017-05-30 Arnold D. Robbins <address@hidden>
diff --git a/doc/gawk.info b/doc/gawk.info
index 66998ed..537cae6 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -83,6 +83,7 @@ in (a) below. A copy of the license is included in the
section entitled
* Library Functions:: A Library of 'awk' Functions.
* Sample Programs:: Many 'awk' programs with complete
explanations.
+* Namespaces:: How namespaces work in 'gawk'.
* Advanced Features:: Stuff for advanced users, specific to
'gawk'.
* Internationalization:: Getting 'gawk' to speak your
@@ -479,6 +480,12 @@ in (a) below. A copy of the license is included in the
section entitled
time on their hands.
* Programs Summary:: Summary of programs.
* Programs Exercises:: Exercises.
+* Global Namespace:: The global namespace in standard 'awk'.
+* Qualified Names:: How to qualify names with a namespace.
+* Default Namespace:: The default namespace.
+* Changing The Namespace:: How to change the namespace.
+* Namespace Example:: An example of code using a namespace.
+* Namespace Misc:: Namespace notes for developers.
* Nondecimal Data:: Allowing nondecimal input data.
* Array Sorting:: Facilities for controlling array
traversal and sorting arrays.
@@ -2568,15 +2575,15 @@ The following list describes options mandated by the
POSIX standard:
character (even if it doesn't). This makes building the total
program easier.
- CAUTION: At the moment, there is no requirement that each
- PROGRAM-TEXT be a full syntactic unit. I.e., the following
- currently works:
+ CAUTION: Prior to version *FIXME* 5.0, there was no
+ requirement that each PROGRAM-TEXT be a full syntactic unit.
+ I.e., the following worked:
$ gawk -e 'BEGIN { a = 5 ;' -e 'print a }'
-| 5
- However, this could change in the future, so it's not a good
- idea to rely upon this feature.
+ However, this is no longer true. If you have any scripts that
+ rely upon this feature, you should revise them.
'-E' FILE
'--exec' FILE
@@ -19742,6 +19749,13 @@ This major node describes a feature that is specific
to 'gawk'.
* Menu:
+* Global Namespace:: The global namespace in standard 'awk'.
+* Qualified Names:: How to qualify names with a namespace.
+* Default Namespace:: The default namespace.
+* Changing The Namespace:: How to change the namespace.
+* Namespace Example:: An example of code using a namespace.
+* Namespace Misc:: Namespace notes for developers.
+
File: gawk.info, Node: Global Namespace, Next: Qualified Names, Up:
Namespaces
@@ -19801,6 +19815,9 @@ unqualified identifiers whose names are all uppercase
letters to be in
the 'awk' namespace. This makes it possible for you to easily reference
'gawk''s global variables from different namespaces.
+ It is a syntactic error to use qualified names for function parameter
+names.
+
File: gawk.info, Node: Changing The Namespace, Next: Namespace Example,
Prev: Default Namespace, Up: Namespaces
@@ -19812,7 +19829,7 @@ the top level of your program:
@namespace "passwd"
- BEGIN { }
+ BEGIN { ... }
...
After this directive, all simple non-uppercase identifiers are placed
@@ -19825,17 +19842,14 @@ file, although this is likely to become confusing if
you do it a lot.
being parsed by 'gawk'. There is no concept of a "current"
namespace during runtime. Be sure you understand the distinction.
- Each source file for '-i' and '-f' starts out with an implicit '
-"awk"'.
+ Each source file for '-i' and '-f' starts out with an implicit
+'@namespace "awk"'.
Similarly, each chunk of command-line code with '-e' has such an
implicit statement.
- FIXME: The semantics of '-e' change to require it to be syntactic
-unit.
-
- FIXME: Update doc earlier in this book and change the corresponding
-code.
+ The use of '@namespace' has no influence upon the order of execution
+of 'BEGIN', 'BEGINFILE', 'END', and 'ENDFILE' rules.
File: gawk.info, Node: Namespace Example, Next: Namespace Misc, Prev:
Changing The Namespace, Up: Namespaces
@@ -19875,11 +19889,11 @@ File: gawk.info, Node: Namespace Example, Next:
Namespace Misc, Prev: Changin
RS = "\n"
pwcat = _pw_awklib "pwcat"
- while ((pwcat | getline) > 0)
+ while ((pwcat | getline) > 0) {
Byname[$1] = $0
Byuid[$3] = $0
Bycount[++_pw_total] = $0
-
+ }
close(pwcat)
Count = 0
Inited = 1
@@ -19949,6 +19963,9 @@ File: gawk.info, Node: Namespace Misc, Prev:
Namespace Example, Up: Namespace
Other notes for reviewers:
+'SYMTAB', 'FUNCTAB' and 'PROCINFO["identifiers"]'
+ The subscripts are all fully qualified names.
+
Profiler:
When profiling, we can add an 'Op_Namespace' to the start of each
rule. If it has changed since the previous one, output an
@@ -19957,11 +19974,42 @@ Profiler:
if 'XXX' is all uppercase, strip off the 'awk' part.
Debugger:
- Simply prints fully qualified names all the time. Maybe allow a
+ Simply print fully qualified names all the time. Maybe allow a
'namespace XXX' command in the debugger to set the namespace and it
will use that to create fully qualified names? Have to be careful
about all uppercase names though.
+How does this affect indirect calls?
+ The current namespace is a parse time thing, not a dynamic thing,
+ so for indirect calls to work, use something like:
+
+ @namespace "foo"
+
+ function bar() { ... }
+
+ {
+ ...
+ x = "foo.bar"
+ ...
+ @x()
+ }
+
+ This is particularly true if 'x' is passed as a "function pointer"
+ to another function in another namespace for that function to call
+ through it.
+
+How does this affect '@include'?
+ Basically '@include' should push and pop the namespace. Each
+ '@include' saves the current namespace and starts over with
+ namespace 'awk' until an '@namespace' is seen.
+
+Extension functions
+ Revise the current macros to pass '"awk"' as the namespace argument
+ and add new macros with '_ns' or some such in the name that pass
+ the namespace of the extension. This preserves backwards
+ compatibility at the source level while providing access to
+ namespaces as needed.
+
File: gawk.info, Node: Advanced Features, Next: Internationalization, Prev:
Namespaces, Up: Top
@@ -35973,587 +36021,587 @@ Index
Tag Table:
Node: Top1200
-Node: Foreword343279
-Node: Foreword447721
-Node: Preface49253
-Ref: Preface-Footnote-152112
-Ref: Preface-Footnote-252219
-Ref: Preface-Footnote-352453
-Node: History52595
-Node: Names54947
-Ref: Names-Footnote-156041
-Node: This Manual56188
-Ref: This Manual-Footnote-162673
-Node: Conventions62773
-Node: Manual History65127
-Ref: Manual History-Footnote-168122
-Ref: Manual History-Footnote-268163
-Node: How To Contribute68237
-Node: Acknowledgments68888
-Node: Getting Started73774
-Node: Running gawk76213
-Node: One-shot77403
-Node: Read Terminal78666
-Node: Long80659
-Node: Executable Scripts82172
-Ref: Executable Scripts-Footnote-184967
-Node: Comments85070
-Node: Quoting87554
-Node: DOS Quoting93071
-Node: Sample Data Files95126
-Node: Very Simple97721
-Node: Two Rules102623
-Node: More Complex104508
-Node: Statements/Lines107374
-Ref: Statements/Lines-Footnote-1111833
-Node: Other Features112098
-Node: When113034
-Ref: When-Footnote-1114788
-Node: Intro Summary114853
-Node: Invoking Gawk115737
-Node: Command Line117251
-Node: Options118049
-Ref: Options-Footnote-1134668
-Ref: Options-Footnote-2134898
-Node: Other Arguments134923
-Node: Naming Standard Input137870
-Node: Environment Variables138963
-Node: AWKPATH Variable139521
-Ref: AWKPATH Variable-Footnote-1142932
-Ref: AWKPATH Variable-Footnote-2142966
-Node: AWKLIBPATH Variable143227
-Node: Other Environment Variables144484
-Node: Exit Status148305
-Node: Include Files148982
-Node: Loading Shared Libraries152577
-Node: Obsolete154005
-Node: Undocumented154697
-Node: Invoking Summary154994
-Node: Regexp156654
-Node: Regexp Usage158108
-Node: Escape Sequences160145
-Node: Regexp Operators166377
-Ref: Regexp Operators-Footnote-1173793
-Ref: Regexp Operators-Footnote-2173940
-Node: Bracket Expressions174038
-Ref: table-char-classes176514
-Node: Leftmost Longest179651
-Node: Computed Regexps180954
-Node: GNU Regexp Operators184381
-Node: Case-sensitivity188060
-Ref: Case-sensitivity-Footnote-1190947
-Ref: Case-sensitivity-Footnote-2191182
-Node: Regexp Summary191290
-Node: Reading Files192756
-Node: Records195025
-Node: awk split records195758
-Node: gawk split records200689
-Ref: gawk split records-Footnote-1205229
-Node: Fields205266
-Node: Nonconstant Fields208007
-Ref: Nonconstant Fields-Footnote-1210243
-Node: Changing Fields210447
-Node: Field Separators216375
-Node: Default Field Splitting219073
-Node: Regexp Field Splitting220191
-Node: Single Character Fields223544
-Node: Command Line Field Separator224604
-Node: Full Line Fields227822
-Ref: Full Line Fields-Footnote-1229344
-Ref: Full Line Fields-Footnote-2229390
-Node: Field Splitting Summary229491
-Node: Constant Size231565
-Node: Fixed width data232297
-Node: Skipping intervening235764
-Node: Allowing trailing data236562
-Node: Fields with fixed data237599
-Node: Splitting By Content239117
-Ref: Splitting By Content-Footnote-1242767
-Node: Testing field creation242930
-Node: Multiple Line244551
-Ref: Multiple Line-Footnote-1250435
-Node: Getline250614
-Node: Plain Getline253083
-Node: Getline/Variable255724
-Node: Getline/File256875
-Node: Getline/Variable/File258263
-Ref: Getline/Variable/File-Footnote-1259868
-Node: Getline/Pipe259956
-Node: Getline/Variable/Pipe262663
-Node: Getline/Coprocess263798
-Node: Getline/Variable/Coprocess265065
-Node: Getline Notes265807
-Node: Getline Summary268604
-Ref: table-getline-variants269028
-Node: Read Timeout269776
-Ref: Read Timeout-Footnote-1273682
-Node: Retrying Input273740
-Node: Command-line directories274939
-Node: Input Summary275845
-Node: Input Exercises279017
-Node: Printing279745
-Node: Print281579
-Node: Print Examples283036
-Node: Output Separators285816
-Node: OFMT287833
-Node: Printf289189
-Node: Basic Printf289974
-Node: Control Letters291548
-Node: Format Modifiers295536
-Node: Printf Examples301551
-Node: Redirection304037
-Node: Special FD310878
-Ref: Special FD-Footnote-1314046
-Node: Special Files314120
-Node: Other Inherited Files314737
-Node: Special Network315738
-Node: Special Caveats316598
-Node: Close Files And Pipes317547
-Ref: table-close-pipe-return-values324454
-Ref: Close Files And Pipes-Footnote-1325237
-Ref: Close Files And Pipes-Footnote-2325385
-Node: Nonfatal325537
-Node: Output Summary327862
-Node: Output Exercises329084
-Node: Expressions329763
-Node: Values330951
-Node: Constants331629
-Node: Scalar Constants332320
-Ref: Scalar Constants-Footnote-1333184
-Node: Nondecimal-numbers333434
-Node: Regexp Constants336435
-Node: Using Constant Regexps336961
-Node: Standard Regexp Constants337583
-Node: Strong Regexp Constants340771
-Node: Variables343729
-Node: Using Variables344386
-Node: Assignment Options346296
-Node: Conversion348169
-Node: Strings And Numbers348693
-Ref: Strings And Numbers-Footnote-1351756
-Node: Locale influences conversions351865
-Ref: table-locale-affects354623
-Node: All Operators355241
-Node: Arithmetic Ops355870
-Node: Concatenation358376
-Ref: Concatenation-Footnote-1361223
-Node: Assignment Ops361330
-Ref: table-assign-ops366321
-Node: Increment Ops367634
-Node: Truth Values and Conditions371094
-Node: Truth Values372168
-Node: Typing and Comparison373216
-Node: Variable Typing374036
-Ref: Variable Typing-Footnote-1380499
-Ref: Variable Typing-Footnote-2380571
-Node: Comparison Operators380648
-Ref: table-relational-ops381067
-Node: POSIX String Comparison384562
-Ref: POSIX String Comparison-Footnote-1386257
-Ref: POSIX String Comparison-Footnote-2386396
-Node: Boolean Ops386480
-Ref: Boolean Ops-Footnote-1390962
-Node: Conditional Exp391054
-Node: Function Calls392790
-Node: Precedence396667
-Node: Locales400326
-Node: Expressions Summary401958
-Node: Patterns and Actions404531
-Node: Pattern Overview405651
-Node: Regexp Patterns407328
-Node: Expression Patterns407870
-Node: Ranges411651
-Node: BEGIN/END414759
-Node: Using BEGIN/END415520
-Ref: Using BEGIN/END-Footnote-1418256
-Node: I/O And BEGIN/END418362
-Node: BEGINFILE/ENDFILE420676
-Node: Empty423583
-Node: Using Shell Variables423900
-Node: Action Overview426174
-Node: Statements428499
-Node: If Statement430347
-Node: While Statement431842
-Node: Do Statement433870
-Node: For Statement435018
-Node: Switch Statement438176
-Node: Break Statement440562
-Node: Continue Statement442654
-Node: Next Statement444481
-Node: Nextfile Statement446864
-Node: Exit Statement449516
-Node: Built-in Variables451919
-Node: User-modified453052
-Node: Auto-set460819
-Ref: Auto-set-Footnote-1476416
-Ref: Auto-set-Footnote-2476622
-Node: ARGC and ARGV476678
-Node: Pattern Action Summary480891
-Node: Arrays483321
-Node: Array Basics484650
-Node: Array Intro485494
-Ref: figure-array-elements487469
-Ref: Array Intro-Footnote-1490173
-Node: Reference to Elements490301
-Node: Assigning Elements492765
-Node: Array Example493256
-Node: Scanning an Array495015
-Node: Controlling Scanning498037
-Ref: Controlling Scanning-Footnote-1503436
-Node: Numeric Array Subscripts503752
-Node: Uninitialized Subscripts505936
-Node: Delete507555
-Ref: Delete-Footnote-1510307
-Node: Multidimensional510364
-Node: Multiscanning513459
-Node: Arrays of Arrays515050
-Node: Arrays Summary519817
-Node: Functions521910
-Node: Built-in522948
-Node: Calling Built-in524029
-Node: Numeric Functions526025
-Ref: Numeric Functions-Footnote-1530970
-Ref: Numeric Functions-Footnote-2531327
-Ref: Numeric Functions-Footnote-3531375
-Node: String Functions531647
-Ref: String Functions-Footnote-1555305
-Ref: String Functions-Footnote-2555433
-Ref: String Functions-Footnote-3555681
-Node: Gory Details555768
-Ref: table-sub-escapes557559
-Ref: table-sub-proposed559078
-Ref: table-posix-sub560441
-Ref: table-gensub-escapes561982
-Ref: Gory Details-Footnote-1562805
-Node: I/O Functions562959
-Ref: table-system-return-values569541
-Ref: I/O Functions-Footnote-1571521
-Ref: I/O Functions-Footnote-2571669
-Node: Time Functions571789
-Ref: Time Functions-Footnote-1582456
-Ref: Time Functions-Footnote-2582524
-Ref: Time Functions-Footnote-3582682
-Ref: Time Functions-Footnote-4582793
-Ref: Time Functions-Footnote-5582905
-Ref: Time Functions-Footnote-6583132
-Node: Bitwise Functions583398
-Ref: table-bitwise-ops583992
-Ref: Bitwise Functions-Footnote-1590025
-Ref: Bitwise Functions-Footnote-2590198
-Node: Type Functions590389
-Node: I18N Functions593064
-Node: User-defined594715
-Node: Definition Syntax595520
-Ref: Definition Syntax-Footnote-1601207
-Node: Function Example601278
-Ref: Function Example-Footnote-1604200
-Node: Function Caveats604222
-Node: Calling A Function604740
-Node: Variable Scope605698
-Node: Pass By Value/Reference608692
-Node: Return Statement612191
-Node: Dynamic Typing615170
-Node: Indirect Calls616100
-Ref: Indirect Calls-Footnote-1626351
-Node: Functions Summary626479
-Node: Library Functions629184
-Ref: Library Functions-Footnote-1632791
-Ref: Library Functions-Footnote-2632934
-Node: Library Names633105
-Ref: Library Names-Footnote-1636565
-Ref: Library Names-Footnote-2636788
-Node: General Functions636874
-Node: Strtonum Function637977
-Node: Assert Function640999
-Node: Round Function644325
-Node: Cliff Random Function645866
-Node: Ordinal Functions646882
-Ref: Ordinal Functions-Footnote-1649945
-Ref: Ordinal Functions-Footnote-2650197
-Node: Join Function650407
-Ref: Join Function-Footnote-1652177
-Node: Getlocaltime Function652377
-Node: Readfile Function656119
-Node: Shell Quoting658091
-Node: Data File Management659492
-Node: Filetrans Function660124
-Node: Rewind Function664220
-Node: File Checking666126
-Ref: File Checking-Footnote-1667460
-Node: Empty Files667661
-Node: Ignoring Assigns669640
-Node: Getopt Function671190
-Ref: Getopt Function-Footnote-1682659
-Node: Passwd Functions682859
-Ref: Passwd Functions-Footnote-1691698
-Node: Group Functions691786
-Ref: Group Functions-Footnote-1699684
-Node: Walking Arrays699891
-Node: Library Functions Summary702899
-Node: Library Exercises704305
-Node: Sample Programs704770
-Node: Running Examples705533
-Node: Clones706261
-Node: Cut Program707485
-Node: Egrep Program717414
-Ref: Egrep Program-Footnote-1724926
-Node: Id Program725036
-Node: Split Program728716
-Ref: Split Program-Footnote-1732175
-Node: Tee Program732304
-Node: Uniq Program735094
-Node: Wc Program742520
-Ref: Wc Program-Footnote-1746775
-Node: Miscellaneous Programs746869
-Node: Dupword Program748082
-Node: Alarm Program750112
-Node: Translate Program754967
-Ref: Translate Program-Footnote-1759532
-Node: Labels Program759802
-Ref: Labels Program-Footnote-1763153
-Node: Word Sorting763237
-Node: History Sorting767309
-Node: Extract Program769144
-Node: Simple Sed776673
-Node: Igawk Program779747
-Ref: Igawk Program-Footnote-1794078
-Ref: Igawk Program-Footnote-2794280
-Ref: Igawk Program-Footnote-3794402
-Node: Anagram Program794517
-Node: Signature Program797579
-Node: Programs Summary798826
-Node: Programs Exercises800040
-Ref: Programs Exercises-Footnote-1804169
-Node: Namespaces804260
-Node: Global Namespace804481
-Node: Qualified Names805721
-Node: Default Namespace806402
-Node: Changing The Namespace807099
-Node: Namespace Example808203
-Node: Namespace Misc810262
-Node: Advanced Features811040
-Node: Nondecimal Data813025
-Node: Array Sorting814616
-Node: Controlling Array Traversal815316
-Ref: Controlling Array Traversal-Footnote-1823683
-Node: Array Sorting Functions823801
-Ref: Array Sorting Functions-Footnote-1828892
-Node: Two-way I/O829088
-Ref: Two-way I/O-Footnote-1835639
-Ref: Two-way I/O-Footnote-2835826
-Node: TCP/IP Networking835908
-Node: Profiling839026
-Ref: Profiling-Footnote-1847698
-Node: Advanced Features Summary848021
-Node: Internationalization849865
-Node: I18N and L10N851345
-Node: Explaining gettext852032
-Ref: Explaining gettext-Footnote-1857924
-Ref: Explaining gettext-Footnote-2858109
-Node: Programmer i18n858274
-Ref: Programmer i18n-Footnote-1863223
-Node: Translator i18n863272
-Node: String Extraction864066
-Ref: String Extraction-Footnote-1865198
-Node: Printf Ordering865284
-Ref: Printf Ordering-Footnote-1868070
-Node: I18N Portability868134
-Ref: I18N Portability-Footnote-1870590
-Node: I18N Example870653
-Ref: I18N Example-Footnote-1873459
-Node: Gawk I18N873532
-Node: I18N Summary874177
-Node: Debugger875518
-Node: Debugging876540
-Node: Debugging Concepts876981
-Node: Debugging Terms878790
-Node: Awk Debugging881365
-Node: Sample Debugging Session882271
-Node: Debugger Invocation882805
-Node: Finding The Bug884191
-Node: List of Debugger Commands890669
-Node: Breakpoint Control892002
-Node: Debugger Execution Control895696
-Node: Viewing And Changing Data899058
-Node: Execution Stack902432
-Node: Debugger Info904069
-Node: Miscellaneous Debugger Commands908140
-Node: Readline Support913228
-Node: Limitations914124
-Node: Debugging Summary916233
-Node: Arbitrary Precision Arithmetic917512
-Node: Computer Arithmetic918997
-Ref: table-numeric-ranges922588
-Ref: Computer Arithmetic-Footnote-1923310
-Node: Math Definitions923367
-Ref: table-ieee-formats926681
-Ref: Math Definitions-Footnote-1927284
-Node: MPFR features927389
-Node: FP Math Caution929106
-Ref: FP Math Caution-Footnote-1930178
-Node: Inexactness of computations930547
-Node: Inexact representation931507
-Node: Comparing FP Values932867
-Node: Errors accumulate933949
-Node: Getting Accuracy935382
-Node: Try To Round938092
-Node: Setting precision938991
-Ref: table-predefined-precision-strings939688
-Node: Setting the rounding mode941518
-Ref: table-gawk-rounding-modes941892
-Ref: Setting the rounding mode-Footnote-1945300
-Node: Arbitrary Precision Integers945479
-Ref: Arbitrary Precision Integers-Footnote-1950384
-Node: Checking for MPFR950533
-Node: POSIX Floating Point Problems951830
-Ref: POSIX Floating Point Problems-Footnote-1955701
-Node: Floating point summary955739
-Node: Dynamic Extensions957929
-Node: Extension Intro959482
-Node: Plugin License960748
-Node: Extension Mechanism Outline961545
-Ref: figure-load-extension961984
-Ref: figure-register-new-function963549
-Ref: figure-call-new-function964641
-Node: Extension API Description966703
-Node: Extension API Functions Introduction968345
-Node: General Data Types973679
-Ref: General Data Types-Footnote-1980884
-Node: Memory Allocation Functions981183
-Ref: Memory Allocation Functions-Footnote-1984028
-Node: Constructor Functions984127
-Node: Registration Functions987126
-Node: Extension Functions987811
-Node: Exit Callback Functions993024
-Node: Extension Version String994274
-Node: Input Parsers994937
-Node: Output Wrappers1007644
-Node: Two-way processors1012156
-Node: Printing Messages1014421
-Ref: Printing Messages-Footnote-11015592
-Node: Updating ERRNO1015745
-Node: Requesting Values1016484
-Ref: table-value-types-returned1017221
-Node: Accessing Parameters1018157
-Node: Symbol Table Access1019392
-Node: Symbol table by name1019904
-Node: Symbol table by cookie1021693
-Ref: Symbol table by cookie-Footnote-11025878
-Node: Cached values1025942
-Ref: Cached values-Footnote-11029478
-Node: Array Manipulation1029569
-Ref: Array Manipulation-Footnote-11030660
-Node: Array Data Types1030697
-Ref: Array Data Types-Footnote-11033355
-Node: Array Functions1033447
-Node: Flattening Arrays1037846
-Node: Creating Arrays1044787
-Node: Redirection API1049556
-Node: Extension API Variables1052398
-Node: Extension Versioning1053031
-Ref: gawk-api-version1053468
-Node: Extension API Informational Variables1055196
-Node: Extension API Boilerplate1056260
-Node: Changes from API V11060122
-Node: Finding Extensions1060782
-Node: Extension Example1061341
-Node: Internal File Description1062139
-Node: Internal File Ops1066219
-Ref: Internal File Ops-Footnote-11077619
-Node: Using Internal File Ops1077759
-Ref: Using Internal File Ops-Footnote-11080142
-Node: Extension Samples1080416
-Node: Extension Sample File Functions1081945
-Node: Extension Sample Fnmatch1089594
-Node: Extension Sample Fork1091081
-Node: Extension Sample Inplace1092299
-Node: Extension Sample Ord1095509
-Node: Extension Sample Readdir1096345
-Ref: table-readdir-file-types1097234
-Node: Extension Sample Revout1098039
-Node: Extension Sample Rev2way1098628
-Node: Extension Sample Read write array1099368
-Node: Extension Sample Readfile1101310
-Node: Extension Sample Time1102405
-Node: Extension Sample API Tests1103753
-Node: gawkextlib1104245
-Node: Extension summary1106692
-Node: Extension Exercises1110394
-Node: Language History1111892
-Node: V7/SVR3.11113548
-Node: SVR41115700
-Node: POSIX1117134
-Node: BTL1118513
-Node: POSIX/GNU1119242
-Node: Feature History1125134
-Node: Common Extensions1139558
-Node: Ranges and Locales1140841
-Ref: Ranges and Locales-Footnote-11145457
-Ref: Ranges and Locales-Footnote-21145484
-Ref: Ranges and Locales-Footnote-31145719
-Node: Contributors1145940
-Node: History summary1151500
-Node: Installation1152880
-Node: Gawk Distribution1153824
-Node: Getting1154308
-Node: Extracting1155269
-Node: Distribution contents1156907
-Node: Unix Installation1163249
-Node: Quick Installation1163931
-Node: Shell Startup Files1166345
-Node: Additional Configuration Options1167434
-Node: Configuration Philosophy1169423
-Node: Non-Unix Installation1171792
-Node: PC Installation1172252
-Node: PC Binary Installation1173090
-Node: PC Compiling1173525
-Node: PC Using1174642
-Node: Cygwin1177687
-Node: MSYS1178457
-Node: VMS Installation1178958
-Node: VMS Compilation1179749
-Ref: VMS Compilation-Footnote-11180978
-Node: VMS Dynamic Extensions1181036
-Node: VMS Installation Details1182721
-Node: VMS Running1184974
-Node: VMS GNV1189253
-Node: VMS Old Gawk1189988
-Node: Bugs1190459
-Node: Bug address1191122
-Node: Usenet1193519
-Node: Maintainers1194296
-Node: Other Versions1195672
-Node: Installation summary1202256
-Node: Notes1203291
-Node: Compatibility Mode1204156
-Node: Additions1204938
-Node: Accessing The Source1205863
-Node: Adding Code1207298
-Node: New Ports1213516
-Node: Derived Files1218004
-Ref: Derived Files-Footnote-11223489
-Ref: Derived Files-Footnote-21223524
-Ref: Derived Files-Footnote-31224122
-Node: Future Extensions1224236
-Node: Implementation Limitations1224894
-Node: Extension Design1226077
-Node: Old Extension Problems1227231
-Ref: Old Extension Problems-Footnote-11228749
-Node: Extension New Mechanism Goals1228806
-Ref: Extension New Mechanism Goals-Footnote-11232170
-Node: Extension Other Design Decisions1232359
-Node: Extension Future Growth1234472
-Node: Old Extension Mechanism1235308
-Node: Notes summary1237071
-Node: Basic Concepts1238253
-Node: Basic High Level1238934
-Ref: figure-general-flow1239216
-Ref: figure-process-flow1239901
-Ref: Basic High Level-Footnote-11243202
-Node: Basic Data Typing1243387
-Node: Glossary1246715
-Node: Copying1278662
-Node: GNU Free Documentation License1316201
-Node: Index1341319
+Node: Foreword343786
+Node: Foreword448228
+Node: Preface49760
+Ref: Preface-Footnote-152619
+Ref: Preface-Footnote-252726
+Ref: Preface-Footnote-352960
+Node: History53102
+Node: Names55454
+Ref: Names-Footnote-156548
+Node: This Manual56695
+Ref: This Manual-Footnote-163180
+Node: Conventions63280
+Node: Manual History65634
+Ref: Manual History-Footnote-168629
+Ref: Manual History-Footnote-268670
+Node: How To Contribute68744
+Node: Acknowledgments69395
+Node: Getting Started74281
+Node: Running gawk76720
+Node: One-shot77910
+Node: Read Terminal79173
+Node: Long81166
+Node: Executable Scripts82679
+Ref: Executable Scripts-Footnote-185474
+Node: Comments85577
+Node: Quoting88061
+Node: DOS Quoting93578
+Node: Sample Data Files95633
+Node: Very Simple98228
+Node: Two Rules103130
+Node: More Complex105015
+Node: Statements/Lines107881
+Ref: Statements/Lines-Footnote-1112340
+Node: Other Features112605
+Node: When113541
+Ref: When-Footnote-1115295
+Node: Intro Summary115360
+Node: Invoking Gawk116244
+Node: Command Line117758
+Node: Options118556
+Ref: Options-Footnote-1135199
+Ref: Options-Footnote-2135429
+Node: Other Arguments135454
+Node: Naming Standard Input138401
+Node: Environment Variables139494
+Node: AWKPATH Variable140052
+Ref: AWKPATH Variable-Footnote-1143463
+Ref: AWKPATH Variable-Footnote-2143497
+Node: AWKLIBPATH Variable143758
+Node: Other Environment Variables145015
+Node: Exit Status148836
+Node: Include Files149513
+Node: Loading Shared Libraries153108
+Node: Obsolete154536
+Node: Undocumented155228
+Node: Invoking Summary155525
+Node: Regexp157185
+Node: Regexp Usage158639
+Node: Escape Sequences160676
+Node: Regexp Operators166908
+Ref: Regexp Operators-Footnote-1174324
+Ref: Regexp Operators-Footnote-2174471
+Node: Bracket Expressions174569
+Ref: table-char-classes177045
+Node: Leftmost Longest180182
+Node: Computed Regexps181485
+Node: GNU Regexp Operators184912
+Node: Case-sensitivity188591
+Ref: Case-sensitivity-Footnote-1191478
+Ref: Case-sensitivity-Footnote-2191713
+Node: Regexp Summary191821
+Node: Reading Files193287
+Node: Records195556
+Node: awk split records196289
+Node: gawk split records201220
+Ref: gawk split records-Footnote-1205760
+Node: Fields205797
+Node: Nonconstant Fields208538
+Ref: Nonconstant Fields-Footnote-1210774
+Node: Changing Fields210978
+Node: Field Separators216906
+Node: Default Field Splitting219604
+Node: Regexp Field Splitting220722
+Node: Single Character Fields224075
+Node: Command Line Field Separator225135
+Node: Full Line Fields228353
+Ref: Full Line Fields-Footnote-1229875
+Ref: Full Line Fields-Footnote-2229921
+Node: Field Splitting Summary230022
+Node: Constant Size232096
+Node: Fixed width data232828
+Node: Skipping intervening236295
+Node: Allowing trailing data237093
+Node: Fields with fixed data238130
+Node: Splitting By Content239648
+Ref: Splitting By Content-Footnote-1243298
+Node: Testing field creation243461
+Node: Multiple Line245082
+Ref: Multiple Line-Footnote-1250966
+Node: Getline251145
+Node: Plain Getline253614
+Node: Getline/Variable256255
+Node: Getline/File257406
+Node: Getline/Variable/File258794
+Ref: Getline/Variable/File-Footnote-1260399
+Node: Getline/Pipe260487
+Node: Getline/Variable/Pipe263194
+Node: Getline/Coprocess264329
+Node: Getline/Variable/Coprocess265596
+Node: Getline Notes266338
+Node: Getline Summary269135
+Ref: table-getline-variants269559
+Node: Read Timeout270307
+Ref: Read Timeout-Footnote-1274213
+Node: Retrying Input274271
+Node: Command-line directories275470
+Node: Input Summary276376
+Node: Input Exercises279548
+Node: Printing280276
+Node: Print282110
+Node: Print Examples283567
+Node: Output Separators286347
+Node: OFMT288364
+Node: Printf289720
+Node: Basic Printf290505
+Node: Control Letters292079
+Node: Format Modifiers296067
+Node: Printf Examples302082
+Node: Redirection304568
+Node: Special FD311409
+Ref: Special FD-Footnote-1314577
+Node: Special Files314651
+Node: Other Inherited Files315268
+Node: Special Network316269
+Node: Special Caveats317129
+Node: Close Files And Pipes318078
+Ref: table-close-pipe-return-values324985
+Ref: Close Files And Pipes-Footnote-1325768
+Ref: Close Files And Pipes-Footnote-2325916
+Node: Nonfatal326068
+Node: Output Summary328393
+Node: Output Exercises329615
+Node: Expressions330294
+Node: Values331482
+Node: Constants332160
+Node: Scalar Constants332851
+Ref: Scalar Constants-Footnote-1333715
+Node: Nondecimal-numbers333965
+Node: Regexp Constants336966
+Node: Using Constant Regexps337492
+Node: Standard Regexp Constants338114
+Node: Strong Regexp Constants341302
+Node: Variables344260
+Node: Using Variables344917
+Node: Assignment Options346827
+Node: Conversion348700
+Node: Strings And Numbers349224
+Ref: Strings And Numbers-Footnote-1352287
+Node: Locale influences conversions352396
+Ref: table-locale-affects355154
+Node: All Operators355772
+Node: Arithmetic Ops356401
+Node: Concatenation358907
+Ref: Concatenation-Footnote-1361754
+Node: Assignment Ops361861
+Ref: table-assign-ops366852
+Node: Increment Ops368165
+Node: Truth Values and Conditions371625
+Node: Truth Values372699
+Node: Typing and Comparison373747
+Node: Variable Typing374567
+Ref: Variable Typing-Footnote-1381030
+Ref: Variable Typing-Footnote-2381102
+Node: Comparison Operators381179
+Ref: table-relational-ops381598
+Node: POSIX String Comparison385093
+Ref: POSIX String Comparison-Footnote-1386788
+Ref: POSIX String Comparison-Footnote-2386927
+Node: Boolean Ops387011
+Ref: Boolean Ops-Footnote-1391493
+Node: Conditional Exp391585
+Node: Function Calls393321
+Node: Precedence397198
+Node: Locales400857
+Node: Expressions Summary402489
+Node: Patterns and Actions405062
+Node: Pattern Overview406182
+Node: Regexp Patterns407859
+Node: Expression Patterns408401
+Node: Ranges412182
+Node: BEGIN/END415290
+Node: Using BEGIN/END416051
+Ref: Using BEGIN/END-Footnote-1418787
+Node: I/O And BEGIN/END418893
+Node: BEGINFILE/ENDFILE421207
+Node: Empty424114
+Node: Using Shell Variables424431
+Node: Action Overview426705
+Node: Statements429030
+Node: If Statement430878
+Node: While Statement432373
+Node: Do Statement434401
+Node: For Statement435549
+Node: Switch Statement438707
+Node: Break Statement441093
+Node: Continue Statement443185
+Node: Next Statement445012
+Node: Nextfile Statement447395
+Node: Exit Statement450047
+Node: Built-in Variables452450
+Node: User-modified453583
+Node: Auto-set461350
+Ref: Auto-set-Footnote-1476947
+Ref: Auto-set-Footnote-2477153
+Node: ARGC and ARGV477209
+Node: Pattern Action Summary481422
+Node: Arrays483852
+Node: Array Basics485181
+Node: Array Intro486025
+Ref: figure-array-elements488000
+Ref: Array Intro-Footnote-1490704
+Node: Reference to Elements490832
+Node: Assigning Elements493296
+Node: Array Example493787
+Node: Scanning an Array495546
+Node: Controlling Scanning498568
+Ref: Controlling Scanning-Footnote-1503967
+Node: Numeric Array Subscripts504283
+Node: Uninitialized Subscripts506467
+Node: Delete508086
+Ref: Delete-Footnote-1510838
+Node: Multidimensional510895
+Node: Multiscanning513990
+Node: Arrays of Arrays515581
+Node: Arrays Summary520348
+Node: Functions522441
+Node: Built-in523479
+Node: Calling Built-in524560
+Node: Numeric Functions526556
+Ref: Numeric Functions-Footnote-1531501
+Ref: Numeric Functions-Footnote-2531858
+Ref: Numeric Functions-Footnote-3531906
+Node: String Functions532178
+Ref: String Functions-Footnote-1555836
+Ref: String Functions-Footnote-2555964
+Ref: String Functions-Footnote-3556212
+Node: Gory Details556299
+Ref: table-sub-escapes558090
+Ref: table-sub-proposed559609
+Ref: table-posix-sub560972
+Ref: table-gensub-escapes562513
+Ref: Gory Details-Footnote-1563336
+Node: I/O Functions563490
+Ref: table-system-return-values570072
+Ref: I/O Functions-Footnote-1572052
+Ref: I/O Functions-Footnote-2572200
+Node: Time Functions572320
+Ref: Time Functions-Footnote-1582987
+Ref: Time Functions-Footnote-2583055
+Ref: Time Functions-Footnote-3583213
+Ref: Time Functions-Footnote-4583324
+Ref: Time Functions-Footnote-5583436
+Ref: Time Functions-Footnote-6583663
+Node: Bitwise Functions583929
+Ref: table-bitwise-ops584523
+Ref: Bitwise Functions-Footnote-1590556
+Ref: Bitwise Functions-Footnote-2590729
+Node: Type Functions590920
+Node: I18N Functions593595
+Node: User-defined595246
+Node: Definition Syntax596051
+Ref: Definition Syntax-Footnote-1601738
+Node: Function Example601809
+Ref: Function Example-Footnote-1604731
+Node: Function Caveats604753
+Node: Calling A Function605271
+Node: Variable Scope606229
+Node: Pass By Value/Reference609223
+Node: Return Statement612722
+Node: Dynamic Typing615701
+Node: Indirect Calls616631
+Ref: Indirect Calls-Footnote-1626882
+Node: Functions Summary627010
+Node: Library Functions629715
+Ref: Library Functions-Footnote-1633322
+Ref: Library Functions-Footnote-2633465
+Node: Library Names633636
+Ref: Library Names-Footnote-1637096
+Ref: Library Names-Footnote-2637319
+Node: General Functions637405
+Node: Strtonum Function638508
+Node: Assert Function641530
+Node: Round Function644856
+Node: Cliff Random Function646397
+Node: Ordinal Functions647413
+Ref: Ordinal Functions-Footnote-1650476
+Ref: Ordinal Functions-Footnote-2650728
+Node: Join Function650938
+Ref: Join Function-Footnote-1652708
+Node: Getlocaltime Function652908
+Node: Readfile Function656650
+Node: Shell Quoting658622
+Node: Data File Management660023
+Node: Filetrans Function660655
+Node: Rewind Function664751
+Node: File Checking666657
+Ref: File Checking-Footnote-1667991
+Node: Empty Files668192
+Node: Ignoring Assigns670171
+Node: Getopt Function671721
+Ref: Getopt Function-Footnote-1683190
+Node: Passwd Functions683390
+Ref: Passwd Functions-Footnote-1692229
+Node: Group Functions692317
+Ref: Group Functions-Footnote-1700215
+Node: Walking Arrays700422
+Node: Library Functions Summary703430
+Node: Library Exercises704836
+Node: Sample Programs705301
+Node: Running Examples706064
+Node: Clones706792
+Node: Cut Program708016
+Node: Egrep Program717945
+Ref: Egrep Program-Footnote-1725457
+Node: Id Program725567
+Node: Split Program729247
+Ref: Split Program-Footnote-1732706
+Node: Tee Program732835
+Node: Uniq Program735625
+Node: Wc Program743051
+Ref: Wc Program-Footnote-1747306
+Node: Miscellaneous Programs747400
+Node: Dupword Program748613
+Node: Alarm Program750643
+Node: Translate Program755498
+Ref: Translate Program-Footnote-1760063
+Node: Labels Program760333
+Ref: Labels Program-Footnote-1763684
+Node: Word Sorting763768
+Node: History Sorting767840
+Node: Extract Program769675
+Node: Simple Sed777204
+Node: Igawk Program780278
+Ref: Igawk Program-Footnote-1794609
+Ref: Igawk Program-Footnote-2794811
+Ref: Igawk Program-Footnote-3794933
+Node: Anagram Program795048
+Node: Signature Program798110
+Node: Programs Summary799357
+Node: Programs Exercises800571
+Ref: Programs Exercises-Footnote-1804700
+Node: Namespaces804791
+Node: Global Namespace805406
+Node: Qualified Names806646
+Node: Default Namespace807327
+Node: Changing The Namespace808105
+Node: Namespace Example809194
+Node: Namespace Misc811265
+Node: Advanced Features813179
+Node: Nondecimal Data815164
+Node: Array Sorting816755
+Node: Controlling Array Traversal817455
+Ref: Controlling Array Traversal-Footnote-1825822
+Node: Array Sorting Functions825940
+Ref: Array Sorting Functions-Footnote-1831031
+Node: Two-way I/O831227
+Ref: Two-way I/O-Footnote-1837778
+Ref: Two-way I/O-Footnote-2837965
+Node: TCP/IP Networking838047
+Node: Profiling841165
+Ref: Profiling-Footnote-1849837
+Node: Advanced Features Summary850160
+Node: Internationalization852004
+Node: I18N and L10N853484
+Node: Explaining gettext854171
+Ref: Explaining gettext-Footnote-1860063
+Ref: Explaining gettext-Footnote-2860248
+Node: Programmer i18n860413
+Ref: Programmer i18n-Footnote-1865362
+Node: Translator i18n865411
+Node: String Extraction866205
+Ref: String Extraction-Footnote-1867337
+Node: Printf Ordering867423
+Ref: Printf Ordering-Footnote-1870209
+Node: I18N Portability870273
+Ref: I18N Portability-Footnote-1872729
+Node: I18N Example872792
+Ref: I18N Example-Footnote-1875598
+Node: Gawk I18N875671
+Node: I18N Summary876316
+Node: Debugger877657
+Node: Debugging878679
+Node: Debugging Concepts879120
+Node: Debugging Terms880929
+Node: Awk Debugging883504
+Node: Sample Debugging Session884410
+Node: Debugger Invocation884944
+Node: Finding The Bug886330
+Node: List of Debugger Commands892808
+Node: Breakpoint Control894141
+Node: Debugger Execution Control897835
+Node: Viewing And Changing Data901197
+Node: Execution Stack904571
+Node: Debugger Info906208
+Node: Miscellaneous Debugger Commands910279
+Node: Readline Support915367
+Node: Limitations916263
+Node: Debugging Summary918372
+Node: Arbitrary Precision Arithmetic919651
+Node: Computer Arithmetic921136
+Ref: table-numeric-ranges924727
+Ref: Computer Arithmetic-Footnote-1925449
+Node: Math Definitions925506
+Ref: table-ieee-formats928820
+Ref: Math Definitions-Footnote-1929423
+Node: MPFR features929528
+Node: FP Math Caution931245
+Ref: FP Math Caution-Footnote-1932317
+Node: Inexactness of computations932686
+Node: Inexact representation933646
+Node: Comparing FP Values935006
+Node: Errors accumulate936088
+Node: Getting Accuracy937521
+Node: Try To Round940231
+Node: Setting precision941130
+Ref: table-predefined-precision-strings941827
+Node: Setting the rounding mode943657
+Ref: table-gawk-rounding-modes944031
+Ref: Setting the rounding mode-Footnote-1947439
+Node: Arbitrary Precision Integers947618
+Ref: Arbitrary Precision Integers-Footnote-1952523
+Node: Checking for MPFR952672
+Node: POSIX Floating Point Problems953969
+Ref: POSIX Floating Point Problems-Footnote-1957840
+Node: Floating point summary957878
+Node: Dynamic Extensions960068
+Node: Extension Intro961621
+Node: Plugin License962887
+Node: Extension Mechanism Outline963684
+Ref: figure-load-extension964123
+Ref: figure-register-new-function965688
+Ref: figure-call-new-function966780
+Node: Extension API Description968842
+Node: Extension API Functions Introduction970484
+Node: General Data Types975818
+Ref: General Data Types-Footnote-1983023
+Node: Memory Allocation Functions983322
+Ref: Memory Allocation Functions-Footnote-1986167
+Node: Constructor Functions986266
+Node: Registration Functions989265
+Node: Extension Functions989950
+Node: Exit Callback Functions995163
+Node: Extension Version String996413
+Node: Input Parsers997076
+Node: Output Wrappers1009783
+Node: Two-way processors1014295
+Node: Printing Messages1016560
+Ref: Printing Messages-Footnote-11017731
+Node: Updating ERRNO1017884
+Node: Requesting Values1018623
+Ref: table-value-types-returned1019360
+Node: Accessing Parameters1020296
+Node: Symbol Table Access1021531
+Node: Symbol table by name1022043
+Node: Symbol table by cookie1023832
+Ref: Symbol table by cookie-Footnote-11028017
+Node: Cached values1028081
+Ref: Cached values-Footnote-11031617
+Node: Array Manipulation1031708
+Ref: Array Manipulation-Footnote-11032799
+Node: Array Data Types1032836
+Ref: Array Data Types-Footnote-11035494
+Node: Array Functions1035586
+Node: Flattening Arrays1039985
+Node: Creating Arrays1046926
+Node: Redirection API1051695
+Node: Extension API Variables1054537
+Node: Extension Versioning1055170
+Ref: gawk-api-version1055607
+Node: Extension API Informational Variables1057335
+Node: Extension API Boilerplate1058399
+Node: Changes from API V11062261
+Node: Finding Extensions1062921
+Node: Extension Example1063480
+Node: Internal File Description1064278
+Node: Internal File Ops1068358
+Ref: Internal File Ops-Footnote-11079758
+Node: Using Internal File Ops1079898
+Ref: Using Internal File Ops-Footnote-11082281
+Node: Extension Samples1082555
+Node: Extension Sample File Functions1084084
+Node: Extension Sample Fnmatch1091733
+Node: Extension Sample Fork1093220
+Node: Extension Sample Inplace1094438
+Node: Extension Sample Ord1097648
+Node: Extension Sample Readdir1098484
+Ref: table-readdir-file-types1099373
+Node: Extension Sample Revout1100178
+Node: Extension Sample Rev2way1100767
+Node: Extension Sample Read write array1101507
+Node: Extension Sample Readfile1103449
+Node: Extension Sample Time1104544
+Node: Extension Sample API Tests1105892
+Node: gawkextlib1106384
+Node: Extension summary1108831
+Node: Extension Exercises1112533
+Node: Language History1114031
+Node: V7/SVR3.11115687
+Node: SVR41117839
+Node: POSIX1119273
+Node: BTL1120652
+Node: POSIX/GNU1121381
+Node: Feature History1127273
+Node: Common Extensions1141697
+Node: Ranges and Locales1142980
+Ref: Ranges and Locales-Footnote-11147596
+Ref: Ranges and Locales-Footnote-21147623
+Ref: Ranges and Locales-Footnote-31147858
+Node: Contributors1148079
+Node: History summary1153639
+Node: Installation1155019
+Node: Gawk Distribution1155963
+Node: Getting1156447
+Node: Extracting1157408
+Node: Distribution contents1159046
+Node: Unix Installation1165388
+Node: Quick Installation1166070
+Node: Shell Startup Files1168484
+Node: Additional Configuration Options1169573
+Node: Configuration Philosophy1171562
+Node: Non-Unix Installation1173931
+Node: PC Installation1174391
+Node: PC Binary Installation1175229
+Node: PC Compiling1175664
+Node: PC Using1176781
+Node: Cygwin1179826
+Node: MSYS1180596
+Node: VMS Installation1181097
+Node: VMS Compilation1181888
+Ref: VMS Compilation-Footnote-11183117
+Node: VMS Dynamic Extensions1183175
+Node: VMS Installation Details1184860
+Node: VMS Running1187113
+Node: VMS GNV1191392
+Node: VMS Old Gawk1192127
+Node: Bugs1192598
+Node: Bug address1193261
+Node: Usenet1195658
+Node: Maintainers1196435
+Node: Other Versions1197811
+Node: Installation summary1204395
+Node: Notes1205430
+Node: Compatibility Mode1206295
+Node: Additions1207077
+Node: Accessing The Source1208002
+Node: Adding Code1209437
+Node: New Ports1215655
+Node: Derived Files1220143
+Ref: Derived Files-Footnote-11225628
+Ref: Derived Files-Footnote-21225663
+Ref: Derived Files-Footnote-31226261
+Node: Future Extensions1226375
+Node: Implementation Limitations1227033
+Node: Extension Design1228216
+Node: Old Extension Problems1229370
+Ref: Old Extension Problems-Footnote-11230888
+Node: Extension New Mechanism Goals1230945
+Ref: Extension New Mechanism Goals-Footnote-11234309
+Node: Extension Other Design Decisions1234498
+Node: Extension Future Growth1236611
+Node: Old Extension Mechanism1237447
+Node: Notes summary1239210
+Node: Basic Concepts1240392
+Node: Basic High Level1241073
+Ref: figure-general-flow1241355
+Ref: figure-process-flow1242040
+Ref: Basic High Level-Footnote-11245341
+Node: Basic Data Typing1245526
+Node: Glossary1248854
+Node: Copying1280801
+Node: GNU Free Documentation License1318340
+Node: Index1343458
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 17890ad..17bf2b6 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -454,6 +454,7 @@ particular records in a file and perform operations upon
them.
* Library Functions:: A Library of @command{awk} Functions.
* Sample Programs:: Many @command{awk} programs with complete
explanations.
+* Namespaces:: How namespaces work in @command{gawk}.
* Advanced Features:: Stuff for advanced users, specific to
@command{gawk}.
* Internationalization:: Getting @command{gawk} to speak your
@@ -851,6 +852,12 @@ particular records in a file and perform operations upon
them.
time on their hands.
* Programs Summary:: Summary of programs.
* Programs Exercises:: Exercises.
+* Global Namespace:: The global namespace in standard
@command{awk}.
+* Qualified Names:: How to qualify names with a namespace.
+* Default Namespace:: The default namespace.
+* Changing The Namespace:: How to change the namespace.
+* Namespace Example:: An example of code using a namespace.
+* Namespace Misc:: Namespace notes for developers.
* Nondecimal Data:: Allowing nondecimal input data.
* Array Sorting:: Facilities for controlling array
traversal and sorting arrays.
@@ -3973,8 +3980,9 @@ a newline character (even if it doesn't). This makes
building
the total program easier.
@quotation CAUTION
-At the moment, there is no requirement that each @var{program-text}
-be a full syntactic unit. I.e., the following currently works:
+Prior to @value{PVERSION} @strong{FIXME} 5.0, there was
+no requirement that each @var{program-text}
+be a full syntactic unit. I.e., the following worked:
@example
$ @kbd{gawk -e 'BEGIN @{ a = 5 ;' -e 'print a @}'}
@@ -3982,8 +3990,8 @@ $ @kbd{gawk -e 'BEGIN @{ a = 5 ;' -e 'print a @}'}
@end example
@noindent
-However, this could change in the future, so it's not a
-good idea to rely upon this feature.
+However, this is no longer true. If you have any scripts that
+rely upon this feature, you should revise them.
@end quotation
@item @option{-E} @var{file}
@@ -27605,6 +27613,12 @@ It contains the following chapters:
This @value{CHAPTER} describes a feature that is specific to @command{gawk}.
@menu
+* Global Namespace:: The global namespace in standard @command{awk}.
+* Qualified Names:: How to qualify names with a namespace.
+* Default Namespace:: The default namespace.
+* Changing The Namespace:: How to change the namespace.
+* Namespace Example:: An example of code using a namespace.
+* Namespace Misc:: Namespace notes for developers.
@end menu
@node Global Namespace
@@ -27629,7 +27643,7 @@ still a single namespace for the namespaces, but the
hope is that there
are much fewer namespaces in use by any given program, and thus much
less chance for collisions.)
-Starting with version @strong{FIXME} 5.0, @command{gawk} provides a
+Starting with @value{PVERSION} @strong{FIXME} 5.0, @command{gawk} provides a
mechanism to put functions and global variables into different
namespaces.
@@ -27661,6 +27675,8 @@ forces unqualified identifiers whose names are all
uppercase letters
to be in the @samp{awk} namespace. This makes it possible for you to easily
reference @command{gawk}'s global variables from different namespaces.
+It is a syntactic error to use qualified names for function parameter names.
+
@node Changing The Namespace
@section Changing The Namespace
@@ -27670,7 +27686,7 @@ at the top level of your program:
@example
@@namespace "passwd"
-BEGIN @{ @dot{} @}
+BEGIN @{ @dots{} @}
@dots{}
@end example
@@ -27689,14 +27705,13 @@ the distinction.
@end quotation
Each source file for @option{-i} and @option{-f} starts out with an implicit
address@hidden@namespace "awk"}.
address@hidden@@namespace "awk"}.
Similarly, each chunk of command-line code with @option{-e} has such an
implicit
statement.
-FIXME: The semantics of @option{-e} change to require it to be syntactic unit.
-
-FIXME: Update doc earlier in this book and change the corresponding code.
+The use of @samp{@@namespace} has no influence upon the order of execution
+of @code{BEGIN}, @code{BEGINFILE}, @code{END}, and @code{ENDFILE} rules.
@node Namespace Example
@section Namespace Example
@@ -27734,11 +27749,11 @@ function Init( oldfs, oldrs, olddol0, pwcat,
using_fw, using_fpat)
RS = "\n"
pwcat = _pw_awklib "pwcat"
- while ((pwcat | getline) > 0) {
+ while ((pwcat | getline) > 0) @{
Byname[$1] = $0
Byuid[$3] = $0
Bycount[++_pw_total] = $0
- }
+ @}
close(pwcat)
Count = 0
Inited = 1
@@ -27806,7 +27821,10 @@ function endpwent()
Other notes for reviewers:
address@hidden
address@hidden @asis
address@hidden @code{SYMTAB}, @code{FUNCTAB} and @code{PROCINFO["identifiers"]}
+The subscripts are all fully qualified names.
+
@item Profiler:
When profiling, we can add an @code{Op_Namespace} to the start of
each rule. If it has changed since the previous one, output an
@@ -27816,10 +27834,44 @@ For all @samp{awk.XXX} if @samp{XXX} is all
uppercase, strip
off the @samp{awk} part.
@item Debugger:
-Simply prints fully qualified names all the time. Maybe allow a
+Simply print fully qualified names all the time. Maybe allow a
@samp{namespace @var{xxx}} command in the debugger to set the
namespace and it will use that to create fully qualified names?
Have to be careful about all uppercase names though.
+
address@hidden How does this affect indirect calls?
+The current namespace is a parse time thing, not a dynamic
+thing, so for indirect calls to work, use something like:
+
address@hidden
+@@namespace "foo"
+
+function bar() @{ @dots{} @}
+
address@hidden
+ @dots{}
+ x = "foo.bar"
+ @dots{}
+ @@x()
address@hidden
address@hidden example
+
address@hidden
+This is particularly true if @code{x} is passed as a ``function pointer''
+to another function in another namespace for that function to call
+through it.
+
address@hidden How does this affect @code{@@include}?
+Basically @code{@@include} should push and pop the namespace. Each
@code{@@include}
+saves the current namespace and starts over with namespace @samp{awk} until
+an @code{@@namespace} is seen.
+
address@hidden Extension functions
+Revise the current macros to pass @code{"awk"} as the namespace
+argument and add new macros with @samp{_ns} or some such in the name that
+pass the namespace of the extension. This preserves backwards
+compatibility at the source level while providing access to namespaces
+as needed.
@end table
@node Advanced Features
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 814362a..ef88264 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -449,6 +449,7 @@ particular records in a file and perform operations upon
them.
* Library Functions:: A Library of @command{awk} Functions.
* Sample Programs:: Many @command{awk} programs with complete
explanations.
+* Namespaces:: How namespaces work in @command{gawk}.
* Advanced Features:: Stuff for advanced users, specific to
@command{gawk}.
* Internationalization:: Getting @command{gawk} to speak your
@@ -846,6 +847,12 @@ particular records in a file and perform operations upon
them.
time on their hands.
* Programs Summary:: Summary of programs.
* Programs Exercises:: Exercises.
+* Global Namespace:: The global namespace in standard
@command{awk}.
+* Qualified Names:: How to qualify names with a namespace.
+* Default Namespace:: The default namespace.
+* Changing The Namespace:: How to change the namespace.
+* Namespace Example:: An example of code using a namespace.
+* Namespace Misc:: Namespace notes for developers.
* Nondecimal Data:: Allowing nondecimal input data.
* Array Sorting:: Facilities for controlling array
traversal and sorting arrays.
@@ -3884,8 +3891,9 @@ a newline character (even if it doesn't). This makes
building
the total program easier.
@quotation CAUTION
-At the moment, there is no requirement that each @var{program-text}
-be a full syntactic unit. I.e., the following currently works:
+Prior to @value{PVERSION} @strong{FIXME} 5.0, there was
+no requirement that each @var{program-text}
+be a full syntactic unit. I.e., the following worked:
@example
$ @kbd{gawk -e 'BEGIN @{ a = 5 ;' -e 'print a @}'}
@@ -3893,8 +3901,8 @@ $ @kbd{gawk -e 'BEGIN @{ a = 5 ;' -e 'print a @}'}
@end example
@noindent
-However, this could change in the future, so it's not a
-good idea to rely upon this feature.
+However, this is no longer true. If you have any scripts that
+rely upon this feature, you should revise them.
@end quotation
@item @option{-E} @var{file}
@@ -26619,6 +26627,12 @@ It contains the following chapters:
This @value{CHAPTER} describes a feature that is specific to @command{gawk}.
@menu
+* Global Namespace:: The global namespace in standard @command{awk}.
+* Qualified Names:: How to qualify names with a namespace.
+* Default Namespace:: The default namespace.
+* Changing The Namespace:: How to change the namespace.
+* Namespace Example:: An example of code using a namespace.
+* Namespace Misc:: Namespace notes for developers.
@end menu
@node Global Namespace
@@ -26643,7 +26657,7 @@ still a single namespace for the namespaces, but the
hope is that there
are much fewer namespaces in use by any given program, and thus much
less chance for collisions.)
-Starting with version @strong{FIXME} 5.0, @command{gawk} provides a
+Starting with @value{PVERSION} @strong{FIXME} 5.0, @command{gawk} provides a
mechanism to put functions and global variables into different
namespaces.
@@ -26675,6 +26689,8 @@ forces unqualified identifiers whose names are all
uppercase letters
to be in the @samp{awk} namespace. This makes it possible for you to easily
reference @command{gawk}'s global variables from different namespaces.
+It is a syntactic error to use qualified names for function parameter names.
+
@node Changing The Namespace
@section Changing The Namespace
@@ -26684,7 +26700,7 @@ at the top level of your program:
@example
@@namespace "passwd"
-BEGIN @{ @dot{} @}
+BEGIN @{ @dots{} @}
@dots{}
@end example
@@ -26703,14 +26719,13 @@ the distinction.
@end quotation
Each source file for @option{-i} and @option{-f} starts out with an implicit
address@hidden@namespace "awk"}.
address@hidden@@namespace "awk"}.
Similarly, each chunk of command-line code with @option{-e} has such an
implicit
statement.
-FIXME: The semantics of @option{-e} change to require it to be syntactic unit.
-
-FIXME: Update doc earlier in this book and change the corresponding code.
+The use of @samp{@@namespace} has no influence upon the order of execution
+of @code{BEGIN}, @code{BEGINFILE}, @code{END}, and @code{ENDFILE} rules.
@node Namespace Example
@section Namespace Example
@@ -26748,11 +26763,11 @@ function Init( oldfs, oldrs, olddol0, pwcat,
using_fw, using_fpat)
RS = "\n"
pwcat = _pw_awklib "pwcat"
- while ((pwcat | getline) > 0) {
+ while ((pwcat | getline) > 0) @{
Byname[$1] = $0
Byuid[$3] = $0
Bycount[++_pw_total] = $0
- }
+ @}
close(pwcat)
Count = 0
Inited = 1
@@ -26820,7 +26835,10 @@ function endpwent()
Other notes for reviewers:
address@hidden
address@hidden @asis
address@hidden @code{SYMTAB}, @code{FUNCTAB} and @code{PROCINFO["identifiers"]}
+The subscripts are all fully qualified names.
+
@item Profiler:
When profiling, we can add an @code{Op_Namespace} to the start of
each rule. If it has changed since the previous one, output an
@@ -26830,10 +26848,44 @@ For all @samp{awk.XXX} if @samp{XXX} is all
uppercase, strip
off the @samp{awk} part.
@item Debugger:
-Simply prints fully qualified names all the time. Maybe allow a
+Simply print fully qualified names all the time. Maybe allow a
@samp{namespace @var{xxx}} command in the debugger to set the
namespace and it will use that to create fully qualified names?
Have to be careful about all uppercase names though.
+
address@hidden How does this affect indirect calls?
+The current namespace is a parse time thing, not a dynamic
+thing, so for indirect calls to work, use something like:
+
address@hidden
+@@namespace "foo"
+
+function bar() @{ @dots{} @}
+
address@hidden
+ @dots{}
+ x = "foo.bar"
+ @dots{}
+ @@x()
address@hidden
address@hidden example
+
address@hidden
+This is particularly true if @code{x} is passed as a ``function pointer''
+to another function in another namespace for that function to call
+through it.
+
address@hidden How does this affect @code{@@include}?
+Basically @code{@@include} should push and pop the namespace. Each
@code{@@include}
+saves the current namespace and starts over with namespace @samp{awk} until
+an @code{@@namespace} is seen.
+
address@hidden Extension functions
+Revise the current macros to pass @code{"awk"} as the namespace
+argument and add new macros with @samp{_ns} or some such in the name that
+pass the namespace of the extension. This preserves backwards
+compatibility at the source level while providing access to namespaces
+as needed.
@end table
@node Advanced Features
diff --git a/test/ChangeLog b/test/ChangeLog
index 0d8978f..50d12e1 100644
--- a/test/ChangeLog
+++ b/test/ChangeLog
@@ -1,3 +1,7 @@
+2017-05-30 Arnold D. Robbins <address@hidden>
+
+ * sourceplit.ok: Revise to match changed code.
+
2017-05-24 Andrew J. Schorr <address@hidden>
* fwtest8.ok: Fix field number in error message, thanks to a bug
diff --git a/test/sourcesplit.ok b/test/sourcesplit.ok
index 7ed6ff8..c883f51 100644
--- a/test/sourcesplit.ok
+++ b/test/sourcesplit.ok
@@ -1 +1,3 @@
-5
+gawk: cmd. line:1: BEGIN { a = 5;
+gawk: cmd. line:1: ^ unexpected newline or end of string
+EXIT CODE: 1
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=4f5ceec8298ddaaf5f9140595a86560dde4d04ce
commit 4f5ceec8298ddaaf5f9140595a86560dde4d04ce
Author: Arnold D. Robbins <address@hidden>
Date: Tue May 30 10:58:37 2017 +0300
Initial doc on namespaces.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 0a20506..2efa50b 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,10 @@
2017-05-30 Arnold D. Robbins <address@hidden>
+ * gawktexi.in: Initial doc on namespaces. Serves as a design
+ right now.
+
+2017-05-30 Arnold D. Robbins <address@hidden>
+
* gawktexi.in: Document PROCINFO["argv"].
2017-05-29 Arnold D. Robbins <address@hidden>
diff --git a/doc/gawk.info b/doc/gawk.info
index 821660c..66998ed 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -17030,7 +17030,7 @@ File: gawk.info, Node: Library Exercises, Prev:
Library Functions Summary, Up
an intervening value in 'ARGV' is a variable assignment.
-File: gawk.info, Node: Sample Programs, Next: Advanced Features, Prev:
Library Functions, Up: Top
+File: gawk.info, Node: Sample Programs, Next: Namespaces, Prev: Library
Functions, Up: Top
11 Practical 'awk' Programs
***************************
@@ -19733,9 +19733,239 @@ File: gawk.info, Node: Programs Exercises, Prev:
Programs Summary, Up: Sample
machine' into Google.
-File: gawk.info, Node: Advanced Features, Next: Internationalization, Prev:
Sample Programs, Up: Top
+File: gawk.info, Node: Namespaces, Next: Advanced Features, Prev: Sample
Programs, Up: Top
-12 Advanced Features of 'gawk'
+12 Namespaces in 'gawk'
+***********************
+
+This major node describes a feature that is specific to 'gawk'.
+
+* Menu:
+
+
+File: gawk.info, Node: Global Namespace, Next: Qualified Names, Up:
Namespaces
+
+12.1 Standard 'awk''s Single Namespace
+======================================
+
+In standard 'awk', there is a single, global, "namespace". This means
+that _all_ function names and global variable names must be unique. Two
+different 'awk' source files cannot both define a function named
+'sort()', for example.
+
+ This situation is okay when programs are small, say a few hundred
+lines, or even a few thousand, but it prevents the development of
+reusable libraries of 'awk' functions, and can inadvertently cause
+independently-developed library files to accidentally step on each
+other's "private" global variables (*note Library Names::).
+
+ Most other programming languages solve this issue by providing some
+kind of namespace control: a way to say "this function is in namespace
+X, and that function is in namespace Y." (Of course, there is then
+still a single namespace for the namespaces, but the hope is that there
+are much fewer namespaces in use by any given program, and thus much
+less chance for collisions.)
+
+ Starting with version *FIXME* 5.0, 'gawk' provides a mechanism to put
+functions and global variables into different namespaces.
+
+
+File: gawk.info, Node: Qualified Names, Next: Default Namespace, Prev:
Global Namespace, Up: Namespaces
+
+12.2 Qualified Names
+====================
+
+A "qualified name" is an identifier that includes a namespace name. For
+example, one might have a function named 'posix.getpid()'. Here, the
+namespace is 'posix' and the function name within the namespace is
+'getpid()'. The namespace and variable or function name are separated
+by a period. Only one period is allowed in a qualified name.
+
+ You must use fully qualified names from one namespace to access
+variables in another. This is especially important when using variable
+names to index the special 'SYMTAB' array.
+
+
+File: gawk.info, Node: Default Namespace, Next: Changing The Namespace,
Prev: Qualified Names, Up: Namespaces
+
+12.3 The Default Namespace
+==========================
+
+The default namespace, not surprisingly, is 'awk'. All of the
+predefined 'awk' and 'gawk' variables are in this namespace, and thus
+have qualified names like 'awk.ARGC', 'awk.NF', and so on.
+
+ Furthermore, even when you have changed the namespace for your
+current source file (*note Changing The Namespace::), 'gawk' forces
+unqualified identifiers whose names are all uppercase letters to be in
+the 'awk' namespace. This makes it possible for you to easily reference
+'gawk''s global variables from different namespaces.
+
+
+File: gawk.info, Node: Changing The Namespace, Next: Namespace Example,
Prev: Default Namespace, Up: Namespaces
+
+12.4 Changing The Namespace
+===========================
+
+In order to set the current namespace, use an '@namespace' directive at
+the top level of your program:
+
+ @namespace "passwd"
+
+ BEGIN { }
+ ...
+
+ After this directive, all simple non-uppercase identifiers are placed
+into the 'passwd' namespace.
+
+ You can change the namespace multiple times within a single source
+file, although this is likely to become confusing if you do it a lot.
+
+ NOTE: The namespace concept is one handled while your program is
+ being parsed by 'gawk'. There is no concept of a "current"
+ namespace during runtime. Be sure you understand the distinction.
+
+ Each source file for '-i' and '-f' starts out with an implicit '
+"awk"'.
+
+ Similarly, each chunk of command-line code with '-e' has such an
+implicit statement.
+
+ FIXME: The semantics of '-e' change to require it to be syntactic
+unit.
+
+ FIXME: Update doc earlier in this book and change the corresponding
+code.
+
+
+File: gawk.info, Node: Namespace Example, Next: Namespace Misc, Prev:
Changing The Namespace, Up: Namespaces
+
+12.5 Namespace Example
+======================
+
+ # FIXME: fix this up for real, dates etc
+ #
+ # passwd.awk --- access password file information
+ #
+ # Arnold Robbins, address@hidden, Public Domain
+ # May 1993
+ # Revised October 2000
+ # Revised December 2010
+ #
+ # Reworked for namespaces May 2017
+
+ @namespace "passwd"
+
+ BEGIN {
+ # tailor this to suit your system
+ Awklib = "/usr/local/libexec/awk/"
+ }
+
+ function Init( oldfs, oldrs, olddol0, pwcat, using_fw, using_fpat)
+ {
+ if (Inited)
+ return
+
+ oldfs = FS
+ oldrs = RS
+ olddol0 = $0
+ using_fw = (PROCINFO["FS"] == "FIELDWIDTHS")
+ using_fpat = (PROCINFO["FS"] == "FPAT")
+ FS = ":"
+ RS = "\n"
+
+ pwcat = _pw_awklib "pwcat"
+ while ((pwcat | getline) > 0)
+ Byname[$1] = $0
+ Byuid[$3] = $0
+ Bycount[++_pw_total] = $0
+
+ close(pwcat)
+ Count = 0
+ Inited = 1
+ FS = oldfs
+ if (using_fw)
+ FIELDWIDTHS = FIELDWIDTHS
+ else if (using_fpat)
+ FPAT = FPAT
+ RS = oldrs
+ $0 = olddol0
+ }
+
+ function Getpwnam(name)
+ {
+ Init()
+ return Byname[name]
+ }
+
+ function Getpwuid(uid)
+ {
+ Init()
+ return Byuid[uid]
+ }
+
+ function Getpwent()
+ {
+ Init()
+ if (Count < Total)
+ return Bycount[++Count]
+ return ""
+ }
+
+ function Endpwent()
+ {
+ Count = 0
+ }
+
+ # Compatibility:
+
+ @namespace "awk"
+
+ function getpwnam(name)
+ {
+ return passwd.Getpwnam(name)
+ }
+
+ function getpwuid(uid)
+ {
+ return passwd.Getpwuid(uid)
+ }
+
+ function getpwent()
+ {
+ return passwd.Getpwent()
+ }
+
+ function endpwent()
+ {
+ passwd.Endpwent()
+ }
+
+
+File: gawk.info, Node: Namespace Misc, Prev: Namespace Example, Up:
Namespaces
+
+12.6 Miscellaneous Notes
+========================
+
+Other notes for reviewers:
+
+Profiler:
+ When profiling, we can add an 'Op_Namespace' to the start of each
+ rule. If it has changed since the previous one, output an
+ '@namespace' statement. For each identifier, if it starts with the
+ current namespace, output only the simple part. For all 'awk.XXX'
+ if 'XXX' is all uppercase, strip off the 'awk' part.
+
+Debugger:
+ Simply prints fully qualified names all the time. Maybe allow a
+ 'namespace XXX' command in the debugger to set the namespace and it
+ will use that to create fully qualified names? Have to be careful
+ about all uppercase names though.
+
+
+File: gawk.info, Node: Advanced Features, Next: Internationalization, Prev:
Namespaces, Up: Top
+
+13 Advanced Features of 'gawk'
******************************
Write documentation as if whoever reads it is a violent psychopath
@@ -19781,7 +20011,7 @@ their own:
File: gawk.info, Node: Nondecimal Data, Next: Array Sorting, Up: Advanced
Features
-12.1 Allowing Nondecimal Input Data
+13.1 Allowing Nondecimal Input Data
===================================
If you run 'gawk' with the '--non-decimal-data' option, you can have
@@ -19824,7 +20054,7 @@ request it.
File: gawk.info, Node: Array Sorting, Next: Two-way I/O, Prev: Nondecimal
Data, Up: Advanced Features
-12.2 Controlling Array Traversal and Array Sorting
+13.2 Controlling Array Traversal and Array Sorting
==================================================
'gawk' lets you control the order in which a 'for (INDX in ARRAY)' loop
@@ -19843,7 +20073,7 @@ to order the elements during sorting.
File: gawk.info, Node: Controlling Array Traversal, Next: Array Sorting
Functions, Up: Array Sorting
-12.2.1 Controlling Array Traversal
+13.2.1 Controlling Array Traversal
----------------------------------
By default, the order in which a 'for (INDX in ARRAY)' loop scans an
@@ -20081,7 +20311,7 @@ character, which cannot be part of an identifier.
File: gawk.info, Node: Array Sorting Functions, Prev: Controlling Array
Traversal, Up: Array Sorting
-12.2.2 Sorting Array Values and Indices with 'gawk'
+13.2.2 Sorting Array Values and Indices with 'gawk'
---------------------------------------------------
In most 'awk' implementations, sorting an array requires writing a
@@ -20221,7 +20451,7 @@ POSIX-compatibility mode, and because 'asort()' and
'asorti()' are
File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Array
Sorting, Up: Advanced Features
-12.3 Two-Way Communications with Another Process
+13.3 Two-Way Communications with Another Process
================================================
It is often useful to be able to send data to a separate program for
@@ -20376,7 +20606,7 @@ in Bash.
File: gawk.info, Node: TCP/IP Networking, Next: Profiling, Prev: Two-way
I/O, Up: Advanced Features
-12.4 Using 'gawk' for Network Programming
+13.4 Using 'gawk' for Network Programming
=========================================
'EMRED':
@@ -20456,7 +20686,7 @@ complete introduction and discussion, as well as
extensive examples.
File: gawk.info, Node: Profiling, Next: Advanced Features Summary, Prev:
TCP/IP Networking, Up: Advanced Features
-12.5 Profiling Your 'awk' Programs
+13.5 Profiling Your 'awk' Programs
==================================
You may produce execution traces of your 'awk' programs. This is done
@@ -20715,7 +20945,7 @@ improve this in a subsequent release.
File: gawk.info, Node: Advanced Features Summary, Prev: Profiling, Up:
Advanced Features
-12.6 Summary
+13.6 Summary
============
* The '--non-decimal-data' option causes 'gawk' to treat octal- and
@@ -20756,7 +20986,7 @@ File: gawk.info, Node: Advanced Features Summary,
Prev: Profiling, Up: Advanc
File: gawk.info, Node: Internationalization, Next: Debugger, Prev: Advanced
Features, Up: Top
-13 Internationalization with 'gawk'
+14 Internationalization with 'gawk'
***********************************
Once upon a time, computer makers wrote software that worked only in
@@ -20788,7 +21018,7 @@ requirement.
File: gawk.info, Node: I18N and L10N, Next: Explaining gettext, Up:
Internationalization
-13.1 Internationalization and Localization
+14.1 Internationalization and Localization
==========================================
"Internationalization" means writing (or modifying) a program once, in
@@ -20803,7 +21033,7 @@ read.
File: gawk.info, Node: Explaining gettext, Next: Programmer i18n, Prev:
I18N and L10N, Up: Internationalization
-13.2 GNU 'gettext'
+14.2 GNU 'gettext'
==================
'gawk' uses GNU 'gettext' to provide its internationalization features.
@@ -20950,7 +21180,7 @@ the decimal point, while many Europeans do exactly the
opposite:
File: gawk.info, Node: Programmer i18n, Next: Translator i18n, Prev:
Explaining gettext, Up: Internationalization
-13.3 Internationalizing 'awk' Programs
+14.3 Internationalizing 'awk' Programs
======================================
'gawk' provides the following variables for internationalization:
@@ -21075,7 +21305,7 @@ create and use translations from 'awk'.
File: gawk.info, Node: Translator i18n, Next: I18N Example, Prev:
Programmer i18n, Up: Internationalization
-13.4 Translating 'awk' Programs
+14.4 Translating 'awk' Programs
===============================
Once a program's translatable strings have been marked, they must be
@@ -21096,7 +21326,7 @@ for 'printf' arguments at runtime is covered.
File: gawk.info, Node: String Extraction, Next: Printf Ordering, Up:
Translator i18n
-13.4.1 Extracting Marked Strings
+14.4.1 Extracting Marked Strings
--------------------------------
Once your 'awk' program is working, and all the strings have been marked
@@ -21125,7 +21355,7 @@ for 'guide'.
File: gawk.info, Node: Printf Ordering, Next: I18N Portability, Prev:
String Extraction, Up: Translator i18n
-13.4.2 Rearranging 'printf' Arguments
+14.4.2 Rearranging 'printf' Arguments
-------------------------------------
Format strings for 'printf' and 'sprintf()' (*note Printf::) present a
@@ -21202,7 +21432,7 @@ which the program is first written.
File: gawk.info, Node: I18N Portability, Prev: Printf Ordering, Up:
Translator i18n
-13.4.3 'awk' Portability Issues
+14.4.3 'awk' Portability Issues
-------------------------------
'gawk''s internationalization features were purposely chosen to have as
@@ -21267,7 +21497,7 @@ actually almost portable, requiring very little change:
File: gawk.info, Node: I18N Example, Next: Gawk I18N, Prev: Translator
i18n, Up: Internationalization
-13.5 A Simple Internationalization Example
+14.5 A Simple Internationalization Example
==========================================
Now let's look at a step-by-step example of how to internationalize and
@@ -21360,7 +21590,7 @@ and 'bindtextdomain()' (*note I18N Portability::) are
in a file named
File: gawk.info, Node: Gawk I18N, Next: I18N Summary, Prev: I18N Example,
Up: Internationalization
-13.6 'gawk' Can Speak Your Language
+14.6 'gawk' Can Speak Your Language
===================================
'gawk' itself has been internationalized using the GNU 'gettext'
@@ -21375,7 +21605,7 @@ usage messages, warnings, and fatal errors in the local
language.
File: gawk.info, Node: I18N Summary, Prev: Gawk I18N, Up:
Internationalization
-13.7 Summary
+14.7 Summary
============
* Internationalization means writing a program such that it can use
@@ -21407,7 +21637,7 @@ File: gawk.info, Node: I18N Summary, Prev: Gawk I18N,
Up: Internationalizatio
File: gawk.info, Node: Debugger, Next: Arbitrary Precision Arithmetic,
Prev: Internationalization, Up: Top
-14 Debugging 'awk' Programs
+15 Debugging 'awk' Programs
***************************
It would be nice if computer programs worked perfectly the first time
@@ -21432,7 +21662,7 @@ is easy.
File: gawk.info, Node: Debugging, Next: Sample Debugging Session, Up:
Debugger
-14.1 Introduction to the 'gawk' Debugger
+15.1 Introduction to the 'gawk' Debugger
========================================
This minor node introduces debugging in general and begins the
@@ -21447,7 +21677,7 @@ discussion of debugging in 'gawk'.
File: gawk.info, Node: Debugging Concepts, Next: Debugging Terms, Up:
Debugging
-14.1.1 Debugging in General
+15.1.1 Debugging in General
---------------------------
(If you have used debuggers in other languages, you may want to skip
@@ -21486,7 +21716,7 @@ functional program that you or someone else wrote).
File: gawk.info, Node: Debugging Terms, Next: Awk Debugging, Prev:
Debugging Concepts, Up: Debugging
-14.1.2 Debugging Concepts
+15.1.2 Debugging Concepts
-------------------------
Before diving in to the details, we need to introduce several important
@@ -21538,7 +21768,7 @@ defines terms used throughout the rest of this major
node:
File: gawk.info, Node: Awk Debugging, Prev: Debugging Terms, Up: Debugging
-14.1.3 'awk' Debugging
+15.1.3 'awk' Debugging
----------------------
Debugging an 'awk' program has some specific aspects that are not shared
@@ -21560,7 +21790,7 @@ commands.
File: gawk.info, Node: Sample Debugging Session, Next: List of Debugger
Commands, Prev: Debugging, Up: Debugger
-14.2 Sample 'gawk' Debugging Session
+15.2 Sample 'gawk' Debugging Session
====================================
In order to illustrate the use of 'gawk' as a debugger, let's look at a
@@ -21576,7 +21806,7 @@ example.
File: gawk.info, Node: Debugger Invocation, Next: Finding The Bug, Up:
Sample Debugging Session
-14.2.1 How to Start the Debugger
+15.2.1 How to Start the Debugger
--------------------------------
Starting the debugger is almost exactly like running 'gawk' normally,
@@ -21608,7 +21838,7 @@ code has been executed.
File: gawk.info, Node: Finding The Bug, Prev: Debugger Invocation, Up:
Sample Debugging Session
-14.2.2 Finding the Bug
+15.2.2 Finding the Bug
----------------------
Let's say that we are having a problem using (a faulty version of)
@@ -21802,7 +22032,7 @@ and problem solved!
File: gawk.info, Node: List of Debugger Commands, Next: Readline Support,
Prev: Sample Debugging Session, Up: Debugger
-14.3 Main Debugger Commands
+15.3 Main Debugger Commands
===========================
The 'gawk' debugger command set can be divided into the following
@@ -21841,7 +22071,7 @@ just by hitting 'Enter'. This works for the commands
'list', 'next',
File: gawk.info, Node: Breakpoint Control, Next: Debugger Execution Control,
Up: List of Debugger Commands
-14.3.1 Control of Breakpoints
+15.3.1 Control of Breakpoints
-----------------------------
As we saw earlier, the first thing you probably want to do in a
@@ -21936,7 +22166,7 @@ The commands for controlling breakpoints are:
File: gawk.info, Node: Debugger Execution Control, Next: Viewing And
Changing Data, Prev: Breakpoint Control, Up: List of Debugger Commands
-14.3.2 Control of Execution
+15.3.2 Control of Execution
---------------------------
Now that your breakpoints are ready, you can start running the program
@@ -22025,7 +22255,7 @@ execution of the program than we saw in our earlier
example:
File: gawk.info, Node: Viewing And Changing Data, Next: Execution Stack,
Prev: Debugger Execution Control, Up: List of Debugger Commands
-14.3.3 Viewing and Changing Data
+15.3.3 Viewing and Changing Data
--------------------------------
The commands for viewing and changing variables inside of 'gawk' are:
@@ -22112,7 +22342,7 @@ AWK STATEMENTS
File: gawk.info, Node: Execution Stack, Next: Debugger Info, Prev: Viewing
And Changing Data, Up: List of Debugger Commands
-14.3.4 Working with the Stack
+15.3.4 Working with the Stack
-----------------------------
Whenever you run a program that contains any function calls, 'gawk'
@@ -22152,7 +22382,7 @@ are:
File: gawk.info, Node: Debugger Info, Next: Miscellaneous Debugger Commands,
Prev: Execution Stack, Up: List of Debugger Commands
-14.3.5 Obtaining Information About the Program and the Debugger State
+15.3.5 Obtaining Information About the Program and the Debugger State
---------------------------------------------------------------------
Besides looking at the values of variables, there is often a need to get
@@ -22262,7 +22492,7 @@ from a file. The commands are:
File: gawk.info, Node: Miscellaneous Debugger Commands, Prev: Debugger Info,
Up: List of Debugger Commands
-14.3.6 Miscellaneous Commands
+15.3.6 Miscellaneous Commands
-----------------------------
There are a few more commands that do not fit into the previous
@@ -22381,7 +22611,7 @@ categories, as follows:
File: gawk.info, Node: Readline Support, Next: Limitations, Prev: List of
Debugger Commands, Up: Debugger
-14.4 Readline Support
+15.4 Readline Support
=====================
If 'gawk' is compiled with the GNU Readline library
@@ -22408,7 +22638,7 @@ Variable name completion
File: gawk.info, Node: Limitations, Next: Debugging Summary, Prev: Readline
Support, Up: Debugger
-14.5 Limitations
+15.5 Limitations
================
We hope you find the 'gawk' debugger useful and enjoyable to work with,
@@ -22451,7 +22681,7 @@ some limitations. A few that it's worth being aware of
are:
File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger
-14.6 Summary
+15.6 Summary
============
* Programs rarely work correctly the first time. Finding bugs is
@@ -22482,7 +22712,7 @@ File: gawk.info, Node: Debugging Summary, Prev:
Limitations, Up: Debugger
File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic
Extensions, Prev: Debugger, Up: Top
-15 Arithmetic and Arbitrary-Precision Arithmetic with 'gawk'
+16 Arithmetic and Arbitrary-Precision Arithmetic with 'gawk'
************************************************************
This major node introduces some basic concepts relating to how computers
@@ -22513,7 +22743,7 @@ are not quite in agreement.
File: gawk.info, Node: Computer Arithmetic, Next: Math Definitions, Up:
Arbitrary Precision Arithmetic
-15.1 A General Description of Computer Arithmetic
+16.1 A General Description of Computer Arithmetic
=================================================
Until now, we have worked with data as either numbers or strings.
@@ -22582,7 +22812,7 @@ ranges. Integer values are usually either 32 or 64
bits in size.
Single-precision floating-point values occupy 32 bits, whereas
double-precision floating-point values occupy 64 bits. Floating-point
values are always signed. The possible ranges of values are shown in
-*note Table 15.1: table-numeric-ranges.
+*note Table 16.1: table-numeric-ranges.
Numeric representation Minimum value Maximum value
---------------------------------------------------------------------------
@@ -22599,7 +22829,7 @@ Double-precision 2.225074e-308
1.797693e308
floating point
(approximate)
-Table 15.1: Value ranges for different numeric representations
+Table 16.1: Value ranges for different numeric representations
---------- Footnotes ----------
@@ -22608,7 +22838,7 @@ Table 15.1: Value ranges for different numeric
representations
File: gawk.info, Node: Math Definitions, Next: MPFR features, Prev:
Computer Arithmetic, Up: Arbitrary Precision Arithmetic
-15.2 Other Stuff to Know
+16.2 Other Stuff to Know
========================
The rest of this major node uses a number of terms. Here are some
@@ -22688,7 +22918,7 @@ IEEE 754 types are 32-bit single precision, 64-bit
double precision, and
precision formats to allow greater precisions and larger exponent
ranges. ('awk' uses only the 64-bit double-precision format.)
- *note Table 15.2: table-ieee-formats. lists the precision and
+ *note Table 16.2: table-ieee-formats. lists the precision and
exponent field values for the basic IEEE 754 binary formats.
Name Total bits Precision Minimum Maximum
@@ -22698,7 +22928,7 @@ Single 32 24 -126
+127
Double 64 53 -1022 +1023
Quadruple 128 113 -16382 +16383
-Table 15.2: Basic IEEE format values
+Table 16.2: Basic IEEE format values
NOTE: The precision numbers include the implied leading one that
gives them one extra bit of significand.
@@ -22711,7 +22941,7 @@ paraphrased, and for the examples.
File: gawk.info, Node: MPFR features, Next: FP Math Caution, Prev: Math
Definitions, Up: Arbitrary Precision Arithmetic
-15.3 Arbitrary-Precision Arithmetic Features in 'gawk'
+16.3 Arbitrary-Precision Arithmetic Features in 'gawk'
======================================================
By default, 'gawk' uses the double-precision floating-point values
@@ -22749,7 +22979,7 @@ information.
File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers,
Prev: MPFR features, Up: Arbitrary Precision Arithmetic
-15.4 Floating-Point Arithmetic: Caveat Emptor!
+16.4 Floating-Point Arithmetic: Caveat Emptor!
==============================================
Math class is tough!
@@ -22783,7 +23013,7 @@ in computer science.
File: gawk.info, Node: Inexactness of computations, Next: Getting Accuracy,
Up: FP Math Caution
-15.4.1 Floating-Point Arithmetic Is Not Exact
+16.4.1 Floating-Point Arithmetic Is Not Exact
---------------------------------------------
Binary floating-point representations and arithmetic are inexact.
@@ -22804,7 +23034,7 @@ be sure of the number of significant decimal places in
the final result.
File: gawk.info, Node: Inexact representation, Next: Comparing FP Values,
Up: Inexactness of computations
-15.4.1.1 Many Numbers Cannot Be Represented Exactly
+16.4.1.1 Many Numbers Cannot Be Represented Exactly
...................................................
So, before you start to write any code, you should think about what you
@@ -22835,7 +23065,7 @@ previous example, produces an output identical to the
input.
File: gawk.info, Node: Comparing FP Values, Next: Errors accumulate, Prev:
Inexact representation, Up: Inexactness of computations
-15.4.1.2 Be Careful Comparing Values
+16.4.1.2 Be Careful Comparing Values
....................................
Because the underlying representation can be a little bit off from the
@@ -22864,7 +23094,7 @@ defined elsewhere in your program.)
File: gawk.info, Node: Errors accumulate, Prev: Comparing FP Values, Up:
Inexactness of computations
-15.4.1.3 Errors Accumulate
+16.4.1.3 Errors Accumulate
..........................
The loss of accuracy during a single computation with floating-point
@@ -22912,7 +23142,7 @@ representations yield an unexpected result:
File: gawk.info, Node: Getting Accuracy, Next: Try To Round, Prev:
Inexactness of computations, Up: FP Math Caution
-15.4.2 Getting the Accuracy You Need
+16.4.2 Getting the Accuracy You Need
------------------------------------
Can arbitrary-precision arithmetic give exact results? There are no
@@ -22973,7 +23203,7 @@ hand is often the correct approach in such situations.
File: gawk.info, Node: Try To Round, Next: Setting precision, Prev: Getting
Accuracy, Up: FP Math Caution
-15.4.3 Try a Few Extra Bits of Precision and Rounding
+16.4.3 Try a Few Extra Bits of Precision and Rounding
-----------------------------------------------------
Instead of arbitrary-precision floating-point arithmetic, often all you
@@ -23000,7 +23230,7 @@ iterations:
File: gawk.info, Node: Setting precision, Next: Setting the rounding mode,
Prev: Try To Round, Up: FP Math Caution
-15.4.4 Setting the Precision
+16.4.4 Setting the Precision
----------------------------
'gawk' uses a global working precision; it does not keep track of the
@@ -23009,7 +23239,7 @@ operation or calling a built-in function rounds the
result to the
current working precision. The default working precision is 53 bits,
which you can modify using the predefined variable 'PREC'. You can also
set the value to one of the predefined case-insensitive strings shown in
-*note Table 15.3: table-predefined-precision-strings, to emulate an IEEE
+*note Table 16.3: table-predefined-precision-strings, to emulate an IEEE
754 binary format.
'PREC' IEEE 754 binary format
@@ -23020,7 +23250,7 @@ set the value to one of the predefined case-insensitive
strings shown in
'"quad"' Basic 128-bit quadruple precision
'"oct"' 256-bit octuple precision
-Table 15.3: Predefined precision strings for 'PREC'
+Table 16.3: Predefined precision strings for 'PREC'
The following example illustrates the effects of changing precision
on arithmetic operations:
@@ -23057,12 +23287,12 @@ on arithmetic operations:
File: gawk.info, Node: Setting the rounding mode, Prev: Setting precision,
Up: FP Math Caution
-15.4.5 Setting the Rounding Mode
+16.4.5 Setting the Rounding Mode
--------------------------------
The 'ROUNDMODE' variable provides program-level control over the
rounding mode. The correspondence between 'ROUNDMODE' and the IEEE
-rounding modes is shown in *note Table 15.4: table-gawk-rounding-modes.
+rounding modes is shown in *note Table 16.4: table-gawk-rounding-modes.
Rounding mode IEEE name 'ROUNDMODE'
---------------------------------------------------------------------------
@@ -23073,10 +23303,10 @@ Round toward zero 'roundTowardZero'
'"Z"' or '"z"'
Round to nearest, ties away 'roundTiesToAway' '"A"' or '"a"'
from zero
-Table 15.4: 'gawk' rounding modes
+Table 16.4: 'gawk' rounding modes
'ROUNDMODE' has the default value '"N"', which selects the IEEE 754
-rounding mode 'roundTiesToEven'. In *note Table 15.4:
+rounding mode 'roundTiesToEven'. In *note Table 16.4:
table-gawk-rounding-modes, the value '"A"' selects 'roundTiesToAway'.
This is only available if your version of the MPFR library supports it;
otherwise, setting 'ROUNDMODE' to '"A"' has no effect.
@@ -23148,7 +23378,7 @@ round halfway cases for 'printf'.
File: gawk.info, Node: Arbitrary Precision Integers, Next: Checking for
MPFR, Prev: FP Math Caution, Up: Arbitrary Precision Arithmetic
-15.5 Arbitrary-Precision Integer Arithmetic with 'gawk'
+16.5 Arbitrary-Precision Integer Arithmetic with 'gawk'
=======================================================
When given the '-M' option, 'gawk' performs all integer arithmetic using
@@ -23278,7 +23508,7 @@ Wolfram Web Resource
File: gawk.info, Node: Checking for MPFR, Next: POSIX Floating Point
Problems, Prev: Arbitrary Precision Integers, Up: Arbitrary Precision
Arithmetic
-15.6 How To Check If MPFR Is Available
+16.6 How To Check If MPFR Is Available
======================================
Occasionally, you might like to be able to check if 'gawk' was invoked
@@ -23315,7 +23545,7 @@ arbitrary-precision arithmetic is available:
File: gawk.info, Node: POSIX Floating Point Problems, Next: Floating point
summary, Prev: Checking for MPFR, Up: Arbitrary Precision Arithmetic
-15.7 Standards Versus Existing Practice
+16.7 Standards Versus Existing Practice
=======================================
Historically, 'awk' has converted any nonnumeric-looking string to the
@@ -23402,7 +23632,7 @@ and infinity values. The solution implemented in
'gawk' is as follows:
File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point
Problems, Up: Arbitrary Precision Arithmetic
-15.8 Summary
+16.8 Summary
============
* Most computer arithmetic is done using either integers or
@@ -23455,7 +23685,7 @@ File: gawk.info, Node: Floating point summary, Prev:
POSIX Floating Point Prob
File: gawk.info, Node: Dynamic Extensions, Next: Language History, Prev:
Arbitrary Precision Arithmetic, Up: Top
-16 Writing Extensions for 'gawk'
+17 Writing Extensions for 'gawk'
********************************
It is possible to add new functions written in C or C++ to 'gawk' using
@@ -23489,7 +23719,7 @@ sample extensions are automatically built and installed
when 'gawk' is.
File: gawk.info, Node: Extension Intro, Next: Plugin License, Up: Dynamic
Extensions
-16.1 Introduction
+17.1 Introduction
=================
An "extension" (sometimes called a "plug-in") is a piece of external
@@ -23516,7 +23746,7 @@ and design.
File: gawk.info, Node: Plugin License, Next: Extension Mechanism Outline,
Prev: Extension Intro, Up: Dynamic Extensions
-16.2 Extension Licensing
+17.2 Extension Licensing
========================
Every dynamic extension must be distributed under a license that is
@@ -23536,12 +23766,12 @@ symbol exists in the global scope. Something like
this is enough:
File: gawk.info, Node: Extension Mechanism Outline, Next: Extension API
Description, Prev: Plugin License, Up: Dynamic Extensions
-16.3 How It Works at a High Level
+17.3 How It Works at a High Level
=================================
Communication between 'gawk' and an extension is two-way. First, when
an extension is loaded, 'gawk' passes it a pointer to a 'struct' whose
-fields are function pointers. This is shown in *note Figure 16.1:
+fields are function pointers. This is shown in *note Figure 17.1:
figure-load-extension.
[image src="api-figure1.png" alt="Loading the extension" text="
API
@@ -23569,12 +23799,12 @@ figure-load-extension.
gawk Main Program Address Space Extension" ]
-Figure 16.1: Loading the extension
+Figure 17.1: Loading the extension
The extension can call functions inside 'gawk' through these function
pointers, at runtime, without needing (link-time) access to 'gawk''s
symbols. One of these function pointers is to a function for
-"registering" new functions. This is shown in *note Figure 16.2:
+"registering" new functions. This is shown in *note Figure 17.2:
figure-register-new-function.
[image src="api-figure2.png" alt="Registering a new Function" text="
register_ext_func({ \"chdir\", do_chdir, 1 });
@@ -23590,13 +23820,13 @@ figure-register-new-function.
gawk Main Program Address Space Extension" ]
-Figure 16.2: Registering a new function
+Figure 17.2: Registering a new function
In the other direction, the extension registers its new functions
with 'gawk' by passing function pointers to the functions that provide
the new feature ('do_chdir()', for example). 'gawk' associates the
function pointer with a name and can then call it, using a defined
-calling convention. This is shown in *note Figure 16.3:
+calling convention. This is shown in *note Figure 17.3:
figure-call-new-function.
[image src="api-figure3.png" alt="Calling the new function" text=" BEGIN {
@@ -23613,7 +23843,7 @@ figure-call-new-function.
gawk Main Program Address Space Extension" ]
-Figure 16.3: Calling the new function
+Figure 17.3: Calling the new function
The 'do_XXX()' function, in turn, then uses the function pointers in
the API 'struct' to do its work, such as updating variables or arrays,
@@ -23645,7 +23875,7 @@ Example::) and also in the 'testext.c' code for testing
the APIs.
File: gawk.info, Node: Extension API Description, Next: Finding Extensions,
Prev: Extension Mechanism Outline, Up: Dynamic Extensions
-16.4 API Description
+17.4 API Description
====================
C or C++ code for an extension must include the header file 'gawkapi.h',
@@ -23677,7 +23907,7 @@ API in detail.
File: gawk.info, Node: Extension API Functions Introduction, Next: General
Data Types, Up: Extension API Description
-16.4.1 Introduction
+17.4.1 Introduction
-------------------
Access to facilities within 'gawk' is achieved by calling through
@@ -23807,7 +24037,7 @@ macros as if they were functions.
File: gawk.info, Node: General Data Types, Next: Memory Allocation
Functions, Prev: Extension API Functions Introduction, Up: Extension API
Description
-16.4.2 General-Purpose Data Types
+17.4.2 General-Purpose Data Types
---------------------------------
I have a true love/hate relationship with unions.
@@ -23978,7 +24208,7 @@ See also the entry for "Cookie" in the *note Glossary::.
File: gawk.info, Node: Memory Allocation Functions, Next: Constructor
Functions, Prev: General Data Types, Up: Extension API Description
-16.4.3 Memory Allocation Functions and Convenience Macros
+17.4.3 Memory Allocation Functions and Convenience Macros
---------------------------------------------------------
The API provides a number of "memory allocation" functions for
@@ -24054,7 +24284,7 @@ Unix-like systems as well.
File: gawk.info, Node: Constructor Functions, Next: Registration Functions,
Prev: Memory Allocation Functions, Up: Extension API Description
-16.4.4 Constructor Functions
+17.4.4 Constructor Functions
----------------------------
The API provides a number of "constructor" functions for creating string
@@ -24117,7 +24347,7 @@ code would use them:
File: gawk.info, Node: Registration Functions, Next: Printing Messages,
Prev: Constructor Functions, Up: Extension API Description
-16.4.5 Registration Functions
+17.4.5 Registration Functions
-----------------------------
This minor node describes the API functions for registering parts of
@@ -24135,7 +24365,7 @@ your extension with 'gawk'.
File: gawk.info, Node: Extension Functions, Next: Exit Callback Functions,
Up: Registration Functions
-16.4.5.1 Registering An Extension Function
+17.4.5.1 Registering An Extension Function
..........................................
Extension functions are described by the following record:
@@ -24248,7 +24478,7 @@ A minimum number of arguments is required, and no more
than a maximum is allowed
File: gawk.info, Node: Exit Callback Functions, Next: Extension Version
String, Prev: Extension Functions, Up: Registration Functions
-16.4.5.2 Registering An Exit Callback Function
+17.4.5.2 Registering An Exit Callback Function
..............................................
An "exit callback" function is a function that 'gawk' calls before it
@@ -24278,7 +24508,7 @@ order--that is, in the reverse order in which they are
registered with
File: gawk.info, Node: Extension Version String, Next: Input Parsers, Prev:
Exit Callback Functions, Up: Registration Functions
-16.4.5.3 Registering An Extension Version String
+17.4.5.3 Registering An Extension Version String
................................................
You can register a version string that indicates the name and version of
@@ -24295,7 +24525,7 @@ invoked with the '--version' option.
File: gawk.info, Node: Input Parsers, Next: Output Wrappers, Prev:
Extension Version String, Up: Registration Functions
-16.4.5.4 Customized Input Parsers
+17.4.5.4 Customized Input Parsers
.................................
By default, 'gawk' reads text files as its input. It uses the value of
@@ -24573,7 +24803,7 @@ example.
File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev:
Input Parsers, Up: Registration Functions
-16.4.5.5 Customized Output Wrappers
+17.4.5.5 Customized Output Wrappers
...................................
An "output wrapper" is the mirror image of an input parser. It allows
@@ -24679,7 +24909,7 @@ just use normally.
File: gawk.info, Node: Two-way processors, Prev: Output Wrappers, Up:
Registration Functions
-16.4.5.6 Customized Two-way Processors
+17.4.5.6 Customized Two-way Processors
......................................
A "two-way processor" combines an input parser and an output wrapper for
@@ -24733,7 +24963,7 @@ and 'XXX_take_control_of()'.
File: gawk.info, Node: Printing Messages, Next: Updating ERRNO, Prev:
Registration Functions, Up: Extension API Description
-16.4.6 Printing Messages
+17.4.6 Printing Messages
------------------------
You can print different kinds of warning messages from your extension,
@@ -24767,7 +24997,7 @@ the pity.
File: gawk.info, Node: Updating ERRNO, Next: Requesting Values, Prev:
Printing Messages, Up: Extension API Description
-16.4.7 Updating 'ERRNO'
+17.4.7 Updating 'ERRNO'
-----------------------
The following functions allow you to update the 'ERRNO' variable:
@@ -24788,7 +25018,7 @@ The following functions allow you to update the 'ERRNO'
variable:
File: gawk.info, Node: Requesting Values, Next: Accessing Parameters, Prev:
Updating ERRNO, Up: Extension API Description
-16.4.8 Requesting Values
+17.4.8 Requesting Values
------------------------
All of the functions that return values from 'gawk' work in the same
@@ -24798,7 +25028,7 @@ function returns true and fills in the 'awk_value_t'
result. Otherwise,
the function returns false, and the 'val_type' member indicates the type
of the actual value. You may then print an error message or reissue the
request for the actual value type, as appropriate. This behavior is
-summarized in *note Table 16.1: table-value-types-returned.
+summarized in *note Table 17.1: table-value-types-returned.
Type of Actual Value
--------------------------------------------------------------------------
@@ -24814,12 +25044,12 @@ Requested Array false false false
false Array false
Value false false false false false false
cookie
-Table 16.1: API value types returned
+Table 17.1: API value types returned
File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access,
Prev: Requesting Values, Up: Extension API Description
-16.4.9 Accessing and Updating Parameters
+17.4.9 Accessing and Updating Parameters
----------------------------------------
Two functions give you access to the arguments (parameters) passed to
@@ -24831,7 +25061,7 @@ your extension function. They are:
Fill in the 'awk_value_t' structure pointed to by 'result' with the
'count'th argument. Return true if the actual type matches
'wanted', and false otherwise. In the latter case,
- 'result->val_type' indicates the actual type (*note Table 16.1:
+ 'result->val_type' indicates the actual type (*note Table 17.1:
table-value-types-returned.). Counts are zero-based--the first
argument is numbered zero, the second one, and so on. 'wanted'
indicates the type of value expected.
@@ -24845,7 +25075,7 @@ your extension function. They are:
File: gawk.info, Node: Symbol Table Access, Next: Array Manipulation, Prev:
Accessing Parameters, Up: Extension API Description
-16.4.10 Symbol Table Access
+17.4.10 Symbol Table Access
---------------------------
Two sets of routines provide access to global variables, and one set
@@ -24860,7 +25090,7 @@ allows you to create and release cached values.
File: gawk.info, Node: Symbol table by name, Next: Symbol table by cookie,
Up: Symbol Table Access
-16.4.10.1 Variable Access and Update by Name
+17.4.10.1 Variable Access and Update by Name
............................................
The following routines provide the ability to access and update global
@@ -24877,7 +25107,7 @@ termed a "symbol table". The functions are as follows:
regular C string. 'wanted' indicates the type of value expected.
Return true if the actual type matches 'wanted', and false
otherwise. In the latter case, 'result->val_type' indicates the
- actual type (*note Table 16.1: table-value-types-returned.).
+ actual type (*note Table 17.1: table-value-types-returned.).
'awk_bool_t sym_update(const char *name, awk_value_t *value);'
Update the variable named by the string 'name', which is a regular
@@ -24896,7 +25126,7 @@ change any of those variables.
File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev:
Symbol table by name, Up: Symbol Table Access
-16.4.10.2 Variable Access and Update by Cookie
+17.4.10.2 Variable Access and Update by Cookie
..............................................
A "scalar cookie" is an opaque handle that provides access to a global
@@ -25010,7 +25240,7 @@ like this:
File: gawk.info, Node: Cached values, Prev: Symbol table by cookie, Up:
Symbol Table Access
-16.4.10.3 Creating and Using Cached Values
+17.4.10.3 Creating and Using Cached Values
..........................................
The routines in this minor node allow you to create and release cached
@@ -25107,7 +25337,7 @@ using 'release_value()'.
File: gawk.info, Node: Array Manipulation, Next: Redirection API, Prev:
Symbol Table Access, Up: Extension API Description
-16.4.11 Array Manipulation
+17.4.11 Array Manipulation
--------------------------
The primary data structure(1) in 'awk' is the associative array (*note
@@ -25134,7 +25364,7 @@ arrays of arrays (*note General Data Types::).
File: gawk.info, Node: Array Data Types, Next: Array Functions, Up: Array
Manipulation
-16.4.11.1 Array Data Types
+17.4.11.1 Array Data Types
..........................
The data types associated with arrays are as follows:
@@ -25201,7 +25431,7 @@ overuse this term.
File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev:
Array Data Types, Up: Array Manipulation
-16.4.11.2 Array Functions
+17.4.11.2 Array Functions
.........................
The following functions relate to individual array elements:
@@ -25219,7 +25449,7 @@ The following functions relate to individual array
elements:
value of the element whose index is 'index'. 'wanted' specifies
the type of value you wish to retrieve. Return false if 'wanted'
does not match the actual type or if 'index' is not in the array
- (*note Table 16.1: table-value-types-returned.).
+ (*note Table 17.1: table-value-types-returned.).
The value for 'index' can be numeric, in which case 'gawk' converts
it to a string. Using nonintegral values is possible, but requires
@@ -25288,7 +25518,7 @@ The following functions relate to individual array
elements:
File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev:
Array Functions, Up: Array Manipulation
-16.4.11.3 Working With All The Elements of an Array
+17.4.11.3 Working With All The Elements of an Array
...................................................
To "flatten" an array is to create a structure that represents the full
@@ -25461,7 +25691,7 @@ return value to success, and returns:
File: gawk.info, Node: Creating Arrays, Prev: Flattening Arrays, Up: Array
Manipulation
-16.4.11.4 How To Create and Populate Arrays
+17.4.11.4 How To Create and Populate Arrays
...........................................
Besides working with arrays created by 'awk' code, you can create arrays
@@ -25600,7 +25830,7 @@ environment variable.)
File: gawk.info, Node: Redirection API, Next: Extension API Variables,
Prev: Array Manipulation, Up: Extension API Description
-16.4.12 Accessing and Manipulating Redirections
+17.4.12 Accessing and Manipulating Redirections
-----------------------------------------------
The following function allows extensions to access and manipulate
@@ -25669,7 +25899,7 @@ I/O multiplexing and a socket library.
File: gawk.info, Node: Extension API Variables, Next: Extension API
Boilerplate, Prev: Redirection API, Up: Extension API Description
-16.4.13 API Variables
+17.4.13 API Variables
---------------------
The API provides two sets of variables. The first provides information
@@ -25686,7 +25916,7 @@ information about how 'gawk' was invoked.
File: gawk.info, Node: Extension Versioning, Next: Extension API
Informational Variables, Up: Extension API Variables
-16.4.13.1 API Version Constants and Variables
+17.4.13.1 API Version Constants and Variables
.............................................
The API provides both a "major" and a "minor" version number. The API
@@ -25699,7 +25929,7 @@ API Version C Preprocessor Define enum constant
Major 'gawk_api_major_version' 'GAWK_API_MAJOR_VERSION'
Minor 'gawk_api_minor_version' 'GAWK_API_MINOR_VERSION'
-Table 16.2: gawk API version constants
+Table 17.2: gawk API version constants
The minor version increases when new functions are added to the API.
Such new functions are always added to the end of the API 'struct'.
@@ -25738,7 +25968,7 @@ Boilerplate::).
File: gawk.info, Node: Extension API Informational Variables, Prev:
Extension Versioning, Up: Extension API Variables
-16.4.13.2 Informational Variables
+17.4.13.2 Informational Variables
.................................
The API provides access to several variables that describe whether the
@@ -25773,7 +26003,7 @@ change during execution.
File: gawk.info, Node: Extension API Boilerplate, Next: Changes from API V1,
Prev: Extension API Variables, Up: Extension API Description
-16.4.14 Boilerplate Code
+17.4.14 Boilerplate Code
------------------------
As mentioned earlier (*note Extension Mechanism Outline::), the function
@@ -25874,7 +26104,7 @@ does the following:
File: gawk.info, Node: Changes from API V1, Prev: Extension API Boilerplate,
Up: Extension API Description
-16.4.15 Changes From Version 1 of the API
+17.4.15 Changes From Version 1 of the API
-----------------------------------------
The current API is _not_ binary compatible with version 1 of the API.
@@ -25890,7 +26120,7 @@ implementation function.
File: gawk.info, Node: Finding Extensions, Next: Extension Example, Prev:
Extension API Description, Up: Dynamic Extensions
-16.5 How 'gawk' Finds Extensions
+17.5 How 'gawk' Finds Extensions
================================
Compiled extensions have to be installed in a directory where 'gawk' can
@@ -25902,7 +26132,7 @@ compiled extensions. *Note AWKLIBPATH Variable:: for
more information.
File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev:
Finding Extensions, Up: Dynamic Extensions
-16.6 Example: Some File Functions
+17.6 Example: Some File Functions
=================================
No matter where you go, there you are.
@@ -25923,7 +26153,7 @@ in an extension.
File: gawk.info, Node: Internal File Description, Next: Internal File Ops,
Up: Extension Example
-16.6.1 Using 'chdir()' and 'stat()'
+17.6.1 Using 'chdir()' and 'stat()'
-----------------------------------
This minor node shows how to use the new functions at the 'awk' level
@@ -26053,7 +26283,7 @@ Elements::):
File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops,
Prev: Internal File Description, Up: Extension Example
-16.6.2 C Code for 'chdir()' and 'stat()'
+17.6.2 C Code for 'chdir()' and 'stat()'
----------------------------------------
Here is the C code for these extensions.(1)
@@ -26396,7 +26626,7 @@ version.
File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops,
Up: Extension Example
-16.6.3 Integrating the Extensions
+17.6.3 Integrating the Extensions
---------------------------------
Now that the code is written, it must be possible to add it at runtime
@@ -26477,7 +26707,7 @@ file. *Note gawkextlib:: for Internet links to the
tools.
File: gawk.info, Node: Extension Samples, Next: gawkextlib, Prev: Extension
Example, Up: Dynamic Extensions
-16.7 The Sample Extensions in the 'gawk' Distribution
+17.7 The Sample Extensions in the 'gawk' Distribution
=====================================================
This minor node provides a brief overview of the sample extensions that
@@ -26507,7 +26737,7 @@ the extension API.
File: gawk.info, Node: Extension Sample File Functions, Next: Extension
Sample Fnmatch, Up: Extension Samples
-16.7.1 File-Related Functions
+17.7.1 File-Related Functions
-----------------------------
The 'filefuncs' extension provides three different functions, as
@@ -26677,7 +26907,7 @@ the 'fts()' extension function.
File: gawk.info, Node: Extension Sample Fnmatch, Next: Extension Sample
Fork, Prev: Extension Sample File Functions, Up: Extension Samples
-16.7.2 Interface to 'fnmatch()'
+17.7.2 Interface to 'fnmatch()'
-------------------------------
This extension provides an interface to the C library 'fnmatch()'
@@ -26728,7 +26958,7 @@ Array element Corresponding flag defined by
'fnmatch()'
File: gawk.info, Node: Extension Sample Fork, Next: Extension Sample
Inplace, Prev: Extension Sample Fnmatch, Up: Extension Samples
-16.7.3 Interface to 'fork()', 'wait()', and 'waitpid()'
+17.7.3 Interface to 'fork()', 'wait()', and 'waitpid()'
-------------------------------------------------------
The 'fork' extension adds three functions, as follows:
@@ -26765,7 +26995,7 @@ The 'fork' extension adds three functions, as follows:
File: gawk.info, Node: Extension Sample Inplace, Next: Extension Sample Ord,
Prev: Extension Sample Fork, Up: Extension Samples
-16.7.4 Enabling In-Place File Editing
+17.7.4 Enabling In-Place File Editing
-------------------------------------
The 'inplace' extension emulates GNU 'sed''s '-i' option, which performs
@@ -26846,7 +27076,7 @@ signal is received, a temporary file may be left behind.
File: gawk.info, Node: Extension Sample Ord, Next: Extension Sample Readdir,
Prev: Extension Sample Inplace, Up: Extension Samples
-16.7.5 Character and Numeric values: 'ord()' and 'chr()'
+17.7.5 Character and Numeric values: 'ord()' and 'chr()'
--------------------------------------------------------
The 'ordchr' extension adds two functions, named 'ord()' and 'chr()', as
@@ -26873,7 +27103,7 @@ same name. Here is an example:
File: gawk.info, Node: Extension Sample Readdir, Next: Extension Sample
Revout, Prev: Extension Sample Ord, Up: Extension Samples
-16.7.6 Reading Directories
+17.7.6 Reading Directories
--------------------------
The 'readdir' extension adds an input parser for directories. The usage
@@ -26890,7 +27120,7 @@ number and the file name, separated by a forward slash
character. On
systems where the directory entry contains the file type, the record has
a third field (also separated by a slash), which is a single letter
indicating the type of the file. The letters and their corresponding
-file types are shown in *note Table 16.3: table-readdir-file-types.
+file types are shown in *note Table 17.3: table-readdir-file-types.
Letter File type
--------------------------------------------------------------------------
@@ -26903,7 +27133,7 @@ Letter File type
's' Socket
'u' Anything else (unknown)
-Table 16.3: File types returned by the 'readdir' extension
+Table 17.3: File types returned by the 'readdir' extension
On systems without the file type information, the third field is
always 'u'.
@@ -26923,7 +27153,7 @@ always 'u'.
File: gawk.info, Node: Extension Sample Revout, Next: Extension Sample
Rev2way, Prev: Extension Sample Readdir, Up: Extension Samples
-16.7.7 Reversing Output
+17.7.7 Reversing Output
-----------------------
The 'revoutput' extension adds a simple output wrapper that reverses the
@@ -26943,7 +27173,7 @@ unwary. Here is an example:
File: gawk.info, Node: Extension Sample Rev2way, Next: Extension Sample Read
write array, Prev: Extension Sample Revout, Up: Extension Samples
-16.7.8 Two-Way I/O Example
+17.7.8 Two-Way I/O Example
--------------------------
The 'revtwoway' extension adds a simple two-way processor that reverses
@@ -26967,7 +27197,7 @@ to use it:
File: gawk.info, Node: Extension Sample Read write array, Next: Extension
Sample Readfile, Prev: Extension Sample Rev2way, Up: Extension Samples
-16.7.9 Dumping and Restoring an Array
+17.7.9 Dumping and Restoring an Array
-------------------------------------
The 'rwarray' extension adds two functions, named 'writea()' and
@@ -27014,7 +27244,7 @@ on systems with a different one, but this has not been
tried.
File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample
Time, Prev: Extension Sample Read write array, Up: Extension Samples
-16.7.10 Reading an Entire File
+17.7.10 Reading an Entire File
------------------------------
The 'readfile' extension adds a single function named 'readfile()', and
@@ -27047,7 +27277,7 @@ an input parser:
File: gawk.info, Node: Extension Sample Time, Next: Extension Sample API
Tests, Prev: Extension Sample Readfile, Up: Extension Samples
-16.7.11 Extension Time Functions
+17.7.11 Extension Time Functions
--------------------------------
The 'time' extension adds two functions, named 'gettimeofday()' and
@@ -27078,7 +27308,7 @@ The 'time' extension adds two functions, named
'gettimeofday()' and
File: gawk.info, Node: Extension Sample API Tests, Prev: Extension Sample
Time, Up: Extension Samples
-16.7.12 API Tests
+17.7.12 API Tests
-----------------
The 'testext' extension exercises parts of the extension API that are
@@ -27090,7 +27320,7 @@ code and runs the tests. See the source file for more
information.
File: gawk.info, Node: gawkextlib, Next: Extension summary, Prev: Extension
Samples, Up: Dynamic Extensions
-16.8 The 'gawkextlib' Project
+17.8 The 'gawkextlib' Project
=============================
The 'gawkextlib' (http://sourceforge.net/projects/gawkextlib/) project
@@ -27156,7 +27386,7 @@ project's website for more information.
File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev:
gawkextlib, Up: Dynamic Extensions
-16.9 Summary
+17.9 Summary
============
* You can write extensions (sometimes called plug-ins) for 'gawk' in
@@ -27244,7 +27474,7 @@ File: gawk.info, Node: Extension summary, Next:
Extension Exercises, Prev: ga
File: gawk.info, Node: Extension Exercises, Prev: Extension summary, Up:
Dynamic Extensions
-16.10 Exercises
+17.10 Exercises
===============
1. Add functions to implement system calls such as 'chown()',
@@ -36062,261 +36292,268 @@ Node: Walking Arrays699891
Node: Library Functions Summary702899
Node: Library Exercises704305
Node: Sample Programs704770
-Node: Running Examples705540
-Node: Clones706268
-Node: Cut Program707492
-Node: Egrep Program717421
-Ref: Egrep Program-Footnote-1724933
-Node: Id Program725043
-Node: Split Program728723
-Ref: Split Program-Footnote-1732182
-Node: Tee Program732311
-Node: Uniq Program735101
-Node: Wc Program742527
-Ref: Wc Program-Footnote-1746782
-Node: Miscellaneous Programs746876
-Node: Dupword Program748089
-Node: Alarm Program750119
-Node: Translate Program754974
-Ref: Translate Program-Footnote-1759539
-Node: Labels Program759809
-Ref: Labels Program-Footnote-1763160
-Node: Word Sorting763244
-Node: History Sorting767316
-Node: Extract Program769151
-Node: Simple Sed776680
-Node: Igawk Program779754
-Ref: Igawk Program-Footnote-1794085
-Ref: Igawk Program-Footnote-2794287
-Ref: Igawk Program-Footnote-3794409
-Node: Anagram Program794524
-Node: Signature Program797586
-Node: Programs Summary798833
-Node: Programs Exercises800047
-Ref: Programs Exercises-Footnote-1804176
-Node: Advanced Features804267
-Node: Nondecimal Data806257
-Node: Array Sorting807848
-Node: Controlling Array Traversal808548
-Ref: Controlling Array Traversal-Footnote-1816915
-Node: Array Sorting Functions817033
-Ref: Array Sorting Functions-Footnote-1822124
-Node: Two-way I/O822320
-Ref: Two-way I/O-Footnote-1828871
-Ref: Two-way I/O-Footnote-2829058
-Node: TCP/IP Networking829140
-Node: Profiling832258
-Ref: Profiling-Footnote-1840930
-Node: Advanced Features Summary841253
-Node: Internationalization843097
-Node: I18N and L10N844577
-Node: Explaining gettext845264
-Ref: Explaining gettext-Footnote-1851156
-Ref: Explaining gettext-Footnote-2851341
-Node: Programmer i18n851506
-Ref: Programmer i18n-Footnote-1856455
-Node: Translator i18n856504
-Node: String Extraction857298
-Ref: String Extraction-Footnote-1858430
-Node: Printf Ordering858516
-Ref: Printf Ordering-Footnote-1861302
-Node: I18N Portability861366
-Ref: I18N Portability-Footnote-1863822
-Node: I18N Example863885
-Ref: I18N Example-Footnote-1866691
-Node: Gawk I18N866764
-Node: I18N Summary867409
-Node: Debugger868750
-Node: Debugging869772
-Node: Debugging Concepts870213
-Node: Debugging Terms872022
-Node: Awk Debugging874597
-Node: Sample Debugging Session875503
-Node: Debugger Invocation876037
-Node: Finding The Bug877423
-Node: List of Debugger Commands883901
-Node: Breakpoint Control885234
-Node: Debugger Execution Control888928
-Node: Viewing And Changing Data892290
-Node: Execution Stack895664
-Node: Debugger Info897301
-Node: Miscellaneous Debugger Commands901372
-Node: Readline Support906460
-Node: Limitations907356
-Node: Debugging Summary909465
-Node: Arbitrary Precision Arithmetic910744
-Node: Computer Arithmetic912229
-Ref: table-numeric-ranges915820
-Ref: Computer Arithmetic-Footnote-1916542
-Node: Math Definitions916599
-Ref: table-ieee-formats919913
-Ref: Math Definitions-Footnote-1920516
-Node: MPFR features920621
-Node: FP Math Caution922338
-Ref: FP Math Caution-Footnote-1923410
-Node: Inexactness of computations923779
-Node: Inexact representation924739
-Node: Comparing FP Values926099
-Node: Errors accumulate927181
-Node: Getting Accuracy928614
-Node: Try To Round931324
-Node: Setting precision932223
-Ref: table-predefined-precision-strings932920
-Node: Setting the rounding mode934750
-Ref: table-gawk-rounding-modes935124
-Ref: Setting the rounding mode-Footnote-1938532
-Node: Arbitrary Precision Integers938711
-Ref: Arbitrary Precision Integers-Footnote-1943616
-Node: Checking for MPFR943765
-Node: POSIX Floating Point Problems945062
-Ref: POSIX Floating Point Problems-Footnote-1948933
-Node: Floating point summary948971
-Node: Dynamic Extensions951161
-Node: Extension Intro952714
-Node: Plugin License953980
-Node: Extension Mechanism Outline954777
-Ref: figure-load-extension955216
-Ref: figure-register-new-function956781
-Ref: figure-call-new-function957873
-Node: Extension API Description959935
-Node: Extension API Functions Introduction961577
-Node: General Data Types966911
-Ref: General Data Types-Footnote-1974116
-Node: Memory Allocation Functions974415
-Ref: Memory Allocation Functions-Footnote-1977260
-Node: Constructor Functions977359
-Node: Registration Functions980358
-Node: Extension Functions981043
-Node: Exit Callback Functions986256
-Node: Extension Version String987506
-Node: Input Parsers988169
-Node: Output Wrappers1000876
-Node: Two-way processors1005388
-Node: Printing Messages1007653
-Ref: Printing Messages-Footnote-11008824
-Node: Updating ERRNO1008977
-Node: Requesting Values1009716
-Ref: table-value-types-returned1010453
-Node: Accessing Parameters1011389
-Node: Symbol Table Access1012624
-Node: Symbol table by name1013136
-Node: Symbol table by cookie1014925
-Ref: Symbol table by cookie-Footnote-11019110
-Node: Cached values1019174
-Ref: Cached values-Footnote-11022710
-Node: Array Manipulation1022801
-Ref: Array Manipulation-Footnote-11023892
-Node: Array Data Types1023929
-Ref: Array Data Types-Footnote-11026587
-Node: Array Functions1026679
-Node: Flattening Arrays1031078
-Node: Creating Arrays1038019
-Node: Redirection API1042788
-Node: Extension API Variables1045630
-Node: Extension Versioning1046263
-Ref: gawk-api-version1046700
-Node: Extension API Informational Variables1048428
-Node: Extension API Boilerplate1049492
-Node: Changes from API V11053354
-Node: Finding Extensions1054014
-Node: Extension Example1054573
-Node: Internal File Description1055371
-Node: Internal File Ops1059451
-Ref: Internal File Ops-Footnote-11070851
-Node: Using Internal File Ops1070991
-Ref: Using Internal File Ops-Footnote-11073374
-Node: Extension Samples1073648
-Node: Extension Sample File Functions1075177
-Node: Extension Sample Fnmatch1082826
-Node: Extension Sample Fork1084313
-Node: Extension Sample Inplace1085531
-Node: Extension Sample Ord1088741
-Node: Extension Sample Readdir1089577
-Ref: table-readdir-file-types1090466
-Node: Extension Sample Revout1091271
-Node: Extension Sample Rev2way1091860
-Node: Extension Sample Read write array1092600
-Node: Extension Sample Readfile1094542
-Node: Extension Sample Time1095637
-Node: Extension Sample API Tests1096985
-Node: gawkextlib1097477
-Node: Extension summary1099924
-Node: Extension Exercises1103626
-Node: Language History1105124
-Node: V7/SVR3.11106780
-Node: SVR41108932
-Node: POSIX1110366
-Node: BTL1111745
-Node: POSIX/GNU1112474
-Node: Feature History1118366
-Node: Common Extensions1132790
-Node: Ranges and Locales1134073
-Ref: Ranges and Locales-Footnote-11138689
-Ref: Ranges and Locales-Footnote-21138716
-Ref: Ranges and Locales-Footnote-31138951
-Node: Contributors1139172
-Node: History summary1144732
-Node: Installation1146112
-Node: Gawk Distribution1147056
-Node: Getting1147540
-Node: Extracting1148501
-Node: Distribution contents1150139
-Node: Unix Installation1156481
-Node: Quick Installation1157163
-Node: Shell Startup Files1159577
-Node: Additional Configuration Options1160666
-Node: Configuration Philosophy1162655
-Node: Non-Unix Installation1165024
-Node: PC Installation1165484
-Node: PC Binary Installation1166322
-Node: PC Compiling1166757
-Node: PC Using1167874
-Node: Cygwin1170919
-Node: MSYS1171689
-Node: VMS Installation1172190
-Node: VMS Compilation1172981
-Ref: VMS Compilation-Footnote-11174210
-Node: VMS Dynamic Extensions1174268
-Node: VMS Installation Details1175953
-Node: VMS Running1178206
-Node: VMS GNV1182485
-Node: VMS Old Gawk1183220
-Node: Bugs1183691
-Node: Bug address1184354
-Node: Usenet1186751
-Node: Maintainers1187528
-Node: Other Versions1188904
-Node: Installation summary1195488
-Node: Notes1196523
-Node: Compatibility Mode1197388
-Node: Additions1198170
-Node: Accessing The Source1199095
-Node: Adding Code1200530
-Node: New Ports1206748
-Node: Derived Files1211236
-Ref: Derived Files-Footnote-11216721
-Ref: Derived Files-Footnote-21216756
-Ref: Derived Files-Footnote-31217354
-Node: Future Extensions1217468
-Node: Implementation Limitations1218126
-Node: Extension Design1219309
-Node: Old Extension Problems1220463
-Ref: Old Extension Problems-Footnote-11221981
-Node: Extension New Mechanism Goals1222038
-Ref: Extension New Mechanism Goals-Footnote-11225402
-Node: Extension Other Design Decisions1225591
-Node: Extension Future Growth1227704
-Node: Old Extension Mechanism1228540
-Node: Notes summary1230303
-Node: Basic Concepts1231485
-Node: Basic High Level1232166
-Ref: figure-general-flow1232448
-Ref: figure-process-flow1233133
-Ref: Basic High Level-Footnote-11236434
-Node: Basic Data Typing1236619
-Node: Glossary1239947
-Node: Copying1271894
-Node: GNU Free Documentation License1309433
-Node: Index1334551
+Node: Running Examples705533
+Node: Clones706261
+Node: Cut Program707485
+Node: Egrep Program717414
+Ref: Egrep Program-Footnote-1724926
+Node: Id Program725036
+Node: Split Program728716
+Ref: Split Program-Footnote-1732175
+Node: Tee Program732304
+Node: Uniq Program735094
+Node: Wc Program742520
+Ref: Wc Program-Footnote-1746775
+Node: Miscellaneous Programs746869
+Node: Dupword Program748082
+Node: Alarm Program750112
+Node: Translate Program754967
+Ref: Translate Program-Footnote-1759532
+Node: Labels Program759802
+Ref: Labels Program-Footnote-1763153
+Node: Word Sorting763237
+Node: History Sorting767309
+Node: Extract Program769144
+Node: Simple Sed776673
+Node: Igawk Program779747
+Ref: Igawk Program-Footnote-1794078
+Ref: Igawk Program-Footnote-2794280
+Ref: Igawk Program-Footnote-3794402
+Node: Anagram Program794517
+Node: Signature Program797579
+Node: Programs Summary798826
+Node: Programs Exercises800040
+Ref: Programs Exercises-Footnote-1804169
+Node: Namespaces804260
+Node: Global Namespace804481
+Node: Qualified Names805721
+Node: Default Namespace806402
+Node: Changing The Namespace807099
+Node: Namespace Example808203
+Node: Namespace Misc810262
+Node: Advanced Features811040
+Node: Nondecimal Data813025
+Node: Array Sorting814616
+Node: Controlling Array Traversal815316
+Ref: Controlling Array Traversal-Footnote-1823683
+Node: Array Sorting Functions823801
+Ref: Array Sorting Functions-Footnote-1828892
+Node: Two-way I/O829088
+Ref: Two-way I/O-Footnote-1835639
+Ref: Two-way I/O-Footnote-2835826
+Node: TCP/IP Networking835908
+Node: Profiling839026
+Ref: Profiling-Footnote-1847698
+Node: Advanced Features Summary848021
+Node: Internationalization849865
+Node: I18N and L10N851345
+Node: Explaining gettext852032
+Ref: Explaining gettext-Footnote-1857924
+Ref: Explaining gettext-Footnote-2858109
+Node: Programmer i18n858274
+Ref: Programmer i18n-Footnote-1863223
+Node: Translator i18n863272
+Node: String Extraction864066
+Ref: String Extraction-Footnote-1865198
+Node: Printf Ordering865284
+Ref: Printf Ordering-Footnote-1868070
+Node: I18N Portability868134
+Ref: I18N Portability-Footnote-1870590
+Node: I18N Example870653
+Ref: I18N Example-Footnote-1873459
+Node: Gawk I18N873532
+Node: I18N Summary874177
+Node: Debugger875518
+Node: Debugging876540
+Node: Debugging Concepts876981
+Node: Debugging Terms878790
+Node: Awk Debugging881365
+Node: Sample Debugging Session882271
+Node: Debugger Invocation882805
+Node: Finding The Bug884191
+Node: List of Debugger Commands890669
+Node: Breakpoint Control892002
+Node: Debugger Execution Control895696
+Node: Viewing And Changing Data899058
+Node: Execution Stack902432
+Node: Debugger Info904069
+Node: Miscellaneous Debugger Commands908140
+Node: Readline Support913228
+Node: Limitations914124
+Node: Debugging Summary916233
+Node: Arbitrary Precision Arithmetic917512
+Node: Computer Arithmetic918997
+Ref: table-numeric-ranges922588
+Ref: Computer Arithmetic-Footnote-1923310
+Node: Math Definitions923367
+Ref: table-ieee-formats926681
+Ref: Math Definitions-Footnote-1927284
+Node: MPFR features927389
+Node: FP Math Caution929106
+Ref: FP Math Caution-Footnote-1930178
+Node: Inexactness of computations930547
+Node: Inexact representation931507
+Node: Comparing FP Values932867
+Node: Errors accumulate933949
+Node: Getting Accuracy935382
+Node: Try To Round938092
+Node: Setting precision938991
+Ref: table-predefined-precision-strings939688
+Node: Setting the rounding mode941518
+Ref: table-gawk-rounding-modes941892
+Ref: Setting the rounding mode-Footnote-1945300
+Node: Arbitrary Precision Integers945479
+Ref: Arbitrary Precision Integers-Footnote-1950384
+Node: Checking for MPFR950533
+Node: POSIX Floating Point Problems951830
+Ref: POSIX Floating Point Problems-Footnote-1955701
+Node: Floating point summary955739
+Node: Dynamic Extensions957929
+Node: Extension Intro959482
+Node: Plugin License960748
+Node: Extension Mechanism Outline961545
+Ref: figure-load-extension961984
+Ref: figure-register-new-function963549
+Ref: figure-call-new-function964641
+Node: Extension API Description966703
+Node: Extension API Functions Introduction968345
+Node: General Data Types973679
+Ref: General Data Types-Footnote-1980884
+Node: Memory Allocation Functions981183
+Ref: Memory Allocation Functions-Footnote-1984028
+Node: Constructor Functions984127
+Node: Registration Functions987126
+Node: Extension Functions987811
+Node: Exit Callback Functions993024
+Node: Extension Version String994274
+Node: Input Parsers994937
+Node: Output Wrappers1007644
+Node: Two-way processors1012156
+Node: Printing Messages1014421
+Ref: Printing Messages-Footnote-11015592
+Node: Updating ERRNO1015745
+Node: Requesting Values1016484
+Ref: table-value-types-returned1017221
+Node: Accessing Parameters1018157
+Node: Symbol Table Access1019392
+Node: Symbol table by name1019904
+Node: Symbol table by cookie1021693
+Ref: Symbol table by cookie-Footnote-11025878
+Node: Cached values1025942
+Ref: Cached values-Footnote-11029478
+Node: Array Manipulation1029569
+Ref: Array Manipulation-Footnote-11030660
+Node: Array Data Types1030697
+Ref: Array Data Types-Footnote-11033355
+Node: Array Functions1033447
+Node: Flattening Arrays1037846
+Node: Creating Arrays1044787
+Node: Redirection API1049556
+Node: Extension API Variables1052398
+Node: Extension Versioning1053031
+Ref: gawk-api-version1053468
+Node: Extension API Informational Variables1055196
+Node: Extension API Boilerplate1056260
+Node: Changes from API V11060122
+Node: Finding Extensions1060782
+Node: Extension Example1061341
+Node: Internal File Description1062139
+Node: Internal File Ops1066219
+Ref: Internal File Ops-Footnote-11077619
+Node: Using Internal File Ops1077759
+Ref: Using Internal File Ops-Footnote-11080142
+Node: Extension Samples1080416
+Node: Extension Sample File Functions1081945
+Node: Extension Sample Fnmatch1089594
+Node: Extension Sample Fork1091081
+Node: Extension Sample Inplace1092299
+Node: Extension Sample Ord1095509
+Node: Extension Sample Readdir1096345
+Ref: table-readdir-file-types1097234
+Node: Extension Sample Revout1098039
+Node: Extension Sample Rev2way1098628
+Node: Extension Sample Read write array1099368
+Node: Extension Sample Readfile1101310
+Node: Extension Sample Time1102405
+Node: Extension Sample API Tests1103753
+Node: gawkextlib1104245
+Node: Extension summary1106692
+Node: Extension Exercises1110394
+Node: Language History1111892
+Node: V7/SVR3.11113548
+Node: SVR41115700
+Node: POSIX1117134
+Node: BTL1118513
+Node: POSIX/GNU1119242
+Node: Feature History1125134
+Node: Common Extensions1139558
+Node: Ranges and Locales1140841
+Ref: Ranges and Locales-Footnote-11145457
+Ref: Ranges and Locales-Footnote-21145484
+Ref: Ranges and Locales-Footnote-31145719
+Node: Contributors1145940
+Node: History summary1151500
+Node: Installation1152880
+Node: Gawk Distribution1153824
+Node: Getting1154308
+Node: Extracting1155269
+Node: Distribution contents1156907
+Node: Unix Installation1163249
+Node: Quick Installation1163931
+Node: Shell Startup Files1166345
+Node: Additional Configuration Options1167434
+Node: Configuration Philosophy1169423
+Node: Non-Unix Installation1171792
+Node: PC Installation1172252
+Node: PC Binary Installation1173090
+Node: PC Compiling1173525
+Node: PC Using1174642
+Node: Cygwin1177687
+Node: MSYS1178457
+Node: VMS Installation1178958
+Node: VMS Compilation1179749
+Ref: VMS Compilation-Footnote-11180978
+Node: VMS Dynamic Extensions1181036
+Node: VMS Installation Details1182721
+Node: VMS Running1184974
+Node: VMS GNV1189253
+Node: VMS Old Gawk1189988
+Node: Bugs1190459
+Node: Bug address1191122
+Node: Usenet1193519
+Node: Maintainers1194296
+Node: Other Versions1195672
+Node: Installation summary1202256
+Node: Notes1203291
+Node: Compatibility Mode1204156
+Node: Additions1204938
+Node: Accessing The Source1205863
+Node: Adding Code1207298
+Node: New Ports1213516
+Node: Derived Files1218004
+Ref: Derived Files-Footnote-11223489
+Ref: Derived Files-Footnote-21223524
+Ref: Derived Files-Footnote-31224122
+Node: Future Extensions1224236
+Node: Implementation Limitations1224894
+Node: Extension Design1226077
+Node: Old Extension Problems1227231
+Ref: Old Extension Problems-Footnote-11228749
+Node: Extension New Mechanism Goals1228806
+Ref: Extension New Mechanism Goals-Footnote-11232170
+Node: Extension Other Design Decisions1232359
+Node: Extension Future Growth1234472
+Node: Old Extension Mechanism1235308
+Node: Notes summary1237071
+Node: Basic Concepts1238253
+Node: Basic High Level1238934
+Ref: figure-general-flow1239216
+Ref: figure-process-flow1239901
+Ref: Basic High Level-Footnote-11243202
+Node: Basic Data Typing1243387
+Node: Glossary1246715
+Node: Copying1278662
+Node: GNU Free Documentation License1316201
+Node: Index1341319
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index c344acf..17890ad 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -27580,6 +27580,9 @@ It contains the following chapters:
@itemize @value{BULLET}
@item
address@hidden
+
address@hidden
@ref{Advanced Features}
@item
@@ -27596,6 +27599,229 @@ It contains the following chapters:
@end itemize
@end ifdocbook
address@hidden Namespaces
address@hidden Namespaces in @command{gawk}
+
+This @value{CHAPTER} describes a feature that is specific to @command{gawk}.
+
address@hidden
address@hidden menu
+
address@hidden Global Namespace
address@hidden Standard @command{awk}'s Single Namespace
+
+In standard @command{awk}, there is a single, global, @dfn{namespace}.
+This means that @emph{all} function names and global variable names must
+be unique. Two different @command{awk} source files cannot both define
+a function named @code{sort()}, for example.
+
+This situation is okay when programs are small, say a few hundred lines,
+or even a few thousand, but it prevents the development of reusable
+libraries of @command{awk} functions, and can inadvertently cause
+independently-developed library files to accidentally step on each other's
+``private'' global variables
+(@pxref{Library Names}).
+
+Most other programming languages solve this issue by providing some kind
+of namespace control: a way to say ``this function is in namespace @var{X},
+and that function is in namespace @var{Y}.'' (Of course, there is then
+still a single namespace for the namespaces, but the hope is that there
+are much fewer namespaces in use by any given program, and thus much
+less chance for collisions.)
+
+Starting with version @strong{FIXME} 5.0, @command{gawk} provides a
+mechanism to put functions and global variables into different
+namespaces.
+
address@hidden Qualified Names
address@hidden Qualified Names
+
+A @dfn{qualified name} is an identifier that includes a namespace
+name. For example, one might have a function named @code{posix.getpid()}.
+Here, the namespace is @samp{posix} and the function name within the
+namespace is @samp{getpid()}. The namespace and variable or function
+name are separated by a period. Only one period is allowed in
+a qualified name.
+
+You must use fully qualified names from one namespace to access variables
+in another. This is especially important when using variable
+names to index the special @code{SYMTAB} array.
+
address@hidden Default Namespace
address@hidden The Default Namespace
+
+The default namespace, not surprisingly, is @samp{awk}.
+All of the predefined @command{awk} and @command{gawk} variables
+are in this namespace, and thus have qualified names like
address@hidden, @code{awk.NF}, and so on.
+
+Furthermore, even when you have changed the namespace for your
+current source file (@pxref{Changing The Namespace}), @command{gawk}
+forces unqualified identifiers whose names are all uppercase letters
+to be in the @samp{awk} namespace. This makes it possible for you to easily
+reference @command{gawk}'s global variables from different namespaces.
+
address@hidden Changing The Namespace
address@hidden Changing The Namespace
+
+In order to set the current namespace, use an @samp{@@namespace} directive
+at the top level of your program:
+
address@hidden
+@@namespace "passwd"
+
+BEGIN @{ @dot{} @}
address@hidden
address@hidden example
+
+After this directive, all simple non-uppercase identifiers are
+placed into the @samp{passwd} namespace.
+
+You can change the namespace multiple times within a single
+source file, although this is likely to become confusing if you
+do it a lot.
+
address@hidden NOTE
+The namespace concept is one handled while your program is
+being parsed by @command{gawk}. There is no concept of a
+``current'' namespace during runtime. Be sure you understand
+the distinction.
address@hidden quotation
+
+Each source file for @option{-i} and @option{-f} starts out with an implicit
address@hidden@namespace "awk"}.
+
+Similarly, each chunk of command-line code with @option{-e} has such an
implicit
+statement.
+
+FIXME: The semantics of @option{-e} change to require it to be syntactic unit.
+
+FIXME: Update doc earlier in this book and change the corresponding code.
+
address@hidden Namespace Example
address@hidden Namespace Example
+
address@hidden
+# FIXME: fix this up for real, dates etc
+#
+# passwd.awk --- access password file information
+#
+# Arnold Robbins, arnold@@skeeve.com, Public Domain
+# May 1993
+# Revised October 2000
+# Revised December 2010
+#
+# Reworked for namespaces May 2017
+
+@@namespace "passwd"
+
+BEGIN @{
+ # tailor this to suit your system
+ Awklib = "/usr/local/libexec/awk/"
address@hidden
+
+function Init( oldfs, oldrs, olddol0, pwcat, using_fw, using_fpat)
address@hidden
+ if (Inited)
+ return
+
+ oldfs = FS
+ oldrs = RS
+ olddol0 = $0
+ using_fw = (PROCINFO["FS"] == "FIELDWIDTHS")
+ using_fpat = (PROCINFO["FS"] == "FPAT")
+ FS = ":"
+ RS = "\n"
+
+ pwcat = _pw_awklib "pwcat"
+ while ((pwcat | getline) > 0) {
+ Byname[$1] = $0
+ Byuid[$3] = $0
+ Bycount[++_pw_total] = $0
+ }
+ close(pwcat)
+ Count = 0
+ Inited = 1
+ FS = oldfs
+ if (using_fw)
+ FIELDWIDTHS = FIELDWIDTHS
+ else if (using_fpat)
+ FPAT = FPAT
+ RS = oldrs
+ $0 = olddol0
address@hidden
+
+function Getpwnam(name)
address@hidden
+ Init()
+ return Byname[name]
address@hidden
+
+function Getpwuid(uid)
address@hidden
+ Init()
+ return Byuid[uid]
address@hidden
+
+function Getpwent()
address@hidden
+ Init()
+ if (Count < Total)
+ return Bycount[++Count]
+ return ""
address@hidden
+
+function Endpwent()
address@hidden
+ Count = 0
address@hidden
+
+# Compatibility:
+
+@@namespace "awk"
+
+function getpwnam(name)
address@hidden
+ return passwd.Getpwnam(name)
address@hidden
+
+function getpwuid(uid)
address@hidden
+ return passwd.Getpwuid(uid)
address@hidden
+
+function getpwent()
address@hidden
+ return passwd.Getpwent()
address@hidden
+
+function endpwent()
address@hidden
+ passwd.Endpwent()
address@hidden
address@hidden example
+
address@hidden Namespace Misc
address@hidden Miscellaneous Notes
+
+Other notes for reviewers:
+
address@hidden
address@hidden Profiler:
+When profiling, we can add an @code{Op_Namespace} to the start of
+each rule. If it has changed since the previous one, output an
address@hidden@@namespace} statement. For each identifier, if it starts
+with the current namespace, output only the simple part.
+For all @samp{awk.XXX} if @samp{XXX} is all uppercase, strip
+off the @samp{awk} part.
+
address@hidden Debugger:
+Simply prints fully qualified names all the time. Maybe allow a
address@hidden @var{xxx}} command in the debugger to set the
+namespace and it will use that to create fully qualified names?
+Have to be careful about all uppercase names though.
address@hidden table
+
@node Advanced Features
@chapter Advanced Features of @command{gawk}
@cindex @command{gawk}, features, advanced
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 4cf6294..814362a 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -26594,6 +26594,9 @@ It contains the following chapters:
@itemize @value{BULLET}
@item
address@hidden
+
address@hidden
@ref{Advanced Features}
@item
@@ -26610,6 +26613,229 @@ It contains the following chapters:
@end itemize
@end ifdocbook
address@hidden Namespaces
address@hidden Namespaces in @command{gawk}
+
+This @value{CHAPTER} describes a feature that is specific to @command{gawk}.
+
address@hidden
address@hidden menu
+
address@hidden Global Namespace
address@hidden Standard @command{awk}'s Single Namespace
+
+In standard @command{awk}, there is a single, global, @dfn{namespace}.
+This means that @emph{all} function names and global variable names must
+be unique. Two different @command{awk} source files cannot both define
+a function named @code{sort()}, for example.
+
+This situation is okay when programs are small, say a few hundred lines,
+or even a few thousand, but it prevents the development of reusable
+libraries of @command{awk} functions, and can inadvertently cause
+independently-developed library files to accidentally step on each other's
+``private'' global variables
+(@pxref{Library Names}).
+
+Most other programming languages solve this issue by providing some kind
+of namespace control: a way to say ``this function is in namespace @var{X},
+and that function is in namespace @var{Y}.'' (Of course, there is then
+still a single namespace for the namespaces, but the hope is that there
+are much fewer namespaces in use by any given program, and thus much
+less chance for collisions.)
+
+Starting with version @strong{FIXME} 5.0, @command{gawk} provides a
+mechanism to put functions and global variables into different
+namespaces.
+
address@hidden Qualified Names
address@hidden Qualified Names
+
+A @dfn{qualified name} is an identifier that includes a namespace
+name. For example, one might have a function named @code{posix.getpid()}.
+Here, the namespace is @samp{posix} and the function name within the
+namespace is @samp{getpid()}. The namespace and variable or function
+name are separated by a period. Only one period is allowed in
+a qualified name.
+
+You must use fully qualified names from one namespace to access variables
+in another. This is especially important when using variable
+names to index the special @code{SYMTAB} array.
+
address@hidden Default Namespace
address@hidden The Default Namespace
+
+The default namespace, not surprisingly, is @samp{awk}.
+All of the predefined @command{awk} and @command{gawk} variables
+are in this namespace, and thus have qualified names like
address@hidden, @code{awk.NF}, and so on.
+
+Furthermore, even when you have changed the namespace for your
+current source file (@pxref{Changing The Namespace}), @command{gawk}
+forces unqualified identifiers whose names are all uppercase letters
+to be in the @samp{awk} namespace. This makes it possible for you to easily
+reference @command{gawk}'s global variables from different namespaces.
+
address@hidden Changing The Namespace
address@hidden Changing The Namespace
+
+In order to set the current namespace, use an @samp{@@namespace} directive
+at the top level of your program:
+
address@hidden
+@@namespace "passwd"
+
+BEGIN @{ @dot{} @}
address@hidden
address@hidden example
+
+After this directive, all simple non-uppercase identifiers are
+placed into the @samp{passwd} namespace.
+
+You can change the namespace multiple times within a single
+source file, although this is likely to become confusing if you
+do it a lot.
+
address@hidden NOTE
+The namespace concept is one handled while your program is
+being parsed by @command{gawk}. There is no concept of a
+``current'' namespace during runtime. Be sure you understand
+the distinction.
address@hidden quotation
+
+Each source file for @option{-i} and @option{-f} starts out with an implicit
address@hidden@namespace "awk"}.
+
+Similarly, each chunk of command-line code with @option{-e} has such an
implicit
+statement.
+
+FIXME: The semantics of @option{-e} change to require it to be syntactic unit.
+
+FIXME: Update doc earlier in this book and change the corresponding code.
+
address@hidden Namespace Example
address@hidden Namespace Example
+
address@hidden
+# FIXME: fix this up for real, dates etc
+#
+# passwd.awk --- access password file information
+#
+# Arnold Robbins, arnold@@skeeve.com, Public Domain
+# May 1993
+# Revised October 2000
+# Revised December 2010
+#
+# Reworked for namespaces May 2017
+
+@@namespace "passwd"
+
+BEGIN @{
+ # tailor this to suit your system
+ Awklib = "/usr/local/libexec/awk/"
address@hidden
+
+function Init( oldfs, oldrs, olddol0, pwcat, using_fw, using_fpat)
address@hidden
+ if (Inited)
+ return
+
+ oldfs = FS
+ oldrs = RS
+ olddol0 = $0
+ using_fw = (PROCINFO["FS"] == "FIELDWIDTHS")
+ using_fpat = (PROCINFO["FS"] == "FPAT")
+ FS = ":"
+ RS = "\n"
+
+ pwcat = _pw_awklib "pwcat"
+ while ((pwcat | getline) > 0) {
+ Byname[$1] = $0
+ Byuid[$3] = $0
+ Bycount[++_pw_total] = $0
+ }
+ close(pwcat)
+ Count = 0
+ Inited = 1
+ FS = oldfs
+ if (using_fw)
+ FIELDWIDTHS = FIELDWIDTHS
+ else if (using_fpat)
+ FPAT = FPAT
+ RS = oldrs
+ $0 = olddol0
address@hidden
+
+function Getpwnam(name)
address@hidden
+ Init()
+ return Byname[name]
address@hidden
+
+function Getpwuid(uid)
address@hidden
+ Init()
+ return Byuid[uid]
address@hidden
+
+function Getpwent()
address@hidden
+ Init()
+ if (Count < Total)
+ return Bycount[++Count]
+ return ""
address@hidden
+
+function Endpwent()
address@hidden
+ Count = 0
address@hidden
+
+# Compatibility:
+
+@@namespace "awk"
+
+function getpwnam(name)
address@hidden
+ return passwd.Getpwnam(name)
address@hidden
+
+function getpwuid(uid)
address@hidden
+ return passwd.Getpwuid(uid)
address@hidden
+
+function getpwent()
address@hidden
+ return passwd.Getpwent()
address@hidden
+
+function endpwent()
address@hidden
+ passwd.Endpwent()
address@hidden
address@hidden example
+
address@hidden Namespace Misc
address@hidden Miscellaneous Notes
+
+Other notes for reviewers:
+
address@hidden
address@hidden Profiler:
+When profiling, we can add an @code{Op_Namespace} to the start of
+each rule. If it has changed since the previous one, output an
address@hidden@@namespace} statement. For each identifier, if it starts
+with the current namespace, output only the simple part.
+For all @samp{awk.XXX} if @samp{XXX} is all uppercase, strip
+off the @samp{awk} part.
+
address@hidden Debugger:
+Simply prints fully qualified names all the time. Maybe allow a
address@hidden @var{xxx}} command in the debugger to set the
+namespace and it will use that to create fully qualified names?
+Have to be careful about all uppercase names though.
address@hidden table
+
@node Advanced Features
@chapter Advanced Features of @command{gawk}
@cindex @command{gawk}, features, advanced
-----------------------------------------------------------------------
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, feature/namespaces, created. gawk-4.1.0-2570-gc5788a1,
Arnold Robbins <=