├── .gitignore ├── .gitattributes ├── cabal.project.local ├── TODO.md ├── CHANGELOG.md ├── LICENSE ├── README.md ├── regex-rure.cabal ├── test └── Spec.hs ├── src └── Regex │ ├── Rure │ └── FFI.chs │ └── Rure.chs ├── cbits └── rure.h └── COPYING /.gitignore: -------------------------------------------------------------------------------- 1 | dist-newstyle 2 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | cbits/* linguist-vendored 2 | -------------------------------------------------------------------------------- /cabal.project.local: -------------------------------------------------------------------------------- 1 | haddock-internal: true 2 | -------------------------------------------------------------------------------- /TODO.md: -------------------------------------------------------------------------------- 1 | - [ ] `compileSet` segfaults if given >3 pointers? 2 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # 0.1.2.1 2 | 3 | * Restyle 4 | 5 | # 0.1.2.0 6 | 7 | * Add some higher-level functions for dealing with captures 8 | 9 | # 0.1.1.0 10 | 11 | * Add missing low-level functions 12 | 13 | # 0.1.0.3 14 | 15 | * Use `unsafe` for FFI 16 | 17 | # 0.1.0.2 18 | 19 | * Add `cross` flag to ease cross-compilation 20 | 21 | # 0.1.0.1 22 | 23 | * Bundle `rure.h` 24 | 25 | # 0.1.0.0 26 | 27 | * Initial release 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (C) 2021-2022 Vanessa McHale 2 | 3 | This program is free software: you can redistribute it and/or modify 4 | it under the terms of the GNU Affero General Public License as published by 5 | the Free Software Foundation, either version 3 of the License, or 6 | (at your option) any later version. 7 | 8 | This program is distributed in the hope that it will be useful, 9 | but WITHOUT ANY WARRANTY; without even the implied warranty of 10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 | GNU Affero General Public License for more details. 12 | 13 | You should have received a copy of the GNU Affero General Public License 14 | along with this program. If not, see . 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Bindings to Rust's [regular expression library](https://github.com/rust-lang/regex). See [here](https://github.com/rust-lang/regex/tree/master/regex-capi#c-api-for-rusts-regex-engine) for installation instructions. You'll need to put `librure.so` or `librure.dylib` etc. where libraries go on your system. 2 | 3 | Lower-level bindings are exhaustive; higher-level bindings do not include 4 | capture groups. 5 | 6 | # Performance 7 | 8 | As of 0.1.0.3: 9 | 10 | ``` 11 | benchmarking rure/matches 12 | time 334.6 ns (334.1 ns .. 335.2 ns) 13 | 1.000 R² (1.000 R² .. 1.000 R²) 14 | mean 333.8 ns (333.5 ns .. 334.2 ns) 15 | std dev 1.247 ns (1.058 ns .. 1.649 ns) 16 | 17 | benchmarking tdfa/matches 18 | time 1.180 μs (1.180 μs .. 1.181 μs) 19 | 1.000 R² (1.000 R² .. 1.000 R²) 20 | mean 1.179 μs (1.179 μs .. 1.180 μs) 21 | std dev 2.029 ns (1.607 ns .. 2.851 ns) 22 | ``` 23 | -------------------------------------------------------------------------------- /regex-rure.cabal: -------------------------------------------------------------------------------- 1 | cabal-version: 1.18 2 | name: regex-rure 3 | version: 0.1.2.1 4 | license: AGPL-3 5 | license-file: COPYING 6 | maintainer: vamchale@gmail.com 7 | author: Vanessa McHale 8 | synopsis: Bindings to Rust's regex library 9 | description: 10 | Bindings to Rust's regex library, including a higher-level API. 11 | 12 | category: Text, Regex 13 | build-type: Simple 14 | extra-source-files: 15 | README.md 16 | cbits/rure.h 17 | 18 | extra-doc-files: CHANGELOG.md 19 | 20 | source-repository head 21 | type: git 22 | location: https://github.com/vmchale/rure 23 | 24 | flag cross 25 | description: Enable to ease cross-compiling 26 | default: False 27 | manual: True 28 | 29 | library 30 | exposed-modules: 31 | Regex.Rure 32 | Regex.Rure.FFI 33 | 34 | hs-source-dirs: src 35 | default-language: Haskell2010 36 | extra-libraries: rure 37 | include-dirs: cbits 38 | install-includes: cbits/rure.h 39 | ghc-options: -Wall 40 | build-depends: 41 | base >=4.10.0.0 && <5, 42 | bytestring >=0.11.0.0 43 | 44 | if !flag(cross) 45 | build-tool-depends: c2hs:c2hs >=0.26.1 46 | 47 | if impl(ghc >=8.0) 48 | ghc-options: 49 | -Wincomplete-uni-patterns -Wincomplete-record-updates 50 | -Wredundant-constraints -Widentities 51 | 52 | if impl(ghc >=8.4) 53 | ghc-options: -Wmissing-export-lists 54 | 55 | if impl(ghc >=8.2) 56 | ghc-options: -Wcpp-undef 57 | 58 | if impl(ghc >=8.10) 59 | ghc-options: -Wunused-packages 60 | 61 | test-suite regex-rure-test 62 | type: exitcode-stdio-1.0 63 | main-is: Spec.hs 64 | hs-source-dirs: test 65 | default-language: Haskell2010 66 | other-extensions: OverloadedStrings 67 | ghc-options: -Wall 68 | build-depends: 69 | base, 70 | tasty, 71 | tasty-hunit, 72 | regex-rure, 73 | bytestring 74 | 75 | if impl(ghc >=8.0) 76 | ghc-options: 77 | -Wincomplete-uni-patterns -Wincomplete-record-updates 78 | -Wredundant-constraints -Widentities 79 | 80 | if impl(ghc >=8.4) 81 | ghc-options: -Wmissing-export-lists 82 | 83 | if impl(ghc >=8.2) 84 | ghc-options: -Wcpp-undef 85 | 86 | if impl(ghc >=8.10) 87 | ghc-options: -Wunused-packages 88 | -------------------------------------------------------------------------------- /test/Spec.hs: -------------------------------------------------------------------------------- 1 | {-# LANGUAGE OverloadedStrings #-} 2 | 3 | module Main (main) where 4 | 5 | import qualified Data.ByteString as BS 6 | import Foreign.C.Types (CSize) 7 | import Regex.Rure 8 | import Test.Tasty 9 | import Test.Tasty.HUnit 10 | 11 | main :: IO () 12 | main = defaultMain $ 13 | testGroup "High-level interface" 14 | [ testCase "Matches a file extension" (matchY "\\.awk$" "/usr/share/vim/vim82/tools/mve.awk") 15 | , testCase "Matches file extensions" $ 16 | matchesY ["\\.y$", "\\.hs$", "\\.chs$", "\\.x$", "\\.lhs"] "Setup.hs" 17 | , testCase "Matches pattern" $ 18 | matchesSet ["\\.y$", "\\.hs$", "\\.chs$", "\\.x$", "\\.lhs"] "Setup.hs" 19 | [False, True, False, False, False] 20 | , testCase "Matches at" (findAt "libj\\.dylib$" "/Applications/j903/bin/libj.dylib" (RureMatch 23 33)) 21 | , testCase "Matches at (plural)" $ 22 | matchesAt "\\d{4}-\\d{2}-\\d{2}" "2012-03-14 2013-01-01 2014-07-05" 23 | [ RureMatch 0 10 24 | , RureMatch 11 21 25 | , RureMatch 22 32 26 | ] 27 | , testCase "captures year" $ 28 | captures' "(\\d{4})-(\\d{2})-(\\d{2})" "2021-03-14" 1 (RureMatch 0 4) 29 | , testCase "captures month" $ 30 | captures' "(\\d{4})-(\\d{2})-(\\d{2})" "2021-03-14" 2 (RureMatch 5 7) 31 | , testCase "Matches captures" $ 32 | capturess "(\\d{4})-(\\d{2})-(\\d{2})" "2012-03-14 2013-01-01 2014-07-05" 1 33 | [ RureMatch 0 4 34 | , RureMatch 11 15 35 | , RureMatch 22 26 36 | ] 37 | , testCase "Matches captures" $ 38 | capturess "(\\d{4})-(\\d{2})-(\\d{2})" "2012-03-14 2013-01-01 2014-07-05" 2 39 | [ RureMatch 5 7 40 | , RureMatch 16 18 41 | , RureMatch 27 29 42 | ] 43 | ] 44 | 45 | capturess :: BS.ByteString 46 | -> BS.ByteString -- ^ Haystack 47 | -> CSize -- ^ Index 48 | -> [RureMatch] 49 | -> Assertion 50 | capturess re haystack ix expected = do 51 | Right rp <- compile rureDefaultFlags re 52 | actual <- captures rp haystack ix 53 | actual @?= expected 54 | 55 | captures' :: BS.ByteString 56 | -> BS.ByteString -- ^ Haystack 57 | -> CSize -- ^ Index 58 | -> RureMatch 59 | -> Assertion 60 | captures' re haystack ix expected = do 61 | Right rp <- compile rureDefaultFlags re 62 | Just actual <- findCaptures rp haystack ix 0 63 | actual @?= expected 64 | 65 | matchesAt :: BS.ByteString -> BS.ByteString -> [RureMatch] -> Assertion 66 | matchesAt re haystack expected = 67 | let (Right actual) = hsMatches rureDefaultFlags re haystack 68 | in actual @?= expected 69 | 70 | findAt :: BS.ByteString -> BS.ByteString -> RureMatch -> Assertion 71 | findAt re haystack expected = 72 | let (Right actual) = hsFind rureDefaultFlags re haystack 73 | in actual @?= Just expected 74 | 75 | matchesSet :: [BS.ByteString] -> BS.ByteString -> [Bool] -> Assertion 76 | matchesSet res haystack expected = 77 | case hsSetMatches rureDefaultFlags res haystack of 78 | Left err -> assertFailure err 79 | Right actual -> actual @?= expected 80 | 81 | matchesY :: [BS.ByteString] -> BS.ByteString -> Assertion 82 | matchesY res haystack = 83 | case hsSetIsMatch rureDefaultFlags res haystack of 84 | Left err -> assertFailure err 85 | Right b -> assertBool "matches (set)" b 86 | 87 | matchY :: BS.ByteString -> BS.ByteString -> Assertion 88 | matchY re haystack = 89 | case hsIsMatch rureDefaultFlags re haystack of 90 | Left err -> assertFailure err 91 | Right b -> assertBool "matches" b 92 | -------------------------------------------------------------------------------- /src/Regex/Rure/FFI.chs: -------------------------------------------------------------------------------- 1 | -- | See @rure.h@ for documentation + how to use. 2 | module Regex.Rure.FFI ( -- * Types 3 | -- ** Abstract types 4 | Rure 5 | , RureOptions 6 | , RureError 7 | , RureCaptures 8 | , RureSet 9 | , RureIter 10 | , RureIterCaptureNames 11 | -- ** Integer types 12 | , UInt8 13 | , UInt32 14 | -- ** Types 15 | , RureMatch (..) 16 | , RureFlags 17 | -- ** Pointer types (c2hs) 18 | , RurePtr 19 | , RureErrorPtr 20 | , RureOptionsPtr 21 | , RureIterPtr 22 | , RureCapturesPtr 23 | , RureSetPtr 24 | , RureIterCaptureNamesPtr 25 | -- * Functions 26 | -- ** Allocation 27 | , rureOptionsNew 28 | , rureOptionsFree 29 | , rureErrorNew 30 | , rureErrorFree 31 | , rureIterNew 32 | , rureFree 33 | , rureIterFree 34 | , rureCapturesNew 35 | , rureCapturesFree 36 | , rureSetFree 37 | , rureIterCaptureNamesNew 38 | , rureIterCaptureNamesFree 39 | -- ** Options 40 | , rureOptionsSizeLimit 41 | , rureOptionsDfaSizeLimit 42 | , rureErrorMessage 43 | -- ** Compilation 44 | , rureCompile 45 | , rureCompileMust 46 | , rureCompileSet 47 | -- ** Matching 48 | , rureIsMatch 49 | , rureFind 50 | , rureIterNext 51 | , rureIterNextCaptures 52 | , rureCapturesAt 53 | , rureCapturesLen 54 | , rureFindCaptures 55 | , rureShortestMatch 56 | , rureCaptureNameIndex 57 | , rureSetIsMatch 58 | , rureSetMatches 59 | , rureSetLen 60 | , rureIterCaptureNamesNext 61 | -- ** Flags 62 | , rureFlagCaseI 63 | , rureFlagMulti 64 | , rureFlagDotNL 65 | , rureFlagSwapGreed 66 | , rureFlagSpace 67 | , rureFlagUnicode 68 | , rureDefaultFlags 69 | -- ** String utilities 70 | , rureEscapeMust 71 | , rureCstringFree 72 | ) where 73 | 74 | import Data.Bits (Bits, (.|.), shift) 75 | import Data.Coerce (coerce) 76 | import Data.Int (Int32) 77 | import Data.Semigroup (Semigroup (..)) 78 | import Foreign.C.String (CString) 79 | import Foreign.C.Types (CBool, CSize) 80 | import Foreign.Ptr (Ptr, castPtr) 81 | 82 | #include 83 | 84 | type UInt8 = {# type uint8_t #} 85 | {#typedef uint8_t UInt8#} 86 | {#default in `Ptr UInt8' [uint8_t *] id#} -- TODO: bytestring? 87 | 88 | type UInt32 = {# type uint32_t #} 89 | 90 | newtype RureFlags = RureFlags UInt32 91 | 92 | instance Semigroup RureFlags where 93 | (<>) (RureFlags x) (RureFlags y) = RureFlags (x .|. y) 94 | 95 | data Rure 96 | 97 | data RureOptions 98 | 99 | data RureMatch = RureMatch { start :: !CSize, end :: !CSize } deriving (Eq, Show) 100 | 101 | data RureError 102 | 103 | data RureIter 104 | 105 | data RureCaptures 106 | 107 | data RureIterCaptureNames 108 | 109 | data RureSet 110 | 111 | (<<) :: Bits a => a -> Int -> a 112 | m << n = m `shift` n 113 | 114 | rureFlagCaseI :: RureFlags 115 | rureFlagCaseI = RureFlags ({# const RURE_FLAG_CASEI #}) 116 | 117 | rureFlagMulti :: RureFlags 118 | rureFlagMulti = RureFlags ({# const RURE_FLAG_MULTI #}) 119 | 120 | rureFlagDotNL :: RureFlags 121 | rureFlagDotNL = RureFlags ({# const RURE_FLAG_DOTNL #}) 122 | 123 | rureFlagSwapGreed :: RureFlags 124 | rureFlagSwapGreed = RureFlags ({# const RURE_FLAG_SWAP_GREED #}) 125 | 126 | rureFlagSpace :: RureFlags 127 | rureFlagSpace = RureFlags ({# const RURE_FLAG_SPACE #}) 128 | 129 | rureFlagUnicode :: RureFlags 130 | rureFlagUnicode = RureFlags ({# const RURE_FLAG_UNICODE #}) 131 | 132 | rureDefaultFlags :: RureFlags 133 | rureDefaultFlags = RureFlags ({# const RURE_FLAG_UNICODE #}) 134 | 135 | {# pointer *rure as RurePtr foreign finalizer rure_free as ^ -> Rure #} 136 | {# pointer *rure_options as RureOptionsPtr foreign finalizer rure_options_free as ^ -> RureOptions #} 137 | {# pointer *rure_error as RureErrorPtr foreign finalizer rure_error_free as ^ -> RureError #} 138 | {# pointer *rure_iter as RureIterPtr foreign finalizer rure_iter_free as ^ -> RureIter #} 139 | {# pointer *rure_captures as RureCapturesPtr foreign finalizer rure_captures_free as ^ -> RureCaptures #} 140 | {# pointer *rure_set as RureSetPtr foreign finalizer rure_set_free as ^ -> RureSet #} 141 | {# pointer *rure_iter_capture_names as RureIterCaptureNamesPtr foreign finalizer rure_iter_capture_names_free as ^ -> RureIterCaptureNames #} 142 | 143 | {# fun unsafe rure_compile_must as ^ { `CString' } -> `Ptr Rure' id #} 144 | {# fun unsafe rure_compile as ^ { `Ptr UInt8' 145 | , coerce `CSize' 146 | , coerce `RureFlags' 147 | , `RureOptionsPtr' 148 | , `RureErrorPtr' 149 | } -> `Ptr Rure' id 150 | #} 151 | {# fun unsafe rure_is_match as ^ { `RurePtr', `Ptr UInt8', coerce `CSize', coerce `CSize' } -> `Bool' #} 152 | {# fun unsafe rure_find as ^ { `RurePtr' 153 | , `Ptr UInt8' 154 | , coerce `CSize' 155 | , coerce `CSize' 156 | , castPtr `Ptr RureMatch' 157 | } -> `Bool' 158 | #} 159 | {# fun unsafe rure_find_captures as ^ { `RurePtr' 160 | , `Ptr UInt8' 161 | , coerce `CSize' 162 | , coerce `CSize' 163 | , `RureCapturesPtr' 164 | } -> `Bool' 165 | #} 166 | {# fun unsafe rure_shortest_match as ^ { `RurePtr' 167 | , `Ptr UInt8' 168 | , coerce `CSize' 169 | , coerce `CSize' 170 | , castPtr `Ptr CSize' 171 | } -> `Bool' 172 | #} 173 | {# fun unsafe rure_capture_name_index as ^ { `RurePtr' 174 | , `CString' 175 | } -> `Int32' 176 | #} 177 | {# fun unsafe rure_iter_capture_names_new as ^ { `RurePtr' } -> `Ptr RureIterCaptureNames' id #} 178 | {# fun unsafe rure_iter_capture_names_next as ^ { `RureIterCaptureNamesPtr', id `Ptr CString' } -> `Bool' #} 179 | {# fun unsafe rure_iter_new as ^ { `RurePtr' } -> `Ptr RureIter' id #} 180 | {# fun unsafe rure_iter_next as ^ { `RureIterPtr' 181 | , `Ptr UInt8' 182 | , coerce `CSize' 183 | , castPtr `Ptr RureMatch' 184 | } -> `Bool' 185 | #} 186 | {# fun unsafe rure_iter_next_captures as ^ { `RureIterPtr' 187 | , `Ptr UInt8' 188 | , coerce `CSize' 189 | , `RureCapturesPtr' 190 | } -> `Bool' 191 | #} 192 | {# fun unsafe rure_captures_new as ^ { `RurePtr' } -> `Ptr RureCaptures' id #} 193 | {# fun unsafe rure_captures_at as ^ { `RureCapturesPtr', coerce `CSize', castPtr `Ptr RureMatch' } -> `Bool' #} 194 | {# fun unsafe rure_captures_len as ^ { `RureCapturesPtr' } -> `CSize' coerce #} 195 | {# fun unsafe rure_options_new as ^ { } -> `Ptr RureOptions' id #} 196 | {# fun unsafe rure_options_size_limit as ^ { `RureOptionsPtr', coerce `CSize' } -> `()' #} 197 | {# fun unsafe rure_options_dfa_size_limit as ^ { `RureOptionsPtr', coerce `CSize' } -> `()' #} 198 | {# fun unsafe rure_compile_set as ^ { id `Ptr (Ptr UInt8)' 199 | , castPtr `Ptr CSize' 200 | , coerce `CSize' 201 | , coerce `RureFlags' 202 | , `RureOptionsPtr' 203 | , `RureErrorPtr' 204 | } -> `Ptr RureSet' id 205 | #} 206 | {# fun unsafe rure_set_is_match as ^ { `RureSetPtr' 207 | , `Ptr UInt8' 208 | , coerce `CSize' 209 | , coerce `CSize' 210 | } -> `Bool' 211 | #} 212 | {# fun unsafe rure_set_matches as ^ { `RureSetPtr' 213 | , `Ptr UInt8' 214 | , coerce `CSize' 215 | , coerce `CSize' 216 | , castPtr `Ptr CBool' 217 | } -> `Bool' 218 | #} 219 | {# fun unsafe rure_set_len as ^ { `RureSetPtr' } -> `CSize' coerce #} 220 | {# fun unsafe rure_error_new as ^ { } -> `Ptr RureError' id #} 221 | {# fun unsafe rure_error_message as ^ { `RureErrorPtr' } -> `String' #} 222 | {# fun unsafe rure_escape_must as ^ { `CString' } -> `CString' #} 223 | {# fun unsafe rure_cstring_free as ^ { `CString' } -> `()' #} 224 | -------------------------------------------------------------------------------- /src/Regex/Rure.chs: -------------------------------------------------------------------------------- 1 | module Regex.Rure ( -- * Higher-level functions 2 | hsMatches 3 | , hsIsMatch 4 | , hsSetIsMatch 5 | , hsFind 6 | , hsSetMatches 7 | -- * Functions in 'IO'. 8 | , compile 9 | , compileSet 10 | , isMatch 11 | , setIsMatch 12 | , setMatches 13 | , find 14 | , matches 15 | , matches' 16 | , mkIter 17 | , findCaptures 18 | , captures 19 | -- * Types 20 | , RureMatch (..) 21 | -- ** Pointer types 22 | , RurePtr 23 | , RureIterPtr 24 | , RureSetPtr 25 | -- * Options/flags 26 | , RureFlags 27 | , rureFlagCaseI 28 | , rureFlagMulti 29 | , rureFlagDotNL 30 | , rureFlagSwapGreed 31 | , rureFlagSpace 32 | , rureFlagUnicode 33 | , rureDefaultFlags 34 | ) where 35 | 36 | import Data.Coerce (coerce) 37 | import qualified Data.ByteString as BS 38 | import qualified Data.ByteString.Internal as BS 39 | import qualified Data.ByteString.Unsafe as BS 40 | import Data.Foldable (traverse_) 41 | import Foreign.C.Types (CSize) 42 | import Foreign.ForeignPtr (castForeignPtr, newForeignPtr, touchForeignPtr) 43 | import Foreign.ForeignPtr.Unsafe (unsafeForeignPtrToPtr) 44 | import Foreign.Ptr (castPtr, nullPtr, Ptr) 45 | import Foreign.Storable (sizeOf) 46 | import Foreign.Marshal.Alloc (allocaBytes) 47 | import Foreign.Marshal.Array (peekArray, pokeArray) 48 | import Regex.Rure.FFI 49 | import System.IO.Unsafe (unsafePerformIO) 50 | 51 | #include 52 | 53 | infixr 9 ? 54 | infixr 9 ?? 55 | 56 | x ? b = if b then x else pure Nothing 57 | x ?? b = (Just<$>x) ? b 58 | 59 | capturesAt :: RureCapturesPtr -> CSize -> IO (Maybe RureMatch) 60 | capturesAt rcp sz = 61 | allocaBytes {# sizeof rure_match #} $ \matchPtr -> do 62 | res <- rureCapturesAt rcp sz matchPtr 63 | rureMatchFromPtr matchPtr ?? res 64 | 65 | {-# DEPRECATED mkIter "This creates a stateful pointer in an otherwise pure API" #-} 66 | mkIter :: RurePtr -> IO RureIterPtr 67 | mkIter rePtr = 68 | castForeignPtr <$> (newForeignPtr rureIterFree . castPtr =<< rureIterNew rePtr) 69 | 70 | compileSet :: RureFlags -> [BS.ByteString] -> IO (Either String RureSetPtr) 71 | compileSet flags bss = do 72 | preErr <- rureErrorNew 73 | err <- castForeignPtr <$> newForeignPtr rureErrorFree (castPtr preErr) 74 | preOpt <- rureOptionsNew 75 | opt <- castForeignPtr <$> newForeignPtr rureOptionsFree (castPtr preOpt) 76 | allocaBytes lBytes $ \bPtrs -> 77 | allocaBytes lBytes $ \szs -> do 78 | pokeArray bPtrs (fmap unsafeForeignPtrToPtr ps) 79 | pokeArray szs (fromIntegral <$> ss) 80 | res <- rureCompileSet (castPtr bPtrs) szs (fromIntegral l) flags opt err 81 | traverse_ touchForeignPtr ps 82 | if res == nullPtr 83 | then Left <$> rureErrorMessage err 84 | else Right . castForeignPtr <$> newForeignPtr rureSetFree (castPtr res) 85 | where l = length bss 86 | lBytes = l * sizeOf (undefined :: Ptr a) 87 | rip (BS.BS psϵ lϵ) = (psϵ, lϵ) 88 | (ps, ss) = unzip (fmap rip bss) 89 | 90 | compile :: RureFlags -> BS.ByteString -> IO (Either String RurePtr) 91 | compile flags re = do 92 | preErr <- rureErrorNew 93 | err <- castForeignPtr <$> newForeignPtr rureErrorFree (castPtr preErr) 94 | preOpt <- rureOptionsNew 95 | opt <- castForeignPtr <$> newForeignPtr rureOptionsFree (castPtr preOpt) 96 | BS.unsafeUseAsCStringLen re $ \(p, sz) -> do 97 | res <- rureCompile (castPtr p) (fromIntegral sz) flags opt err 98 | if res == nullPtr 99 | then Left <$> rureErrorMessage err 100 | else Right . castForeignPtr <$> newForeignPtr rureFree (castPtr res) 101 | 102 | {-# NOINLINE hsMatches #-} 103 | hsMatches :: RureFlags 104 | -> BS.ByteString -- ^ Regex 105 | -> BS.ByteString -- ^ Haystack (unicode) 106 | -> Either String [RureMatch] 107 | hsMatches flags re haystack = unsafePerformIO $ do 108 | rePtr <- compile flags re 109 | case rePtr of 110 | Left err -> pure (Left err) 111 | Right rp -> Right <$> ((\riPtr -> matches riPtr haystack) =<< mkIter rp) 112 | 113 | -- | @since 0.1.2.0 114 | matches' :: RurePtr 115 | -> BS.ByteString 116 | -> IO [RureMatch] 117 | matches' rp haystack = do 118 | ri <- mkIter rp 119 | matches ri haystack 120 | 121 | {-# DEPRECATED matches "Use matches', which is not stateful" #-} 122 | matches :: RureIterPtr 123 | -> BS.ByteString 124 | -> IO [RureMatch] 125 | matches reIPtr haystack = do 126 | res <- next 127 | case res of 128 | Nothing -> pure [] 129 | Just m -> (m:) <$> matches reIPtr haystack 130 | where 131 | next :: IO (Maybe RureMatch) 132 | next = allocaBytes {# sizeof rure_match #} $ \matchPtr -> do 133 | res <- BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> 134 | rureIterNext reIPtr (castPtr p) (fromIntegral sz) matchPtr 135 | rureMatchFromPtr matchPtr ?? res 136 | 137 | rureMatchFromPtr :: Ptr RureMatch -> IO RureMatch 138 | rureMatchFromPtr matchPtr = 139 | RureMatch 140 | <$> fmap coerce ({# get rure_match->start #} matchPtr) 141 | <*> fmap coerce ({# get rure_match->end #} matchPtr) 142 | 143 | {-# NOINLINE hsFind #-} 144 | hsFind :: RureFlags 145 | -> BS.ByteString -- ^ Regex 146 | -> BS.ByteString -- ^ Haystack 147 | -> Either String (Maybe (RureMatch)) 148 | hsFind flags re haystack = unsafePerformIO $ do 149 | rePtr <- compile flags re 150 | case rePtr of 151 | Left err -> pure (Left err) 152 | Right rp -> Right <$> find rp haystack 0 153 | 154 | allocCapPtr :: RurePtr -> IO RureCapturesPtr 155 | allocCapPtr rp = do 156 | capPtr <- rureCapturesNew rp 157 | castForeignPtr <$> newForeignPtr rureCapturesFree (castPtr capPtr) 158 | 159 | -- | @since 0.1.2.0 160 | captures :: RurePtr 161 | -> BS.ByteString 162 | -> CSize -- ^ Index (for captures) 163 | -> IO [RureMatch] 164 | captures re haystack n = do 165 | capPtr <- allocCapPtr re 166 | reIPtr <- mkIter re 167 | loop capPtr reIPtr 168 | where 169 | loop :: RureCapturesPtr -- ^ For results 170 | -> RureIterPtr 171 | -> IO [RureMatch] 172 | loop capPtr reIPtr = do 173 | res <- next n 174 | case res of 175 | Nothing -> pure [] 176 | Just m -> (m:) <$> loop capPtr reIPtr 177 | where 178 | next :: CSize -- ^ Index (captures) 179 | -> IO (Maybe RureMatch) 180 | next ix = do 181 | res <- BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> 182 | rureIterNextCaptures reIPtr (castPtr p) (fromIntegral sz) capPtr 183 | capturesAt capPtr ix ? res 184 | 185 | -- | @since 0.1.2.0 186 | findCaptures :: RurePtr 187 | -> BS.ByteString 188 | -> CSize -- ^ Index (captures) 189 | -> CSize -- ^ Start 190 | -> IO (Maybe RureMatch) 191 | findCaptures rp haystack ix start' = do 192 | capFp <- allocCapPtr rp 193 | res <- BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> 194 | rureFindCaptures rp (castPtr p) (fromIntegral sz) start' capFp 195 | capturesAt capFp ix ? res 196 | 197 | find :: RurePtr 198 | -> BS.ByteString -- ^ Unicode 199 | -> CSize -- ^ Start 200 | -> IO (Maybe RureMatch) 201 | find rePtr haystack start' = 202 | allocaBytes {# sizeof rure_match #} $ \matchPtr -> do 203 | res <- BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> 204 | rureFind rePtr (castPtr p) (fromIntegral sz) start' matchPtr 205 | rureMatchFromPtr matchPtr ?? res 206 | 207 | {-# NOINLINE hsSetMatches #-} 208 | hsSetMatches :: RureFlags 209 | -> [BS.ByteString] 210 | -> BS.ByteString 211 | -> Either String [Bool] 212 | hsSetMatches flags res haystack = unsafePerformIO $ do 213 | resPtr <- compileSet flags res 214 | case resPtr of 215 | Left err -> pure (Left err) 216 | Right rsp -> Right <$> setMatches rsp haystack 0 217 | 218 | {-# NOINLINE hsSetIsMatch #-} 219 | hsSetIsMatch :: RureFlags 220 | -> [BS.ByteString] -- ^ Needles (regex) 221 | -> BS.ByteString -- ^ Haystack 222 | -> Either String Bool 223 | hsSetIsMatch flags res haystack = unsafePerformIO $ do 224 | resPtr <- compileSet flags res 225 | case resPtr of 226 | Left err -> pure (Left err) 227 | Right rsp -> Right <$> setIsMatch rsp haystack 0 228 | 229 | {-# NOINLINE hsIsMatch #-} 230 | hsIsMatch :: RureFlags 231 | -> BS.ByteString -- ^ Regex 232 | -> BS.ByteString -- ^ Haystack (unicode) 233 | -> Either String Bool 234 | hsIsMatch flags re haystack = unsafePerformIO $ do 235 | rePtr <- compile flags re 236 | case rePtr of 237 | Left err -> pure (Left err) 238 | Right rp -> Right <$> isMatch rp haystack 0 239 | 240 | setIsMatch :: RureSetPtr 241 | -> BS.ByteString -- ^ Unicode 242 | -> CSize -- ^ Start 243 | -> IO Bool 244 | setIsMatch rsPtr haystack startϵ = 245 | BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> 246 | rureSetIsMatch rsPtr (castPtr p) (fromIntegral sz) startϵ 247 | 248 | setMatches :: RureSetPtr 249 | -> BS.ByteString 250 | -> CSize 251 | -> IO [Bool] 252 | setMatches rsPtr haystack startϵ = 253 | BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> do 254 | l <- fromIntegral <$> rureSetLen rsPtr 255 | allocaBytes l $ \boolPtr -> do 256 | rureSetMatches rsPtr (castPtr p) (fromIntegral sz) startϵ boolPtr 257 | map cB <$> peekArray l boolPtr 258 | where cB 0 = False 259 | cB _ = True 260 | 261 | isMatch :: RurePtr 262 | -> BS.ByteString -- ^ Unicode 263 | -> CSize -- ^ Start 264 | -> IO Bool 265 | isMatch rePtr haystack start' = 266 | BS.unsafeUseAsCStringLen haystack $ \(p, sz) -> 267 | rureIsMatch rePtr (castPtr p) (fromIntegral sz) start' 268 | -------------------------------------------------------------------------------- /cbits/rure.h: -------------------------------------------------------------------------------- 1 | #ifndef _RURE_H 2 | #define _RURE_H 3 | 4 | #include 5 | #include 6 | #include 7 | 8 | #ifdef __cplusplus 9 | extern "C" { 10 | #endif 11 | 12 | /* 13 | * rure is the type of a compiled regular expression. 14 | * 15 | * An rure can be safely used from multiple threads simultaneously. 16 | */ 17 | typedef struct rure rure; 18 | 19 | /* 20 | * rure_set is the type of a set of compiled regular expressions. 21 | * 22 | * A rure can be safely used from multiple threads simultaneously. 23 | */ 24 | typedef struct rure_set rure_set; 25 | 26 | /* 27 | * rure_options is the set of non-flag configuration options for compiling 28 | * a regular expression. Currently, only two options are available: setting 29 | * the size limit of the compiled program and setting the size limit of the 30 | * cache of states that the DFA uses while searching. 31 | * 32 | * For most uses, the default settings will work fine, and NULL can be passed 33 | * wherever a *rure_options is expected. 34 | */ 35 | typedef struct rure_options rure_options; 36 | 37 | /* 38 | * The flags listed below can be used in rure_compile to set the default 39 | * flags. All flags can otherwise be toggled in the expression itself using 40 | * standard syntax, e.g., `(?i)` turns case insensitive matching on and `(?-i)` 41 | * disables it. 42 | */ 43 | /* The case insensitive (i) flag. */ 44 | #define RURE_FLAG_CASEI (1 << 0) 45 | /* The multi-line matching (m) flag. (^ and $ match new line boundaries.) */ 46 | #define RURE_FLAG_MULTI (1 << 1) 47 | /* The any character (s) flag. (. matches new line.) */ 48 | #define RURE_FLAG_DOTNL (1 << 2) 49 | /* The greedy swap (U) flag. (e.g., + is ungreedy and +? is greedy.) */ 50 | #define RURE_FLAG_SWAP_GREED (1 << 3) 51 | /* The ignore whitespace (x) flag. */ 52 | #define RURE_FLAG_SPACE (1 << 4) 53 | /* The Unicode (u) flag. */ 54 | #define RURE_FLAG_UNICODE (1 << 5) 55 | /* The default set of flags enabled when no flags are set. */ 56 | #define RURE_DEFAULT_FLAGS RURE_FLAG_UNICODE 57 | 58 | /* 59 | * rure_match corresponds to the location of a single match in a haystack. 60 | */ 61 | typedef struct rure_match { 62 | /* The start position. */ 63 | size_t start; 64 | /* The end position. */ 65 | size_t end; 66 | } rure_match; 67 | 68 | /* 69 | * rure_captures represents storage for sub-capture locations of a match. 70 | * 71 | * Computing the capture groups of a match can carry a significant performance 72 | * penalty, so their use in the API is optional. 73 | * 74 | * An rure_captures value can be reused in multiple calls to rure_find_captures, 75 | * so long as it is used with the compiled regular expression that created 76 | * it. 77 | * 78 | * An rure_captures value may outlive its corresponding rure and can be freed 79 | * independently. 80 | * 81 | * It is not safe to use from multiple threads simultaneously. 82 | */ 83 | typedef struct rure_captures rure_captures; 84 | 85 | /* 86 | * rure_iter is an iterator over successive non-overlapping matches in a 87 | * particular haystack. 88 | * 89 | * An rure_iter value may not outlive its corresponding rure and should be freed 90 | * before its corresponding rure is freed. 91 | * 92 | * It is not safe to use from multiple threads simultaneously. 93 | */ 94 | typedef struct rure_iter rure_iter; 95 | 96 | /* 97 | * rure_iter_capture_names is an iterator over the list of capture group names 98 | * in this particular rure. 99 | * 100 | * An rure_iter_capture_names value may not outlive its corresponding rure, 101 | * and should be freed before its corresponding rure is freed. 102 | * 103 | * It is not safe to use from multiple threads simultaneously. 104 | */ 105 | typedef struct rure_iter_capture_names rure_iter_capture_names; 106 | 107 | /* 108 | * rure_error is an error that caused compilation to fail. 109 | * 110 | * Most errors are syntax errors but an error can be returned if the compiled 111 | * regular expression would be too big. 112 | * 113 | * Whenever a function accepts an *rure_error, it is safe to pass NULL. (But 114 | * you will not get access to the error if one occurred.) 115 | * 116 | * It is not safe to use from multiple threads simultaneously. 117 | */ 118 | typedef struct rure_error rure_error; 119 | 120 | /* 121 | * rure_compile_must compiles the given pattern into a regular expression. If 122 | * compilation fails for any reason, an error message is printed to stderr and 123 | * the process is aborted. 124 | * 125 | * The pattern given should be in UTF-8. For convenience, this accepts a C 126 | * string, which means the pattern cannot usefully contain NUL. If your pattern 127 | * may contain NUL, consider using a regular expression escape sequence, or 128 | * just use rure_compile. 129 | * 130 | * This uses RURE_DEFAULT_FLAGS. 131 | * 132 | * The compiled expression returned may be used from multiple threads 133 | * simultaneously. 134 | */ 135 | rure *rure_compile_must(const char *pattern); 136 | 137 | /* 138 | * rure_compile compiles the given pattern into a regular expression. The 139 | * pattern must be valid UTF-8 and the length corresponds to the number of 140 | * bytes in the pattern. 141 | * 142 | * flags is a bitfield. Valid values are constants declared with prefix 143 | * RURE_FLAG_. 144 | * 145 | * options contains non-flag configuration settings. If it's NULL, default 146 | * settings are used. options may be freed immediately after a call to 147 | * rure_compile. 148 | * 149 | * error is set if there was a problem compiling the pattern (including if the 150 | * pattern is not valid UTF-8). If error is NULL, then no error information 151 | * is returned. In all cases, if an error occurs, NULL is returned. 152 | * 153 | * The compiled expression returned may be used from multiple threads 154 | * simultaneously. 155 | */ 156 | rure *rure_compile(const uint8_t *pattern, size_t length, 157 | uint32_t flags, rure_options *options, 158 | rure_error *error); 159 | 160 | /* 161 | * rure_free frees the given compiled regular expression. 162 | * 163 | * This must be called at most once for any rure. 164 | */ 165 | void rure_free(rure *re); 166 | 167 | /* 168 | * rure_is_match returns true if and only if re matches anywhere in haystack. 169 | * 170 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 171 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 172 | * length should be the number of bytes in haystack. 173 | * 174 | * start is the position at which to start searching. Note that setting the 175 | * start position is distinct from incrementing the pointer, since the regex 176 | * engine may look at bytes before the start position to determine match 177 | * information. For example, if the start position is greater than 0, then the 178 | * \A ("begin text") anchor can never match. 179 | * 180 | * rure_is_match should be preferred to rure_find since it may be faster. 181 | * 182 | * N.B. The performance of this search is not impacted by the presence of 183 | * capturing groups in your regular expression. 184 | */ 185 | bool rure_is_match(rure *re, const uint8_t *haystack, size_t length, 186 | size_t start); 187 | 188 | /* 189 | * rure_find returns true if and only if re matches anywhere in haystack. 190 | * If a match is found, then its start and end offsets (in bytes) are set 191 | * on the match pointer given. 192 | * 193 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 194 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 195 | * length should be the number of bytes in haystack. 196 | * 197 | * start is the position at which to start searching. Note that setting the 198 | * start position is distinct from incrementing the pointer, since the regex 199 | * engine may look at bytes before the start position to determine match 200 | * information. For example, if the start position is greater than 0, then the 201 | * \A ("begin text") anchor can never match. 202 | * 203 | * rure_find should be preferred to rure_find_captures since it may be faster. 204 | * 205 | * N.B. The performance of this search is not impacted by the presence of 206 | * capturing groups in your regular expression. 207 | */ 208 | bool rure_find(rure *re, const uint8_t *haystack, size_t length, 209 | size_t start, rure_match *match); 210 | 211 | /* 212 | * rure_find_captures returns true if and only if re matches anywhere in 213 | * haystack. If a match is found, then all of its capture locations are stored 214 | * in the captures pointer given. 215 | * 216 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 217 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 218 | * length should be the number of bytes in haystack. 219 | * 220 | * start is the position at which to start searching. Note that setting the 221 | * start position is distinct from incrementing the pointer, since the regex 222 | * engine may look at bytes before the start position to determine match 223 | * information. For example, if the start position is greater than 0, then the 224 | * \A ("begin text") anchor can never match. 225 | * 226 | * Only use this function if you specifically need access to capture locations. 227 | * It is not necessary to use this function just because your regular 228 | * expression contains capturing groups. 229 | * 230 | * Capture locations can be accessed using the rure_captures_* functions. 231 | * 232 | * N.B. The performance of this search can be impacted by the number of 233 | * capturing groups. If you're using this function, it may be beneficial to 234 | * use non-capturing groups (e.g., `(?:re)`) where possible. 235 | */ 236 | bool rure_find_captures(rure *re, const uint8_t *haystack, size_t length, 237 | size_t start, rure_captures *captures); 238 | 239 | /* 240 | * rure_shortest_match returns true if and only if re matches anywhere in 241 | * haystack. If a match is found, then its end location is stored in the 242 | * pointer given. The end location is the place at which the regex engine 243 | * determined that a match exists, but may occur before the end of the proper 244 | * leftmost-first match. 245 | * 246 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 247 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 248 | * length should be the number of bytes in haystack. 249 | * 250 | * start is the position at which to start searching. Note that setting the 251 | * start position is distinct from incrementing the pointer, since the regex 252 | * engine may look at bytes before the start position to determine match 253 | * information. For example, if the start position is greater than 0, then the 254 | * \A ("begin text") anchor can never match. 255 | * 256 | * rure_shortest_match should be preferred to rure_find since it may be faster. 257 | * 258 | * N.B. The performance of this search is not impacted by the presence of 259 | * capturing groups in your regular expression. 260 | */ 261 | bool rure_shortest_match(rure *re, const uint8_t *haystack, size_t length, 262 | size_t start, size_t *end); 263 | 264 | /* 265 | * rure_capture_name_index returns the capture index for the name given. If 266 | * no such named capturing group exists in re, then -1 is returned. 267 | * 268 | * The capture index may be used with rure_captures_at. 269 | * 270 | * This function never returns 0 since the first capture group always 271 | * corresponds to the entire match and is always unnamed. 272 | */ 273 | int32_t rure_capture_name_index(rure *re, const char *name); 274 | 275 | /* 276 | * rure_iter_capture_names_new creates a new capture_names iterator. 277 | * 278 | * An iterator will report all successive capture group names of re. 279 | */ 280 | rure_iter_capture_names *rure_iter_capture_names_new(rure *re); 281 | 282 | /* 283 | * rure_iter_capture_names_free frees the iterator given. 284 | * 285 | * It must be called at most once. 286 | */ 287 | void rure_iter_capture_names_free(rure_iter_capture_names *it); 288 | 289 | /* 290 | * rure_iter_capture_names_next advances the iterator and returns true 291 | * if and only if another capture group name exists. 292 | * 293 | * The value of the capture group name is written to the provided pointer. 294 | */ 295 | bool rure_iter_capture_names_next(rure_iter_capture_names *it, char **name); 296 | 297 | /* 298 | * rure_iter_new creates a new iterator. 299 | * 300 | * An iterator will report all successive non-overlapping matches of re. 301 | * When calling iterator functions, the same haystack and length must be 302 | * supplied to all invocations. (Strict pointer equality is, however, not 303 | * required.) 304 | */ 305 | rure_iter *rure_iter_new(rure *re); 306 | 307 | /* 308 | * rure_iter_free frees the iterator given. 309 | * 310 | * It must be called at most once. 311 | */ 312 | void rure_iter_free(rure_iter *it); 313 | 314 | /* 315 | * rure_iter_next advances the iterator and returns true if and only if a 316 | * match was found. If a match is found, then the match pointer is set with the 317 | * start and end location of the match, in bytes. 318 | * 319 | * If no match is found, then subsequent calls will return false indefinitely. 320 | * 321 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 322 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 323 | * length should be the number of bytes in haystack. The given haystack must 324 | * be logically equivalent to all other haystacks given to this iterator. 325 | * 326 | * rure_iter_next should be preferred to rure_iter_next_captures since it may 327 | * be faster. 328 | * 329 | * N.B. The performance of this search is not impacted by the presence of 330 | * capturing groups in your regular expression. 331 | */ 332 | bool rure_iter_next(rure_iter *it, const uint8_t *haystack, size_t length, 333 | rure_match *match); 334 | 335 | /* 336 | * rure_iter_next_captures advances the iterator and returns true if and only if a 337 | * match was found. If a match is found, then all of its capture locations are 338 | * stored in the captures pointer given. 339 | * 340 | * If no match is found, then subsequent calls will return false indefinitely. 341 | * 342 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 343 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 344 | * length should be the number of bytes in haystack. The given haystack must 345 | * be logically equivalent to all other haystacks given to this iterator. 346 | * 347 | * Only use this function if you specifically need access to capture locations. 348 | * It is not necessary to use this function just because your regular 349 | * expression contains capturing groups. 350 | * 351 | * Capture locations can be accessed using the rure_captures_* functions. 352 | * 353 | * N.B. The performance of this search can be impacted by the number of 354 | * capturing groups. If you're using this function, it may be beneficial to 355 | * use non-capturing groups (e.g., `(?:re)`) where possible. 356 | */ 357 | bool rure_iter_next_captures(rure_iter *it, 358 | const uint8_t *haystack, size_t length, 359 | rure_captures *captures); 360 | 361 | /* 362 | * rure_captures_new allocates storage for all capturing groups in re. 363 | * 364 | * An rure_captures value may be reused on subsequent calls to 365 | * rure_find_captures or rure_iter_next_captures. 366 | * 367 | * An rure_captures value may be freed independently of re, although any 368 | * particular rure_captures should be used only with the re given here. 369 | * 370 | * It is not safe to use an rure_captures value from multiple threads 371 | * simultaneously. 372 | */ 373 | rure_captures *rure_captures_new(rure *re); 374 | 375 | /* 376 | * rure_captures_free frees the given captures. 377 | * 378 | * This must be called at most once. 379 | */ 380 | void rure_captures_free(rure_captures *captures); 381 | 382 | /* 383 | * rure_captures_at returns true if and only if the capturing group at the 384 | * index given was part of a match. If so, the given match pointer is populated 385 | * with the start and end location (in bytes) of the capturing group. 386 | * 387 | * If no capture group with the index i exists, then false is 388 | * returned. (A capturing group exists if and only if i is less than 389 | * rure_captures_len(captures).) 390 | * 391 | * Note that index 0 corresponds to the full match. 392 | */ 393 | bool rure_captures_at(rure_captures *captures, size_t i, rure_match *match); 394 | 395 | /* 396 | * rure_captures_len returns the number of capturing groups in the given 397 | * captures. 398 | */ 399 | size_t rure_captures_len(rure_captures *captures); 400 | 401 | /* 402 | * rure_options_new allocates space for options. 403 | * 404 | * Options may be freed immediately after a call to rure_compile, but otherwise 405 | * may be freely used in multiple calls to rure_compile. 406 | * 407 | * It is not safe to set options from multiple threads simultaneously. It is 408 | * safe to call rure_compile from multiple threads simultaneously using the 409 | * same options pointer. 410 | */ 411 | rure_options *rure_options_new(); 412 | 413 | /* 414 | * rure_options_free frees the given options. 415 | * 416 | * This must be called at most once. 417 | */ 418 | void rure_options_free(rure_options *options); 419 | 420 | /* 421 | * rure_options_size_limit sets the appoximate size limit of the compiled 422 | * regular expression. 423 | * 424 | * This size limit roughly corresponds to the number of bytes occupied by a 425 | * single compiled program. If the program would exceed this number, then a 426 | * compilation error will be returned from rure_compile. 427 | */ 428 | void rure_options_size_limit(rure_options *options, size_t limit); 429 | 430 | /* 431 | * rure_options_dfa_size_limit sets the approximate size of the cache used by 432 | * the DFA during search. 433 | * 434 | * This roughly corresponds to the number of bytes that the DFA will use while 435 | * searching. 436 | * 437 | * Note that this is a *per thread* limit. There is no way to set a global 438 | * limit. In particular, if a regular expression is used from multiple threads 439 | * simultaneously, then each thread may use up to the number of bytes 440 | * specified here. 441 | */ 442 | void rure_options_dfa_size_limit(rure_options *options, size_t limit); 443 | 444 | /* 445 | * rure_compile_set compiles the given list of patterns into a single regular 446 | * expression which can be matched in a linear-scan. Each pattern in patterns 447 | * must be valid UTF-8 and the length of each pattern in patterns corresponds 448 | * to a byte length in patterns_lengths. 449 | * 450 | * The number of patterns to compile is specified by patterns_count. patterns 451 | * must contain at least this many entries. 452 | * 453 | * flags is a bitfield. Valid values are constants declared with prefix 454 | * RURE_FLAG_. 455 | * 456 | * options contains non-flag configuration settings. If it's NULL, default 457 | * settings are used. options may be freed immediately after a call to 458 | * rure_compile. 459 | * 460 | * error is set if there was a problem compiling the pattern. 461 | * 462 | * The compiled expression set returned may be used from multiple threads. 463 | */ 464 | rure_set *rure_compile_set(const uint8_t **patterns, 465 | const size_t *patterns_lengths, 466 | size_t patterns_count, 467 | uint32_t flags, 468 | rure_options *options, 469 | rure_error *error); 470 | 471 | /* 472 | * rure_set_free frees the given compiled regular expression set. 473 | * 474 | * This must be called at most once for any rure_set. 475 | */ 476 | void rure_set_free(rure_set *re); 477 | 478 | /* 479 | * rure_is_match returns true if and only if any regexes within the set 480 | * match anywhere in the haystack. Once a match has been located, the 481 | * matching engine will quit immediately. 482 | * 483 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 484 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 485 | * length should be the number of bytes in haystack. 486 | * 487 | * start is the position at which to start searching. Note that setting the 488 | * start position is distinct from incrementing the pointer, since the regex 489 | * engine may look at bytes before the start position to determine match 490 | * information. For example, if the start position is greater than 0, then the 491 | * \A ("begin text") anchor can never match. 492 | */ 493 | bool rure_set_is_match(rure_set *re, const uint8_t *haystack, size_t length, 494 | size_t start); 495 | 496 | /* 497 | * rure_set_matches compares each regex in the set against the haystack and 498 | * modifies matches with the match result of each pattern. Match results are 499 | * ordered in the same way as the rure_set was compiled. For example, 500 | * index 0 of matches corresponds to the first pattern passed to 501 | * `rure_compile_set`. 502 | * 503 | * haystack may contain arbitrary bytes, but ASCII compatible text is more 504 | * useful. UTF-8 is even more useful. Other text encodings aren't supported. 505 | * length should be the number of bytes in haystack. 506 | * 507 | * start is the position at which to start searching. Note that setting the 508 | * start position is distinct from incrementing the pointer, since the regex 509 | * engine may look at bytes before the start position to determine match 510 | * information. For example, if the start position is greater than 0, then the 511 | * \A ("begin text") anchor can never match. 512 | * 513 | * matches must be greater than or equal to the number of patterns the 514 | * rure_set was compiled with. 515 | * 516 | * Only use this function if you specifically need to know which regexes 517 | * matched within the set. To determine if any of the regexes matched without 518 | * caring which, use rure_set_is_match. 519 | */ 520 | bool rure_set_matches(rure_set *re, const uint8_t *haystack, size_t length, 521 | size_t start, bool *matches); 522 | 523 | /* 524 | * rure_set_len returns the number of patterns rure_set was compiled with. 525 | */ 526 | size_t rure_set_len(rure_set *re); 527 | 528 | /* 529 | * rure_error_new allocates space for an error. 530 | * 531 | * If error information is desired, then rure_error_new should be called 532 | * to create an rure_error pointer, and that pointer can be passed to 533 | * rure_compile. If an error occurred, then rure_compile will return NULL and 534 | * the error pointer will be set. A message can then be extracted. 535 | * 536 | * It is not safe to use errors from multiple threads simultaneously. An error 537 | * value may be reused on subsequent calls to rure_compile. 538 | */ 539 | rure_error *rure_error_new(); 540 | 541 | /* 542 | * rure_error_free frees the error given. 543 | * 544 | * This must be called at most once. 545 | */ 546 | void rure_error_free(rure_error *err); 547 | 548 | /* 549 | * rure_error_message returns a NUL terminated string that describes the error 550 | * message. 551 | * 552 | * The pointer returned must not be freed. Instead, it will be freed when 553 | * rure_error_free is called. If err is used in subsequent calls to 554 | * rure_compile, then this pointer may change or become invalid. 555 | */ 556 | const char *rure_error_message(rure_error *err); 557 | 558 | /* 559 | * rure_escape_must returns a NUL terminated string where all meta characters 560 | * have been escaped. If escaping fails for any reason, an error message is 561 | * printed to stderr and the process is aborted. 562 | * 563 | * The pattern given should be in UTF-8. For convenience, this accepts a C 564 | * string, which means the pattern cannot contain a NUL byte. These correspond 565 | * to the only two failure conditions of this function. That is, if the caller 566 | * guarantees that the given pattern is valid UTF-8 and does not contain a 567 | * NUL byte, then this is guaranteed to succeed (modulo out-of-memory errors). 568 | * 569 | * The pointer returned must not be freed directly. Instead, it should be freed 570 | * by calling rure_cstring_free. 571 | */ 572 | const char *rure_escape_must(const char *pattern); 573 | 574 | /* 575 | * rure_cstring_free frees the string given. 576 | * 577 | * This must be called at most once per string. 578 | */ 579 | void rure_cstring_free(char *s); 580 | 581 | #ifdef __cplusplus 582 | } 583 | #endif 584 | 585 | #endif 586 | -------------------------------------------------------------------------------- /COPYING: -------------------------------------------------------------------------------- 1 | GNU AFFERO GENERAL PUBLIC LICENSE 2 | Version 3, 19 November 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU Affero General Public License is a free, copyleft license for 11 | software and other kinds of works, specifically designed to ensure 12 | cooperation with the community in the case of network server software. 13 | 14 | The licenses for most software and other practical works are designed 15 | to take away your freedom to share and change the works. By contrast, 16 | our General Public Licenses are intended to guarantee your freedom to 17 | share and change all versions of a program--to make sure it remains free 18 | software for all its users. 19 | 20 | When we speak of free software, we are referring to freedom, not 21 | price. Our General Public Licenses are designed to make sure that you 22 | have the freedom to distribute copies of free software (and charge for 23 | them if you wish), that you receive source code or can get it if you 24 | want it, that you can change the software or use pieces of it in new 25 | free programs, and that you know you can do these things. 26 | 27 | Developers that use our General Public Licenses protect your rights 28 | with two steps: (1) assert copyright on the software, and (2) offer 29 | you this License which gives you legal permission to copy, distribute 30 | and/or modify the software. 31 | 32 | A secondary benefit of defending all users' freedom is that 33 | improvements made in alternate versions of the program, if they 34 | receive widespread use, become available for other developers to 35 | incorporate. Many developers of free software are heartened and 36 | encouraged by the resulting cooperation. However, in the case of 37 | software used on network servers, this result may fail to come about. 38 | The GNU General Public License permits making a modified version and 39 | letting the public access it on a server without ever releasing its 40 | source code to the public. 41 | 42 | The GNU Affero General Public License is designed specifically to 43 | ensure that, in such cases, the modified source code becomes available 44 | to the community. It requires the operator of a network server to 45 | provide the source code of the modified version running there to the 46 | users of that server. Therefore, public use of a modified version, on 47 | a publicly accessible server, gives the public access to the source 48 | code of the modified version. 49 | 50 | An older license, called the Affero General Public License and 51 | published by Affero, was designed to accomplish similar goals. This is 52 | a different license, not a version of the Affero GPL, but Affero has 53 | released a new version of the Affero GPL which permits relicensing under 54 | this license. 55 | 56 | The precise terms and conditions for copying, distribution and 57 | modification follow. 58 | 59 | TERMS AND CONDITIONS 60 | 61 | 0. Definitions. 62 | 63 | "This License" refers to version 3 of the GNU Affero General Public License. 64 | 65 | "Copyright" also means copyright-like laws that apply to other kinds of 66 | works, such as semiconductor masks. 67 | 68 | "The Program" refers to any copyrightable work licensed under this 69 | License. Each licensee is addressed as "you". "Licensees" and 70 | "recipients" may be individuals or organizations. 71 | 72 | To "modify" a work means to copy from or adapt all or part of the work 73 | in a fashion requiring copyright permission, other than the making of an 74 | exact copy. The resulting work is called a "modified version" of the 75 | earlier work or a work "based on" the earlier work. 76 | 77 | A "covered work" means either the unmodified Program or a work based 78 | on the Program. 79 | 80 | To "propagate" a work means to do anything with it that, without 81 | permission, would make you directly or secondarily liable for 82 | infringement under applicable copyright law, except executing it on a 83 | computer or modifying a private copy. Propagation includes copying, 84 | distribution (with or without modification), making available to the 85 | public, and in some countries other activities as well. 86 | 87 | To "convey" a work means any kind of propagation that enables other 88 | parties to make or receive copies. Mere interaction with a user through 89 | a computer network, with no transfer of a copy, is not conveying. 90 | 91 | An interactive user interface displays "Appropriate Legal Notices" 92 | to the extent that it includes a convenient and prominently visible 93 | feature that (1) displays an appropriate copyright notice, and (2) 94 | tells the user that there is no warranty for the work (except to the 95 | extent that warranties are provided), that licensees may convey the 96 | work under this License, and how to view a copy of this License. If 97 | the interface presents a list of user commands or options, such as a 98 | menu, a prominent item in the list meets this criterion. 99 | 100 | 1. Source Code. 101 | 102 | The "source code" for a work means the preferred form of the work 103 | for making modifications to it. "Object code" means any non-source 104 | form of a work. 105 | 106 | A "Standard Interface" means an interface that either is an official 107 | standard defined by a recognized standards body, or, in the case of 108 | interfaces specified for a particular programming language, one that 109 | is widely used among developers working in that language. 110 | 111 | The "System Libraries" of an executable work include anything, other 112 | than the work as a whole, that (a) is included in the normal form of 113 | packaging a Major Component, but which is not part of that Major 114 | Component, and (b) serves only to enable use of the work with that 115 | Major Component, or to implement a Standard Interface for which an 116 | implementation is available to the public in source code form. A 117 | "Major Component", in this context, means a major essential component 118 | (kernel, window system, and so on) of the specific operating system 119 | (if any) on which the executable work runs, or a compiler used to 120 | produce the work, or an object code interpreter used to run it. 121 | 122 | The "Corresponding Source" for a work in object code form means all 123 | the source code needed to generate, install, and (for an executable 124 | work) run the object code and to modify the work, including scripts to 125 | control those activities. However, it does not include the work's 126 | System Libraries, or general-purpose tools or generally available free 127 | programs which are used unmodified in performing those activities but 128 | which are not part of the work. For example, Corresponding Source 129 | includes interface definition files associated with source files for 130 | the work, and the source code for shared libraries and dynamically 131 | linked subprograms that the work is specifically designed to require, 132 | such as by intimate data communication or control flow between those 133 | subprograms and other parts of the work. 134 | 135 | The Corresponding Source need not include anything that users 136 | can regenerate automatically from other parts of the Corresponding 137 | Source. 138 | 139 | The Corresponding Source for a work in source code form is that 140 | same work. 141 | 142 | 2. Basic Permissions. 143 | 144 | All rights granted under this License are granted for the term of 145 | copyright on the Program, and are irrevocable provided the stated 146 | conditions are met. This License explicitly affirms your unlimited 147 | permission to run the unmodified Program. The output from running a 148 | covered work is covered by this License only if the output, given its 149 | content, constitutes a covered work. This License acknowledges your 150 | rights of fair use or other equivalent, as provided by copyright law. 151 | 152 | You may make, run and propagate covered works that you do not 153 | convey, without conditions so long as your license otherwise remains 154 | in force. You may convey covered works to others for the sole purpose 155 | of having them make modifications exclusively for you, or provide you 156 | with facilities for running those works, provided that you comply with 157 | the terms of this License in conveying all material for which you do 158 | not control copyright. Those thus making or running the covered works 159 | for you must do so exclusively on your behalf, under your direction 160 | and control, on terms that prohibit them from making any copies of 161 | your copyrighted material outside their relationship with you. 162 | 163 | Conveying under any other circumstances is permitted solely under 164 | the conditions stated below. Sublicensing is not allowed; section 10 165 | makes it unnecessary. 166 | 167 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 168 | 169 | No covered work shall be deemed part of an effective technological 170 | measure under any applicable law fulfilling obligations under article 171 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 172 | similar laws prohibiting or restricting circumvention of such 173 | measures. 174 | 175 | When you convey a covered work, you waive any legal power to forbid 176 | circumvention of technological measures to the extent such circumvention 177 | is effected by exercising rights under this License with respect to 178 | the covered work, and you disclaim any intention to limit operation or 179 | modification of the work as a means of enforcing, against the work's 180 | users, your or third parties' legal rights to forbid circumvention of 181 | technological measures. 182 | 183 | 4. Conveying Verbatim Copies. 184 | 185 | You may convey verbatim copies of the Program's source code as you 186 | receive it, in any medium, provided that you conspicuously and 187 | appropriately publish on each copy an appropriate copyright notice; 188 | keep intact all notices stating that this License and any 189 | non-permissive terms added in accord with section 7 apply to the code; 190 | keep intact all notices of the absence of any warranty; and give all 191 | recipients a copy of this License along with the Program. 192 | 193 | You may charge any price or no price for each copy that you convey, 194 | and you may offer support or warranty protection for a fee. 195 | 196 | 5. Conveying Modified Source Versions. 197 | 198 | You may convey a work based on the Program, or the modifications to 199 | produce it from the Program, in the form of source code under the 200 | terms of section 4, provided that you also meet all of these conditions: 201 | 202 | a) The work must carry prominent notices stating that you modified 203 | it, and giving a relevant date. 204 | 205 | b) The work must carry prominent notices stating that it is 206 | released under this License and any conditions added under section 207 | 7. This requirement modifies the requirement in section 4 to 208 | "keep intact all notices". 209 | 210 | c) You must license the entire work, as a whole, under this 211 | License to anyone who comes into possession of a copy. This 212 | License will therefore apply, along with any applicable section 7 213 | additional terms, to the whole of the work, and all its parts, 214 | regardless of how they are packaged. This License gives no 215 | permission to license the work in any other way, but it does not 216 | invalidate such permission if you have separately received it. 217 | 218 | d) If the work has interactive user interfaces, each must display 219 | Appropriate Legal Notices; however, if the Program has interactive 220 | interfaces that do not display Appropriate Legal Notices, your 221 | work need not make them do so. 222 | 223 | A compilation of a covered work with other separate and independent 224 | works, which are not by their nature extensions of the covered work, 225 | and which are not combined with it such as to form a larger program, 226 | in or on a volume of a storage or distribution medium, is called an 227 | "aggregate" if the compilation and its resulting copyright are not 228 | used to limit the access or legal rights of the compilation's users 229 | beyond what the individual works permit. Inclusion of a covered work 230 | in an aggregate does not cause this License to apply to the other 231 | parts of the aggregate. 232 | 233 | 6. Conveying Non-Source Forms. 234 | 235 | You may convey a covered work in object code form under the terms 236 | of sections 4 and 5, provided that you also convey the 237 | machine-readable Corresponding Source under the terms of this License, 238 | in one of these ways: 239 | 240 | a) Convey the object code in, or embodied in, a physical product 241 | (including a physical distribution medium), accompanied by the 242 | Corresponding Source fixed on a durable physical medium 243 | customarily used for software interchange. 244 | 245 | b) Convey the object code in, or embodied in, a physical product 246 | (including a physical distribution medium), accompanied by a 247 | written offer, valid for at least three years and valid for as 248 | long as you offer spare parts or customer support for that product 249 | model, to give anyone who possesses the object code either (1) a 250 | copy of the Corresponding Source for all the software in the 251 | product that is covered by this License, on a durable physical 252 | medium customarily used for software interchange, for a price no 253 | more than your reasonable cost of physically performing this 254 | conveying of source, or (2) access to copy the 255 | Corresponding Source from a network server at no charge. 256 | 257 | c) Convey individual copies of the object code with a copy of the 258 | written offer to provide the Corresponding Source. This 259 | alternative is allowed only occasionally and noncommercially, and 260 | only if you received the object code with such an offer, in accord 261 | with subsection 6b. 262 | 263 | d) Convey the object code by offering access from a designated 264 | place (gratis or for a charge), and offer equivalent access to the 265 | Corresponding Source in the same way through the same place at no 266 | further charge. You need not require recipients to copy the 267 | Corresponding Source along with the object code. If the place to 268 | copy the object code is a network server, the Corresponding Source 269 | may be on a different server (operated by you or a third party) 270 | that supports equivalent copying facilities, provided you maintain 271 | clear directions next to the object code saying where to find the 272 | Corresponding Source. Regardless of what server hosts the 273 | Corresponding Source, you remain obligated to ensure that it is 274 | available for as long as needed to satisfy these requirements. 275 | 276 | e) Convey the object code using peer-to-peer transmission, provided 277 | you inform other peers where the object code and Corresponding 278 | Source of the work are being offered to the general public at no 279 | charge under subsection 6d. 280 | 281 | A separable portion of the object code, whose source code is excluded 282 | from the Corresponding Source as a System Library, need not be 283 | included in conveying the object code work. 284 | 285 | A "User Product" is either (1) a "consumer product", which means any 286 | tangible personal property which is normally used for personal, family, 287 | or household purposes, or (2) anything designed or sold for incorporation 288 | into a dwelling. In determining whether a product is a consumer product, 289 | doubtful cases shall be resolved in favor of coverage. For a particular 290 | product received by a particular user, "normally used" refers to a 291 | typical or common use of that class of product, regardless of the status 292 | of the particular user or of the way in which the particular user 293 | actually uses, or expects or is expected to use, the product. A product 294 | is a consumer product regardless of whether the product has substantial 295 | commercial, industrial or non-consumer uses, unless such uses represent 296 | the only significant mode of use of the product. 297 | 298 | "Installation Information" for a User Product means any methods, 299 | procedures, authorization keys, or other information required to install 300 | and execute modified versions of a covered work in that User Product from 301 | a modified version of its Corresponding Source. The information must 302 | suffice to ensure that the continued functioning of the modified object 303 | code is in no case prevented or interfered with solely because 304 | modification has been made. 305 | 306 | If you convey an object code work under this section in, or with, or 307 | specifically for use in, a User Product, and the conveying occurs as 308 | part of a transaction in which the right of possession and use of the 309 | User Product is transferred to the recipient in perpetuity or for a 310 | fixed term (regardless of how the transaction is characterized), the 311 | Corresponding Source conveyed under this section must be accompanied 312 | by the Installation Information. But this requirement does not apply 313 | if neither you nor any third party retains the ability to install 314 | modified object code on the User Product (for example, the work has 315 | been installed in ROM). 316 | 317 | The requirement to provide Installation Information does not include a 318 | requirement to continue to provide support service, warranty, or updates 319 | for a work that has been modified or installed by the recipient, or for 320 | the User Product in which it has been modified or installed. Access to a 321 | network may be denied when the modification itself materially and 322 | adversely affects the operation of the network or violates the rules and 323 | protocols for communication across the network. 324 | 325 | Corresponding Source conveyed, and Installation Information provided, 326 | in accord with this section must be in a format that is publicly 327 | documented (and with an implementation available to the public in 328 | source code form), and must require no special password or key for 329 | unpacking, reading or copying. 330 | 331 | 7. Additional Terms. 332 | 333 | "Additional permissions" are terms that supplement the terms of this 334 | License by making exceptions from one or more of its conditions. 335 | Additional permissions that are applicable to the entire Program shall 336 | be treated as though they were included in this License, to the extent 337 | that they are valid under applicable law. If additional permissions 338 | apply only to part of the Program, that part may be used separately 339 | under those permissions, but the entire Program remains governed by 340 | this License without regard to the additional permissions. 341 | 342 | When you convey a copy of a covered work, you may at your option 343 | remove any additional permissions from that copy, or from any part of 344 | it. (Additional permissions may be written to require their own 345 | removal in certain cases when you modify the work.) You may place 346 | additional permissions on material, added by you to a covered work, 347 | for which you have or can give appropriate copyright permission. 348 | 349 | Notwithstanding any other provision of this License, for material you 350 | add to a covered work, you may (if authorized by the copyright holders of 351 | that material) supplement the terms of this License with terms: 352 | 353 | a) Disclaiming warranty or limiting liability differently from the 354 | terms of sections 15 and 16 of this License; or 355 | 356 | b) Requiring preservation of specified reasonable legal notices or 357 | author attributions in that material or in the Appropriate Legal 358 | Notices displayed by works containing it; or 359 | 360 | c) Prohibiting misrepresentation of the origin of that material, or 361 | requiring that modified versions of such material be marked in 362 | reasonable ways as different from the original version; or 363 | 364 | d) Limiting the use for publicity purposes of names of licensors or 365 | authors of the material; or 366 | 367 | e) Declining to grant rights under trademark law for use of some 368 | trade names, trademarks, or service marks; or 369 | 370 | f) Requiring indemnification of licensors and authors of that 371 | material by anyone who conveys the material (or modified versions of 372 | it) with contractual assumptions of liability to the recipient, for 373 | any liability that these contractual assumptions directly impose on 374 | those licensors and authors. 375 | 376 | All other non-permissive additional terms are considered "further 377 | restrictions" within the meaning of section 10. If the Program as you 378 | received it, or any part of it, contains a notice stating that it is 379 | governed by this License along with a term that is a further 380 | restriction, you may remove that term. If a license document contains 381 | a further restriction but permits relicensing or conveying under this 382 | License, you may add to a covered work material governed by the terms 383 | of that license document, provided that the further restriction does 384 | not survive such relicensing or conveying. 385 | 386 | If you add terms to a covered work in accord with this section, you 387 | must place, in the relevant source files, a statement of the 388 | additional terms that apply to those files, or a notice indicating 389 | where to find the applicable terms. 390 | 391 | Additional terms, permissive or non-permissive, may be stated in the 392 | form of a separately written license, or stated as exceptions; 393 | the above requirements apply either way. 394 | 395 | 8. Termination. 396 | 397 | You may not propagate or modify a covered work except as expressly 398 | provided under this License. Any attempt otherwise to propagate or 399 | modify it is void, and will automatically terminate your rights under 400 | this License (including any patent licenses granted under the third 401 | paragraph of section 11). 402 | 403 | However, if you cease all violation of this License, then your 404 | license from a particular copyright holder is reinstated (a) 405 | provisionally, unless and until the copyright holder explicitly and 406 | finally terminates your license, and (b) permanently, if the copyright 407 | holder fails to notify you of the violation by some reasonable means 408 | prior to 60 days after the cessation. 409 | 410 | Moreover, your license from a particular copyright holder is 411 | reinstated permanently if the copyright holder notifies you of the 412 | violation by some reasonable means, this is the first time you have 413 | received notice of violation of this License (for any work) from that 414 | copyright holder, and you cure the violation prior to 30 days after 415 | your receipt of the notice. 416 | 417 | Termination of your rights under this section does not terminate the 418 | licenses of parties who have received copies or rights from you under 419 | this License. If your rights have been terminated and not permanently 420 | reinstated, you do not qualify to receive new licenses for the same 421 | material under section 10. 422 | 423 | 9. Acceptance Not Required for Having Copies. 424 | 425 | You are not required to accept this License in order to receive or 426 | run a copy of the Program. Ancillary propagation of a covered work 427 | occurring solely as a consequence of using peer-to-peer transmission 428 | to receive a copy likewise does not require acceptance. However, 429 | nothing other than this License grants you permission to propagate or 430 | modify any covered work. These actions infringe copyright if you do 431 | not accept this License. Therefore, by modifying or propagating a 432 | covered work, you indicate your acceptance of this License to do so. 433 | 434 | 10. Automatic Licensing of Downstream Recipients. 435 | 436 | Each time you convey a covered work, the recipient automatically 437 | receives a license from the original licensors, to run, modify and 438 | propagate that work, subject to this License. You are not responsible 439 | for enforcing compliance by third parties with this License. 440 | 441 | An "entity transaction" is a transaction transferring control of an 442 | organization, or substantially all assets of one, or subdividing an 443 | organization, or merging organizations. If propagation of a covered 444 | work results from an entity transaction, each party to that 445 | transaction who receives a copy of the work also receives whatever 446 | licenses to the work the party's predecessor in interest had or could 447 | give under the previous paragraph, plus a right to possession of the 448 | Corresponding Source of the work from the predecessor in interest, if 449 | the predecessor has it or can get it with reasonable efforts. 450 | 451 | You may not impose any further restrictions on the exercise of the 452 | rights granted or affirmed under this License. For example, you may 453 | not impose a license fee, royalty, or other charge for exercise of 454 | rights granted under this License, and you may not initiate litigation 455 | (including a cross-claim or counterclaim in a lawsuit) alleging that 456 | any patent claim is infringed by making, using, selling, offering for 457 | sale, or importing the Program or any portion of it. 458 | 459 | 11. Patents. 460 | 461 | A "contributor" is a copyright holder who authorizes use under this 462 | License of the Program or a work on which the Program is based. The 463 | work thus licensed is called the contributor's "contributor version". 464 | 465 | A contributor's "essential patent claims" are all patent claims 466 | owned or controlled by the contributor, whether already acquired or 467 | hereafter acquired, that would be infringed by some manner, permitted 468 | by this License, of making, using, or selling its contributor version, 469 | but do not include claims that would be infringed only as a 470 | consequence of further modification of the contributor version. For 471 | purposes of this definition, "control" includes the right to grant 472 | patent sublicenses in a manner consistent with the requirements of 473 | this License. 474 | 475 | Each contributor grants you a non-exclusive, worldwide, royalty-free 476 | patent license under the contributor's essential patent claims, to 477 | make, use, sell, offer for sale, import and otherwise run, modify and 478 | propagate the contents of its contributor version. 479 | 480 | In the following three paragraphs, a "patent license" is any express 481 | agreement or commitment, however denominated, not to enforce a patent 482 | (such as an express permission to practice a patent or covenant not to 483 | sue for patent infringement). To "grant" such a patent license to a 484 | party means to make such an agreement or commitment not to enforce a 485 | patent against the party. 486 | 487 | If you convey a covered work, knowingly relying on a patent license, 488 | and the Corresponding Source of the work is not available for anyone 489 | to copy, free of charge and under the terms of this License, through a 490 | publicly available network server or other readily accessible means, 491 | then you must either (1) cause the Corresponding Source to be so 492 | available, or (2) arrange to deprive yourself of the benefit of the 493 | patent license for this particular work, or (3) arrange, in a manner 494 | consistent with the requirements of this License, to extend the patent 495 | license to downstream recipients. "Knowingly relying" means you have 496 | actual knowledge that, but for the patent license, your conveying the 497 | covered work in a country, or your recipient's use of the covered work 498 | in a country, would infringe one or more identifiable patents in that 499 | country that you have reason to believe are valid. 500 | 501 | If, pursuant to or in connection with a single transaction or 502 | arrangement, you convey, or propagate by procuring conveyance of, a 503 | covered work, and grant a patent license to some of the parties 504 | receiving the covered work authorizing them to use, propagate, modify 505 | or convey a specific copy of the covered work, then the patent license 506 | you grant is automatically extended to all recipients of the covered 507 | work and works based on it. 508 | 509 | A patent license is "discriminatory" if it does not include within 510 | the scope of its coverage, prohibits the exercise of, or is 511 | conditioned on the non-exercise of one or more of the rights that are 512 | specifically granted under this License. You may not convey a covered 513 | work if you are a party to an arrangement with a third party that is 514 | in the business of distributing software, under which you make payment 515 | to the third party based on the extent of your activity of conveying 516 | the work, and under which the third party grants, to any of the 517 | parties who would receive the covered work from you, a discriminatory 518 | patent license (a) in connection with copies of the covered work 519 | conveyed by you (or copies made from those copies), or (b) primarily 520 | for and in connection with specific products or compilations that 521 | contain the covered work, unless you entered into that arrangement, 522 | or that patent license was granted, prior to 28 March 2007. 523 | 524 | Nothing in this License shall be construed as excluding or limiting 525 | any implied license or other defenses to infringement that may 526 | otherwise be available to you under applicable patent law. 527 | 528 | 12. No Surrender of Others' Freedom. 529 | 530 | If conditions are imposed on you (whether by court order, agreement or 531 | otherwise) that contradict the conditions of this License, they do not 532 | excuse you from the conditions of this License. If you cannot convey a 533 | covered work so as to satisfy simultaneously your obligations under this 534 | License and any other pertinent obligations, then as a consequence you may 535 | not convey it at all. For example, if you agree to terms that obligate you 536 | to collect a royalty for further conveying from those to whom you convey 537 | the Program, the only way you could satisfy both those terms and this 538 | License would be to refrain entirely from conveying the Program. 539 | 540 | 13. Remote Network Interaction; Use with the GNU General Public License. 541 | 542 | Notwithstanding any other provision of this License, if you modify the 543 | Program, your modified version must prominently offer all users 544 | interacting with it remotely through a computer network (if your version 545 | supports such interaction) an opportunity to receive the Corresponding 546 | Source of your version by providing access to the Corresponding Source 547 | from a network server at no charge, through some standard or customary 548 | means of facilitating copying of software. This Corresponding Source 549 | shall include the Corresponding Source for any work covered by version 3 550 | of the GNU General Public License that is incorporated pursuant to the 551 | following paragraph. 552 | 553 | Notwithstanding any other provision of this License, you have 554 | permission to link or combine any covered work with a work licensed 555 | under version 3 of the GNU General Public License into a single 556 | combined work, and to convey the resulting work. The terms of this 557 | License will continue to apply to the part which is the covered work, 558 | but the work with which it is combined will remain governed by version 559 | 3 of the GNU General Public License. 560 | 561 | 14. Revised Versions of this License. 562 | 563 | The Free Software Foundation may publish revised and/or new versions of 564 | the GNU Affero General Public License from time to time. Such new versions 565 | will be similar in spirit to the present version, but may differ in detail to 566 | address new problems or concerns. 567 | 568 | Each version is given a distinguishing version number. If the 569 | Program specifies that a certain numbered version of the GNU Affero General 570 | Public License "or any later version" applies to it, you have the 571 | option of following the terms and conditions either of that numbered 572 | version or of any later version published by the Free Software 573 | Foundation. If the Program does not specify a version number of the 574 | GNU Affero General Public License, you may choose any version ever published 575 | by the Free Software Foundation. 576 | 577 | If the Program specifies that a proxy can decide which future 578 | versions of the GNU Affero General Public License can be used, that proxy's 579 | public statement of acceptance of a version permanently authorizes you 580 | to choose that version for the Program. 581 | 582 | Later license versions may give you additional or different 583 | permissions. However, no additional obligations are imposed on any 584 | author or copyright holder as a result of your choosing to follow a 585 | later version. 586 | 587 | 15. Disclaimer of Warranty. 588 | 589 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 590 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 591 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 592 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 593 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 594 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 595 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 596 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 597 | 598 | 16. Limitation of Liability. 599 | 600 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 601 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 602 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 603 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 604 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 605 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 606 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 607 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 608 | SUCH DAMAGES. 609 | 610 | 17. Interpretation of Sections 15 and 16. 611 | 612 | If the disclaimer of warranty and limitation of liability provided 613 | above cannot be given local legal effect according to their terms, 614 | reviewing courts shall apply local law that most closely approximates 615 | an absolute waiver of all civil liability in connection with the 616 | Program, unless a warranty or assumption of liability accompanies a 617 | copy of the Program in return for a fee. 618 | 619 | END OF TERMS AND CONDITIONS 620 | 621 | How to Apply These Terms to Your New Programs 622 | 623 | If you develop a new program, and you want it to be of the greatest 624 | possible use to the public, the best way to achieve this is to make it 625 | free software which everyone can redistribute and change under these terms. 626 | 627 | To do so, attach the following notices to the program. It is safest 628 | to attach them to the start of each source file to most effectively 629 | state the exclusion of warranty; and each file should have at least 630 | the "copyright" line and a pointer to where the full notice is found. 631 | 632 | 633 | Copyright (C) 634 | 635 | This program is free software: you can redistribute it and/or modify 636 | it under the terms of the GNU Affero General Public License as published by 637 | the Free Software Foundation, either version 3 of the License, or 638 | (at your option) any later version. 639 | 640 | This program is distributed in the hope that it will be useful, 641 | but WITHOUT ANY WARRANTY; without even the implied warranty of 642 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 643 | GNU Affero General Public License for more details. 644 | 645 | You should have received a copy of the GNU Affero General Public License 646 | along with this program. If not, see . 647 | 648 | Also add information on how to contact you by electronic and paper mail. 649 | 650 | If your software can interact with users remotely through a computer 651 | network, you should also make sure that it provides a way for users to 652 | get its source. For example, if your program is a web application, its 653 | interface could display a "Source" link that leads users to an archive 654 | of the code. There are many ways you could offer source, and different 655 | solutions will be better for different programs; see section 13 for the 656 | specific requirements. 657 | 658 | You should also get your employer (if you work as a programmer) or school, 659 | if any, to sign a "copyright disclaimer" for the program, if necessary. 660 | For more information on this, and how to apply and follow the GNU AGPL, see 661 | . 662 | --------------------------------------------------------------------------------