home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / libpics / csparse.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  10.0 KB  |  349 lines
  1.  
  2. /*  W3 Copyright statement 
  3. Copyright 1995 by: Massachusetts Institute of Technology (MIT), INRIA</H2>
  4.  
  5. This W3C software is being provided by the copyright holders under the
  6. following license. By obtaining, using and/or copying this software,
  7. you agree that you have read, understood, and will comply with the
  8. following terms and conditions: 
  9.  
  10. Permission to use, copy, modify, and distribute this software and its
  11. documentation for any purpose and without fee or royalty is hereby
  12. granted, provided that the full text of this NOTICE appears on
  13. <EM>ALL</EM> copies of the software and documentation or portions
  14. thereof, including modifications, that you make. 
  15.  
  16. <B>THIS SOFTWARE IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO
  17. REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE,
  18. BUT NOT LIMITATION, COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR
  19. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR
  20. THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY
  21. THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
  22. COPYRIGHT HOLDERS WILL BEAR NO LIABILITY FOR ANY USE OF THIS SOFTWARE
  23. OR DOCUMENTATION.
  24.  
  25. The name and trademarks of copyright holders may NOT be used
  26. in advertising or publicity pertaining to the software without
  27. specific, written prior permission.  Title to copyright in this
  28. software and any associated documentation will at all times remain
  29. with copyright holders. 
  30. */
  31. /*                                                                         Parser for libpics
  32.                                     PARSER FOR LIBPICS
  33.                                              
  34.  */
  35. /*
  36. **      (c) COPYRIGHT MIT 1996.
  37. **      Please first read the full copyright statement in the file COPYRIGH.
  38. */
  39. /*
  40.  
  41.    This module provides the interface to CSParse.c. The parser is used to parse labels,
  42.    machine-readable descriptions, and users. The application creates one of these and
  43.    iteratevely calls CSParse_parseChunk until it returns a done or an error.
  44.    
  45.  */
  46. #ifndef CSPARSE_H
  47. #define CSPARSE_H
  48. #include "cslutils.h"
  49. #include "htchunk.h"
  50. /*
  51.  
  52. NOWIN
  53.  
  54.    tells CSParse where it is in the task of tokenizing
  55.    
  56.  */
  57. typedef enum {
  58.     NowIn_INVALID = 0,
  59.     NowIn_NEEDOPEN,
  60.     NowIn_ENGINE,
  61.     NowIn_NEEDCLOSE,
  62.     NowIn_END,
  63.     NowIn_MATCHCLOSE,
  64.     NowIn_ERROR,
  65.     NowIn_CHAIN
  66.     } NowIn_t;
  67. /*
  68.  
  69.   Construction/Destruction
  70.   
  71.    The parse objects are never created by the application, but instead by one of the
  72.    objects that it is used to parse.
  73.    
  74.  */
  75. extern CSParse_t * CSParse_new(void);
  76. extern void CSParse_delete(CSParse_t * me);
  77. /*
  78.  
  79.   some handy definitions
  80.   
  81.  */
  82. #define LPAREN '('
  83. #define RPAREN ')'
  84. #define LCURLY '{'
  85. #define RCURLY '}'
  86. #define LBRACKET '['
  87. #define RBRACKET ']'
  88. #define SQUOTE 0x27 /* avoid confusing parens checking editors */
  89. #define DQUOTE 0x22
  90. #define LPARENSTR "("
  91. #define RPARENSTR ")"
  92. #define raysize(A) (sizeof(A)/sizeof(A[0]))
  93. /*
  94.  
  95.                                       SUBPARSER DATA
  96.                                              
  97. PUNCT
  98.  
  99.    valid punctuation
  100.    
  101.  */
  102. typedef enum {Punct_ZERO = 1, Punct_WHITE = 2, Punct_LPAREN = 4, 
  103.               Punct_WHITE_LPAREN = (Punct_WHITE|Punct_LPAREN),
  104.               Punct_RPAREN = 8, Punct_LPAREN_RPAREN = (Punct_LPAREN|Punct_RPAREN), 
  105.               Punct_WHITE_LPAREN_RPAREN = (Punct_WHITE|Punct_LPAREN|Punct_RPAREN), 
  106.               Punct_ALL = 0xf} Punct_t;
  107. /*
  108.  
  109. SUBSTATE
  110.  
  111.    Enumerated bits that are used to mark a parsing state. Because they are bits, as
  112.    opposed to sequential numbers, a StateToken may or more than one together and serve
  113.    more than one state. They must have identical outcomes if this is to be exploited.
  114.    
  115.    By convention, the following SubState names are used:
  116.    
  117.    X - has no state
  118.    
  119.    N - is a newly created object
  120.    
  121.    A-H - substate definitions. Because they are non-conflicting bits, a subparser may have
  122.    options that sit in more than state. For instance, the string "error" may be matched in
  123.    states A and C with:
  124.    
  125.    {"error test", SubState_A|SubState_C, Punct_LPAREN, 0, "error"} *probs* I meant to keep
  126.    these 16 bit caompatible, but ran up short at the end of one StateToken list. This can
  127.    be fixed if anyone needs a 16 bit enum.
  128.    
  129.  */
  130. typedef enum {SubState_X = -1, SubState_N = 0x4000, SubState_A = 1,
  131.               SubState_B = 2, SubState_C = 4, SubState_D = 8,
  132.               SubState_E = 0x10, SubState_F = 0x20, SubState_G = 0x40,
  133.               SubState_H = 0x80, SubState_I = 0x100} SubState_t;
  134. /*
  135.  
  136.    forward declaration for StateToken_t
  137.    
  138.  */
  139. typedef struct StateToken_s StateToken_t;
  140. /*
  141.  
  142. ENGINE
  143.  
  144.    called by CSParse to process tokens and punctuation
  145.    
  146.  */
  147. typedef NowIn_t Engine_t(CSParse_t * pCSParse, char demark, void * pVoid);
  148. /*
  149.  
  150.    Engine employed by the Label, MacRed, and User parsers
  151.    
  152.  */
  153. Engine_t CSParse_targetParser;
  154. /*
  155.  
  156. SUBSTATE METHODS
  157.  
  158.    All methods return a StateRet.
  159.    
  160.   Check
  161.   
  162.    see if a value is legitimate, may also record it
  163.    
  164.  */
  165. typedef StateRet_t Check_t(CSParse_t * pCSParse, StateToken_t * pStateToken,
  166.                            char * token, char demark);
  167. /*
  168.  
  169.    Punctuation checker to be employed by Check_t functions
  170.    
  171.  */
  172. extern BOOL Punct_badDemark(Punct_t validPunctuation, char demark);
  173. /*
  174.  
  175.   Open
  176.   
  177.    create a new data structure to be filled by the parser
  178.    
  179.  */
  180. typedef StateRet_t Open_t(CSParse_t * pCSParse, char * token, char demark);
  181. /*
  182.  
  183.   Close
  184.   
  185.    tell the state that the data structure is no longer current
  186.    
  187.  */
  188. typedef StateRet_t Close_t(CSParse_t * pCSParse, char * token, char demark);
  189. /*
  190.  
  191.   Prep
  192.   
  193.    get ready for next state
  194.    
  195.  */
  196. typedef StateRet_t Prep_t(CSParse_t * pCSParse, char * token, char demark);
  197. /*
  198.  
  199.   Destroy
  200.   
  201.    something went wrong, throw away the current object
  202.    
  203.  */
  204. typedef void Destroy_t(CSParse_t * pCSParse);
  205. /*
  206.  
  207. COMMAND
  208.  
  209.    substate commands
  210.    
  211.    open - call the open function for the current data structure
  212.    
  213.    close - call the close
  214.    
  215.    chain - call again on the next state without re-reading data
  216.    
  217.    notoken - clear the token before a chain (so next state just gets punct)
  218.    
  219.    matchany - match any string
  220.    
  221.  */
  222. typedef enum {Command_NONE = 0, Command_OPEN = 1, Command_CLOSE = 2,
  223.               Command_CHAIN = 4, Command_NOTOKEN = 8,
  224.               Command_CLOSE_CHAIN = (Command_CLOSE|Command_CHAIN),
  225.               Command_CHAIN_NOTOKEN = (Command_CHAIN|Command_NOTOKEN),
  226.               Command_CLOSE_CHAIN_NOTOKEN = (Command_CLOSE|Command_CHAIN|Command_NOTOKEN),
  227.               Command_MATCHANY = 0x10,
  228.               Command_MATCHANY_OPEN_CHAIN = (Command_MATCHANY|Command_OPEN|Command_CHAIN),
  229.               Command_MATCHANY_CLOSE = (Command_MATCHANY|Command_CLOSE),
  230.               Command_MATCHANY_CLOSE_CHAIN = (Command_MATCHANY|Command_CLOSE|Command_CHAIN),
  231.               } Command_t;
  232. /*
  233.  
  234. STATETOKEN STRUCTURE
  235.  
  236.    Contains all the information about what tokens are expected in what substates. The
  237.    StateTokens are kept in array referenced by a TargetObject.
  238.    
  239.  */
  240. struct StateToken_s {
  241.     char * note;                /* some usefull text that describes the state - usefulll f
  242. or debugging */
  243.     SubState_t validSubStates;
  244.     Punct_t validPunctuation;
  245.     Check_t * pCheck;   /* call this function to check token */
  246.     char * name1;       /* or compare to this name */
  247.     char * name2;               /* many strings have 2 spellings ("ratings" vs. "r") */
  248.     CSParseTC_t targetChange; /* whether target change implies diving or climbing from cur
  249. rent state */
  250.     TargetObject_t * pNextTargetObject;
  251.     SubState_t nextSubState;
  252.     Command_t command;  /* open, close, chain, etc. */
  253.     Prep_t * pPrep;             /* prepare for next state */
  254.     };
  255. /*
  256.  
  257. TARGETOBJECT STRUCTURE
  258.  
  259.    Methods and a lists of StateTokens associated with a data structure. The methods know
  260.    how to read data into current object and the StateTokens tell when to proceed to the
  261.    next object.
  262.    
  263.  */
  264. struct TargetObject_s {
  265.     char * note;
  266.     Open_t * pOpen;   /* call this function to open structure */
  267.     Close_t * pClose;   /* call this function to close structure */
  268.     Destroy_t * pDestroy;
  269.     StateToken_t * stateTokens; /* array of sub states */
  270.     int stateTokenCount;        /* number of sub states */
  271.     CSParseTC_t targetChange; /* target change signal for opening this parse state */
  272.     };
  273. /*
  274.  
  275. VALTARGET
  276.  
  277.  */
  278. typedef union {
  279.     BVal_t * pTargetBVal;
  280.     FVal_t * pTargetFVal;
  281.     SVal_t * pTargetSVal;
  282.     DVal_t * pTargetDVal;
  283.     HTList ** pTargetList;
  284.     } ValTarget_t;
  285. /*
  286.  
  287. VALTYPE
  288.  
  289.    Write down what value is to be read, and what type it is
  290.    
  291.  */
  292. typedef enum {ValType_NONE, ValType_BVAL, ValType_FVAL,
  293.               ValType_SVAL, ValType_DVAL,
  294.               ValType_COMMENT} ValType_t;
  295. /*
  296.  
  297. PARSECONTEXT
  298.  
  299.    Part of a CSParse. The boundry is a litte fuzzy. Maybe it should not exist.
  300.    
  301.  */
  302. typedef struct {
  303.     Engine_t * engineOf;
  304.     TargetChangeCallback_t * pTargetChangeCallback;
  305.     ParseErrorHandler_t * pParseErrorHandler;
  306.  
  307.     /* for reading [BFSD]Val_t */
  308.     ValTarget_t valTarget;
  309.     ValType_t valType;
  310.  
  311.     char * pTokenError;
  312.  
  313.     BOOL observeQuotes;
  314.     BOOL observedQuotes;
  315.     char * legalChars;
  316.     int legalCharCount;
  317.     } ParseContext_t;
  318. /*
  319.  
  320. CSPARSE STRUCTURE
  321.  
  322.    Full parser state and pointer to the object that it is reading.
  323.    
  324.  */
  325. struct CSParse_s {
  326.     char quoteState;
  327.     NowIn_t nowIn;
  328.     HTChunk * token;
  329.     char demark;
  330.     int offset;
  331.     int depth;
  332.     ParseContext_t * pParseContext;
  333.     union { /* all the types this parse engine fills */
  334.         CSMachRead_t * pCSMachRead; /* defined in CSMacRed.c */
  335.         CSLabel_t * pCSLabel; /* defined in CSLabel.c */
  336.         CSUser_t * pCSUser; /* defined in CSUser.c */
  337.         } target;
  338.     TargetObject_t * pTargetObject;
  339.     SubState_t currentSubState;
  340.     StateToken_t * pStateToken;
  341.     };
  342. /*
  343.  
  344.  */
  345. #endif /* CSPARSE_H */
  346. /*
  347.  
  348.    End of Declaration */
  349.