search

SOF3 / InfoAPI

Placeholder registry and formatting API.
https://sof3.github.io/InfoAPI/defaults
Apache License 2.0
34 stars 6 forks source link

Parameterized Infos #15

Open SOF3 opened 2 years ago

SOF3 commented 2 years ago

Motivation

It is useful to be able to pass simple parameters, such as string and number literals, into the info resolution path. For example, {number add(1)} comes handy in many cases. This also allows to implement new info types like {stringList join(", ")}.

Goals

Non-goals

Design details

Parsing

Currently, the template syntax inside {} is defined as

template := "{" path ("|" path)* "}"
path := qualified_name (" " qualified_name)*
qualified_name := (TOKEN ".")* TOKEN

It is proposed that qualified_name be modified to

qualified_name := (TOKEN ".")* TOKEN parameter_list?
parameter_list := "(" (named_params | unnamed_params) ")"
named_params := TOKEN ":" param_value ("," TOKEN ":" param_value)*
unnamed_params := param_value ("," param_value)*
param_value := JSON_STRING_LITERAL | JSON_NUMBER_LITERAL

In particular, the parser must properly support ) and | inside string literals.

API

Add a new method provideParameterizedInfo, which takes a closure Closure(Info, Arguments): Info. Arguments is one of NamedArguments providing get(string $key) or UnnamedArguments providing get(int $index).

Possible enhancements

Use parameterized infos to implement the following new infos:

SOF3 commented 2 years ago

I think we only need StringListInfo for now. For other list types, it is too complex to support. I don't want to end up reinventing jq and have stuff like .players | map(.name).

Endermanbugzjfc commented 2 years ago

For anyone who is wondering, the syntax in the Parsing section is bnf.

This syntax is for psuedocoding and is not an actual language, Sofe:

search on Wikipedia, it's a syntax specification format

ghost commented 2 years ago

Motivation

It is useful to be able to pass simple parameters, such as string and number literals, into the info resolution path. For example, {number add(1)} comes handy in many cases. This also allows to implement new info types like {stringList join(", ")}.

Goals

  • Provide a way such that infos can take in extra, simple parameters
  • Perform minimal modification on the syntax to support parsing parameters, named or unnamed

Non-goals

  • This issue does not propose dynamic infos. That is, we do not intend to allow arbitrary info names. Info paths should still be statically analyzable so that Graph::pathFind continues to work. This also means return type of an info is fixed, invariant of the input parameters.
  • This issue does not intend to implement complex ASTs that could confuse readers. There are no plans to add recursive infos yet.
  • While this proposal allows lists to be implemented, there are no plans to implement generic infos.

Design details

Parsing

Currently, the template syntax inside {} is defined as

template := "{" path ("|" path)* "}"
path := qualified_name (" " qualified_name)*
qualified_name := (TOKEN ".")* TOKEN

It is proposed that qualified_name be modified to

qualified_name := (TOKEN ".")* TOKEN parameter_list?
parameter_list := "(" (named_params | unnamed_params) ")"
named_params := TOKEN ":" param_value ("," TOKEN ":" param_value)*
unnamed_params := param_value ("," param_value)*
param_value := JSON_STRING_LITERAL | JSON_NUMBER_LITERAL

In particular, the parser must properly support ) and | inside string literals.

API

Add a new method provideParameterizedInfo, which takes a closure Closure(Info, Arguments): Info. Arguments is one of NamedArguments providing get(string $key) or UnnamedArguments providing get(int $index).

Possible enhancements

Use parameterized infos to implement the following new infos:

  • NumberInfo add(number) -> NumberInfo
  • NumberInfo sub(number) -> NumberInfo
  • NumberInfo mul(number) -> NumberInfo
  • NumberInfo div(number) -> NumberInfo
  • NumberInfo reciprocal -> NumberInfo (such that {a reciprocal mul(b)} gives b / a)
  • NumberInfo mod(number) -> NumberInfo
  • NumberInfo imod(number) -> NumberInfo (mod with arguments flipped)
  • StringInfo wrapIfNonEmpty(prefix?: string, suffix?: string) -> StringInfo

what invariant mean

ghost commented 2 years ago

For anyone who is wondering, the syntax in Parsing section is bnf.

ok what bnf mean

ghost commented 2 years ago

I think we only need StringListInfo for now. For other list types, it is too complex to support. I don't want to end up reinventing jq and have stuff like .players | map(.name).

what jq mean

ghost commented 2 years ago

Motivation

It is useful to be able to pass simple parameters, such as string and number literals, into the info resolution path. For example, {number add(1)} comes handy in many cases. This also allows to implement new info types like {stringList join(", ")}.

Goals

  • Provide a way such that infos can take in extra, simple parameters
  • Perform minimal modification on the syntax to support parsing parameters, named or unnamed

Non-goals

  • This issue does not propose dynamic infos. That is, we do not intend to allow arbitrary info names. Info paths should still be statically analyzable so that Graph::pathFind continues to work. This also means return type of an info is fixed, invariant of the input parameters.
  • This issue does not intend to implement complex ASTs that could confuse readers. There are no plans to add recursive infos yet.
  • While this proposal allows lists to be implemented, there are no plans to implement generic infos.

Design details

Parsing

Currently, the template syntax inside {} is defined as

template := "{" path ("|" path)* "}"
path := qualified_name (" " qualified_name)*
qualified_name := (TOKEN ".")* TOKEN

It is proposed that qualified_name be modified to

qualified_name := (TOKEN ".")* TOKEN parameter_list?
parameter_list := "(" (named_params | unnamed_params) ")"
named_params := TOKEN ":" param_value ("," TOKEN ":" param_value)*
unnamed_params := param_value ("," param_value)*
param_value := JSON_STRING_LITERAL | JSON_NUMBER_LITERAL

In particular, the parser must properly support ) and | inside string literals.

API

Add a new method provideParameterizedInfo, which takes a closure Closure(Info, Arguments): Info. Arguments is one of NamedArguments providing get(string $key) or UnnamedArguments providing get(int $index).

Possible enhancements

Use parameterized infos to implement the following new infos:

  • NumberInfo add(number) -> NumberInfo
  • NumberInfo sub(number) -> NumberInfo
  • NumberInfo mul(number) -> NumberInfo
  • NumberInfo div(number) -> NumberInfo
  • NumberInfo reciprocal -> NumberInfo (such that {a reciprocal mul(b)} gives b / a)
  • NumberInfo mod(number) -> NumberInfo
  • NumberInfo imod(number) -> NumberInfo (mod with arguments flipped)
  • StringInfo wrapIfNonEmpty(prefix?: string, suffix?: string) -> StringInfo

Graph::pathFind

SOF3 commented 2 years ago

what invariant mean

oh I meant it doesn't depend on the parameters

what bnf mean

search on Wikipedia, it's a syntax specification format

what jq mean

a Linux command for manipulating JSON data

Graph::pathFind

what about tit?

also @keopiwauyu please don't quote the whole post

SOF3 commented 1 year ago

Parameterized infos will be available in v2: https://github.com/SOF3/InfoAPI/blob/v2-virion/src/ast.php