{
    "content": [
        {
            "type": "text",
            "text": "# char (perldoc)\n\n## Sections\n\n- **Found in /usr/share/perl/5.34/pod/perlfaq4.pod**\n- **Found in /usr/share/perl/5.34/pod/perlfaq5.pod**\n- **Found in /usr/share/perl/5.34/pod/perlfaq6.pod**\n- **Found in /usr/share/perl/5.34/pod/perlfaq8.pod**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "char",
        "section": "-q",
        "mode": "perldoc",
        "summary": null,
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "Found in /usr/share/perl/5.34/pod/perlfaq4.pod",
                "lines": 79,
                "subsections": []
            },
            {
                "name": "Found in /usr/share/perl/5.34/pod/perlfaq5.pod",
                "lines": 127,
                "subsections": []
            },
            {
                "name": "Found in /usr/share/perl/5.34/pod/perlfaq6.pod",
                "lines": 76,
                "subsections": []
            },
            {
                "name": "Found in /usr/share/perl/5.34/pod/perlfaq8.pod",
                "lines": 31,
                "subsections": []
            }
        ],
        "sections": {
            "Found in /usr/share/perl/5.34/pod/perlfaq4.pod": {
                "content": "How do I remove consecutive pairs of characters?\n(contributed by brian d foy)\n\nYou can use the substitution operator to find pairs of characters (or\nruns of characters) and replace them with a single instance. In this\nsubstitution, we find a character in \"(.)\". The memory parentheses store\nthe matched character in the back-reference \"\\g1\" and we use that to\nrequire that the same thing immediately follow it. We replace that part\nof the string with the character in $1.\n\ns/(.)\\g1/$1/g;\n\nWe can also use the transliteration operator, \"tr///\". In this example,\nthe search list side of our \"tr///\" contains nothing, but the \"c\" option\ncomplements that so it contains everything. The replacement list also\ncontains nothing, so the transliteration is almost a no-op since it\nwon't do any replacements (or more exactly, replace the character with\nitself). However, the \"s\" option squashes duplicated and consecutive\ncharacters in the string so a character does not show up next to itself\n\nmy $str = 'Haarlem';   # in the Netherlands\n$str =~ tr///cs;       # Now Harlem, like in New York\n\nHow can I access or change N characters of a string?\nYou can access the first characters of a string with substr(). To get\nthe first character, for example, start at position 0 and grab the\nstring of length 1.\n\nmy $string = \"Just another Perl Hacker\";\nmy $firstchar = substr( $string, 0, 1 );  #  'J'\n\nTo change part of a string, you can use the optional fourth argument\nwhich is the replacement string.\n\nsubstr( $string, 13, 4, \"Perl 5.8.0\" );\n\nYou can also use substr() as an lvalue.\n\nsubstr( $string, 13, 4 ) =  \"Perl 5.8.0\";\n\nHow can I split a [character]-delimited string except when inside [character]?\nSeveral modules can handle this sort of parsing--Text::Balanced,\nText::CSV, Text::CSVXS, and Text::ParseWords, among others.\n\nTake the example case of trying to split a string that is\ncomma-separated into its different fields. You can't use \"split(/,/)\"\nbecause you shouldn't split if the comma is inside quotes. For example,\ntake a data line like this:\n\nSAR001,\"\",\"Cimetrix, Inc\",\"Bob Smith\",\"CAM\",N,8,1,0,7,\"Error, Core Dumped\"\n\nDue to the restriction of the quotes, this is a fairly complex problem.\nThankfully, we have Jeffrey Friedl, author of *Mastering Regular\nExpressions*, to handle these for us. He suggests (assuming your string\nis contained in $text):\n\nmy @new = ();\npush(@new, $+) while $text =~ m{\n\"([^\\\"\\\\]*(?:\\\\.[^\\\"\\\\]*)*)\",? # groups the phrase inside the quotes\n| ([^,]+),?\n| ,\n}gx;\npush(@new, undef) if substr($text,-1,1) eq ',';\n\nIf you want to represent quotation marks inside a\nquotation-mark-delimited field, escape them with backslashes (eg, \"like\n\\\"this\\\"\".\n\nAlternatively, the Text::ParseWords module (part of the standard Perl\ndistribution) lets you say:\n\nuse Text::ParseWords;\n@new = quotewords(\",\", 0, $text);\n\nFor parsing or generating CSV, though, using Text::CSV rather than\nimplementing it yourself is highly recommended; you'll save yourself odd\nbugs popping up later by just using code which has already been tried\nand tested in production for years.\n",
                "subsections": []
            },
            "Found in /usr/share/perl/5.34/pod/perlfaq5.pod": {
                "content": "How can I read a single character from a file? From the keyboard?\nYou can use the builtin \"getc()\" function for most filehandles, but it\nwon't (easily) work on a terminal device. For STDIN, either use the\nTerm::ReadKey module from CPAN or use the sample code in \"getc\" in\nperlfunc.\n\nIf your system supports the portable operating system programming\ninterface (POSIX), you can use the following code, which you'll note\nturns off echo processing as well.\n\n#!/usr/bin/perl -w\nuse strict;\n$| = 1;\nfor (1..4) {\nprint \"gimme: \";\nmy $got = getone();\nprint \"--> $got\\n\";\n}\nexit;\n\nBEGIN {\nuse POSIX qw(:termiosh);\n\nmy ($term, $oterm, $echo, $noecho, $fdstdin);\n\nmy $fdstdin = fileno(STDIN);\n\n$term     = POSIX::Termios->new();\n$term->getattr($fdstdin);\n$oterm     = $term->getlflag();\n\n$echo     = ECHO | ECHOK | ICANON;\n$noecho   = $oterm & ~$echo;\n\nsub cbreak {\n$term->setlflag($noecho);\n$term->setcc(VTIME, 1);\n$term->setattr($fdstdin, TCSANOW);\n}\n\nsub cooked {\n$term->setlflag($oterm);\n$term->setcc(VTIME, 0);\n$term->setattr($fdstdin, TCSANOW);\n}\n\nsub getone {\nmy $key = '';\ncbreak();\nsysread(STDIN, $key, 1);\ncooked();\nreturn $key;\n}\n}\n\nEND { cooked() }\n\nThe Term::ReadKey module from CPAN may be easier to use. Recent versions\ninclude also support for non-portable systems as well.\n\nuse Term::ReadKey;\nopen my $tty, '<', '/dev/tty';\nprint \"Gimme a char: \";\nReadMode \"raw\";\nmy $key = ReadKey 0, $tty;\nReadMode \"normal\";\nprintf \"\\nYou said %s, char number %03d\\n\",\n$key, ord $key;\n\nHow can I tell whether there's a character waiting on a filehandle?\nThe very first thing you should do is look into getting the\nTerm::ReadKey extension from CPAN. As we mentioned earlier, it now even\nhas limited support for non-portable (read: not open systems, closed,\nproprietary, not POSIX, not Unix, etc.) systems.\n\nYou should also check out the Frequently Asked Questions list in\ncomp.unix.* for things like this: the answer is essentially the same.\nIt's very system-dependent. Here's one solution that works on BSD\nsystems:\n\nsub keyready {\nmy($rin, $nfd);\nvec($rin, fileno(STDIN), 1) = 1;\nreturn $nfd = select($rin,undef,undef,0);\n}\n\nIf you want to find out how many characters are waiting, there's also\nthe FIONREAD ioctl call to be looked at. The *h2ph* tool that comes with\nPerl tries to convert C include files to Perl code, which can be\n\"require\"d. FIONREAD ends up defined as a function in the *sys/ioctl.ph*\nfile:\n\nrequire './sys/ioctl.ph';\n\n$size = pack(\"L\", 0);\nioctl(FH, FIONREAD(), $size)    or die \"Couldn't call ioctl: $!\\n\";\n$size = unpack(\"L\", $size);\n\nIf *h2ph* wasn't installed or doesn't work for you, you can *grep* the\ninclude files by hand:\n\n% grep FIONREAD /usr/include/*/*\n/usr/include/asm/ioctls.h:#define FIONREAD      0x541B\n\nOr write a small C program using the editor of champions:\n\n% cat > fionread.c\n#include <sys/ioctl.h>\nmain() {\nprintf(\"%#08x\\n\", FIONREAD);\n}\n^D\n% cc -o fionread fionread.c\n% ./fionread\n0x4004667f\n\nAnd then hard-code it, leaving porting as an exercise to your successor.\n\n$FIONREAD = 0x4004667f;         # XXX: opsys dependent\n\n$size = pack(\"L\", 0);\nioctl(FH, $FIONREAD, $size)     or die \"Couldn't call ioctl: $!\\n\";\n$size = unpack(\"L\", $size);\n\nFIONREAD requires a filehandle connected to a stream, meaning that\nsockets, pipes, and tty devices work, but *not* files.\n",
                "subsections": []
            },
            "Found in /usr/share/perl/5.34/pod/perlfaq6.pod": {
                "content": "How can I make \"\\w\" match national character sets?\nPut \"use locale;\" in your script. The \\w character class is taken from\nthe current locale.\n\nSee perllocale for details.\n\nHow can I match strings with multibyte characters?\nStarting from Perl 5.6 Perl has had some level of multibyte character\nsupport. Perl 5.8 or later is recommended. Supported multibyte character\nrepertoires include Unicode, and legacy encodings through the Encode\nmodule. See perluniintro, perlunicode, and Encode.\n\nIf you are stuck with older Perls, you can do Unicode with the\nUnicode::String module, and character conversions using the\nUnicode::Map8 and Unicode::Map modules. If you are using Japanese\nencodings, you might try using the jperl 5.00503.\n\nFinally, the following set of approaches was offered by Jeffrey Friedl,\nwhose article in issue #5 of The Perl Journal talks about this very\nmatter.\n\nLet's suppose you have some weird Martian encoding where pairs of ASCII\nuppercase letters encode single Martian letters (i.e. the two bytes \"CV\"\nmake a single Martian letter, as do the two bytes \"SG\", \"VS\", \"XX\",\netc.). Other bytes represent single characters, just like ASCII.\n\nSo, the string of Martian \"I am CVSGXX!\" uses 12 bytes to encode the\nnine characters 'I', ' ', 'a', 'm', ' ', 'CV', 'SG', 'XX', '!'.\n\nNow, say you want to search for the single character \"/GX/\". Perl\ndoesn't know about Martian, so it'll find the two bytes \"GX\" in the \"I\nam CVSGXX!\" string, even though that character isn't there: it just\nlooks like it is because \"SG\" is next to \"XX\", but there's no real \"GX\".\nThis is a big problem.\n\nHere are a few ways, all painful, to deal with it:\n\n# Make sure adjacent \"martian\" bytes are no longer adjacent.\n$martian =~ s/([A-Z][A-Z])/ $1 /g;\n\nprint \"found GX!\\n\" if $martian =~ /GX/;\n\nOr like this:\n\nmy @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;\n# above is conceptually similar to:     my @chars = $text =~ m/(.)/g;\n#\nforeach my $char (@chars) {\nprint \"found GX!\\n\", last if $char eq 'GX';\n}\n\nOr like this:\n\nwhile ($martian =~ m/\\G([A-Z][A-Z]|.)/gs) {  # \\G probably unneeded\nif ($1 eq 'GX') {\nprint \"found GX!\\n\";\nlast;\n}\n}\n\nHere's another, slightly less painful, way to do it from Benjamin\nGoldberg, who uses a zero-width negative look-behind assertion.\n\nprint \"found GX!\\n\" if    $martian =~ m/\n(?<![A-Z])\n(?:[A-Z][A-Z])*?\nGX\n/x;\n\nThis succeeds if the \"martian\" character GX is in the string, and fails\notherwise. If you don't like using (?<!), a zero-width negative\nlook-behind assertion, you can replace (?<![A-Z]) with (?:^|[^A-Z]).\n\nIt does have the drawback of putting the wrong thing in $-[0] and $+[0],\nbut this usually can be worked around.\n",
                "subsections": []
            },
            "Found in /usr/share/perl/5.34/pod/perlfaq8.pod": {
                "content": "How do I trap control characters/signals?\nYou don't actually \"trap\" a control character. Instead, that character\ngenerates a signal which is sent to your terminal's currently\nforegrounded process group, which you then trap in your process. Signals\nare documented in \"Signals\" in perlipc and the section on \"Signals\" in\nthe Camel.\n\nYou can set the values of the %SIG hash to be the functions you want to\nhandle the signal. After perl catches the signal, it looks in %SIG for a\nkey with the same name as the signal, then calls the subroutine value\nfor that key.\n\n# as an anonymous subroutine\n\n$SIG{INT} = sub { syswrite(STDERR, \"ouch\\n\", 5 ) };\n\n# or a reference to a function\n\n$SIG{INT} = \\&ouch;\n\n# or the name of the function as a string\n\n$SIG{INT} = \"ouch\";\n\nPerl versions before 5.8 had in its C source code signal handlers which\nwould catch the signal and possibly run a Perl function that you had set\nin %SIG. This violated the rules of signal handling at that level\ncausing perl to dump core. Since version 5.8.0, perl looks at %SIG after\nthe signal has been caught, rather than while it is being caught.\nPrevious versions of this answer were incorrect.\n",
                "subsections": []
            }
        }
    }
}