~vcs-imports/gawk/master : revision 730

539

* Computed Regexps:: Using Dynamic Regexps.

540

* GNU Regexp Operators:: Operators specific to GNU software.

541

* Case-sensitivity:: How to do case-insensitive matching.

542

* Strong Regexp Constants:: Strongly typed regexp constants.

543

542

* Regexp Summary:: Regular expressions summary.

544

543

* Records:: Controlling how data is split into

545

544

records.

622

621

* Nondecimal-numbers:: What are octal and hex numbers.

623

622

* Regexp Constants:: Regular Expression constants.

624

623

* Using Constant Regexps:: When and how to use a regexp constant.

624

* Standard Regexp Constants:: Regexp constants in standard

625

@command{awk}.

626

* Strong Regexp Constants:: Strongly typed regexp constants.

625

627

* Variables:: Variables give names to values for

626

628

later use.

627

629

* Using Variables:: Using variables in your programs.

924

926

* Array Functions:: Functions for working with arrays.

925

927

* Flattening Arrays:: How to flatten arrays.

926

928

* Creating Arrays:: How to create and populate arrays.

927

* Redirection API:: How to access and manipulate redirections.

929

* Redirection API:: How to access and manipulate

930

redirections.

928

931

* Extension API Variables:: Variables provided by the API.

929

932

* Extension Versioning:: API Version information.

930

933

* Extension API Informational Variables:: Variables providing information about

988

991

* Configuration Philosophy:: How it's all supposed to work.

989

992

* Non-Unix Installation:: Installation on Other Operating

990

993

Systems.

991

* PC Installation:: Installing and Compiling @command{gawk} on

992

Microsoft Windows.

994

* PC Installation:: Installing and Compiling

995

@command{gawk} on Microsoft Windows.

993

996

* PC Binary Installation:: Installing a prepared distribution.

994

* PC Compiling:: Compiling @command{gawk} for Windows32.

997

* PC Compiling:: Compiling @command{gawk} for

998

Windows32.

995

999

* PC Using:: Running @command{gawk} on Windows32.

996

1000

* Cygwin:: Building and running @command{gawk}

997

1001

for Cygwin.

5004

5008

* Computed Regexps:: Using Dynamic Regexps.

5005

5009

* GNU Regexp Operators:: Operators specific to GNU software.

5006

5010

* Case-sensitivity:: How to do case-insensitive matching.

5007

* Strong Regexp Constants:: Strongly typed regexp constants.

5008

5011

* Regexp Summary:: Regular expressions summary.

5009

5012

@end menu

5010

5013

6265

6268

compatibility mode (@pxref{Options}).

6266

6269

Case is always significant in compatibility mode.

6267

6270

6268

@node Strong Regexp Constants

6269

@section Strongly Typed Regexp Constants

6270

6271

This @value{SECTION} describes a @command{gawk}-specific feature.

6272

6273

Regexp constants (@code{/@dots{}/}) hold a strange position in the

6274

@command{awk} language. In most contexts, they act like an expression:

6275

@samp{$0 ~ /@dots{}/}. In other contexts, they denote only a regexp to

6276

be matched. In no case are they really a ``first class citizen'' of the

6277

language. That is, you cannot define a scalar variable whose type is

6278

``regexp'' in the same sense that you can define a variable to be a

6279

number or a string:

6280

6281

@example

6282

num = 42 @ii{Numeric variable}

6283

str = "hi" @ii{String variable}

6284

re = /foo/ @ii{Wrong!} re @ii{is the result of} $0 ~ /foo/

6285

@end example

6286

6287

6271

@node Regexp Summary

6288

6272

@section Summary

6289

6273

10794

10778

@samp{11} in octal is 1 times 8 plus 1. This equals 9 in decimal.

10795

10779

In hexadecimal, there are 16 digits. Because the everyday decimal

10796

10780

number system only has ten digits (@samp{0}--@samp{9}), the letters

10797

@samp{a} through @samp{f} are used to represent the rest.

10781

@samp{a} through @samp{f} represent the rest.

10798

10782

(Case in the letters is usually irrelevant; hexadecimal @samp{a} and @samp{A}

10799

10783

have the same value.)

10800

10784

Thus, @samp{11} in

10926

10910

@node Using Constant Regexps

10927

10911

@subsection Using Regular Expression Constants

10928

10912

10913

Regular expression constants consist of text describing

10914

a regular expression enclosed in slashes (such as @code{/the +answer/}).

10915

This @value{SECTION} describes how such constants work in

10916

POSIX @command{awk} and @command{gawk}, and then goes on to describe

10917

@dfn{strongly typed regexp constants}, which are a @command{gawk} extension.

10918

10919

@menu

10920

* Standard Regexp Constants:: Regexp constants in standard @command{awk}.

10921

* Strong Regexp Constants:: Strongly typed regexp constants.

10922

@end menu

10923

10924

@node Standard Regexp Constants

10925

@subsubsection Standard Regular Expression Constants

10926

10929

10927

@cindex dark corner, regexp constants

10930

10928

When used on the righthand side of the @samp{~} or @samp{!~}

10931

10929

operators, a regexp constant merely stands for the regexp that is to be

11033

11031

a parameter to a user-defined function, because passing a truth value in

11034

11032

this way is probably not what was intended.

11035

11033

11034

@node Strong Regexp Constants

11035

@subsubsection Strongly Typed Regexp Constants

11036

11037

This @value{SECTION} describes a @command{gawk}-specific feature.

11038

11039

As we saw in the previous @value{SECTION},

11040

regexp constants (@code{/@dots{}/}) hold a strange position in the

