Return to pepsy.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/pepsy.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {Pepsy}\label{pepsy}
        !             4: The \man pepsy(1) program is a table-driven replacement for \pgm{pepy} and
        !             5: \pgm{posy}.
        !             6: At present,
        !             7: all three compilers are available as a part of the standard distribution.
        !             8: In the next major release,
        !             9: \pgm{pepy} and \pgm{posy} will remain,
        !            10: but most likely will not be installed by default.
        !            11: 
        !            12: The remainder of this chapter describes how to use \pgm{pepsy}.
        !            13: By virtue of having presented the preceeding two chapters,
        !            14: only a terse discussion is needed!
        !            15: 
        !            16: \section      {Abstract Syntax Module}
        !            17: As with \pgm{posy},
        !            18: the \pgm{pepsy} program reads a description of an {\em abstract syntax
        !            19: module\/}
        !            20: and produces the corresponding {\em C\/} structures along with several tables
        !            21: that define the mapping between the ASN.1 objects in the module and the
        !            22: {\em C\/} structures.
        !            23: This tables replaces the work done by the \pgm{pepy} program.
        !            24: 
        !            25: Note that unlike \pgm{posy},
        !            26: \pgm{pepsy} does not accept annotations in the abstract syntax module.
        !            27: It should be raw ASN.1,
        !            28: either entered by hand,
        !            29: or produced by the \pgm{rosy} program.
        !            30: Note that you must tell \pgm{rosy} when \pgm{pepsy} will be used.
        !            31: This is accomplished with the \switch"pepsy" option,
        !            32: e.g.,
        !            33: \begin{quote}\small\begin{verbatim}
        !            34: .ry.py:;          rosy -pepsy $(RYFLAGS) $<
        !            35: \end{verbatim}\end{quote}
        !            36: 
        !            37: \section      {PEPSY Environment}
        !            38: The \pgm{pepsy} program will produce two files after reading its abstract
        !            39: syntax module.
        !            40: 
        !            41: \subsection    {C Language Structures}
        !            42: For each type in the abstract syntax module,
        !            43: \pgm{pepy} will define a corresponding {\em C\/} language structure
        !            44: (\verb"struct"),
        !            45: using the same rules as \pgm{posy}
        !            46: (see Section~\ref{posy:c-struct} on page~\pageref{posy:c-struct}).
        !            47: 
        !            48: \subsection    {Mapping tables}
        !            49: In addition to the definition of {\em C\/} language structures,
        !            50: \pgm{pepsy} will generate a {\em C\/} file containing several tables that
        !            51: define the mapping between the structures and the corresponding ASN.1 objects.
        !            52: As this is entirely an automatic process,
        !            53: the contents of the tables are relatively unimportant.
        !            54: 
        !            55: \section      {Known Deficiences}
        !            56: \pgm{pepsy} uses essentially the same front-end as the \man posy(1) program,
        !            57: so it has some limitations in the ASN.1 syntax it can accept.
        !            58: Consult Section~\ref{posy:deficiencies} on page~\pageref{posy:deficiencies}
        !            59: for the details.
        !            60: 
        !            61: \section      {Running PEPSY}
        !            62: Here are a few things to know when running \pgm{pepsy}.
        !            63: 
        !            64: \subsection    {Options}
        !            65: The \pgm{pepsy} program has a few options to modify its behavior.
        !            66: 
        !            67: The \switch"A" switch directs \pgm{pepsy} to produce mapping tables for
        !            68: encoding, decoding, and printing.
        !            69: 
        !            70: The \switch"a" switch directs \pgm{pepy} to augment the \verb"#include" file
        !            71: it generates with commentary text.
        !            72: 
        !            73: The \switch"d" switch is a no-op with \pgm{pepsy},
        !            74: as it always ignores all \pgm{pepy}-style augmentations,
        !            75: including the 
        !            76: ``verbatim'' actions occuring at the very beginning and end of the module.
        !            77: 
        !            78: The \switch"f" switch directs \pgm{posy} to generate {\em C\/} macros to
        !            79: deallocate the structures it defines
        !            80: (e.g., for type \verb"type_MODULE_type",
        !            81: a macro called \verb"free_MODULE_type" is defined).
        !            82: 
        !            83: As with \pgm{posy},
        !            84: the \switch"h" switch enables additional heuristics when \pgm{pepsy} generates
        !            85: a {\em C\/} language structure definition.
        !            86: See Section~\ref{posy:options} on page~\pageref{posy:options}.
        !            87: 
        !            88: Normally, \pgm{posy} prints the name of each type as it works.
        !            89: The \switch"s" switch disables this behavior.
        !            90: 
        !            91: \subsection    {Makefiles}
        !            92: By convention,
        !            93: input files to \pgm{pepsy} have the extension \verb".py".
        !            94: In order to remain consistent with the naming scheme used by \pgm{posy},
        !            95: rather than starting with file \verb"module.py",
        !            96: we assume we are starting with file \verb"MODULE-asn.py".
        !            97: Let us arbitrarily select the file named \verb"MODULE-types.py" for the
        !            98: augmented abstract syntax module produced by \pgm{posy}.
        !            99: Hence
        !           100: \begin{quote}\begin{verbatim}
        !           101: pepsy MODULE-asn.py
        !           102: \end{verbatim}\end{quote}
        !           103: will produce:
        !           104: \begin{describe}
        !           105: \item[\verb"MODULE-types.h":]  the {\em C\/} language structures;
        !           106:                                and,
        !           107: 
        !           108: \item[\verb"MODULE_tables.c":] the mapping tables.
        !           109: \end{describe}
        !           110: 
        !           111: Our \man make(1) rules are:
        !           112: \begin{quote}\small\begin{verbatim}
        !           113: MODULE_tables.o:  MODULE_tables.c MODULE-types.h
        !           114: 
        !           115: MODULE_tables.c MODULE_tables.h: MODULE-asn.py
        !           116:                pepsy -A -f -h MODULE-asn.py
        !           117: \end{verbatim}\end{quote}

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.