form.h

Go to the documentation of this file.

/* Copyright (C) 2026 Chris Piker <chris-piker@uiowa.edu>
 *
 * Author: C. Piker, via Claude Opus 5
 *
 * This file is part of das2C, the Core Das2 C Library.
 *
 * Das2C is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *
 * Das2C is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
 * more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 2.1 along with das2C; if not, see <http://www.gnu.org/licenses/>.
 */
 
/* Note this is a library-internal file, no stable public API is defined here */
 
#ifndef _das_form_h_
#define _das_form_h_
 
#include <das3/value.h>
#include <das3/units.h>
#include <das3/datum.h>
#include <das3/operator.h>
#include <das3/property.h>
 
/* Only to get the VARIDX_* index vocabulary.
   Nothing here uses generator functions or classes. */
#include <das3/generator.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* A formalism's named references -- a frame, a body, a center -- are plain
   strings stored on the form. */
#define DASFORM_NAME_SZ 64
 
struct das_buffer;
 
typedef struct das_form DasForm;
 
 
/* ========================================================================= *
 * das_operand: what a variable tells a form.
 * ========================================================================= */
 
typedef struct das_operand {
 
   /* The operand's formalism, carried so a form can recognize a partner by
      vtable address.  Peer to peer, never upward. */
   const DasForm* pForm;
 
   das_val_type   vtElem;       /* what one cell of this operand holds */
   das_units      units;
 
   /* The internal shape as DECLARED.  Rank matters and the product does not:
      a 3;3 rotation and a nine component vector share an element count and
      are not the same thing. */
   int            nIntRank;              /* 0 for a scalar, aIntShape untouched */
   ptrdiff_t      aIntShape[VARIDX_MAX];
 
} das_operand;
 
DAS_API size_t das_operand_elems(const das_operand* pThis);
 
 
/* ========================================================================= *
 * DasBinOp: the resolved recipe for one pairing.
 *
 * Handed back by binOpLeft/binOpRight once, at DasVarBin construction.  The
 * walker reads six facts off it and then calls apply() per item forever; it
 * never asks again what math made a value.
 *
 * Derived types carry whatever that pairing needs.  This is where a unit
 * conversion factor lives for linear, and a component permutation for
 * rotation -- private to the pairing that needs it, not a field every
 * formalism pays for.
 * ========================================================================= */
 
typedef struct das_binop DasBinOp;
 
typedef struct DasBinOp_VTbl {
 
   /* One item run from each side in, one item run out.  Item-at-a-time is
      the whole contract; see THE RULE above. */
   bool (*apply)(
      const DasBinOp* pThis, const ubyte* pLRun, const ubyte* pRRun,
      ubyte* pOutRun
   );
 
   void (*release)(DasBinOp* pThis);   /* derived storage, then free */
 
} DasBinOp_VTbl;
 
struct das_binop {
 
   const DasBinOp_VTbl* pVTbl;
 
   /* Everything the walker needs, settled once by the resolving form. */
   DasForm*     pForm;                    /* result formalism, owned here */
   das_units    units;
   das_val_type vtOut;
   int          nIntRank;                 /* result item shape; a rotation */
   ptrdiff_t    aIntShape[VARIDX_MAX];    /* applied to a vector SHRINKS it */
 
   int nRef;
};
 
typedef enum das_binop_stat_e {
   dbsDecline = 0,
   dbsOkay,
   dbsRefuse
} das_binop_stat;
 
DAS_API int  DasBinOp_incRef(DasBinOp* pThis);
DAS_API int  DasBinOp_decRef(DasBinOp* pThis);
 
#define DasBinOp_apply(P,L,R,O) ((P)->pVTbl->apply((P),(L),(R),(O)))
 
 
/* ========================================================================= *
 * DasForm, the base.
 * ========================================================================= */
 
