Commits

Doug Burke committed 3221aa3

doc changes and note of replaceArcs possible removal

Comments (0)

Files changed (3)

     - toRDFGraph now uses the supplied labels to set up the namespace
       rather than using an empty namespace map.
 
+    - minor documentation improvements.
+
 0.3.1.1:
 
   - N3 I/O: 

Swish/RDF/GraphClass.hs

 
 import Data.List (union, (\\))
 
--- | Labelled Directed Graph class
---
---  Minimum required implementation:  `setArcs`, `getArcs` and `containedIn`.
---
 --  NOTE:  I wanted to declare this as a subclass of Functor, but
 --  the constraint on the label type seems to prevent that.
 --  So I've just declared specific instances to be Functors.
 --
+
+{-|
+Labelled Directed Graph class
+
+Minimum required implementation:  `setArcs`, `getArcs` and `containedIn`
+(although @containedIn@ may be removed as it is currently unused).
+-}
 class (Eq (lg lb), Eq lb ) => LDGraph lg lb
     where
     --  empty graph
     nodes g     = foldl union [] (map arcNodes (getArcs g))
     
     -- | Test for graph containment in another.
+    --
+    -- At present this is unused and may be removed in a future release.
     containedIn :: lg lb -> lg lb -> Bool 
     
     -- | Update the arcs in a graph using a supplied function.
   This means adding the emptyGr function to the interface
 -}
 
--- |Function to replace arcs in a graph with a given list of arcs
+-- |Function to replace arcs in a graph with a given list of arcs.
+--
+-- This is identical to @flip setArcs@ and so may be removed.
+--    
 replaceArcs :: (LDGraph lg lb) => lg lb -> [Arc lb] -> lg lb
-replaceArcs gr as = update (const as) gr
+replaceArcs = flip setArcs
+-- replaceArcs gr as = update (const as) gr
 
 -- | Label class
 --
 
 -- | Arc type
 
-data Arc lb = Arc { asubj, apred, aobj :: lb }
-    deriving (Eq, Functor, F.Foldable, T.Traversable)
+data Arc lb = Arc 
+              { asubj :: lb  -- ^ The subject of the arc.
+              , apred :: lb  -- ^ The predicate (property) of the arc.
+              , aobj :: lb   -- ^ The object of the arc.
+              }
+            deriving (Eq, Functor, F.Foldable, T.Traversable)
 
+-- | Return the subject of the arc.
 arcSubj :: Arc lb -> lb
 arcSubj = asubj
 
+-- | Return the predicate (property) of the arc.
 arcPred :: Arc lb -> lb
 arcPred = apred
 
+-- | Return the object of the arc.
 arcObj :: Arc lb -> lb
 arcObj = aobj
 
        -> Arc lb
 arc = Arc
 
+-- | Convert an Arc into a tuple.
 arcToTriple :: Arc lb -> (lb,lb,lb)
 arcToTriple (Arc s p o) = (s, p, o)
--- arcToTriple a = (asubj a,apred a,aobj a)
 
+-- | Create an Arc from a tuple.
 arcFromTriple :: (lb,lb,lb) -> Arc lb
 arcFromTriple (s,p,o) = Arc s p o
 
     show (Arc lb1 lb2 lb3) =
         "("++ show lb1 ++","++ show lb2 ++","++ show lb3 ++")"
 
+-- | Identify arcs.
 type Selector lb = Arc lb -> Bool
 
 hasLabel :: (Eq lb) => lb -> Arc lb -> Bool

Swish/RDF/RDFGraph.hs

 
 -- instances for type conversion to/from RDFLabel
   
+-- | This is just `id`.
 instance ToRDFLabel RDFLabel where
   toRDFLabel = id
   
+-- | This is just `Just . id`.  
 instance FromRDFLabel RDFLabel where
   fromRDFLabel = Just . id
   
 tLabel :: (Show a) => ScopedName -> (String -> String) -> a -> RDFLabel                      
 tLabel dtype conv = flip Lit (Just dtype) . conv . show                      
 
