The parser.ini Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The parser.ini Reference Manual

This is the parser.ini Reference Manual, version 0.7.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 05:33:10 2022 GMT+0.

Table of Contents


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.


Previous: , Up: Systems   [Contents][Index]

2.1 parser.ini

Provides parsing of Ini expressions.

Maintainer

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

Author

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

License

LLGPLv3

Version

0.7.0

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

parser.ini.asd.

Child Components

3 Modules

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


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 parser.ini/src

Source

parser.ini.asd.

Parent Component

parser.ini (system).

Child Components

Previous: , Up: Modules   [Contents][Index]

3.2 parser.ini/examples

Source

parser.ini.asd.

Parent Component

parser.ini (system).

Child Component

etc.lisp (file).


4 Files

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


Next: , Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

4.1.1 parser.ini/parser.ini.asd

Source

parser.ini.asd.

Parent Component

parser.ini (system).

ASDF Systems

parser.ini.


4.1.2 parser.ini/src/package.lisp

Source

parser.ini.asd.

Parent Component

src (module).

Packages

parser.ini.


4.1.3 parser.ini/src/conditions.lisp

Dependency

package.lisp (file).

Source

parser.ini.asd.

Parent Component

src (module).

Public Interface

4.1.4 parser.ini/src/variables.lisp

Dependency

conditions.lisp (file).

Source

parser.ini.asd.

Parent Component

src (module).

Public Interface

4.1.5 parser.ini/src/protocol.lisp

Dependency

variables.lisp (file).

Source

parser.ini.asd.

Parent Component

src (module).

Public Interface

parse (generic function).


4.1.6 parser.ini/src/grammar.lisp

Dependency

protocol.lisp (file).

Source

parser.ini.asd.

Parent Component

src (module).

Internals

Previous: , Up: Files   [Contents][Index]

4.2 Static


4.2.1 parser.ini/README.org

Source

parser.ini.asd.

Parent Component

parser.ini (system).


4.2.2 parser.ini/examples/etc.lisp

Source

parser.ini.asd.

Parent Component

examples (module).


5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

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.

Use List
  • alexandria.
  • common-lisp.
  • let-plus.
  • more-conditions.
  • parser.common-rules.
Public Interface
Internals

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Public Interface


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.

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.

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.

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.

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.


6.1.2 Generic functions

Generic Reader: ini-parse-error-location (condition)
Package

parser.ini.

Methods
Reader Method: ini-parse-error-location ((condition ini-parse-error))
Source

conditions.lisp.

Target Slot

location.

Generic Reader: ini-parse-error-source (condition)
Package

parser.ini.

Methods
Reader Method: ini-parse-error-source ((condition ini-parse-error))
Source

conditions.lisp.

Target Slot

source.

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.

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 :around (source builder &key start end junk-allowed)

6.1.3 Conditions

Condition: ini-parse-error

This error is signaled when parsing ini input fails.

Package

parser.ini.

Source

conditions.lisp.

Direct superclasses
  • chainable-condition.
  • parse-error.
Direct methods
Direct Default Initargs
InitargValue
:source(missing-required-initarg (quote ini-parse-error) source)
Direct slots
Slot: source

Stores the source string in which the parse error occurred.

Initargs

:source

Readers

ini-parse-error-source.

Writers

This slot is read-only.

Slot: location

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

(START . END)

where END can be nil

Initform

(quote nil)

Initargs

:location

Readers

ini-parse-error-location.

Writers

This slot is read-only.


6.2 Internals


Previous: , Up: Internals   [Contents][Index]

6.2.1 Ordinary functions

Function: parse-assignment-operator/expression (text start end)
Package

parser.ini.

Source

grammar.lisp.

Function: parse-name-component-separator/expression (text start end)
Package

parser.ini.

Source

grammar.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   E   F   G   I   M   P   R   S   V  
Index Entry  Section

C
Condition, ini-parse-error: Public conditions
conditions.lisp: The parser․ini/src/conditions․lisp file

E
etc.lisp: The parser․ini/examples/etc․lisp file
examples: The parser․ini/examples module

F
File, conditions.lisp: The parser․ini/src/conditions․lisp file
File, etc.lisp: The parser․ini/examples/etc․lisp file
File, grammar.lisp: The parser․ini/src/grammar․lisp file
File, package.lisp: The parser․ini/src/package․lisp file
File, parser.ini.asd: The parser․ini/parser․ini․asd file
File, protocol.lisp: The parser․ini/src/protocol․lisp file
File, readme.org: The parser․ini/readme․org file
File, variables.lisp: The parser․ini/src/variables․lisp file

G
grammar.lisp: The parser․ini/src/grammar․lisp file

I
ini-parse-error: Public conditions

M
Module, examples: The parser․ini/examples module
Module, src: The parser․ini/src module

P
Package, parser.ini: The parser․ini package
package.lisp: The parser․ini/src/package․lisp file
parser.ini: The parser․ini system
parser.ini: The parser․ini package
parser.ini.asd: The parser․ini/parser․ini․asd file
protocol.lisp: The parser․ini/src/protocol․lisp file

R
readme.org: The parser․ini/readme․org file

S
src: The parser․ini/src module
System, parser.ini: The parser․ini system

V
variables.lisp: The parser․ini/src/variables․lisp file

Jump to:   C   E   F   G   I   M   P   R   S   V