The parser.ini Reference Manual

Table of Contents

The parser.ini Reference Manual

This is the parser.ini Reference Manual, version 0.7.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 18:52:41 2020 GMT+0.

1 Introduction

#+TITLE:       parser.ini README
#+AUTHOR:      Jan Moringen
#+EMAIL:       jmoringe@techfak.uni-bielefeld.de
#+DESCRIPTION: Parser for ini-like configuration files with builder-based protocol.
#+KEYWORDS:    parser, ini, config, esrap
#+LANGUAGE:    en

* Introduction

  The =parser.ini= system provides a parser for the "ini-like" family
  of configuration syntaxes. A [[https://github.com/scymtym/architecture.builder-protocol][builder-based protocol]] is used to
  construct parse results.

  #+ATTR_HTML: :alt "build status image" :title Build Status :align right
  [[https://travis-ci.org/scymtym/parser.ini][https://travis-ci.org/scymtym/parser.ini.svg]]

* Tutorial

  To parse a string of configuration options and return the result as
  a simple list-based structure, the =parse= function is called with
  the symbol =list= instead of a more complicated builder object:

  #+BEGIN_SRC lisp :results value code :exports both
    (parser.ini:parse "[section] option = value" 'list)
  #+END_SRC

  #+RESULTS:
  #+BEGIN_SRC lisp

  ((:SECTION
    (:SECTION-OPTION
     (((:OPTION NIL :NAME ("option") :VALUE "value" :BOUNDS (10 . 24)))))
    :NAME ("section") :BOUNDS (0 . 9)))
  #+END_SRC

  Syntactic variants (comments, assignment operator, interpretation of
  whitespace in values, etc.) are controlled via special variables
  (note ~:~ instead of ~=~):

  #+BEGIN_SRC lisp :results value code :exports both
    (let ((parser.ini:*assignment-operator* #\:))
      (parser.ini:parse "[section] option: value" 'list))
  #+END_SRC

  #+RESULTS:
  #+BEGIN_SRC lisp

  ((:SECTION
    (:SECTION-OPTION
     (((:OPTION NIL :NAME ("option") :VALUE "value" :BOUNDS (10 . 23)))))
    :NAME ("section") :BOUNDS (0 . 9)))
  #+END_SRC

  The builder-based protocol allows constructing arbitrary result
  objects:

  #+BEGIN_SRC lisp :results value :exports both
    (defstruct located bounds)
    (defstruct (section (:include located)) name options)
    (defstruct (option (:include located)) name value)

    (defmethod architecture.builder-protocol:make-node
        ((builder (eql :my-builder)) (kind (eql :section)) &key name bounds)
      (make-section :name name :bounds bounds))

    (defmethod architecture.builder-protocol:relate
        ((builder  (eql :my-builder))
         (relation (eql :section-option))
         (left     section)
         (right    option)
         &key)
      (alexandria:appendf (section-options left) (list right))
      left)

    (defmethod architecture.builder-protocol:make-node
        ((builder (eql :my-builder)) (kind (eql :option)) &key name value bounds)
      (make-option :name name :value value :bounds bounds))

    (parser.ini:parse "[section] option = value" :my-builder)
  #+END_SRC

  #+RESULTS:
  : (#S(SECTION
  :     :BOUNDS (0 . 9)
  :     :NAME ("section")
  :     :OPTIONS (#S(OPTION :BOUNDS (10 . 24) :NAME ("option") :VALUE "value"))))
  : NIL
  : T

* TODO Reference


* Settings                                                         :noexport:

#+OPTIONS: H:2 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil todo:t pri:nil tags:not-in-toc

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 parser.ini

Maintainer

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

Author

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

License

LLGPLv3

Description

Provides parsing of Ini expressions.

Version

0.7.0

Dependencies

• alexandria
• let-plus (at least version 0.2)
• more-conditions (at least version 0.1.0)
• esrap (at least version 0.15)
• architecture.builder-protocol (at least version 0.1)
• parser.common-rules (at least version 0.1)

Source

parser.ini.asd (file)

Components

• src (module)
• readme.org (file)
• examples (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 parser.ini/src

Parent

parser.ini (system)

Location

src/

Components

• package.lisp (file)
• conditions.lisp (file)
• variables.lisp (file)
• protocol.lisp (file)
• grammar.lisp (file)

3.2 parser.ini/examples

Parent

parser.ini (system)

Location

examples/

Component

etc.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 parser.ini.asd

Location

parser.ini.asd

Systems

parser.ini (system)

4.1.2 parser.ini/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

parser.ini

4.1.3 parser.ini/src/conditions.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/conditions.lisp

Exported Definitions

• ini-parse-error (condition)
• ini-parse-error-location (method)
• ini-parse-error-source (method)

4.1.4 parser.ini/src/variables.lisp

Dependency

conditions.lisp (file)

Parent

src (module)

Location

src/variables.lisp

Exported Definitions

• *assignment-operator* (special variable)
• *comment-starter* (special variable)
• *include-empty-sections?* (special variable)
• *name-component-separator* (special variable)
• *value-terminating-whitespace-expression* (special variable)

4.1.5 parser.ini/src/protocol.lisp

Dependency

variables.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions

• parse (generic function)
• parse (method)
• parse (method)
• parse (method)
• parse (method)
• parse (method)

4.1.6 parser.ini/src/grammar.lisp

Dependency

protocol.lisp (file)

Parent

src (module)

Location

src/grammar.lisp

Internal Definitions

• parse-assignment-operator/expression (function)
• parse-name-component-separator/expression (function)

4.2 Static

4.2.1 parser.ini/README.org

Parent

parser.ini (system)

Location

README.org

4.2.2 parser.ini/examples/etc.lisp

Parent

examples (module)

Location

examples/etc.lisp

5 Packages

Packages are listed by definition order.

5.1 parser.ini

This package provides the main entry point

parse SOURCE BUILDER [generic function]

Parse the content of SOURCE as "ini-like" configuration
options, construct a parse result using BUILDER and return it.

The builder protocol consists of

architecture.builder-protocol:make-node BUILDER KIND &rest ARGS [generic function]

Create objects representing sections and options with
KIND :section and :option respectively.

architecture.builder-protocol:relate BUILDER RELATION LEFT RIGHT &rest ARGS [generic function]

Attach options to their containing sections with
relation :section-option.

Parsing may signal

ini-parse-error [condition]

Syntactic variants can be controlled by binding the special
variables

*comment-starter* [special variable]

Controls which character initiates a comment. Defaults to "#".

*assignment-expression* [special variable]

Controls assignment expression. Defaults to "=".

*value-terminating-whitespace-expression* [special variable]

Controls which whitespace terminates option values. By default,
all whitespace terminates option values.

Source

package.lisp (file)

Use List

• parser.common-rules
• more-conditions
• let-plus
• alexandria.1.0.0
• common-lisp

Exported Definitions

• *assignment-operator* (special variable)
• *comment-starter* (special variable)
• *include-empty-sections?* (special variable)
• *name-component-separator* (special variable)
• *value-terminating-whitespace-expression* (special variable)
• ini-parse-error (condition)
• ini-parse-error-location (generic function)
• ini-parse-error-location (method)
• ini-parse-error-source (generic function)
• ini-parse-error-source (method)
• parse (generic function)
• parse (method)
• parse (method)
• parse (method)
• parse (method)
• parse (method)

Internal Definitions

• parse-assignment-operator/expression (function)
• parse-name-component-separator/expression (function)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: *assignment-operator*

Controls the accepted assignment syntax. The default is the character "=".

Package

parser.ini

Source

variables.lisp (file)

Special Variable: *comment-starter*

Controls which character starts a comment. The default is ##.

If bound to either ## or #;, the respective character turns the rest of the current line into a comment.

If bound to ‘nil’, comments are disallowed.

Package

parser.ini

Source

variables.lisp (file)

Special Variable: *include-empty-sections?*

Controls whether empty sections, i.e. "section" in

[section]
[next section]

should be included in the parse result.

Package

parser.ini

Source

variables.lisp (file)

Special Variable: *name-component-separator*

Controls the syntax for separating name components. The default is the character ".".

Note the value nil corresponds to "no component separator" which leads to names not being split into components.

Package

parser.ini

Source

variables.lisp (file)

Special Variable: *value-terminating-whitespace-expression*

Controls which kinds of whitespace terminate option values. The default is :all which corresponds to any whitespace terminating the value of an option.

For some values of this variable, quoting has to be used when whitespace in option values is required.

Package

parser.ini

Source

variables.lisp (file)

6.1.2 Generic functions

Generic Function: ini-parse-error-location CONDITION

Package

parser.ini

Methods

Method: ini-parse-error-location (CONDITION ini-parse-error)

Source

conditions.lisp (file)

Generic Function: ini-parse-error-source CONDITION

Package

parser.ini

Methods

Method: ini-parse-error-source (CONDITION ini-parse-error)

Source

conditions.lisp (file)

Generic Function: parse SOURCE BUILDER &key START END JUNK-ALLOWED

Parse the content of SOURCE as "ini-like" configuration options, construct a parse result using BUILDER and return it.

START and END can be used to restrict parsing to a sub-sequence of SOURCE.

JUNK-ALLOWED controls whether an error is signaled when a successful parse does not consume the entire input in SOURCE (or the sub-sequence delimited by START and END).

Signal a ‘ini-parse-error’ when errors are encountered.

Package

parser.ini

Source

protocol.lisp (file)

Methods

Method: parse (SOURCE pathname) BUILDER &key START END JUNK-ALLOWED

Method: parse (SOURCE stream) BUILDER &key START END JUNK-ALLOWED

Method: parse (SOURCE string) BUILDER &key START END JUNK-ALLOWED

Method: parse SOURCE BUILDER &key START END JUNK-ALLOWED

Method: parse SOURCE BUILDER &key START END JUNK-ALLOWED around

6.1.3 Conditions

Condition: ini-parse-error ()

This error is signaled when parsing ini input fails.

Package

parser.ini

Source

conditions.lisp (file)

Direct superclasses

• chainable-condition (condition)
• parse-error (condition)

Direct methods

• ini-parse-error-location (method)
• ini-parse-error-source (method)

Direct slots

Slot: source

Stores the source string in which the parse error occurred.

Initargs

:source

Readers

ini-parse-error-source (generic function)

Slot: location

Stores the location at which the parse error occurred. The format is

(START . END)

where END can be nil

Initargs

:location

Initform

(quote nil)

Readers

ini-parse-error-location (generic function)

Direct Default Initargs

Initarg	Value
:source	(more-conditions:missing-required-initarg (quote parser.ini:ini-parse-error) :source)

6.2 Internal definitions

6.2.1 Functions

Function: parse-assignment-operator/expression TEXT START END

Package

parser.ini

Source

grammar.lisp (file)

Function: parse-name-component-separator/expression TEXT START END

Package

parser.ini

Source

grammar.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types