Skip to main content Link Search Menu Expand Document (external link)
effect-libs

TemplatePlaceholder overview

This module implements a CVTemplatePlaceholder type which is one of the constituents of CVTemplate’s (see Template.ts and TemplatePart.ts)

Each CVTemplatePlaceholder defines a parser and a formatter:

  • The parser takes a text, consumes a part of that text, optionnally converts the consumed part to a value of type T and, if successful, returns a Right of that value and of what has not been consumed. In case of failure, it returns a Left.
  • The formatter takes a value of type T, converts it to a string (if T is not string), checks that the result is coherent and, if so, returns a Right of that string. Otherwise, it returns a Left

Table of contents

Constructors

anythingBut

This CVTemplatePlaceholder instance is a special case of the fulfilling CVTemplatePlaceholder instance. The parser of this Placeholder reads from the text until it meets one of the forbiddenChars passed as parameter (the result must be a non-empty string). The formatter only accepts a non-empty string that does not contain any of the forbidden chars and write it to the text. forbiddenChars should be an array of 1-character strings (will not throw otherwise but strange behaviors can be expected)

Signature

export declare const anythingBut: <const N extends string>({
  name,
  forbiddenChars
}: {
  readonly name: N
  readonly forbiddenChars: MTypes.OverOne<string>
}) => Type<N, string>

fixedLength

Builds a CVTemplatePlaceholder instance that parses/formats exactly length characters from a string. length must be a strictly positive integer.

Signature

export declare const fixedLength: <const N extends string>({
  name,
  length
}: {
  readonly name: N
  readonly length: number
}) => Type<N, string>

fixedLengthToReal

Same as fixedLength but the parser tries to convert the consumed text into a CVReal using the passed CVNumberBase10Format. The formatter takes a CVReal and tries to convert and write it as an n-character string. If the number to parse/format is less than length characters, fillChar is trimmed/padded between the sign and the number so that the length condition is respected. fillChar must be a one-character string (but no error is triggered if you do not respect that condition)

Signature

export declare const fixedLengthToReal: <const N extends string>(params: {
  readonly name: N
  readonly length: number
  readonly fillChar: string
  readonly numberBase10Format: CVNumberBase10Format.Type
}) => Type<N, CVReal.Type>

fulfilling

Builds a CVTemplatePlaceholder whose parser reads as much of the text as it can that fulfills the passed regular expression. The formatter only accepts a string that matches the passed regular expression and writes it into the text. regExp must start with the ^ character. Otherwise, the parser and formatter will not work properly.

Signature

export declare const fulfilling: <const N extends string>({
  name,
  regExp,
  regExpDescriptor
}: {
  readonly name: N
  readonly regExp: RegExp
  readonly regExpDescriptor: string
}) => Type<N, string>

make

Constructor

Signature

export declare const make: <const N extends string, T>(params: Omit<MTypes.Data<Type<N, T>>, "label">) => Type<N, T>

mappedLiterals

Builds a CVTemplatePlaceholder instance that works as a map:

The parser expects one of the keys of keyValuePairs and will return the associated value. The formatter expects one of the values of keyValuePairs and will return the associated key.

keyValuePairs should define a bijection (each key and each value must be present only once). It is best if the type of the values defines a toString method. Value equality is checked with The Effect Equal.equals function.

schemaInstance is a Schema instance that transforms a value of type T into a value of type T. It is an optional parameter. You need only provide it if you intend to use a CVTemplate built from this CVTemplatePlaceholder within the Effect.Schema module. In that case, you can build such a Schema with the Schema.declare function (if you don’t provide it, the Schema will return an error)

Signature

export declare const mappedLiterals: <const N extends string, T>({
  name,
  keyValuePairs,
  schemaInstance
}: {
  readonly name: N
  readonly keyValuePairs: ReadonlyArray<readonly [string, T]>
  readonly schemaInstance?: Schema.Schema<T, T>
}) => Type<N, T>

paddedFixedLength

Same as fixedLength but the consumed text is trimmed off of a fillChar at fillPosition and the written text is padded with a fillChar at fillPosition. fillChar should be a one-character string. length must be a strictly positive integer. See the meaning of disallowEmptyString in MString.trim

Signature

export declare const paddedFixedLength: <const N extends string>(params: {
  readonly name: N
  readonly length: number
  readonly fillChar: string
  readonly fillPosition: MString.FillPosition
  readonly disallowEmptyString: boolean
}) => Type<N, string>

real

Builds a CVTemplatePlaceholder whose parser reads from the text all the characters that it can interpret as a number in the provided numberBase10Format and converts the consumed text into a CVReal. The formatter takes a CVReal and converts it into a string according to the provided numberBase10Format.

Signature

export declare const real: <const N extends string>({
  name,
  numberBase10Format
}: {
  readonly name: N
  readonly numberBase10Format: CVNumberBase10Format.Type
}) => Type<N, CVReal.Type>

realMappedLiterals

Same as mappedLiterals but T is assumed to be CVReal which should be the most usual use case

