swish-0.10.10.0: A semantic web toolkit.

Copyright | (c) 2003 Graham Klyne 2009 Vasili I Galchin 2011 2012 2014 2015 2016 2018 2020 2022 2024 Douglas Burke
License | GPL V2
Maintainer | Douglas Burke
Stability | experimental
Portability | CPP, FlexibleInstances, OverloadedStrings
Safe Haskell | Safe-Inferred
Language | Haskell2010

Swish.VarBinding

Description

This module defines functions for representing and manipulating query binding variable sets. This is the key data that mediates between query and back substitution when performing inferences. A framework of query variable modifiers is provided that can be used to implement richer inferences, such as filtering of query results, or replacing values based on known relationships.

Synopsis

- data VarBinding a b = VarBinding {
  - vbMap :: a -> Maybe b
  - vbEnum :: Set (a, b)
  - vbNull :: Bool
  }
- nullVarBinding :: VarBinding a b
- boundVars :: (Ord a, Ord b) => VarBinding a b -> Set a
- subBinding :: (Ord a, Ord b) => VarBinding a b -> VarBinding a b -> Bool
- makeVarBinding :: (Ord a, Ord b) => [(a, b)] -> VarBinding a b
- applyVarBinding :: VarBinding a a -> a -> a
- joinVarBindings :: (Ord a, Ord b) => VarBinding a b -> VarBinding a b -> VarBinding a b
- addVarBinding :: (Ord a, Ord b) => a -> b -> VarBinding a b -> VarBinding a b
- data VarBindingModify a b = VarBindingModify {
  - vbmName :: ScopedName
  - vbmApply :: [VarBinding a b] -> [VarBinding a b]
  - vbmVocab :: [a]
  - vbmUsage :: [[a]]
  }
- type OpenVarBindingModify lb vn = [lb] -> VarBindingModify lb vn
- openVbmName :: OpenVarBindingModify lb vn -> ScopedName
- vbmCompatibility :: Eq a => VarBindingModify a b -> [a] -> Maybe [a]
- vbmCompose :: Eq a => VarBindingModify a b -> VarBindingModify a b -> Maybe (VarBindingModify a b)
- composeSequence :: Eq a => [VarBindingModify a b] -> Maybe (VarBindingModify a b)
- findCompositions :: Eq a => [VarBindingModify a b] -> [a] -> [VarBindingModify a b]
- findComposition :: Eq a => [VarBindingModify a b] -> [a] -> Maybe (VarBindingModify a b)
- data VarBindingFilter a b = VarBindingFilter {
  - vbfName :: ScopedName
  - vbfVocab :: [a]
  - vbfTest :: VarBinding a b -> Bool
  }
- makeVarFilterModify :: VarBindingFilter a b -> VarBindingModify a b
- makeVarTestFilter :: ScopedName -> (b -> Bool) -> a -> VarBindingFilter a b
- makeVarCompareFilter :: ScopedName -> (b -> b -> Bool) -> a -> a -> VarBindingFilter a b
- varBindingId :: VarBindingModify a b
- nullVarBindingModify :: OpenVarBindingModify a b
- varFilterDisjunction :: Eq a => [VarBindingFilter a b] -> VarBindingFilter a b
- varFilterConjunction :: Eq a => [VarBindingFilter a b] -> VarBindingFilter a b
- varFilterEQ :: Eq b => a -> a -> VarBindingFilter a b
- varFilterNE :: Eq b => a -> a -> VarBindingFilter a b

# Documentation

data VarBinding a b Source #

VarBinding is the type of an arbitrary variable bindings value, where the type of the bound values is not specified.

Constructors

VarBinding |

Fields

- vbMap :: a -> Maybe b
- vbEnum :: Set (a, b)
- vbNull :: Bool

#### Instances

Instances details

(Ord a, Ord b) => Monoid (VarBinding a b) Source # |
Instance details Defined in Swish.VarBinding Methods mempty :: VarBinding a b Source # mappend :: VarBinding a b -> VarBinding a b -> VarBinding a b Source # mconcat :: [VarBinding a b] -> VarBinding a b Source #
(Ord a, Ord b) => Semigroup (VarBinding a b) Source # | When combining instances, if there is an overlapping binding then the value from the first instance is used.
Instance details Defined in Swish.VarBinding Methods (<>) :: VarBinding a b -> VarBinding a b -> VarBinding a b Source # sconcat :: NonEmpty (VarBinding a b) -> VarBinding a b Source # stimes :: Integral b0 => b0 -> VarBinding a b -> VarBinding a b Source #
(Show a, Show b) => Show (VarBinding a b) Source # | The Show instance only displays the pairs of variables in the binding.
Instance details Defined in Swish.VarBinding Methods showsPrec :: Int -> VarBinding a b -> ShowS Source # show :: VarBinding a b -> String Source # showList :: [VarBinding a b] -> ShowS Source #
(Ord a, Ord b) => Eq (VarBinding a b) Source # | The Eq instance is defined as the set equivalence of the pairs of variables in the binding.
Instance details Defined in Swish.VarBinding Methods (==) :: VarBinding a b -> VarBinding a b -> Bool Source # (/=) :: VarBinding a b -> VarBinding a b -> Bool Source #
(Ord a, Ord b) => Ord (VarBinding a b) Source # | The Ord instance is defined only on the pairs of variables in the binding.