typedef struct DasForm_VTbl {
 
   const char* sKind;          /* the wire kind= token, "vector", "rotation" */
 
   /* An unbound instance for setParam to fill.  Registering this in form.c's
      kind table is the ENTIRE footprint of a new formalism outside its own
      file; if it ever becomes more than that, this layer has failed. */
   DasForm* (*create)(void);
 
   /* Accept one <ops> attribute.  A form refuses a name it does not know: a
      reader that claims a kind must not skip a misspelled parameter. */
   DasErrCode (*setParam)(
      DasForm* pThis, const char* sName, const char* sVal
   );
 
   /* Is this form usable for a variable of this internal shape?
    *
    * Called once when the form is attached to a variable.
    *
    * Derived classes of DasForm need to check to see if all their required
    * parameters are initialize or the defaults are okay.  It's also the time
    * to see if the external world will hand-in element composites of the right
    * shape.  Basically the hand-shake agreement stage.
    *
    * NULL when a kind has nothing to insist on.  
    * @returns DAS_OKAY or error naming what is wrong. 
    */
   DasErrCode (*validate)(
      DasForm* pThis, int nIntRank, const ptrdiff_t* pIntShape
   );
 
   /* Read one formalism parameter. 
    *
    * @param pType, when not NULL, receives a DASPROP_* code in that
    * adheres to DasProp_type() return type.  For formalisms an parameter
    * names imply an explicit type, which is provided here.
    *
    * @returns NULL if this form has no such parameter.  The returned string 
    *   is owned by the form and lives as long as it does.
    */
   const char* (*getParam)(
      const DasForm* pThis, const char* sName, ubyte* pType
   );
 
   /* Emit <ops .../>.  TALKATIVE: state a parameter even at its default,
      since the schema cannot carry a default behind an anyAttribute. */
   DasErrCode (*encode)(
      const DasForm* pThis, struct das_buffer* pBuf
   );
 
   /* Read one item run into a typed datum.  NULL when the kind has no single
      datum form. */
   bool (*pack)(
      const DasForm* pThis, const das_operand* pOp, const ubyte* pRun,
      das_datum* pOut
   );
 
   /* The das_val_type a datum from this kind carries, vtUnknown to fall back
      to the element type. */
   das_val_type (*datumType)(const DasForm* pThis);
 
   /* Render one item run.  NULL means "no rendering of my own", and the
      caller falls back to printing the cells as plain numbers. */
   char* (*prnRun)(
      const DasForm* pThis, const ubyte* pRun, uint32_t nElems,
      das_val_type et, char* sBuf, int nLen
   );
 
   /* The canonical symbol for one component, in storage order.  NULL if this
    * kind has no named components, or none for that component.
    *
    * No shape argument.  A form is owned outright by one variable and was
    * handed that variable's intern= at validate(), so it already knows how
    * many components it is describing.
    */
   const char* (*compSym)(const DasForm* pThis, int iComp);
 
   /* Claim a pairing, or decline it for the other side to try.
    *
    * pThis is pL->pForm in the Left hook and pR->pForm in the Right one; it
    * rides along so every slot has the same shape.  The operands are NEVER
    * reordered by either hook, so an undefined pairing fails loud instead of
    * silently commuting.
    *
    * nOp is a D2BOP_* code from operator.h.  There is no separate formalism
    * op enum; the library already has one vocabulary for operators and
    * das_vt_merge() and Units_canMerge() both speak it.
    */
   das_binop_stat (*binOpLeft)(
      const DasForm* pThis, const das_operand* pL, int nOp,
      const das_operand* pR, DasBinOp** ppOut
   );
   das_binop_stat (*binOpRight)(
      const DasForm* pThis, const das_operand* pL, int nOp,
      const das_operand* pR, DasBinOp** ppOut
   );
 
   DasForm* (*copy)(const DasForm* pThis);
   void     (*release)(DasForm* pThis);
 
} DasForm_VTbl;
 
struct das_form {
   const DasForm_VTbl* pVTbl;
};
 
#define DasForm_kindStr(P) ((P)->pVTbl->sKind)
 
#define DasForm_isKind(P,VT)  (((P) != NULL)&&((P)->pVTbl == (VT)))
 
/* The vtable every unrecognized kind= binds to.  Exported so that its address
   can be compared.  Client code uses the DAS_FORM_EXT macro below and has no
   reason to name this directly. */
DAS_API extern const DasForm_VTbl das_form_generic_vtbl;
 
#define DAS_FORM_EXT (&das_form_generic_vtbl)
 
DAS_API const char* DasFormGeneric_kind(const DasForm* pThis);
 
DAS_API bool DasFormGeneric_paramAt(
   const DasForm* pThis, int iParam, const char** psName, const char** psVal
);
 
DAS_API void     del_DasForm(DasForm* pThis);
 
DAS_API DasForm* DasForm_copy(const DasForm* pThis);
 
DAS_API const char* DasForm_getParam(
   const DasForm* pThis, const char* sName, ubyte* pType
);
 
DAS_API DasForm* new_DasForm_pairs(const char** psAttr);
 
DAS_API const char* DasForm_compSym(const DasForm* pThis, int iComp);
 
DAS_API char* DasForm_prnRun(
   const DasForm* pThis, const ubyte* pRun, uint32_t nElems,
   das_val_type et, char* sBuf, int nLen
);
 
DAS_API char* DasForm_toStr(const DasForm* pThis, char* sBuf, int nLen);
 
DAS_API DasErrCode DasForm_validate(
   DasForm* pThis, int nIntRank, const ptrdiff_t* pIntShape
);
 
/* INTERNAL, shared by the formalisms that carry a component order.  Emits
   sysorder= when it says something the default does not: a non-ascending
   order, printed to the component count recorded when validate() was run. 
   
   Use sysorder= in XML headers when the order is not ascending.  pOrder is
   uComps entries long slot to canonical component, so this works for a nine
   element rotation as readily as a three element vector. */
DasErrCode _das_form_prnOrder(
   struct das_buffer* pBuf, const ubyte* pOrder, ubyte uComps
);
 
DAS_API const DasForm_VTbl* das_form_lookup(const char* sKind);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_form_h_ */