tex

Documentation

Index

• Constants
• Variables
• func CompilationError(message string, cause error, extra KV) error
• func ExtendError(err error, extra KV)
• func InputError(message string, cause error, extra KV) error
• func IsCompilationError(err error) bool
• func IsInputError(err error) bool
• func IsQueueError(err error) bool
• func IsReferenceError(err error) bool
• func IsUnknownError(err error) bool
• func JobBaseDir() string
• func QueueError(message string, cause error, extra KV) error
• func ReferenceError(references []string) error
• func SetDefaultEngine(name string) error
• func SetJobBaseDir(dir string) error
• func SupportedEngines() (e []string)
• func UnknownError(message string, cause error, extra KV) error
• type Document
  • func NewDocument(log *zap.Logger, engine Engine, image string) Document
• type Engine
  • func NewEngine(name string, latexmkFlags ...string) Engine
  • func ParseEngine(name string) (Engine, error)
  • func (e Engine) Flags() []string
  • func (engine Engine) LatexmkCmd(main string) []string
  • func (e Engine) Name() string
  • func (e Engine) String() string
• type ErrInvalidWorkDir
  • func (err *ErrInvalidWorkDir) Error() string
  • func (err *ErrInvalidWorkDir) Unwrap() error
• type ErrUnsupportedEngine
  • func (err ErrUnsupportedEngine) Error() string
• type ErrWithCategory
  • func (err *ErrWithCategory) Error() string
  • func (err *ErrWithCategory) Extra() KV
  • func (err *ErrWithCategory) MarshalJSON() ([]byte, error)
  • func (err *ErrWithCategory) Unwrap() error
• type File
• type KV
• type Metrics

Constants

const Mark = "%!texd"

Mark is used to help identifying the main input file from a list of potential candidates. This is a last resort measurement, clients should specify main files explicitly.

Variables

var (
	DefaultEngine = engines[0]
)

var ForbiddenFiles = []string{

	"latexmkrc", ".latexmkrc",
}

ForbiddenFiles is a list of file names which are not allowed for security reasons.

var LatexmkDefaultFlags = []string{
	"-cd",
	"-silent",
	"-pv-", "-pvc-",
}

Functions

func CompilationError

func CompilationError(message string, cause error, extra KV) error

func ExtendError

func ExtendError(err error, extra KV)

ExtendError adds the given extra ke/value pairs to err, if err is a ErrWithCategory. If extra is empty or err is another type of error, this function does nothing.

func InputError

func InputError(message string, cause error, extra KV) error

func IsCompilationError

func IsCompilationError(err error) bool

func IsInputError

func IsInputError(err error) bool

func IsQueueError

func IsQueueError(err error) bool

func IsReferenceError

func IsReferenceError(err error) bool

func IsUnknownError

func IsUnknownError(err error) bool

func JobBaseDir

func JobBaseDir() string

func QueueError

func QueueError(message string, cause error, extra KV) error

func ReferenceError

func ReferenceError(references []string) error

func SetDefaultEngine

func SetDefaultEngine(name string) error

func SetJobBaseDir

func SetJobBaseDir(dir string) error

SetJobBaseDir will update the working directory for texd. If dir is empty, texd will fallback to os.TempDir(). The directory must exist, and it must be writable, otherwise a non-nil error is returned.

func SupportedEngines

func SupportedEngines() (e []string)

func UnknownError

func UnknownError(message string, cause error, extra KV) error

Types

type Document

