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

TemplatePlaceholder overview

This module implements a CVTemplatePlaceholder which constitutes the mutable parts of a CVTemplate (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, optionally converts the consumed part to a value of type T and, if successful, returns a success of that value and of what has not been consumed. In case of failure, it returns a failure.
  • 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 success of that string. Otherwise, it returns a failure

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>

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.Codec<T>
}) => Type<N, T>

number

CVTemplatePlaceholder instance that tries to parse/format a number according to the passed numberBase10Format.

Parsing: if numberBase10Format represents a base-10 number format with a fixed length of l (see CVTemplatePlaceholder.getFixedLength), the parser first reads l characters from the text and tries to convert them to a number in the given format. Otherwise it 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 number.

Formatting: the number is converted to a string according to numberBase10Format. If numberBase10Format represents a base-10 number format with a fixed length of l, the formatter will fail if the result of the conversion is not exactly l-characters long. Otherwise, the formatter never fails.

Signature

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

numberMappedLiterals

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

Signature

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

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 should be a strictly positive integer

Signature

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

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

getLabelledDescription

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

Signature

export declare const getLabelledDescription: (self: Any) => 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. Exists in two versions: a version where the postParser and preFormatter use the same type as the original parser and formatter. And a version where a conversion to another type T1 is implemented.

Signature

export declare const modify: {
  <T>({
    descriptorMapper,
    postParser,
    preFormatter
  }: {
    readonly descriptorMapper: MTypes.OneArgFunction<string>
    readonly postParser: MTypes.OneArgFunction<T, Result.Result<T, MInputError.Type>>
    readonly preFormatter: MTypes.OneArgFunction<T, Result.Result<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, Result.Result<T1, MInputError.Type>>
    readonly preFormatter: MTypes.OneArgFunction<T1, Result.Result<T, MInputError.Type>>
    readonly t1SchemaInstance: Schema.Codec<T1, T1>
  }): <const N extends string>(self: Type<N, T>) => Type<N, T1>
}

Getters

description

Returns the description property of self

Signature

export declare const description: (self: Any) => string

formatter

Returns the formatter property of self

Signature

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

label

Returns the label property of self

Signature

export declare const label: (self: Any) => string

name

Returns the name property of self

Signature

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

parser

Returns the parser property of self

Signature

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

tSchemaInstance

Returns the tSchemaInstance property of self

Signature

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

Models

Any (interface)

Type that represents a CVTemplatePlaceholder from and to any type

Signature

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

Type (class)

Type that represents a CVTemplatePlaceholder

Signature

export declare class Type<N, T> {
  protected constructor({ name, label, description, parser, formatter, tSchemaInstance }: MTypes.Data<Type<N, T>>)
}

make (static method)

Static constructor

Signature

static make<N extends string, T>(params: MTypes.Data<Type<N, T>>): Type<N, T>

[MData.idSymbol] (method)

Returns the id of this

Signature

[MData.idSymbol](): string | (() => string)

name (property)

Name of this TemplatePlaceholder

Signature

readonly name: N

label (property)

Label of this TemplatePlaceholder(usually the name prefixed with ‘#’)

Signature

readonly label: string

description (property)

Descriptor of this TemplatePlaceholder (used for debugging purposes)

Signature

readonly description: string

parser (property)

Parser of this TemplatePlaceholder

Signature

readonly parser: MTypes.OneArgFunction<string, Result.Result<readonly [consumed: T, leftOver: string], MInputError.Type>>

formatter (property)

Formatter of this TemplatePlaceholder

Signature

readonly formatter: MTypes.OneArgFunction<T, Result.Result<string, MInputError.Type>>

tSchemaInstance (property)

Schema instance that represents type T

Signature

readonly tSchemaInstance: Schema.Codec<T, T, never, never>

Module markers

moduleTag

Module tag

Signature

export declare const moduleTag: "@parischap/conversions/formatting/template/TemplatePart/TemplatePlaceholder/"

Utility types

ExtractName (type alias)

Utility type that extracts the Name type of a CVTemplatePlaceholder

Signature

export type ExtractName<P extends Any> = 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 Any> = P extends Type<string, infer T> ? T : never