Instance details

Defined in Swish.VarBinding

Methods

compare :: VarBinding a b -> VarBinding a b -> Ordering Source #

(<) :: VarBinding a b -> VarBinding a b -> Bool Source #

(<=) :: VarBinding a b -> VarBinding a b -> Bool Source #

(>) :: VarBinding a b -> VarBinding a b -> Bool Source #

(>=) :: VarBinding a b -> VarBinding a b -> Bool Source #

max :: VarBinding a b -> VarBinding a b -> VarBinding a b Source #

min :: VarBinding a b -> VarBinding a b -> VarBinding a b Source #

nullVarBinding :: VarBinding a b Source #

The null, or empty, binding maps no query variables. This is the `mempty` instance of the Monoid.

boundVars :: (Ord a, Ord b) => VarBinding a b -> Set a Source #

Return a list of the variables bound by a supplied variable binding

The Ord instance on b is not needed (it was circa GHC 7.6) but is kept in to avoid the need to increase the minor version number.

subBinding :: (Ord a, Ord b) => VarBinding a b -> VarBinding a b -> Bool Source #

VarBinding subset function, tests to see if one query binding is a subset of another; i.e. every query variable mapping defined by one is also defined by the other.

makeVarBinding :: (Ord a, Ord b) => [(a, b)] -> VarBinding a b Source #

Function to make a variable binding from a list of pairs of variable and corresponding assigned value.

applyVarBinding :: VarBinding a a -> a -> a Source #

Apply query binding to a supplied value, returning the value unchanged if no binding is defined

joinVarBindings :: (Ord a, Ord b) => VarBinding a b -> VarBinding a b -> VarBinding a b Source #

Join a pair of query bindings, returning a new binding that maps all variables recognized by either of the input bindings. If the bindings should overlap, such overlap is not detected and the value from the first binding provided is used.

addVarBinding :: (Ord a, Ord b) => a -> b -> VarBinding a b -> VarBinding a b Source #

Add a single new value to a variable binding and return the resulting new variable binding.

data VarBindingModify a b Source #

Define the type of a function to modify variable bindings in forward chaining based on rule antecedent matches. This function is used to implement the "allocated to" logic described in Appendix B of the RDF semantics document, in which a specific blank node is associated with all matches of some specific value by applications of the rule on a given graph. Use `id` if no modification of the variable bindings is required.

This datatype consists of the modifier function itself, which operates on a list of variable bindings rather than a single variable binding (because some modifications share context across a set of bindings), and some additional descriptive information that allows possible usage patterns to be analyzed.

Some usage patterns (see `vbmUsage` for more details):

filter
  all variables are input variables, and the effect of the modifier function is to drop variable bindings that don't satisfy some criterion. Identifiable by an empty element in `vbmUsage`.
source
  all variables are output variables: a raw query could be viewed as a source of variable bindings. Identifiable by an element of `vbmUsage` equal to `vbmVocab`.
modifier
  for each supplied variable binding, one or more new variable bindings may be created that contain the input variables bound as supplied plus some additional variables. Identifiable by an element of `vbmUsage` some subset of `vbmVocab`.

A variety of variable usage patterns may be supported by a given modifier: a modifier may be used to define new variable bindings from existing bindings in a number of ways, or simply to check that some required relationship between bindings is satisfied. (Example, for `a + b = c`, any one variable can be deduced from the other two, or all three may be supplied to check that the relationship does indeed hold.)

Constructors

VarBindingModify |

Fields

- vbmName :: ScopedName

  Name used to identify this variable binding modifier when building inference rules.

- vbmApply :: [VarBinding a b] -> [VarBinding a b]

  Apply variable binding modifier to a list of variable bindings, returning a new list. The result list is not necessarily the same length as the supplied list.

- vbmVocab :: [a]

  List of variables used by this modifier. All results of applying this modifier contain bindings for these variables.

- vbmUsage :: [[a]]

  List of binding modifier usage patterns supported. Each pattern is characterized as a list of variables for which new bindings may be created by some application of this modifier, assuming that bindings for all other variables in `vbmVocab` are supplied.