Signature

export declare const realMappedLiterals: <const N extends string>(params: {
  readonly name: N
  readonly keyValuePairs: ReadonlyArray<readonly [string, CVReal.Type]>
}) => Type<N, CVReal.Type>

toEnd

This CVTemplatePlaceholder instance is another special case of the fulfilling CVTemplatePlaceholder instance. The parser of this CVTemplatePlaceholder reads all the remaining text. The formatter accepts any string and writes it. This CVTemplatePlaceholder should only be used as the last CVTemplatePart of a CVTemplate.

Signature

export declare const toEnd: <const N extends string>(name: N) => Type<N, string>

Destructors

description

Returns the description property of self

Signature

export declare const description: <const N extends string, T>(self: Type<N, T>) => string

formatter

Returns the formatter property of self

Signature

export declare const formatter: <const N extends string, T>(self: Type<N, T>) => Formatter.Type<T>

getLabelledDescription

Returns a description of self, e.g. “#dd: 2-character string left-padded with ‘0’ to unsigned integer.”

Signature

export declare const getLabelledDescription: <N extends string, T>(self: Type<N, T>) => string

label

Returns the label property of self

Signature

export declare const label: <const N extends string, T>(self: Type<N, T>) => string

modify

Returns a copy of self where a postParser function is executed after the parser of self and a preFormatter function is executed before the formatter of self

Signature

export declare const modify: {
  <T>({
    descriptorMapper,
    postParser,
    preFormatter
  }: {
    readonly descriptorMapper: MTypes.OneArgFunction<string>
    readonly postParser: MTypes.OneArgFunction<T, Either.Either<T, MInputError.Type>>
    readonly preFormatter: MTypes.OneArgFunction<T, Either.Either<T, MInputError.Type>>
  }): <const N extends string>(self: Type<N, T>) => Type<N, T>
  <T, T1>({
    descriptorMapper,
    postParser,
    preFormatter,
    t1SchemaInstance
  }: {
    readonly descriptorMapper: MTypes.OneArgFunction<string>
    readonly postParser: MTypes.OneArgFunction<T, Either.Either<T1, MInputError.Type>>
    readonly preFormatter: MTypes.OneArgFunction<T1, Either.Either<T, MInputError.Type>>
    readonly t1SchemaInstance: Schema.Schema<T1, T1>
  }): <const N extends string>(self: Type<N, T>) => Type<N, T1>
}

name

Returns the name property of self

Signature

export declare const name: <const N extends string, T>(self: Type<N, T>) => N

parser

Returns the parser property of self

Signature

export declare const parser: <const N extends string, T>(self: Type<N, T>) => Parser.Type<T>

tSchemaInstance

Returns the tSchemaInstance property of self

Signature

export declare const tSchemaInstance: <const N extends string, T>(self: Type<N, T>) => Schema.Schema<T, T>

Guards

has

Type guard

Signature

export declare const has: (u: unknown) => u is Type<string, unknown>

Models

All (interface)

Type that represents a CVTemplatePlaceholder from and to any type

Signature

export interface All extends Type<string, any> {}

Formatter (namespace)

Namespace of a Formatter

Type (interface)

Type that describes a Formatter

Signature

export interface Type<in T> extends MTypes.OneArgFunction<T, Either.Either<string, MInputError.Type>> {}

Parser (namespace)

Namespace of a Parser

Type (interface)

Type that describes a Parser

Signature

export interface Type<out T>
  extends MTypes.OneArgFunction<string, Either.Either<readonly [consumed: T, leftOver: string], MInputError.Type>> {}

Type (interface)

CVTemplatePlaceholder Type

Signature

export interface Type<out N extends string, in out T> extends MInspectable.Type, Pipeable.Pipeable {
  /** Name of this TemplatePlaceholder */
  readonly name: N

  /** Label of this TemplatePlaceholder(usually the name prefixed with '#') */
  readonly label: string

  /** Descriptor of this TemplatePlaceholder (used for debugging purposes) */
  readonly description: string

  /** Parser of this TemplatePlaceholder */
  readonly parser: Parser.Type<T>

  /** Formatter of this TemplatePlaceholder */
  readonly formatter: Formatter.Type<T>

  /** Schema instance that represents type T */
  readonly tSchemaInstance: Schema.Schema<T, T>

  /** @internal */
  readonly [_TypeId]: { readonly _N: Types.Covariant<N>; readonly _T: Types.Invariant<T> }
}

Module markers

moduleTag

Module tag

Signature

export declare const moduleTag: "@parischap/conversions/TemplatePlaceholder/"

Utility types

ExtractName (type alias)

Utility type that extracts the Name type of a CVTemplatePlaceholder

Signature

export type ExtractName<P extends All> = P extends Type<infer N, infer _> ? N : never

ExtractType (type alias)

Utility type that extracts the output type of a CVTemplatePlaceholder

Signature

export type ExtractType<P extends All> = P extends Type<string, infer T> ? T : never