Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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.
Next: Systems, Previous: The parser.ini Reference Manual, Up: The parser.ini Reference Manual [Contents][Index]
#+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
Next: Modules, Previous: Introduction, Up: The parser.ini Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Provides parsing of Ini expressions.
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
LLGPLv3
0.7.0
Next: Files, Previous: Systems, Up: The parser.ini Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
Next: parser.ini/examples, Previous: Modules, Up: Modules [Contents][Index]
parser.ini (system).
Previous: parser.ini/src, Up: Modules [Contents][Index]
parser.ini (system).
etc.lisp (file).
Next: Packages, Previous: Modules, Up: The parser.ini Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: parser.ini/src/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
parser.ini (system).
Next: parser.ini/src/conditions.lisp, Previous: parser.ini/parser.ini.asd, Up: Lisp [Contents][Index]
src (module).
Next: parser.ini/src/variables.lisp, Previous: parser.ini/src/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
src (module).
Next: parser.ini/src/protocol.lisp, Previous: parser.ini/src/conditions.lisp, Up: Lisp [Contents][Index]
conditions.lisp (file).
src (module).
Next: parser.ini/src/grammar.lisp, Previous: parser.ini/src/variables.lisp, Up: Lisp [Contents][Index]
variables.lisp (file).
src (module).
parse (generic function).
Previous: parser.ini/src/protocol.lisp, Up: Lisp [Contents][Index]
protocol.lisp (file).
src (module).
Next: parser.ini/examples/etc.lisp, Previous: Static, Up: Static [Contents][Index]
parser.ini (system).
Previous: parser.ini/README.org, Up: Static [Contents][Index]
examples (module).
Next: Definitions, Previous: Files, Up: The parser.ini Reference Manual [Contents][Index]
Packages are listed by definition order.
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.
Next: Indexes, Previous: Packages, Up: The parser.ini Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Generic functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
Controls the accepted assignment syntax. The default is the character "=".
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.
Controls whether empty sections, i.e. "section" in
[section]
[next section]
should be included in the parse result.
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.
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.
Next: Conditions, Previous: Special variables, Up: Public Interface [Contents][Index]
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.
Previous: Generic functions, Up: Public Interface [Contents][Index]
This error is signaled when parsing ini input fails.
| Initarg | Value |
|---|---|
| :source | (missing-required-initarg (quote ini-parse-error) source) |
Stores the source string in which the parse error occurred.
:source
This slot is read-only.
Stores the location at which the parse error
occurred. The format is
(START . END)
where END can be nil
(quote nil)
:location
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
Previous: Definitions, Up: The parser.ini Reference Manual [Contents][Index]
| Jump to: | F G I M P |
|---|
| Jump to: | F G I M P |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
L S |
|---|
| Jump to: | *
L S |
|---|
| Jump to: | C E F G I M P R S V |
|---|
| Jump to: | C E F G I M P R S V |
|---|