#### Instances

Instances details

Show (OpenVarBindingModify a b) Source # | Displays the name of the modifier.
Instance details Defined in Swish.VarBinding Methods showsPrec :: Int -> OpenVarBindingModify a b -> ShowS Source # show :: OpenVarBindingModify a b -> String Source # showList :: [OpenVarBindingModify a b] -> ShowS Source #

type OpenVarBindingModify lb vn = [lb] -> VarBindingModify lb vn Source #

Type for variable binding modifier that has yet to be instantiated with respect to the variables that it operates upon.

openVbmName :: OpenVarBindingModify lb vn -> ScopedName Source #

Extract variable binding name from `OpenVarBindingModify` value

(Because only the name is required, the application to an undefined list of variable labels should never be evaluated, as long as the name is not dependent on the variable names in any way.)

NOT QUITE... some of the functions that create `OpenVarBindingModify` instances also pattern-match the number of labels provided, forcing evaluation of the labels parameter, even though it's not used.

vbmCompatibility :: Eq a => VarBindingModify a b -> [a] -> Maybe [a] Source #

Variable binding modifier compatibility test.

Given a list of bound variables and a variable binding modifier, return a list of new variables that may be bound, or `Nothing`.

Note: if the usage pattern component is well-formed (i.e. all elements different) then at most one element can be compatible with a given input variable set.

vbmCompose :: Eq a => VarBindingModify a b -> VarBindingModify a b -> Maybe (VarBindingModify a b) Source #

Compose variable binding modifiers.

Returns `Just a` new variable binding modifier that corresponds to applying the first supplied modifier and then applying the second one, or `Nothing` if the two modifiers cannot be compatibly composed.

NOTE: this function does not, in general, commute.

NOTE: if there are different ways to achieve the same usage, that usage is currently repeated in the result returned.

composeSequence :: Eq a => [VarBindingModify a b] -> Maybe (VarBindingModify a b) Source #

Compose sequence of variable binding modifiers.

findCompositions :: Eq a => [VarBindingModify a b] -> [a] -> [VarBindingModify a b] Source #

Find all compatible compositions of a list of variable binding modifiers for a given set of supplied bound variables.

findComposition :: Eq a => [VarBindingModify a b] -> [a] -> Maybe (VarBindingModify a b) Source #

Return `Just a` compatible composition of variable binding modifiers for a given set of supplied bound variables, or `Nothing` if there is no compatible composition

data VarBindingFilter a b Source #

VarBindingFilter is a function type that tests to see if a query binding satisfies some criterion.

Queries often want to apply some kind of filter or condition to the variable bindings that are processed. In inference rules, it sometimes seems desirable to stipulate additional conditions on the things that are matched.

This function type is used to perform such tests. A number of simple implementations are included below.

Constructors

VarBindingFilter |

Fields

- vbfName :: ScopedName
- vbfVocab :: [a]
- vbfTest :: VarBinding a b -> Bool

makeVarFilterModify :: VarBindingFilter a b -> VarBindingModify a b Source #

Make a variable binding modifier from a variable binding filter value.

makeVarTestFilter :: ScopedName -> (b -> Bool) -> a -> VarBindingFilter a b Source #

Make a variable test filter for a named variable using a supplied value testing function.

makeVarCompareFilter :: ScopedName -> (b -> b -> Bool) -> a -> a -> VarBindingFilter a b Source #

Make a variable comparison filter for named variables using a supplied value comparison function.

varBindingId :: VarBindingModify a b Source #

Variable binding modifier that returns exactly those variable bindings presented.

nullVarBindingModify :: OpenVarBindingModify a b Source #

Null variable binding modifier

This is like `varBindingId` except parameterized by some labels. I think this is redundant, and should be eliminated.

varFilterDisjunction :: Eq a => [VarBindingFilter a b] -> VarBindingFilter a b Source #

This function composes a number of query binding filters into a composite filter that accepts any query binding that satisfies at least one of the component values.

varFilterConjunction :: Eq a => [VarBindingFilter a b] -> VarBindingFilter a b Source #

This function composes a number of query binding filters into a composite filter that accepts any query binding that satisfies all of the component values.

The same function could be achieved by composing the component filter-based modifiers, but this function is more convenient as it avoids the need to check for modifier compatibility.

varFilterEQ :: Eq b => a -> a -> VarBindingFilter a b Source #

This function generates a query binding filter that ensures that two indicated query variables are mapped to the same value.

varFilterNE :: Eq b => a -> a -> VarBindingFilter a b Source #

This function generates a query binding filter that ensures that two indicated query variables are mapped to different values.