The parse-number-range Reference Manual

Table of Contents

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

The parse-number-range Reference Manual

This is the parse-number-range Reference Manual, version 1.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:22:40 2018 GMT+0.


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

1 Introduction

Project's home: http://www.hexstreamsoft.com/projects/parse-number-range/


parse-number-range parses LOOP's convenient "for-as-arithmetic" syntax
into 5 simple values: from, to, limit-kind (:inclusive, :exclusive or
nil if unbounded), by (step) and direction (+ or -)). Further related
utilities are provided. Intended for easy implementation of analogous
functionality in other constructs.

For a description of LOOP's "for-as-arithmetic", see:
http://www.lispworks.com/documentation/HyperSpec/Body/06_abaa.htm

Here's the package name, along with 2 nicknames:
- PARSE-NUMBER-RANGE
- PARSE-NUMRANGE
- PNUMRANGE

Explicit qualification of the exported symbols is recommended, and one
might (:import-from) select symbols, but (:use) is strongly discouraged.

Here are the exported symbols:
parse unparse canonicalize ; "parse" API
kind flags flags-to-keywords ; "info" API

Parse API
---------

Here are the 5 "fundamental" values returned from PARSE and accepted by UNPARSE:

- FROM: The form introduced by :from, :upfrom or :downfrom. Defaults to 0;
- TO: The form introduced by :to, :upto, :downto, :below or :above. NIL means "unbounded";
- LIMIT-KIND:  :inclusive or :exclusive if there's a limit, or NIL if unbounded;
- BY: The form introduced by :by;
- DIRECTION: + or -.

Some functions accept a KEYWORD-POLICY &key argument, which must be
either :strict or :loose. (from 1 to 10) would be valid with :loose
but not with :strict, which demands (:from 1 :to 10).

Use of :loose is strongly discouraged, as it's an unnecessary and evil
feature that typically results in arbitrary interning of symbols in
arbitrary packages.


Function PARSE range &key (keyword-policy :strict)
                          (extrasp nil)
                          (clause-kinds-p extrasp)
                          (clause-keywords-p extrasp)
                          (clauses-alist-p extrasp)
  => from to limit-kind by direction
       &key clause-kinds clause-keywords clauses-alist

By default, PARSE returns only the 5 "fundamental" values (see above):
- FROM: Defaults to 0;
- TO: Defaults to NIL;
- LIMIT-KIND: Defaults to NIL (unbounded);
- BY: Defaults to 1;
- DIRECTION: Defaults to +.

PARSE can compute and return 3 additional pieces of information, on request:
|-----------------|-------------------|----------------------------------------|
| return value    | request-keyword   | description                            |
|-----------------|-------------------|----------------------------------------|
|-----------------|-------------------|----------------------------------------|
| clause-kinds    | clause-kinds-p    | The clause kinds that were present,    |
|                 |                   | in the order they appeared in.         |
|-----------------|-------------------|----------------------------------------|
| clause-keywords | clause-keywords-p | The clause keywords that were present, |
|                 |                   | in the order they appeared in.         |
|-----------------|-------------------|----------------------------------------|
| clauses-alist   | clauses-alist-p   | Alist: (clause-kind . clause-keyword)  |
|-----------------|-------------------|----------------------------------------|


Function UNPARSE from to limit-kind by direction &key clause-kinds
  => range

As you might have guessed, this does the reverse of PARSE...

UNPARSE uses FLAGS-TO-KEYWORDS internally and thus inherits its biases.

CLAUSE-KINDS should be a list of up to 3 elements being a permutation
of the clause-kinds :from, :to and :by. This determines the order that
the clauses will appear in, which might matter in the presence of
side-effects. NIL designates the default order, (:from :to :by).

If the list has 0 or 1 elements, then the default order is used, (:from :to :by).

If the list has 2 elements, then those clauses will appear in the
order specified but no order is specified between the other elements
and these ones and between the other elements among themselves.
(Yeah, a less simplistic implementation would allow simpler and more useful semantics.)

If the list has 3 elements, then the order is completely specified, explicitly.


Function CANONICALIZE range &key (clause-kinds :preserve) (keyword-policy :strict)