11041

@command{awk} language. In most contexts, they act like an expression:

11042

@samp{$0 ~ /@dots{}/}. In other contexts, they denote only a regexp to

11043

be matched. In no case are they really a ``first class citizen'' of the

11044

language. That is, you cannot define a scalar variable whose type is

11045

``regexp'' in the same sense that you can define a variable to be a

11046

number or a string:

11047

11048

@example

11049

num = 42 @ii{Numeric variable}

11050

str = "hi" @ii{String variable}

11051

re = /foo/ @ii{Wrong!} re @ii{is the result of} $0 ~ /foo/

11052

@end example

11053

11054

For a number of more advanced use cases,

11055

it would be nice to have regexp constants that

11056

are @dfn{strongly typed}; in other words, that denote a regexp useful

11057

for matching, and not an expression.

11058

11059

@command{gawk} provides this feature. A strongly typed regexp constant

11060

looks almost like a regular regexp constant, except that it is preceded

11061

by an @samp{@@} sign:

11062

11063

@example

11064

re = @@/foo/ @ii{Regexp variable}

11065

@end example

11066

11067

Strongly typed regexp constants @emph{cannot} be used everywhere that a

11068

regular regexp constant can, because this would make the language even more

11069

confusing. Instead, you may use them only in certain contexts:

11070

11071

@itemize @bullet

11072

@item

11073

On the righthand side of the @samp{~} and @samp{!~} operators: @samp{some_var ~ @@/foo/}

11074

(@pxref{Regexp Usage}).

11075

11076

@item

11077

In the @code{case} part of a @code{switch} statement

11078

(@pxref{Switch Statement}).

11079

11080

@item

11081

As an argument to one of the built-in functions that accept regexp constants:

11082

@code{gensub()},

11083

@code{gsub()},

11084

@code{match()},

11085

@code{patsplit()},

11086

@code{split()},

11087

and

11088

@code{sub()}

11089

(@pxref{String Functions}).

11090

11091

@item

11092

As a parameter in a call to a user-defined function

11093

(@pxref{User-defined}).

11094

11095

@item

11096

On the righthand side of an assignment to a variable: @samp{some_var = @@/foo/}.

11097

In this case, the type of @code{some_var} is regexp. Additionally, @code{some_var}

11098

can be used with @samp{~} and @samp{!~}, passed to one of the built-in functions

11099

listed above, or passed as a parameter to a user-defined function.

11100

@end itemize

11101

11102

You may use the @code{typeof()} built-in function

11103

(@pxref{Type Functions})

11104

to determine if a variable or function parameter is

11105

a regexp variable.

11106

11107

The true power of this feature comes from the ability to create variables that

11108

have regexp type. Such variables can be passed on to user-defined functions,

11109

without the confusing aspects of computed regular expressions created from

11110

strings or string constants. They may also be passed through indirect function

11111

calls (@pxref{Indirect Calls})

11112

and on to the built-in functions that accept regexp constants.

11113

11114

When used in numeric conversions, strongly typed regexp variables convert

11115

to zero. When used in string conversions, they convert to the string

11116

value of the original regexp text.

11117

11036

11118

@node Variables

11037

11119

@subsection Variables

11038

11120

12213

12295

program runs, from @dfn{untyped} before any use,@footnote{@command{gawk}

12214

12296

calls this @dfn{unassigned}, as the following example shows.} to string

12215

12297

or number, and then from string to number or number to string, as the

12216

program progresses.

12298

program progresses. (@command{gawk} also provides regexp-typed scalars,

12299

but let's ignore that for now; @pxref{Strong Regexp Constants}.)

12217

12300

12218

12301

You can't do much with untyped variables, other than tell that they

12219

12302

are untyped. The following program tests @code{a} against @code{""}

19727

19810

@item "array"

19728

19811

@var{x} is an array.

19729

19812

19813

@item "regexp"

19814

@var{x} is a strongly typed regexp (@pxref{Strong Regexp Constants}).

19815

19730

19816

@item "number"

19731

19817

@var{x} is a number.

19732

19818

19784

19870

@end quotation

19785

19871

19786

19872

The @code{typeof()} function is general; it allows you to determine

19787

if a variable or function parameter is a scalar, an array.

19873

if a variable or function parameter is a scalar, an array, or a strongly

19874

typed regexp.

19788

19875

19789

19876

@code{isarray()} is deprecated; you should use @code{typeof()} instead.

19790

19877

You should replace any existing uses of @samp{isarray(var)} in your

32232

32319

* Symbol Table Access:: Functions for accessing global

32233

32320

variables.

32234

32321

* Array Manipulation:: Functions for working with arrays.

32235

* Redirection API:: How to access and manipulate redirections.

32322

* Redirection API:: How to access and manipulate

32323

redirections.

32236

32324

* Extension API Variables:: Variables provided by the API.

32237

32325

* Extension API Boilerplate:: Boilerplate code for using the API.

32238

32326

@end menu

32379

32467

32380

32468

@quotation NOTE

32381

32469

String values passed to an extension by @command{gawk} are always

32382

@sc{NUL}-terminated. Thus it is safe to pass such string values to

32470

@sc{nul}-terminated. Thus it is safe to pass such string values to

32383

32471

standard library and system routines. However, because

32384

@command{gawk} allows embedded @sc{NUL} characters in string data,

32472

@command{gawk} allows embedded @sc{nul} characters in string data,

32385

32473

you should check that @samp{strlen(@var{some_string})} matches

32386

32474

the length for that string passed to the extension before using

32387

32475

it as a regular C string.