tl

README

tl

Package tl implements TL (Type Language) schema parser and writer. Inspired by grammers parser.

Used by gotd/td in code generation pipeline.

go get github.com/gotd/tl

Parsing

This program parses schema from stdin and prints all definitions with their names and types.

package main

import (
	"fmt"
	"os"

	"github.com/gotd/tl"
)

func main() {
	schema, err := tl.Parse(os.Stdin)
	if err != nil {
		panic(err)
	}
	for _, d := range schema.Definitions {
		fmt.Printf("%s#%x = %s;\n", d.Definition.Name, d.Definition.ID, d.Definition.Type)
	}
}

You can use it like that:

$ curl -s "https://raw.githubusercontent.com/tdlib/td/master/td/generate/scheme/td_api.tl" \
    | go run github.com/gotd/tl/cmd/tl-print \
    | less

Output:

double#2210c154 = Double;
string#b5286e24 = String;
int32#5cb934fa = Int32;
int53#6781c7ee = Int53;
int64#5d9ed744 = Int64;
bytes#e937bb82 = Bytes;
boolFalse#bc799737 = Bool;
boolTrue#997275b5 = Bool;
error#9bdd8f1a = Error;
ok#d4edbe69 = Ok;
tdlibParameters#d29c1d7b = TdlibParameters;

//...

Generating

You can also generate .tl file from tl.Schema. Any WriteTo result is valid input for Parse.

package main

import (
	"os"

	"github.com/gotd/tl"
)

func main() {
	def := tl.Definition{
		Name: "error",
		Type: tl.Type{Name: "Error"},
		// Currently you should always pass explicit ID.
		ID: 0x9bdd8f1a,
		Params: []tl.Parameter{
			{
				Name: "code",
				Type: tl.Type{Name: "int32", Bare: true},
			},
			{
				Name: "message",
				Type: tl.Type{Name: "string", Bare: true},
			},
		},
	}
	_, _ = tl.Schema{
		Definitions: []tl.SchemaDefinition{
			{
				Category:   tl.CategoryType,
				Definition: def,
			},
		},
	}.WriteTo(os.Stdout)
}

Output

error#9bdd8f1a code:int32 message:string = Error;

Documentation

Overview

Package tl implements TL schema parser and writer.

TL ("Type Language") is used in MTProto, Telegram binary protocol.

See https://core.telegram.org/mtproto/TL for reference.

Index

• Constants
• type Annotation
  • func (a Annotation) String() string
• type Category
  • func (c Category) MarshalText() ([]byte, error)
  • func (c Category) String() string
  • func (c *Category) UnmarshalText(text []byte) error
• type Class
• type Definition
  • func (d *Definition) Parse(line string) error
  • func (d Definition) String() string
• type Flag
  • func (f *Flag) Parse(s string) error
  • func (f Flag) String() string
• type Parameter
  • func (p Parameter) Conditional() bool
  • func (p *Parameter) Parse(s string) error
  • func (p Parameter) String() string
• type Schema
  • func Parse(reader io.Reader) (*Schema, error)
  • func (s Schema) WriteTo(w io.Writer) (int64, error)
• type SchemaDefinition
• type Type
  • func (p *Type) Parse(s string) error
  • func (p Type) String() string

Constants

const (
	// AnnotationDescription is description of definition or class.
	AnnotationDescription = "description"
	// AnnotationClass is annotation for class.
	AnnotationClass = "class"
	// AnnotationParamDescription is annotation for parameter named "description".
	AnnotationParamDescription = "param_description"
)

Common values for Annotation.Name.

Types

type Annotation

type Annotation struct {
	// Name of annotation.
	//
	// Can be:
	//	* "description" if Value is class or definition description
	//	* "class" if Value is class name, like //@class Foo @description Foo class
	//	* "param_description" if Value is description for "description" parameter
	//	Otherwise, it is description of Name parameter.
	Name string `json:"name"`
	// Value of annotation. Can be description or class name if Name is "class".
	Value string `json:"value"`
}

Annotation represents an annotation comment, like //@name value.