This simply feeds the results of PARSE into UNPARSE. If CLAUSE-KINDS
is :preserve, then :clause-kinds-p t will be specified for PARSE and
the resulting CLAUSE-KINDS result will be fed to UNPARSE. Else, the
provided CLAUSE-KINDS is fed directly to UNPARSE.


Info API
--------

Function KIND keyword &key (errorp t) (keyword-policy :strict)
  => kind direction limit-kind
This function takes a LOOP keyword and returns the following information:

(I have to run away from plaintext for documentation. FAST.
 I tried unicode box drawing characters but they wouldn't align.)

|-----------||--------------------------------|
| Argument  ||   r e t u r n   v a l u e s    |
|-----------||--------------------------------|
| keyword   || kind  | direction | limit-kind |
|-----------||-------|-----------|------------|
|-----------||-------|-----------|------------|
|     :from || :from |    nil    |     nil    |
|-----------||-------|-----------|------------|
| :downfrom || :from |     -     |     nil    |
|-----------||-------|-----------|------------|
|   :upfrom || :from |     +     |     nil    |
|-----------||-------|-----------|------------|
|-----------||-------|-----------|------------|
|       :to || :to   |    nil    | :inclusive |
|-----------||-------|-----------|------------|
|     :upto || :to   |     +     | :inclusive |
|-----------||-------|-----------|------------|
|   :downto || :to   |     -     | :inclusive |
|-----------||-------|-----------|------------|
|    :below || :to   |     +     | :exclusive |
|-----------||-------|-----------|------------|
|    :above || :to   |     -     | :exclusive |
|-----------||-------|-----------|------------|
|-----------||-------|-----------|------------|
|       :by || :by   |     nil   |     nil    |
|-----------||-------|-----------|------------|


Function FLAGS keyword &key (errorp t) (keyword-policy :strict)
  => direction limit-kind

This convenience function simply forwards to KIND
and returns all values but the first.


Function FLAGS-TO-KEYWORDS direction limit-kind
  => from-keyword to-keyword

This function does roughly the opposite of the KIND function. It
returns a FROM-KEYWORD and a TO-KEYWORD (nil if unbounded) that
properly indicate the supplied DIRECTION and LIMIT-KIND.

There are typically multiple valid sets of answers that could be
returned. This function is currently biased as follows, with no way to
request a different bias:

1. The DIRECTION and LIMIT-KIND will always be represented in the
TO-KEYWORD, and never in the FROM-KEYWORD, except for the following
exception:

(flags-to-keywords '- :exclusive) => :downfrom, nil

2. :to is always returned in preference to :upto.


This library is in the Public Domain.
See the UNLICENSE file for details.


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 parse-number-range

Author

Jean-Philippe Paradis <hexstream@gmail.com>

License

Public Domain

Description

Parses LOOP’s convenient "for-as-arithmetic" syntax into 5 simple values: from, to, limit-kind (:inclusive, :exclusive or nil if unbounded), by (step) and direction (+ or -)). Further related utilities are provided. Intended for easy implementation of analogous functionality in other constructs.

Version

1.0

Dependencies
Source

parse-number-range.asd (file)

Components

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

3 Files

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


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

3.1 Lisp


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

3.1.1 parse-number-range.asd

Location

parse-number-range.asd

Systems

parse-number-range (system)


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

3.1.2 parse-number-range/package.lisp

Parent

parse-number-range (system)

Location

package.lisp

Packages

parse-number-range


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

3.1.3 parse-number-range/info.lisp

Dependency

package.lisp (file)

Parent

parse-number-range (system)

Location

info.lisp

Exported Definitions

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

3.1.4 parse-number-range/internals.lisp

Dependency

info.lisp (file)

Parent

parse-number-range (system)

Location

internals.lisp

Internal Definitions

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

3.1.5 parse-number-range/parse.lisp

Dependency

internals.lisp (file)

Parent

parse-number-range (system)

Location

parse.lisp

Exported Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 parse-number-range

Source

package.lisp (file)

Nicknames
Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Functions

Function: canonicalize RANGE &key CLAUSE-KINDS KEYWORD-POLICY
Package

parse-number-range

Source

parse.lisp (file)

Function: flags KEYWORD &key ERRORP KEYWORD-POLICY
Package

parse-number-range

Source

info.lisp (file)

Function: flags-to-keywords DIRECTION LIMIT-KIND
Package

parse-number-range

Source

info.lisp (file)

Function: kind KEYWORD &key ERRORP KEYWORD-POLICY
Package

parse-number-range

Source

info.lisp (file)

Function: parse RANGE &key KEYWORD-POLICY EXTRASP CLAUSE-KINDS-P CLAUSE-KEYWORDS-P CLAUSES-ALIST-P
Package

parse-number-range

Source

parse.lisp (file)

Function: unparse FROM TO LIMIT-KIND BY DIRECTION &key CLAUSE-KINDS
Package

parse-number-range

Source

parse.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Functions

Function: %make-extras-processor CLAUSE-KINDS-P CLAUSE-KEYWORDS-P CLAUSES-ALIST-P
Package

parse-number-range

Source

internals.lisp (file)

Function: %make-flags ()
Package

parse-number-range

Source

internals.lisp (file)

Function: %make-group KIND DEFAULT KEYWORD-DATA-ALIST
Package

parse-number-range

Source

internals.lisp (file)

Function: %make-groups ON-DUPLICATE
Package

parse-number-range

Source

internals.lisp (file)

Function: %make-key-value-processor ON-DUPLICATE
Package

parse-number-range

Source

internals.lisp (file)

Function: %map-plist FUNCTION PLIST
Package

parse-number-range

Source

internals.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, parse-number-range.asd: The parse-number-range<dot>asd file
File, Lisp, parse-number-range/info.lisp: The parse-number-range/info<dot>lisp file
File, Lisp, parse-number-range/internals.lisp: The parse-number-range/internals<dot>lisp file
File, Lisp, parse-number-range/package.lisp: The parse-number-range/package<dot>lisp file
File, Lisp, parse-number-range/parse.lisp: The parse-number-range/parse<dot>lisp file

L
Lisp File, parse-number-range.asd: The parse-number-range<dot>asd file
Lisp File, parse-number-range/info.lisp: The parse-number-range/info<dot>lisp file
Lisp File, parse-number-range/internals.lisp: The parse-number-range/internals<dot>lisp file
Lisp File, parse-number-range/package.lisp: The parse-number-range/package<dot>lisp file
Lisp File, parse-number-range/parse.lisp: The parse-number-range/parse<dot>lisp file

P
parse-number-range.asd: The parse-number-range<dot>asd file
parse-number-range/info.lisp: The parse-number-range/info<dot>lisp file
parse-number-range/internals.lisp: The parse-number-range/internals<dot>lisp file
parse-number-range/package.lisp: The parse-number-range/package<dot>lisp file
parse-number-range/parse.lisp: The parse-number-range/parse<dot>lisp file

Jump to:   F   L   P  

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

A.2 Functions

Jump to:   %  
C   F   K   P   U  
Index Entry  Section

%
%make-extras-processor: Internal functions
%make-flags: Internal functions
%make-group: Internal functions
%make-groups: Internal functions
%make-key-value-processor: Internal functions
%map-plist: Internal functions

C
canonicalize: Exported functions

F
flags: Exported functions
flags-to-keywords: Exported functions
Function, %make-extras-processor: Internal functions
Function, %make-flags: Internal functions
Function, %make-group: Internal functions
Function, %make-groups: Internal functions
Function, %make-key-value-processor: Internal functions
Function, %map-plist: Internal functions
Function, canonicalize: Exported functions
Function, flags: Exported functions
Function, flags-to-keywords: Exported functions
Function, kind: Exported functions
Function, parse: Exported functions
Function, unparse: Exported functions

K
kind: Exported functions

P
parse: Exported functions

U
unparse: Exported functions

Jump to:   %  
C   F   K   P   U  

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

A.3 Variables


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

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, parse-number-range: The parse-number-range package
parse-number-range: The parse-number-range system
parse-number-range: The parse-number-range package

S
System, parse-number-range: The parse-number-range system

Jump to:   P   S