expressions
Description
syside.experimental.expressions – expression templates and their model
encoding.
An expression template is an immutable value describing an expression tree:
literal() for a Python primitive, ref() for a reference to a model
element, op() for an operator application, call() for a function
invocation. Templates have no model identity, compare structurally and hash, so
they can be built once and reused, compared, and used as dictionary keys.
Python operator aliases are provided where the token, the precedence and the
meaning agree between Python and KerML: <, >, <=, >=, +,
-, *, / and %. == is not among them – it stays Python’s
structural comparison of two templates. The operators whose operands are
expressions go through op(), and the body operators select (.?{}) and
collect (.{}) through select() and collect() over a body()
of parameter() values; the classification and metadata operators
(istype, hastype, as, @, @@, meta, all), whose
second operand is a type, go through op() too and build a
TypeOperationTemplate.
instantiate() writes a template into a feature’s value position, creating
fresh model elements; decode() reads such a subgraph back out as a
template, raising UndecodableExpression for a subgraph no template
describes.
Both syside.experimental.builder and syside.experimental.query
build on this package – the constructors accept templates in expression
positions, and the accessors return them – and both re-export the names
above, so ordinary use needs no direct import from here.
Index
Classes
Raised when an expression subgraph corresponds to no template. |
||
An arrow invocation: the template form of |
||
A body parameter, |
||
A body, |
||
A collection, |
||
One end of a connector, |
||
A constructor: the template form of |
||
Base class of the immutable expression-template values. |
||
A feature chain read as a value: the template form of |
||
A feature chain |
||
A function named as an argument after |
||
The unbounded literal: the template form of |
||
A function invocation: the template form of |
||
A literal value: the template form of |
||
The metadata of a model element: the template form of |
||
A multiplicity |
||
The null expression: the template form of |
||
An operator application: the template form of |
||
A reference to a model element: the template form of |
||
A selection, |
||
A time or change trigger, |
||
An operator whose last operand is a type: the template form of |
Attributes
|
||
|
||
|
Functions
Decode an expression element into the template describing it. |
||
Decode a |
||
Decode a |
||
Instantiate |
||
Instantiate |
||
Instantiate |
||
Instantiate |
||
Instantiate |
||
Return the trigger |
||
Return the template for the arrow invocation |
||
Convert a template-valued argument to an |
||
Return the trigger |
||
Return the template for the body |
||
Return the template for the multiplicity |
||
Return the template invoking |
||
Return the template for the feature chain |
||
Return the template for the collection |
||
Return the template for one connector end, |
||
Return the template reading the feature chain |
||
Return the template naming |
||
Return the template for the Python primitive |
||
Return the template for the metadata of the model element |
||
Return the template for the constructor |
||
Return the template applying KerML |
||
Return the template for the body parameter |
||
Return the template referencing the model element |
||
Return the template for the selection |
||
Return the template for the sequence |
||
Return the trigger |
Attributes
- INFINITY: syside.experimental.expressions.InfinityTemplate = None
- NULL: syside.experimental.expressions.NullTemplate = None
Functions
- decode(expression: syside.Element) syside.experimental.expressions.ExpressionTemplate
Decode an expression element into the template describing it.
Handles what both the parser and
instantiate()produce: the four literal kinds,NullExpression,LiteralInfinity,FeatureReferenceExpression,OperatorExpressionover an operator inSUPPORTED_OPERATORS(itsIndexExpressionsubclass included),SelectExpressionandCollectExpressionover a body of one parameter and one result expression,FeatureChainExpression,InvocationExpressionandMetadataAccessExpression, a body (aFeatureReferenceExpressionowning anExpressionof parameters and one result expression) and the operators with a type operand. A reference to abody’s parameter decodes as the
parameter()that declares it. Anything else raisesUndecodableExpression.The operand walk uses
OperatorExpression.operands, which contracts theParameterMembership-> syntheticFeature->FeatureValuechain the parser puts between an operator expression and each of its arguments. A body operand (_WRAPPED_OPERANDS) is unwrapped from itsFeatureReferenceExpression; where the parser writes it as a plain argument (_PARSER_PLAIN_OPERANDS), the plain form decodes alike.Kind tests go through the core’s own checked cast,
try_cast, which returns the cast element orNone.- param expression:
The expression element to decode.
- returns:
The template describing
expression.- raises UndecodableExpression:
If no template describes
expression.
- decode_multiplicity(multiplicity: syside.MultiplicityRange) syside.experimental.expressions.MultiplicityTemplate
Decode a
MultiplicityRangeinto thebounds()template that writes it.- Parameters:
multiplicity – The multiplicity to read, as
declared_multiplicityreturns it.- Returns:
The multiplicity’s template.
- Raises:
UndecodableExpression – If the range has no bounds expression, or a bound is not an integer literal,
*or a feature reference.
- decode_trigger(expression: syside.Expression) syside.experimental.expressions.TriggerTemplate
Decode a
TriggerInvocationExpression: the inverse ofinstantiate_trigger().The one argument’s value is the time or the delay; for
whenit is the body wrapping the condition, read through the wrapper. A parsedwhenwrites the same wrapper.- Parameters:
expression – The payload parameter’s value.
- Returns:
The
TriggerTemplatedescribing it.- Raises:
UndecodableExpression – If
expressionis no trigger invocation, or its argument has a shape no template describes.
- instantiate(feature: syside.Feature, template: syside.experimental.expressions.ExpressionTemplate) syside.Expression
Instantiate
templateas thefeature_valueoffeature.Fresh model elements are created on every call: a template is a value, not a model fragment, so instantiating one twice yields two independent subgraphs. Any existing feature value is replaced.
- Parameters:
feature – The feature whose
feature_valueis written.template – The expression template to instantiate.
- Returns:
The newly created top-level expression element.
- instantiate_argument(slot: syside.experimental.expressions.ArgumentSlot, template: syside.experimental.expressions.ExpressionTemplate) syside.Expression
Instantiate
templateas the expression held directly inslot.Some expression positions of the abstract syntax hold the expression itself rather than a parameter feature carrying it as a value: the condition of an
iforwhile, anuntilclause, a transition’s guard, an analysis case’s result expression (ArgumentSlotlists the slots). This isinstantiate()for those slots. Fresh model elements are created on every call; any expression already in the slot is replaced.- Parameters:
slot – The expression-parameter slot to write.
template – The expression template to instantiate.
- Returns:
The newly created top-level expression element.
- instantiate_member(body: syside.NamespaceBody, membership: type[syside.experimental.expressions.MembershipT], template: syside.experimental.expressions.ExpressionTemplate) tuple[syside.experimental.expressions.MembershipT, syside.Expression]
Instantiate
templateas a new member ofbody, owned by amembership.Some body members of the abstract syntax are a membership owning an expression directly, with no feature between them: a package’s
filtermember is one. This isinstantiate()for those positions. Fresh model elements are created on every call, and the membership is appended after any the body already holds.The membership kind is passed as a class rather than derived, because the created expression’s kind comes from
templateand the pair must be created in one call.- Parameters:
body – The
childrenof the element to add the member to.membership – The membership element-kind to create.
template – The expression template to instantiate as its member.
- Returns:
The new membership and the newly created top-level expression.
- instantiate_multiplicity(slot: syside.OwnedMultiplicityAccessor, template: syside.experimental.expressions.MultiplicityTemplate) syside.MultiplicityRange
Instantiate
templateas the multiplicity held inslot.Creates the
MultiplicityRangeand its bounds expression: a..operator expression over the two bounds, or the one bound alone – what the core parses[1..*]and[4]to. Fresh model elements are created on every call; any multiplicity already in the slot is replaced.- Parameters:
slot – The feature’s
declared_multiplicity_member.template – The multiplicity, built by
bounds().
- Returns:
The newly created
MultiplicityRange.
- instantiate_trigger(feature: syside.Feature, template: syside.experimental.expressions.TriggerTemplate) syside.TriggerInvocationExpression
Instantiate
templateas thefeature_valueoffeature.The value is the
TriggerInvocationExpressionan accept action’s payload parameter holds foraccept at <time>,after <delay>orwhen <condition>. Its one argument is aParameterMembership->Feature->FeatureValue, as any argument’s; awhenargument’s value is the body SysML 2.1validateTriggerInvocationExpressionWhenArgumentrequires (the grammar’sArgumentExpressionMember): aFeatureReferenceExpressionowning the condition, as_append_branch()writes a branch. Fresh model elements are created on every call; any existing feature value is replaced.
- after(delay: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.TriggerTemplate
Return the trigger
after <delay>: accept once the durationdelayhas passed,after(op("[", 5, s))forafter 5 [s].SysML 2.1
validateTriggerInvocationExpressionAfterArgumentrequires the argument’s result to be aQuantities::ScalarQuantityValuewith a duration unit, which no literal is (after 5has no unit), so a literal is refused here rather than built.- Parameters:
delay – The duration, in any form
as_template()accepts.- Returns:
The
TriggerTemplate.- Raises:
ValueError – If
delayis a literal.
- arrow(source: syside.experimental.expressions.ExpressionLike, function: syside.Type, *arguments: syside.experimental.expressions.ExpressionLike | syside.experimental.expressions.FunctionReferenceTemplate, **named: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.ArrowInvocationTemplate
Return the template for the arrow invocation
<source>->function(...).arrow(s, f, b)iss->f(b),arrow(s, f, y=b)iss->f(y = b),arrow(s, collect_fn, body(i, result=i + 1))iss->collect {in i; i + 1}andarrow(s, reduce_fn, function_ref(g))iss->reduce g.sourceis the invocation’s first argument, given before the arrow (KerML 7.4.9.3); the others bind the remaining input parameters as incall(), either positionally or by name.- Parameters:
source – The first argument, canonicalized with
as_template().function – The invoked type.
arguments – The arguments after the function, canonicalized likewise, or one
function_ref().named – The named arguments, keyed by input-parameter name.
- Returns:
- Raises:
TypeError – If
functionis not asyside.Type.ValueError – If both positional and named arguments follow the function, a
function_ref()is not the sole argument, or a keyword names no input parameter offunction.
- as_template(value: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.ExpressionTemplate
Convert a template-valued argument to an
ExpressionTemplate.A template is returned unchanged, a bare model element becomes
ref(), a Python primitive becomesliteral(), and a feature chain becomesdot()from a reference to its first feature. Every function taking aExpressionLikeapplies this first, so the forms are interchangeable at a call site and build the same model.- Parameters:
value – A template, a bare model element, a Python primitive, or a feature chain.
- Returns:
The equivalent
ExpressionTemplate.- Raises:
TypeError – If
valueis of no accepted type.
- at(time: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.TriggerTemplate
Return the trigger
at <time>: accept once the time instanttimeis reached.SysML 2.1
validateTriggerInvocationExpressionAtArgumentrequires the argument’s result to conform toTime::TimeInstantValue, which no literal does, so a literal is refused here rather than built.- Parameters:
time – The time instant, in any form
as_template()accepts.- Returns:
The
TriggerTemplate.- Raises:
ValueError – If
timeis a literal.
- body(*parameters: syside.experimental.expressions.BodyParameterTemplate, result: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.BodyTemplate
Return the template for the body
{in <parameters>; <result>}.Instantiating it creates the parameters, in order, then the result expression, in which each
parameter()references the parameter of the nearest enclosing body declaring its name. A name no enclosing body declares raisesTypeErrorat instantiation, not here: the enclosing bodies are known only then.- Parameters:
parameters – The body’s
inparameters, built byparameter().result – The result expression, canonicalized with
as_template().
- Returns:
The
BodyTemplate, an expression wherever one is accepted, and the bodyselect()andcollect()take.- Raises:
TypeError – If a parameter is not a
BodyParameterTemplate.ValueError – If two parameters have one name.
- bounds(first: syside.experimental.expressions.BoundLike, second: syside.experimental.expressions.BoundLike | None = ...) syside.experimental.expressions.MultiplicityTemplate
Return the template for the multiplicity
[first]or[first..second].bounds(4)is[4],bounds(INFINITY)is[*],bounds(1, INFINITY)is[1..*]andbounds(0, n)is[0..n]. One bound is the upper bound, as in the textual syntax. Each bound is canonicalized to a template here, so the result compares equal to whatsyside.experimental.query.get_multiplicityreads back.- Parameters:
first – The lower bound, or the only bound.
second – The upper bound, or
Nonefor the one-bound form.
- Returns:
The
MultiplicityTemplateover the canonicalized bounds.- Raises:
TypeError – If a bound is not an
int, asyside.Feature,INFINITY, or a literal or reference template of one.ValueError – If an integer bound is negative.
- call(function: syside.Type, *arguments: syside.experimental.expressions.ExpressionLike, **named: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.InvocationTemplate
Return the template invoking
functionon the given arguments.Positional arguments bind the function’s input parameters in order, as
f(a, b)does; keyword arguments name them, asf(x=a, y=b)does, and are resolved here againstfunction’s input parameters (inputs). The textual syntax has one form or the other, so mixing them is refused.- Parameters:
function – The invoked type, a calculation definition or another
syside.Typewith input parameters.arguments – The positional arguments, canonicalized with
as_template().named – The named arguments, keyed by input-parameter name and canonicalized likewise.
- Returns:
The
InvocationTemplatefor the call.- Raises:
TypeError – If
functionis not asyside.Type.ValueError – If both positional and named arguments are given, or a keyword names no input parameter of
function(the message lists the parameters it has).
- chain(first: syside.Feature, second: syside.Feature, *rest: syside.Feature) syside.experimental.expressions.FeatureChainTemplate
Return the template for the feature chain
first.second(and on throughrest).Two features are the least a chain has, which the signature enforces: a chain of one would be the feature itself, and is passed as such.
- Parameters:
first – The feature the chain starts from.
second – A feature of
first’s type.rest – Further features, each of the previous one’s type.
- Returns:
The
FeatureChainTemplateover the features, in order.- Raises:
TypeError – If an argument is not a
syside.Feature.
- collect(source: syside.experimental.expressions.ExpressionLike, body: syside.experimental.expressions.BodyTemplate) syside.experimental.expressions.CollectTemplate
Return the template for the collection
<source>.<body>.collect(s, body(i, result=i + 1))iss.{in i; i + 1}: the body’s result for each value ofs.- Parameters:
source – The sequence collected over, canonicalized with
as_template().body – The expression evaluated per value, built by
body(), with one parameter.
- Returns:
The
CollectTemplate.- Raises:
TypeError – If
bodyis not aBodyTemplate.ValueError – If
bodyhas other than one parameter.
- connector_end(feature: syside.Feature, *, multiplicity: syside.experimental.expressions.MultiplicityTemplate | None = ..., name: str | None = ...) syside.experimental.expressions.ConnectorEndTemplate
Return the template for one connector end,
[<multiplicity>] <name> ::> <feature>.connector_end(a)isaandconnector_end(a, multiplicity=bounds(1), name="e1")is[1] e1 ::> a. A list of them is an n-ary connector’sends=:connect (a, b, d).- Parameters:
feature – The feature the end references. It keeps its own owner.
multiplicity – The end’s multiplicity, built by
bounds().name – The end’s declared name.
- Returns:
The
ConnectorEndTemplate.- Raises:
TypeError – If
featureis not asyside.Feature,multiplicitynot aMultiplicityTemplate, ornamenot astr.
- dot(source: syside.experimental.expressions.ExpressionLike, feature: syside.Feature, *rest: syside.Feature) syside.experimental.expressions.FeatureChainExpressionTemplate
Return the template reading the feature chain
source.feature(and on throughrest).dot(a, b)isa.b;dot(a, e, c)isa.e.c. The source is any expression, canonicalized withas_template(); the path is one or more features, each a feature of the previous one’s type.- Parameters:
source – The expression the path starts from.
feature – The first feature followed from it.
rest – Further features along the path.
- Returns:
The
FeatureChainExpressionTemplatefor the chain.- Raises:
TypeError – If a path entry is not a
syside.Feature.
- function_ref(function: syside.experimental.expressions.FunctionKind) syside.experimental.expressions.FunctionReferenceTemplate
Return the template naming
functionas the argument of an arrow invocation.arrow(s, reduce, function_ref(plus))iss->reduce RealFunctions::'+': the argument evaluates an anonymous expression typed byfunction.- Parameters:
function – The function named.
- Returns:
The
FunctionReferenceTemplate, accepted byarrow()as its sole argument.- Raises:
TypeError – If
functionis not aFunctionKind.
- literal(value: syside.experimental.expressions.LiteralValue) syside.experimental.expressions.LiteralTemplate
Return the template for the Python primitive
value.bool,int,floatandstrare accepted; they instantiate asLiteralBoolean,LiteralInteger,LiteralRationalandLiteralStringrespectively.- Parameters:
value – The Python primitive to wrap.
- Returns:
The
LiteralTemplatecarryingvalue.- Raises:
TypeError – If
valueis of any other type.
- metadata_of(element: syside.Element) syside.experimental.expressions.MetadataAccessTemplate
Return the template for the metadata of the model element
element.Instantiating it produces a
MetadataAccessExpressionnaming the element, which is whata.metadataparses to.- Parameters:
element – The model element whose metadata is accessed.
- Returns:
The
MetadataAccessTemplatenamingelement.- Raises:
TypeError – If
elementis not asyside.Element.
- new(type: syside.Classifier | syside.Feature | syside.experimental.expressions.FeatureChainTemplate, *arguments: syside.experimental.expressions.ExpressionLike, **named: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.ConstructorTemplate
Return the template for the constructor
new <type>(...).new(T)isnew T(),new(T, 1)isnew T(1),new(T, p=1)isnew T(p = 1)andnew(chain(a, b))isnew a.b(). It evaluates to one new instance oftype(KerML 7.4.9.4). Positional arguments bind the type’s public features in order, owned features first; keyword arguments name them, resolved here against the features oftype(of the chain’s last feature for a chain). The textual syntax has one form or the other, so mixing them is refused.- Parameters:
type – The instantiated classifier or feature, or a feature chain.
arguments – The positional arguments, canonicalized with
as_template().named – The named arguments, keyed by feature name and canonicalized likewise.
- Returns:
The
ConstructorTemplate.- Raises:
TypeError – If
typeis no classifier, feature or feature chain.ValueError – If both positional and named arguments are given, or a keyword names no feature of
type(the message lists the features it has).
- op(operator: syside.experimental.expressions.TypeAloneOperator, type_: syside.Type, /) syside.experimental.expressions.TypeOperationTemplate
Return the template applying KerML
operatortooperands.Only the operators in
SUPPORTED_OPERATORSare accepted, each with the operand count the grammar has for it, so an unsupported operator or a wrong operand count fails here rather than producing an expression subgraph that cannot be read back. The operands are in textual order:op("if", c, a, b)isif c ? a else b, andop("-", x)is the unary-x.The operators whose last operand is a type build a
TypeOperationTemplate:op("istype", x, T)isx istype T,op("istype", T)isistype T(self istype T, KerML 7.4.9.2; alsohastypeand@),op("as", x, T)isx as T,op("all", T)isall T, andop("@@", q, M)andop("meta", q, M)areq @@ Mandq meta M, whose first operand is the element whose metadata is tested, asyside.Elementor itsmetadata_of().- Parameters:
operator – The operator’s surface string (e.g.
"*","and","if","istype").operands – The operands, canonicalized with
as_template(), so plain literals and bare elements may be passed directly; a type operand is passed as thesyside.Typeitself.
- Returns:
The
OperationTemplateapplyingoperator, or theTypeOperationTemplatefor an operator with a type operand.- Raises:
ValueError – If
operatoris unsupported (the message names the accepted set) or if the operand count is not one the operator admits.TypeError – If a type operand is not a
syside.Type, or the first operand of@@ormetais not asyside.Elementor aMetadataAccessTemplate.
- op(operator: syside.experimental.expressions.OperandAndTypeOperator, operand: syside.experimental.expressions.ExpressionLike, type_: syside.Type, /) syside.experimental.expressions.TypeOperationTemplate
- op(operator: syside.experimental.expressions.MetadataOperator, element: syside.Element | syside.experimental.expressions.MetadataAccessTemplate, type_: syside.Type, /) syside.experimental.expressions.TypeOperationTemplate
- op(operator: syside.experimental.expressions.PlainOperator, *operands: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.OperationTemplate
- op(operator: str, *operands: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.OperationTemplate | syside.experimental.expressions.TypeOperationTemplate
- parameter(name: str, type: syside.Type | None = ...) syside.experimental.expressions.BodyParameterTemplate
Return the template for the body parameter
in <name> : <type>.The one value serves both roles the name has in the text: passed to
body()it declares the parameter, and inside the body’s result it references it, soi = parameter("i", Integer)thenbody(i, result=i > 0)is{in i : Integer; i > 0}.- Parameters:
name – The parameter’s name.
type – The parameter’s type, or
Nonefor an untyped parameter.
- Returns:
- Raises:
TypeError – If
nameis not astrortypeis neither asyside.TypenorNone.ValueError – If
nameis empty.
- ref(element: syside.Element) syside.experimental.expressions.ReferenceTemplate
Return the template referencing the model element
element.Instantiating it produces a
FeatureReferenceExpressionnaming the element, which is what= xparses to.- Parameters:
element – The model element to reference.
- Returns:
The
ReferenceTemplatenamingelement.- Raises:
TypeError – If
elementis not asyside.Element.
- select(source: syside.experimental.expressions.ExpressionLike, body: syside.experimental.expressions.BodyTemplate) syside.experimental.expressions.SelectTemplate
Return the template for the selection
<source>.?<body>.select(s, body(i, result=i > 0))iss.?{in i; i > 0}: the values ofsfor which the body is true.- Parameters:
source – The sequence selected from, canonicalized with
as_template().body – The condition, built by
body(), with one parameter.
- Returns:
The
SelectTemplate.- Raises:
TypeError – If
bodyis not aBodyTemplate.ValueError – If
bodyhas other than one parameter.
- sequence(first: syside.experimental.expressions.ExpressionLike, second: syside.experimental.expressions.ExpressionLike, *rest: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.OperationTemplate
Return the template for the sequence
(first, second, ...).A sequence is the
,operator over two or more items, which is what the signature enforces: a sequence of one is the item itself, and()is the null expression, which no template describes.sequence(a, b, c)isop(",", a, b, c).- Parameters:
first – The first item, canonicalized with
as_template().second – The second item, likewise.
rest – Further items.
- Returns:
The
OperationTemplateapplying,.
- when(condition: syside.experimental.expressions.ExpressionLike) syside.experimental.expressions.TriggerTemplate
Return the trigger
when <condition>: accept onceconditionbecomes true.SysML 2.1
validateTriggerInvocationExpressionWhenArgumentrequires the argument to be a Boolean-valued expression. Instantiation writes it as the body the constraint asks for (aFeatureReferenceExpressionto an expression whose result iscondition); pass the condition itself. A literal other thanTrueorFalseis refused here rather than built.- Parameters:
condition – The Boolean condition, in any form
as_template()accepts.- Returns:
The
TriggerTemplate.- Raises:
ValueError – If
conditionis a literal that is not abool.