[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

NAME

tclyaml_devguide - TclYAML - The Developer's Guide

Table Of Contents
Synopsis
Description
Developing for TclYAML
- Directory structure
Bugs, Ideas, Feedback
Keywords
Category
Copyright

SYNOPSIS

package require Tcl 8.5
package require tclyaml ?0.5?

DESCRIPTION

Welcome to TclYAML, a binding to the C-based libyaml parser library for YAML Ain't Markup Language.

This document is a guide for developers working on TclYAML, i.e. maintainers fixing bugs, extending the package's functionality, etc.

Please read

first, if that was not done already. Here we assume that the sources are already available in a directory of your choice, and that you not only know how to build and install them, but also have all the necessary requisites to actually do so. The guide to the sources in particular also explains which source code management system is used, where to find it, how to set it up, etc.

Developing for TclYAML

Directory structure

Helpers
Documentation
- "doc/"
  
  This directory contains the documentation sources. The texts are written in doctools format.
- "embedded/"
  
  This directory contains the documentation converted to regular manpages (nroff), Markdown, and HTML. It is called embedded because these files, while derived, are part of the fossil repository, i.e. embedded into it. This enables fossil to access and display these files when serving the repositories' web interface. The "Command Reference" link at https://core.tcl-lang.org/akupries/tclyaml is, for example, accessing the generated Markdown.
Package Code, General structure
- "tclyaml.tcl"
  
  This is the master file of the package. Based on critcl (v3.1) it contain alls the necessary declarations to build the package.
- "policy.tcl"
  
  This is the companions to the "tclyaml.tcl" file which implements the higher-level interfaces on top of the C-based primitive operations, and determines policies.
  
  The documentation (see "doc/") mainly describes the higher-level API, plus the few primitives which are passed through unchanged, i.e. without getting wrapped into Tcl procedures.
- "ly_global.tcl"
  
  Common global code useful to both parsing and generator sides. Mainly the conversion of style values from and to Tcl strings.
- "ly_emitter.tcl"
  
  The generator side of the package, a critcl::class-based class whose instances can convert various Tcl data structures into proper YAML. This class is internal, the user only sees regular Tcl commands, which instantiate and destroy emitter objects as needed.
- "ly_parser.tcl"
  
  The low-level commands for parsing YAML, returning it in the form of various Tcl data structures. Plain commands, not object-based.
- "libyaml/"
  
  A copy of the libyaml 0.2.5 sources. Built as part of TclYAML.
Package Code, Per Package
- tclyaml
  - "tclyaml.tcl"
  - "policy.tcl"
  - "ly_emitter.tcl"
  - "ly_global.tcl"
  - "ly_parser.tcl"
- libyaml
  - "libyaml/"

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the TclYAML Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.

KEYWORDS

YAML, markup language, serialization