func (Annotation) String

func (a Annotation) String() string

type Category

type Category byte

Category of Definition.

const (
	CategoryType Category = iota
	CategoryFunction
)

func (Category) MarshalText

func (c Category) MarshalText() ([]byte, error)

func (Category) String

func (c Category) String() string

func (*Category) UnmarshalText

func (c *Category) UnmarshalText(text []byte) error

type Class

type Class struct {
	Name        string
	Description string
}

Class describes a non-bare Type with one or more constructors.

Example: `//@class InputChatPhoto @description Describes input chat photo`.

type Definition

type Definition struct {
	Namespace     []string    `json:"namespace,omitempty"`      // blank if global
	Name          string      `json:"name"`                     // name of definition, aka "predicate" or "method"
	ID            uint32      `json:"id"`                       // crc32(definition) or explicitly specified
	Params        []Parameter `json:"params,omitempty"`         // can be empty
	Type          Type        `json:"type"`                     // type of definition
	Base          bool        `json:"base,omitempty"`           // base type?
	GenericParams []string    `json:"generic_params,omitempty"` // like {T:Type}
}

Definition represents "Type Language" definition.

See https://core.telegram.org/mtproto/TL for reference.

func (*Definition) Parse

func (d *Definition) Parse(line string) error

Parse TL definition line like `foo#123 code:int name:string = Message;`.

func (Definition) String

func (d Definition) String() string

type Flag

type Flag struct {
	// Name of the parameter.
	Name string `json:"name"`
	// Index represent bit index.
	Index int `json:"index"`
}

Flag describes conditional parameter.

func (*Flag) Parse

func (f *Flag) Parse(s string) error

func (Flag) String

func (f Flag) String() string

type Parameter

type Parameter struct {
	// Name of Parameter.
	Name string `json:"name,omitempty"`
	// Type of Parameter.
	Type Type `json:"type"`
	// Flag specifies flag name and index if parameter is conditional.
	Flag *Flag `json:"flag,omitempty"`
	// Flags denotes whether Parameter is flags field (uint32).
	//
	// If true, Type and Flag are blank.
	Flags bool `json:"flags,omitempty"`
	// contains filtered or unexported fields
}

Parameter with Name and Type.

func (Parameter) Conditional

func (p Parameter) Conditional() bool

func (*Parameter) Parse

func (p *Parameter) Parse(s string) error

func (Parameter) String

func (p Parameter) String() string

type Schema

type Schema struct {
	Layer       int                `json:"layer,omitempty"`
	Definitions []SchemaDefinition `json:"definitions"`
	Classes     []Class            `json:"classes,omitempty"`
}

Schema represents single TL file with information about definitions and so called "Classes" aka non-bare types with one or multiple constructors.

func Parse

func Parse(reader io.Reader) (*Schema, error)

Parse reads Schema from reader.

Can return i/o or validation error.

func (Schema) WriteTo

func (s Schema) WriteTo(w io.Writer) (int64, error)

WriteTo writes whole schema to w, implementing io.WriterTo.

type SchemaDefinition

type SchemaDefinition struct {
	Annotations []Annotation `json:"annotations,omitempty"` // annotations (comments)
	Definition  Definition   `json:"definition"`            // definition
	Category    Category     `json:"category"`              // category of definition (function or type)
}

SchemaDefinition is annotated Definition with Category.

type Type

type Type struct {
	Namespace  []string `json:"namespace,omitempty"`   // namespace components of the type
	Name       string   `json:"name,omitempty"`        // the name of the type
	Bare       bool     `json:"bare,omitempty"`        // whether this type is bare or boxed
	Percent    bool     `json:"-"`                     // whether this type has percent in name (like %Message)
	GenericRef bool     `json:"generic_ref,omitempty"` // whether the type name refers to a generic definition
	GenericArg *Type    `json:"generic_arg,omitempty"` // generic arguments of the type
}

Type of a Definition or a Parameter.

func (*Type) Parse

func (p *Type) Parse(s string) error

func (Type) String

func (p Type) String() string