.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "File::CountLines 3pm" .TH File::CountLines 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::CountLines \- efficiently count the number of line breaks in a file. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use File::CountLines qw(count_lines); \& my $no_of_lines = count_lines(\*(Aq/etc/passwd\*(Aq); \& \& # other uses \& my $carriage_returns = count_lines( \& \*(Aqpath/to/file.txt\*(Aq, \& style => \*(Aqcr\*(Aq, \& ); \& # possible styles are \*(Aqnative\*(Aq (the default), \*(Aqcr\*(Aq, \*(Aqlf\*(Aq .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" perlfaq5 answers the question on how to count the number of lines in a file. This module is a convenient wrapper around that method, with additional options. .PP More specifically, it counts the number of \fIline breaks\fR rather than lines. On Unix systems nearlly all text files end with a newline (by convention), so usually the number of lines and number of line breaks is equal. .PP Since different operating systems have different ideas of what a newline is, you can specifiy a \f(CW\*(C`style\*(C'\fR option, which can be one of the following values: .ie n .IP """native""" 4 .el .IP "\f(CWnative\fR" 4 .IX Item "native" This takes Perl's \f(CW\*(C`\en\*(C'\fR as the line separator, which should be the right thing in most cases. See perlport for details. This is the default. .ie n .IP """cr""" 4 .el .IP "\f(CWcr\fR" 4 .IX Item "cr" Take a carriage return as line separator (MacOS style) .ie n .IP """lf""" 4 .el .IP "\f(CWlf\fR" 4 .IX Item "lf" Take a line feed as line separator (Unix style) .ie n .IP """crlf""" 4 .el .IP "\f(CWcrlf\fR" 4 .IX Item "crlf" Take a carriage return followed by a line feed as separator (Microsoft Windows style) .PP Alternatively you can specify an arbitrary separator like this: .PP .Vb 1 \& my $lists = count_lines($file, separator => \*(Aq\eend{itemize}\*(Aq); .Ve .PP It is taken verbatim and searched for in the file. .PP The file is read in equally sized blocks. The size of the blocks can be supplied with the \f(CW\*(C`blocksize\*(C'\fR option. The default is 4096, and can be changed by setting \f(CW$File::CountLines::BlockSize\fR. .PP Do not use a block size smaller than the length of the separator, that might produce wrong results. (In general there's no reason to chose a smaller block size at all. Depending on your size a larger block size might speed up things a bit.) .SH "Character Encodings" .IX Header "Character Encodings" If you supply a separator yourself, it should not be a decoded string. .PP The file is read in binary mode, which implies that this module works fine for text files in ASCII-compatible encodings, including \&\s-1ASCII\s0 itself, \s-1UTF\-8\s0 and all the ISO\-8859\-* encodings (aka Latin\-1, Latin\-2, ...). .PP Note that the multi byte encodings like \s-1UTF\-32,\s0 UTF\-16le, UTF\-16be and \s-1UCS\-2\s0 encode a line feed character in a way that the \f(CW0x0A\fR byte is a substring of the encoded character, but if you search blindly for that byte you will get false positives. For example the \fI\s-1LATIN CAPITAL LETTER C WITH DOT ABOVE\s0\fR, U+010A has the byte sequence \f(CW\*(C`0x0A 0x01\*(C'\fR when encoded as UTF\-16le, so it would be counted as a newline. Even search for \&\f(CW\*(C`0x0A 0x00\*(C'\fR might give false positives. .PP So the summary is that for now you can't use this module in a meaningful way to count lines of text files in encodings that are not ASCII-compatible. If there's demand for, I can implement that though. .SH "Extending" .IX Header "Extending" You can add your own \s-1EOL\s0 styles by adding them to the \&\f(CW%File::CountLines::StyleMap\fR hash, with the name of the style as hash key and the separator as the value. .SH "AUTHOR" .IX Header "AUTHOR" Moritz Lenz , .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2008 by Moritz A. Lenz. This module is free software. You may use, redistribute and modify it under the same terms as perl itself. .PP Example code included in this package may be used as if it were in the Public Domain. .SH "DEVELOPMENT" .IX Header "DEVELOPMENT" You can obtain the latest development version from : .PP .Vb 1 \& git clone git://github.com/moritz/File\-CountLines.git .Ve