+-- | The character is converted to an untyped literal of length one.
 instance ToRDFLabel Char where
   toRDFLabel = flip Lit Nothing . (:[])
 
+-- | The label must be an untyped literal containing a single character.
 instance FromRDFLabel Char where
   fromRDFLabel (Lit [c] Nothing) = Just c
   fromRDFLabel _ = Nothing
 
+-- | Strings are converted to untyped literals.
 instance ToRDFLabel String where
   toRDFLabel = flip Lit Nothing
 
+-- | Only untyped literals are converted to strings.
 instance FromRDFLabel String where
   fromRDFLabel (Lit xs Nothing) = Just xs
   fromRDFLabel _ = Nothing
 
+strToBool :: String -> Maybe Bool
+strToBool s | s `elem` ["1", "true"]  = Just True
+            | s `elem` ["0", "false"] = Just False
+            | otherwise               = Nothing
+
 -- | Converts to a literal with a @xsd:boolean@ datatype.
 instance ToRDFLabel Bool where
   toRDFLabel b = Lit (if b then "true" else "false") (Just xsd_boolean)
                                                  
-strToBool :: String -> Maybe Bool
-strToBool s | s `elem` ["1", "true"]  = Just True
-            | s `elem` ["0", "false"] = Just False
-            | otherwise               = Nothing
-
--- | Converts from a literal with a @xsd:boolean@ datatype.
+-- | Converts from a literal with a @xsd:boolean@ datatype. The
+-- literal can be any of the supported XSD forms - e.g. \"0\" or
+-- \"true\".
 instance FromRDFLabel Bool where
   fromRDFLabel = fLabel strToBool xsd_boolean
 
 strToDouble :: String -> Maybe Double      
 strToDouble = strToRealFloat Just
 
+-- | Converts to a literal with a @xsd:float@ datatype.
 instance ToRDFLabel Float where
   toRDFLabel = fromRealFloat xsd_float
   
+-- | Converts from a literal with a @xsd:float@ datatype.
+-- The conversion will fail if the value is outside the valid range of
+-- a Haskell `Float`.
 instance FromRDFLabel Float where
   fromRDFLabel = fLabel strToFloat xsd_float
                  
+-- | Converts to a literal with a @xsd:double@ datatype.
 instance ToRDFLabel Double where
   toRDFLabel = fromRealFloat xsd_double
   
+-- | Converts from a literal with a @xsd:double@ datatype.
 instance FromRDFLabel Double where
   fromRDFLabel = fLabel strToDouble xsd_double
   
 --         
 -- TODO: add in support for Int8/..., Word8/...  
 --  
+
+-- | Converts to a literal with a @xsd:integer@ datatype.
 instance ToRDFLabel Int where
   toRDFLabel = tLabel xsd_integer id
 
   
   in maybeRead s >>= conv
 
+-- | Converts from a literal with a @xsd:integer@ datatype.
+-- The conversion will fail if the value is outside the valid range of
+-- a Haskell `Int`.
 instance FromRDFLabel Int where
   fromRDFLabel = fLabel strToInt xsd_integer
 
+-- | Converts to a literal with a @xsd:integer@ datatype.
 instance ToRDFLabel Integer where
   toRDFLabel = tLabel xsd_integer id
 
+-- | Converts from a literal with a @xsd:integer@ datatype.
 instance FromRDFLabel Integer where
   fromRDFLabel = fLabel maybeRead xsd_integer
 
 toDayFormat :: String -> Maybe Day
 toDayFormat = toTimeFormat "%F"
     
+-- | Converts to a literal with a @xsd:datetime@ datatype.
 instance ToRDFLabel UTCTime where
   toRDFLabel = flip Lit (Just xsd_dateTime) . fromUTCFormat
   
+-- | Converts from a literal with a @xsd:datetime@ datatype.
 instance FromRDFLabel UTCTime where
   fromRDFLabel = fLabel toUTCFormat xsd_dateTime
   
+-- | Converts to a literal with a @xsd:date@ datatype.
 instance ToRDFLabel Day where
   toRDFLabel = flip Lit (Just xsd_date) . fromDayFormat
 
