nucleus/library/textual/parser_bits.h

   1 #ifndef PARSER_BITS_CLASS
   2 #define PARSER_BITS_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : parser_bits                                                       *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19
  20 namespace textual {
  21
  22 //! Warehouses some functions that are often useful during text parsing.
  23
  24 class parser_bits
  25 {
  26 public:
  27   //! Line endings is an enumeration of the separator character(s) used for text files.
  28   /*!  on unix, every line in a text file has a line feed (LF) character appended to the line.
  29   on ms-dos and ms-windows, each line has a carriage return (CR) and line feed (LF) appended
  30   instead.  a synonym for the line_ending is "eol" which stands for "end of line".  */
  31   enum line_ending {
  32     LF_AT_END = -15,  //!< Unix standard is LF_AT_END ("\n").
  33     CRLF_AT_END,  //!< DOS standard is CRLF_AT_END ("\r\n").
  34     NO_ENDING  //!< No additional characters added as line endings.
  35   };
  36
  37   static const char *eol_to_chars(line_ending ending);
  38     //!< returns the C string form for the "ending" value.
  39
  40   static line_ending platform_eol();
  41     //!< provides the appropriate ending on the current OS platform.
  42
  43   static const char *platform_eol_to_chars();
  44     //!< provides the characters that make up this platform's line ending.
  45
  46   static void translate_CR_for_platform(basis::astring &to_translate);
  47     //!< flips embedded EOL characters for this platform's needs.
  48     /*!< runs through the string "to_translate" and changes any CR or CRLF
  49     combinations into the EOL (end-of-line) character that's appropriate
  50     for this operating system. */
  51
  52   static basis::astring substitute_env_vars(const basis::astring &text,
  53           bool leave_unknown = true);
  54     //!< resolves embedded environment variables in "text".
  55     /*!< replaces the names of any environment variables in "text" with the
  56     variable's value and returns the resulting string.  the variable names
  57     are marked by a single dollar before an alphanumeric identifier
  58     (underscores are valid), for example:  $PATH  if the "leave_unknown" flag
  59     is true, then any unmatched variables are left in the text with a question
  60     mark instead of a dollar sign.  if it's false, then they are simply
  61     replaced with nothing at all. */
  62
  63   static bool is_printable_ascii(char to_check);
  64     //!< returns true if "to_check" is a normally visible ASCII character.
  65     /*!< this is defined very simply by it being within the range of 32 to
  66     126.  that entire range should be printable in ASCII.  before 32 we have
  67     control characters.  after 126 we have potentially freakish looking
  68     characters.  this is obviously not appropriate for utf-8 or unicode. */
  69
  70   static bool white_space_no_cr(char to_check);
  71     //!< reports if "to_check" is white space but not a carriage return.
  72     /*!< returns true if the character "to_check" is considered a white space,
  73     but is not part of an end of line combo (both '\n' and '\r' are
  74     disallowed).  the allowed set includes tab ('\t') and space (' ') only. */
  75
  76   static bool is_eol(char to_check);
  77     //!< returns true if "to_check" is part of an end-of-line sequence.
  78     /*!< this returns true for both the '\r' and '\n' characters. */
  79
  80   static bool white_space(char to_check);
  81     //!< returns true if the character "to_check" is considered a white space.
  82     /*!< this set includes tab ('\t'), space (' '), carriage return ('\n'),
  83     and line feed ('\r'). */
  84
  85   static bool is_alphanumeric(char look_at);
  86     //!< returns true if "look_at" is one of the alphanumeric characters.
  87     /*!< This includes a to z in either case and 0 to 9. */
  88   static bool is_alphanumeric(const char *look_at, int len);
  89     //!< returns true if the char ptr "look_at" is all alphanumeric characters.
  90   static bool is_alphanumeric(const basis::astring &look_at, int len);
  91     //!< returns true if the string "look_at" is all alphanumeric characters.
  92
  93   static bool is_alpha(char look_at);
  94     //!< returns true if "look_at" is one of the alphabetical characters.
  95     /*!< This includes a to z in either case. */
  96   static bool is_alpha(const char *look_at, int len);
  97     //!< returns true if the char ptr "look_at" is all alphabetical characters.
  98   static bool is_alpha(const basis::astring &look_at, int len);
  99     //!< returns true if the string "look_at" is all alphabetical characters.
 100
 101   static bool is_numeric(char look_at);
 102     //!< returns true if "look_at" is a valid numerical character.
 103     /*! this allows the '-' character for negative numbers also (but only for
 104     first character if the char* or astring versions are used).  does not
 105     support floating point numbers or exponential notation yet. */
 106   static bool is_numeric(const char *look_at, int len);
 107     //!< returns true if "look_at" is all valid numerical characters.
 108   static bool is_numeric(const basis::astring &look_at, int len);
 109     //!< returns true if the "look_at" string has only valid numerical chars.
 110
 111   static bool is_hexadecimal(char look_at);
 112     //!< returns true if "look_at" is one of the hexadecimal characters.
 113     /*!< This includes a to f in either case and 0 to 9. */
 114   static bool is_hexadecimal(const char *look_at, int len);
 115     //!< returns true if "look_at" is all hexadecimal characters.
 116   static bool is_hexadecimal(const basis::astring &look_at, int len);
 117     //!< returns true if the string "look_at" is all hexadecimal characters.
 118
 119   static bool is_identifier(char look_at);
 120     //!< returns true if "look_at" is a valid identifier character.
 121     /*!< this just allows alphanumeric characters and underscore. */
 122   static bool is_identifier(const char *look_at, int len);
 123     //!< returns true if "look_at" is composed of valid identifier character.
 124     /*!< additionally, identifiers cannot start with a number. */
 125   static bool is_identifier(const basis::astring &look_at, int len);
 126     //!< like is_identifier() above but operates on a string.
 127 };
 128
 129 } //namespace.
 130
 131 #endif
 132