Contents

What does parse mean?

See Wikipedia:Parsing. See also the opposite: rendering.

How do we parse PSYC?

This is an instruction booklet on how to write a parser according to both the old and new PSYC syntax. The basic procedure is the same.

  1. You need two hashes, one for current variables, one for permanent ones. I'll call them cvars and pvars.
  2. You can save the object pointer of the current parser at creation time into an internal permanent variable, like this: pvars["_INTERNAL_origin"] = this;
  3. Receive an empty packet first. It's a dot (old) or pipe (new) on a line by itself.
  4. LOOP TOP: Enter the packet parsing loop.
  5. First thing you do is put a copy of the pvars into the cvars (careful to copy the actual data structures, not the reference).
  6. Look at your input line by line.
  7. Look at the first character on the line, is it an operator glyph?
  8. Handle the temporary variable prefixed by ":": Put the value into the appropriate cvars.
  9. Handle persistent variables prefixed by "=": Put its name and value into both pvars and cvars.
  10. Handle "+" by appending the value to the existing value, then copy it to both pvars and cvars. In fact the + and - operation changes depending on variable type, but we aren't using this yet.
  11. Handle "-" by removing the appropriate variable from both pvars and cvars. Real subtraction isn't defined yet, and we aren't using it.
  12. Ignore lines that start with "?", "!" or other as yet undefined glyph.
  13. You should encounter an empty line which separates PSYC's routing layer from PSYC's end-to-end layer (we call it entity layer). If the routing vars contained the _length variable, you should read that number of bytes into a buffer - it will contain the rest of the packet: entity vars, the method and the body. So in that case continue working with the buffer. Oh, while you're at it, make sure the following bytes after the buffer are the end-of-packet marker.
  14. If you are not the intended recipient of the packet (which you can now tell by looking at the routing header) you must have taken up the role of a router. You can now choose to route the packet without parsing the rest of it. If no content-length was given you will have to scan for the end-of-packet marker, which is a dot (old) or pipe (new) on a line by itself.
  15. Now you are in the entity header. You should again receive lines that begin with an operator, a variable name and optionally their value.
  16. Should you encounter any alphanumeric character, or the underscore "_", that's the method.
  17. Right after finding the method, stop looking at line beginnings, break out of your header parsing loop.
  18. If a content-length was given, the rest of the buffer will be your body. Otherwise put every following line of data into the body until you hit the terminating "." or "|" on its line by itself.
  19. Dispatch the newly parsed packet: Pass the method, body and cvars to the API. Routing and entity vars are usually merged at this point, since we are done routing.
  20. Now you can start your LOOP again from its TOP.

In order to support the old syntax what's missing here is list and line continuations.

For the new PSYC syntax you need to parse length-prefixed variables according to Spec:Packet instead of the obsoleted line and list continuations. And the new list syntaxes, of course.

<coyo> The syntax is rather beautiful, isnt it? ;3

Implementations

Let's look at some more parsers. Many of them are unfinished/prototypical, so use with care. Our web server however does not do any syntax highlighting. You may want to store the files and view them with your best editing technology. For LPC highlighting tips look here.

Spec:Packet compatible

Old Syntax