+-- | Converts from a literal with a @xsd:date@ datatype.
 instance FromRDFLabel Day where
   fromRDFLabel = fLabel toDayFormat xsd_date
   
+-- | Converts to a Resource.
 instance ToRDFLabel ScopedName where  
   toRDFLabel = Res
 
+-- | Converts from a Resource.
 instance FromRDFLabel ScopedName where
   fromRDFLabel (Res sn) = Just sn
   fromRDFLabel _        = Nothing
   
+-- | Converts to a Resource.
 instance ToRDFLabel QName where  
   toRDFLabel = Res . makeQNameScopedName
   
+-- | Converts from a Resource.
 instance FromRDFLabel QName where
   fromRDFLabel (Res sn) = Just $ getQName sn
   fromRDFLabel _        = Nothing
   
+-- | Converts to a Resource.
 instance ToRDFLabel URI where  
   toRDFLabel u = Res $ makeUriScopedName $ uriToString id u ""
   
+-- | Converts from a Resource.
 instance FromRDFLabel URI where
   fromRDFLabel (Res sn) = parseURI $ getScopedNameURI sn
   fromRDFLabel _        = Nothing
   res_rdfd_maxCardinality, res_owl_sameAs, res_log_implies
   :: RDFLabel
 
-res_rdf_type                = Res rdf_type
-res_rdf_first               = Res rdf_first
+res_rdf_type                = Res rdf_type 
+res_rdf_first               = Res rdf_first 
 res_rdf_rest                = Res rdf_rest
 res_rdf_nil                 = Res rdf_nil
 res_rdfs_member             = Res rdfs_member
 
 -- | Convert 3 RDF labels to a RDF triple.
 --
---   See also `arcFromTriple`.
+--   See also `Swish.RDF.GraphClass.arcFromTriple`.
 toRDFTriple :: 
   (ToRDFLabel s, ToRDFLabel p, ToRDFLabel o) 
   => s -- ^ Subject 
 
 -- | Extract the contents of a RDF triple.
 --
---   See also `arcToTriple`.
+--   See also `Swish.RDF.GraphClass.arcToTriple`.
 fromRDFTriple :: 
   (FromRDFLabel s, FromRDFLabel p, FromRDFLabel o) 
   => RDFTriple 
 
 type RevNamespaceMap = LookupMap RevNamespace
 
+-- | Create an emoty namespace map.
 emptyNamespaceMap :: NamespaceMap
 emptyNamespaceMap = LookupMap []
 
 -- | Graph formula entry
 
 data LookupFormula lb gr = Formula
-    { formLabel :: lb
-    , formGraph :: gr
+    { formLabel :: lb -- ^ The label for the formula
+    , formGraph :: gr -- ^ The contents of the formula
     }
 
 instance (Eq lb, Eq gr) => Eq (LookupFormula lb gr) where
 
 type FormulaMap lb = LookupMap (LookupFormula lb (NSGraph lb))
 
+-- | Create an empty formula map.
 emptyFormulaMap :: FormulaMap RDFLabel
 emptyFormulaMap = LookupMap []
 
     
 -}
 
--- | Memory-based graph with namespaces and subgraphs
+{-|
 
+Memory-based graph with namespaces and subgraphs.
+
+The primary means for adding arcs to an existing graph
+are: 
+
+ - `setArcs` from the `LDGraph` instance, which replaces the 
+    existing set of arcs and does not change the namespace 
+    map.
+
+ - `addArc` which checks that the arc is unknown before
+    adding it but does not change the namespace map or
+    re-label any blank nodes in the arc.
+
+-}
 data NSGraph lb = NSGraph