type Document interface {
	// WorkingDirectory returns the path to a random directory, for
	// AddFile and NewWriter to place new files in it. Compilation will
	// usually happen by changing directory into it.
	//
	// On the first invocation, this will try to create a new, randomly
	// named directory.
	WorkingDirectory() (string, error)

	// AddFile saves the given content as a file in the document's
	// working directory, with the given name.
	//
	// The name is subject to strict validation, any deviation from the
	// rules will end in an InputError:
	//	- no duplicate files,
	//	- no funny characters,
	//	- only relative paths,
	//	- no directory traversal.
	// Additional rules may be imposed by the underlying file system.
	AddFile(name, contents string) error

	// NewWriter allows adding new files using an io.Writer. You MUST
	// call Close() on the returned handle.
	//
	// The name has the same restrictions as outlined in AddFile.
	NewWriter(name string) (io.WriteCloser, error)

	// Cleanup removes the working directory and any contents. You need
	// to read/copy the result PDF with GetResult() before cleaning up.
	Cleanup() error

	// Image declares which Docker image should be used when compiling
	// the sources. Optional and only relevant, when using the Docker
	// executor.
	Image() string

	// Engine defines the LaTeX engine to compile the document with.
	Engine() Engine

	// SetMainInput marks a previously added file (either through AddFile
	// or NewWriter) as main input file ("jobname") for LaTeX.
	//
	// It returns an error, if the file naming rules are violated (see
	// AddFile), or if it references an unknown file. In both cases,
	// no internal state is updated.
	//
	// On success, the MainInput() method will directly return the
	// given name, and stop guessing the main input file.
	SetMainInput(name string) error

	// MainInput tries to guess the main input file for the LaTeX
	// compiler. Candidates taken from .tex files in the root working
	// directory:
	//	- highest precedence have files starting with a "%!texd" mark
	//	- if none of those exists, use files with a \documentclass in the
	//	  first 1 KiB
	//	- if none of those exists, assume any remaining file could be
	//	  a main input file.
	// If in any step only one candidate is found, this return its name,
	// and an error otherwise.
	MainInput() (string, error)

	// GetResult returns a handle to read the compiled PDF. If MainInput()
	// returns an error, GetResult will wrap it in an InputError. If the
	// PDF file does not exist, GetResult will return a CompilationError.
	GetResult() (io.ReadCloser, error)

	// GetLogs returns a handle to read the TeX compiler logs. If MainInput()
	// returns an error, GetLogs will wrap it in an InputError. If the
	// log file does not exist, GetLogs will return a CompilationError.
	GetLogs() (io.ReadCloser, error)

	// Metrics reports file sizes.
	Metrics() Metrics
}

A Document outlines the methods needed to create a PDF file from TeX sources, within the context of TeX.

func NewDocument

func NewDocument(log *zap.Logger, engine Engine, image string) Document

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

func NewEngine

func NewEngine(name string, latexmkFlags ...string) Engine

func ParseEngine

func ParseEngine(name string) (Engine, error)

func (Engine) Flags

func (e Engine) Flags() []string

func (Engine) LatexmkCmd

func (engine Engine) LatexmkCmd(main string) []string

LatexmkCmd builds a command line for latexmk invocation.

func (Engine) Name

func (e Engine) Name() string

func (Engine) String

func (e Engine) String() string

type ErrInvalidWorkDir

type ErrInvalidWorkDir struct {
	// contains filtered or unexported fields
}

func (*ErrInvalidWorkDir) Error

func (err *ErrInvalidWorkDir) Error() string

func (*ErrInvalidWorkDir) Unwrap

func (err *ErrInvalidWorkDir) Unwrap() error

type ErrUnsupportedEngine

type ErrUnsupportedEngine string

func (ErrUnsupportedEngine) Error

func (err ErrUnsupportedEngine) Error() string

type ErrWithCategory

type ErrWithCategory struct {
	// contains filtered or unexported fields
}

func (*ErrWithCategory) Error

func (err *ErrWithCategory) Error() string

func (*ErrWithCategory) Extra

func (err *ErrWithCategory) Extra() KV

func (*ErrWithCategory) MarshalJSON

func (err *ErrWithCategory) MarshalJSON() ([]byte, error)

func (*ErrWithCategory) Unwrap

func (err *ErrWithCategory) Unwrap() error

type File

type File struct {
	// contains filtered or unexported fields
}

type KV

type KV map[string]interface{}

type Metrics

type Metrics struct {
	// TexFiles covers .tex, .sty, .cls and similar files.
	TexFiles []int
	// AssetFiles covers image files (.png, .jpg), font files (.ttf, .otf)
	// and other .pdf files.
	AssetFiles []int
	// DateFiles covers .csv, .xml and .json files.
	DataFiles []int
	// OtherFiles includes files not covered by other categories.
	OtherFiles []int
	// ResultFile covers the compiled PDF document. A value of -1
	// means that no PDF was produced.
	Result int
}

Metrics hold file sizes for input and output files. Each category field (TexFiles, AssetFiles, ...) is a slice with one size entry per file.