The parser.ini Reference Manual

Table of Contents

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

The parser.ini Reference Manual

This is the parser.ini Reference Manual, version 0.6.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:22:49 2018 GMT+0.


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

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 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


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

2 Systems

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


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

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.6.0

Dependencies
Source

parser.ini.asd (file)

Components

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

3 Modules

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


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

3.1 parser.ini/src

Parent

parser.ini (system)

Location

src/

Components

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

3.2 parser.ini/examples

Parent

parser.ini (system)

Location

examples/

Component

etc.lisp (file)


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

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 files   [Contents][Index]

4.1.1 parser.ini.asd

Location

parser.ini.asd

Systems

parser.ini (system)


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

4.1.2 parser.ini/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

parser.ini


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

4.1.3 parser.ini/src/conditions.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/conditions.lisp

Exported Definitions

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

4.1.4 parser.ini/src/variables.lisp

Dependency

conditions.lisp (file)

Parent

src (module)

Location

src/variables.lisp

Exported Definitions

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

4.1.5 parser.ini/src/protocol.lisp

Dependency

variables.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions

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

4.1.6 parser.ini/src/grammar.lisp

Dependency

protocol.lisp (file)

Parent

src (module)

Location

src/grammar.lisp

Internal Definitions

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

4.2 Other


Next: , Previous: , Up: Other files   [Contents][Index]

4.2.1 parser.ini/README.org

Parent

parser.ini (system)

Location

README.org


Previous: , Up: Other files   [Contents][Index]

4.2.2 parser.ini/examples/etc.lisp

Parent

examples (module)

Location

examples/etc.lisp


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

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

*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
Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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: *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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

Previous: , Up: Exported definitions   [Contents][Index]

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
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
InitargValue
:source(more-conditions:missing-required-initarg (quote parser.ini:ini-parse-error) :source)

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

6.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   M   O   P  
Index Entry  Section

F
File, Lisp, parser.ini.asd: The parser<dot>ini<dot>asd file
File, Lisp, parser.ini/src/conditions.lisp: The parser<dot>ini/src/conditions<dot>lisp file
File, Lisp, parser.ini/src/grammar.lisp: The parser<dot>ini/src/grammar<dot>lisp file
File, Lisp, parser.ini/src/package.lisp: The parser<dot>ini/src/package<dot>lisp file
File, Lisp, parser.ini/src/protocol.lisp: The parser<dot>ini/src/protocol<dot>lisp file
File, Lisp, parser.ini/src/variables.lisp: The parser<dot>ini/src/variables<dot>lisp file
File, other, parser.ini/examples/etc.lisp: The parser<dot>ini/examples/etc<dot>lisp file
File, other, parser.ini/README.org: The parser<dot>ini/readme<dot>org file

L
Lisp File, parser.ini.asd: The parser<dot>ini<dot>asd file
Lisp File, parser.ini/src/conditions.lisp: The parser<dot>ini/src/conditions<dot>lisp file
Lisp File, parser.ini/src/grammar.lisp: The parser<dot>ini/src/grammar<dot>lisp file
Lisp File, parser.ini/src/package.lisp: The parser<dot>ini/src/package<dot>lisp file
Lisp File, parser.ini/src/protocol.lisp: The parser<dot>ini/src/protocol<dot>lisp file
Lisp File, parser.ini/src/variables.lisp: The parser<dot>ini/src/variables<dot>lisp file

M
Module, parser.ini/examples: The parser<dot>ini/examples module
Module, parser.ini/src: The parser<dot>ini/src module

O
Other File, parser.ini/examples/etc.lisp: The parser<dot>ini/examples/etc<dot>lisp file
Other File, parser.ini/README.org: The parser<dot>ini/readme<dot>org file

P
parser.ini.asd: The parser<dot>ini<dot>asd file
parser.ini/examples: The parser<dot>ini/examples module
parser.ini/examples/etc.lisp: The parser<dot>ini/examples/etc<dot>lisp file
parser.ini/README.org: The parser<dot>ini/readme<dot>org file
parser.ini/src: The parser<dot>ini/src module
parser.ini/src/conditions.lisp: The parser<dot>ini/src/conditions<dot>lisp file
parser.ini/src/grammar.lisp: The parser<dot>ini/src/grammar<dot>lisp file
parser.ini/src/package.lisp: The parser<dot>ini/src/package<dot>lisp file
parser.ini/src/protocol.lisp: The parser<dot>ini/src/protocol<dot>lisp file
parser.ini/src/variables.lisp: The parser<dot>ini/src/variables<dot>lisp file

Jump to:   F   L   M   O   P  

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

A.2 Functions

Jump to:   F   G   I   M   P  
Index Entry  Section

F
Function, parse-assignment-operator/expression: Internal functions
Function, parse-name-component-separator/expression: Internal functions

G
Generic Function, ini-parse-error-location: Exported generic functions
Generic Function, ini-parse-error-source: Exported generic functions
Generic Function, parse: Exported generic functions

I
ini-parse-error-location: Exported generic functions
ini-parse-error-location: Exported generic functions
ini-parse-error-source: Exported generic functions
ini-parse-error-source: Exported generic functions

M
Method, ini-parse-error-location: Exported generic functions
Method, ini-parse-error-source: Exported generic functions
Method, parse: Exported generic functions
Method, parse: Exported generic functions
Method, parse: Exported generic functions
Method, parse: Exported generic functions
Method, parse: Exported generic functions

P
parse: Exported generic functions
parse: Exported generic functions
parse: Exported generic functions
parse: Exported generic functions
parse: Exported generic functions
parse: Exported generic functions
parse-assignment-operator/expression: Internal functions
parse-name-component-separator/expression: Internal functions

Jump to:   F   G   I   M   P  

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

A.3 Variables

Jump to:   *  
L   S  
Index Entry  Section

*
*assignment-operator*: Exported special variables
*name-component-separator*: Exported special variables
*value-terminating-whitespace-expression*: Exported special variables

L
location: Exported conditions

S
Slot, location: Exported conditions
Slot, source: Exported conditions
source: Exported conditions
Special Variable, *assignment-operator*: Exported special variables
Special Variable, *name-component-separator*: Exported special variables
Special Variable, *value-terminating-whitespace-expression*: Exported special variables

Jump to:   *  
L   S  

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

A.4 Data types

Jump to:   C   I   P   S  
Index Entry  Section

C
Condition, ini-parse-error: Exported conditions

I
ini-parse-error: Exported conditions

P
Package, parser.ini: The parser<dot>ini package
parser.ini: The parser<dot>ini system
parser.ini: The parser<dot>ini package

S
System, parser.ini: The parser<dot>ini system

Jump to:   C   I   P   S