-    { namespaces :: NamespaceMap
-    , formulae   :: FormulaMap lb
-    , statements :: [Arc lb]
+    { namespaces :: NamespaceMap    -- ^ the namespaces to use
+    , formulae   :: FormulaMap lb   -- ^ any associated formulae (a.k.a. sub- or named- graps)
+    , statements :: [Arc lb]        -- ^ the statements in the graph
     }
 
+-- | Retrieve the namespace map in the graph.
 getNamespaces :: NSGraph lb -> NamespaceMap
 getNamespaces = namespaces
 
 setNamespaces      :: NamespaceMap -> NSGraph lb -> NSGraph lb
 setNamespaces ns g = g { namespaces=ns }
 
+-- | Retrieve the formulae in the graph.
 getFormulae :: NSGraph lb -> FormulaMap lb
 getFormulae = formulae
 
 setFormulae      :: FormulaMap lb -> NSGraph lb -> NSGraph lb
 setFormulae fs g = g { formulae=fs }
 
+-- | Find a formula in the graph, if it exists.
 getFormula     :: (Label lb) => NSGraph lb -> lb -> Maybe (NSGraph lb)
 getFormula g l = mapFindMaybe l (formulae g)
 
     setArcs as g = g { statements=as }
     containedIn = error "containedIn for LDGraph NSGraph lb is undefined!" -- TODO: should there be one defined?
 
--- | Add an arc to the graph. It does not check for duplicates
--- nor does it relabel any blank nodes in the input arc.
+{-|
+Add an arc to the graph. It does not relabel any blank nodes in the input arc,
+nor does it change the namespace map, 
+but it does ensure that the arc is unknown before adding it.
+-}
 addArc :: (Label lb) => Arc lb -> NSGraph lb -> NSGraph lb
 addArc ar gr = gr { statements=addSetElem ar (statements gr) }
 
         add gr1 (remapLabels dupbn allbn id gr2)
 
 -- |Return list of all labels (including properties) in the graph
---  satisfying a supplied filter predicate.
+--  satisfying a supplied filter predicate. This routine
+--  includes the labels in any formulae.
 allLabels :: (Label lb) => (lb -> Bool) -> NSGraph lb -> [lb]
-allLabels p gr = filter p (unionNodes p (formulaNodes p gr) (labels gr) )
+allLabels p gr = filter p (unionNodes p (formulaNodes p gr) (labels gr) ) 
+                 
+{- TODO: is the leading 'filter p' needed in allLabels?
+-}
 
 -- |Return list of all subjects and objects in the graph
 --  satisfying a supplied filter predicate.
 unionNodes :: (Label lb) => (lb -> Bool) -> [lb] -> [lb] -> [lb]
 unionNodes p ls1 ls2 = ls1 `union` filter p ls2
 
--- |Remap selected nodes in graph:
+-- |Remap selected nodes in graph.
 --
 --  This is the node renaming operation that prevents graph-scoped
 --  variable nodes from being merged when two graphs are merged.
 -- which is how this routine was defined in version @0.3.1.1@
 -- and earlier.
 --
-toRDFGraph :: [Arc RDFLabel] -> RDFGraph
+toRDFGraph :: [RDFTriple] -> RDFGraph
 -- toRDFGraph arcs = emptyRDFGraph { statements = arcs }
 toRDFGraph arcs = 
   let lbls = concatMap (\(Arc s p o) -> [s,p,o]) arcs
       getDataType (Lit _ (Just dt)) = dt
       getDataType _ = nullScopedName -- should not happen
       nsmap = foldl' mapAddIfNew emptyNamespaceMap (ns1++ns2)
-  in emptyRDFGraph { namespaces = nsmap, statements = arcs }
+  in mempty { namespaces = nsmap, statements = arcs }
 
 -- |Create a new, empty RDF graph.
+--
+-- This uses `mempty` from the `Monoid` instance
+-- of `NSGraph`.
+--
 emptyRDFGraph :: RDFGraph
 emptyRDFGraph = mempty 
 
 --  [[[TODO:  I think this may be redundant - the default graph
 --  class has an update method which accepts a function to update
 --  the arcs, not touching other parts of the graph value.]]]
-updateRDFGraph :: RDFGraph -> [Arc RDFLabel] -> RDFGraph
+updateRDFGraph :: RDFGraph -> [RDFTriple] -> RDFGraph
 updateRDFGraph gr as = gr { statements=as }
 -}
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.