├── CHANGELOG.md ├── .gitignore ├── README.md ├── placeholder.cabal ├── .github └── workflows │ └── ci.yml ├── t └── Test.hs ├── src └── Control │ └── Placeholder.hs └── LICENSE.md /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Revision history for placeholder 2 | 3 | ## [next] 4 | 5 | * Minor documentation flow improvements 6 | 7 | ## 0 -- 2024-09-11 8 | 9 | * First version. Released on an unsuspecting world. 10 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | dist 2 | dist-newstyle 3 | docs 4 | wiki 5 | TAGS 6 | tags 7 | wip 8 | .DS_Store 9 | .*.swp 10 | .*.swo 11 | *.o 12 | *.hi 13 | *~ 14 | *# 15 | .stack-work/ 16 | cabal-dev 17 | *.chi 18 | *.chs.h 19 | *.dyn_o 20 | *.dyn_hi 21 | .hpc 22 | .hsenv 23 | .cabal-sandbox/ 24 | cabal.sandbox.config 25 | *.prof 26 | *.aux 27 | *.hp 28 | *.eventlog 29 | cabal.project.local 30 | cabal.project.local~ 31 | .HTF/ 32 | .ghc.environment.* 33 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | placeholder 2 | =========== 3 | 4 | [![Hackage](https://img.shields.io/hackage/v/placeholder.svg)](https://hackage.haskell.org/package/placeholder) [![Build Status](https://github.com/ekmett/placeholder/actions/workflows/ci.yml/badge.svg)](https://github.com/ekmett/placeholder/actions/workflows/ci.yml) 5 | 6 | This package provides spiritual equivalents to rust's `todo!` and `unimplemented!` macros. 7 | 8 | Contact Information 9 | ------------------- 10 | 11 | Contributions and bug reports are welcome! 12 | 13 | Please feel free to contact me through github or on the #haskell IRC channel on irc.freenode.net. 14 | 15 | -Edward Kmett 16 | -------------------------------------------------------------------------------- /placeholder.cabal: -------------------------------------------------------------------------------- 1 | cabal-version: 3.4 2 | name: placeholder 3 | version: 0 4 | synopsis: placeholder definitions for TODO and unimplemented 5 | description: placeholder definitions for TODO and unimplemented code 6 | homepage: https://github.com/ekmett/placeholder 7 | license: BSD-2-Clause OR Apache-2.0 8 | license-file: LICENSE.md 9 | author: Edward Kmett 10 | maintainer: Edward Kmett 11 | copyright: Copyright (c) 2024 Edward Kmett 12 | stability: experimental 13 | category: Control 14 | build-type: Simple 15 | extra-doc-files: README.md, CHANGELOG.md 16 | tested-with: GHC == 9.4.8 17 | || == 9.6.6 18 | || == 9.8.2 19 | || == 9.10.1 20 | 21 | source-repository head 22 | type: git 23 | location: https://github.com/ekmett/placeholder 24 | 25 | common base 26 | default-language: Haskell2010 27 | build-depends: 28 | base >= 4.14 && < 5, 29 | ghc-prim 30 | ghc-options: 31 | -Wall -Wincomplete-uni-patterns -Wincomplete-record-updates 32 | -Wredundant-constraints -Widentities 33 | -Wno-simplifiable-class-constraints 34 | 35 | common test 36 | import: base 37 | hs-source-dirs: t 38 | build-depends: 39 | filepath >= 1.4, 40 | placeholder, 41 | tasty >= 1.2, 42 | tasty-hunit >= 0.10.0 43 | 44 | library 45 | import: base 46 | hs-source-dirs: src 47 | exposed-modules: Control.Placeholder 48 | 49 | test-suite placeholder-test 50 | import: test 51 | type: exitcode-stdio-1.0 52 | main-is: Test.hs 53 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: haskell ci 2 | on: 3 | push: 4 | pull_request: 5 | workflow_dispatch: 6 | jobs: 7 | generate-matrix: 8 | name: "Generate matrix from cabal" 9 | outputs: 10 | matrix: ${{ steps.set-matrix.outputs.matrix }} 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Extract the tested GHC versions 14 | id: set-matrix 15 | uses: kleidukos/get-tested@v0.1.7.0 16 | with: 17 | cabal-file: placeholder.cabal 18 | ubuntu-version: latest 19 | macos-version: latest 20 | windows-version: latest 21 | version: 0.1.7.0 22 | tests: 23 | name: ${{ matrix.ghc }} on ${{ matrix.os }} 24 | needs: generate-matrix 25 | runs-on: ${{ matrix.os }} 26 | strategy: 27 | fail-fast: false 28 | matrix: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }} 29 | steps: 30 | - uses: actions/checkout@v4 31 | - uses: haskell-actions/setup@v2 32 | id: setup-haskell 33 | with: 34 | ghc-version: ${{ matrix.ghc }} 35 | - run: cabal freeze --enable-tests 36 | - uses: actions/cache@v2 37 | with: 38 | path: ${{ steps.setup-haskell.outputs.cabal-store }} 39 | key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }} 40 | restore-keys: ${{ runner.os }}-${{ matrix.ghc }}- 41 | - run: cabal build all 42 | - run: cabal test --test-option=--color=always --test-show-details=always test:placeholder-test 43 | - run: cabal test --enable-profiling --test-option=--color=always --test-show-details=always test:placeholder-test 44 | -------------------------------------------------------------------------------- /t/Test.hs: -------------------------------------------------------------------------------- 1 | {-# LANGUAGE ScopedTypeVariables #-} 2 | {-# OPTIONS_GHC -Wno-deprecations #-} 3 | 4 | import Control.Exception 5 | import Control.Monad (when) 6 | import Control.Placeholder 7 | import Data.List 8 | import System.FilePath(()) 9 | import Test.Tasty 10 | import Test.Tasty.HUnit 11 | 12 | main :: IO () 13 | main = defaultMain tests 14 | 15 | tests :: TestTree 16 | tests = testGroup "All tests" [ 17 | basic 18 | ] 19 | 20 | basic :: TestTree 21 | basic = testGroup "Basic" [ 22 | testCase "todo" todoTest 23 | , testCase "unimplemented" unimplementedTest 24 | ] 25 | 26 | todoTest :: IO () 27 | todoTest = do 28 | Left (ex :: TodoException) <- try (evaluate todo) 29 | let msg = show ex 30 | assertBool ("unexpected message: " ++ msg) 31 | $ "Control.Placeholder.todo: not yet implemented" `isPrefixOf` msg 32 | let has x = x `isInfixOf` msg 33 | assertBool ("unexpected HasCallStack format: " ++ msg) $ 34 | all has [ 35 | "CallStack (from HasCallStack):" 36 | , "todo, called at t" "Test.hs:28:47 in" 37 | ] 38 | when (has "CallStack (from -prof)") $ --enable-profiling enabled 39 | assertBool ("unexpected -prof stack format: " ++ msg) $ 40 | all has [ 41 | "Control.Placeholder.todo (src" "Control" "Placeholder.hs:120:1-66)" 42 | , "Main.todoTest (t" "Test.hs:(27,1)-(44,7))" 43 | , "Main.CAF ()" 44 | ] 45 | 46 | unimplementedTest :: IO () 47 | unimplementedTest = do 48 | Left (ex :: UnimplementedException) <- try (evaluate unimplemented) 49 | let msg = show ex 50 | assertBool ("unexpected message: " ++ msg) 51 | $ "Control.Placeholder.unimplemented: unimplemented" `isPrefixOf` msg 52 | -------------------------------------------------------------------------------- /src/Control/Placeholder.hs: -------------------------------------------------------------------------------- 1 | {-# LANGUAGE BlockArguments #-} 2 | {-# LANGUAGE CPP #-} 3 | {-# LANGUAGE DataKinds #-} 4 | {-# LANGUAGE DeriveAnyClass #-} 5 | {-# LANGUAGE ImplicitParams #-} 6 | {-# LANGUAGE MagicHash #-} 7 | {-# LANGUAGE PatternSynonyms #-} 8 | {-# LANGUAGE PolyKinds #-} 9 | {-# LANGUAGE RankNTypes #-} 10 | {-# LANGUAGE Trustworthy #-} 11 | {-# LANGUAGE ViewPatterns #-} 12 | 13 | -- | 14 | -- Copyright : (c) Edward Kmett 2024 15 | -- License : BSD-2-Clause OR Apache-2.0 16 | -- Maintainer : Edward Kmett 17 | -- Stability : experimental 18 | -- Portability: non-portable 19 | -- 20 | -- Various functions to indicate unfinished or generally unimplemented code 21 | 22 | #if __GLASGOW_HASKELL__ >= 980 23 | #define WARNING_IN_XTODO WARNING in "x-todo" 24 | #else 25 | #define WARNING_IN_XTODO WARNING 26 | #endif 27 | 28 | module Control.Placeholder 29 | ( 30 | -- * Combinators 31 | todo 32 | , unimplemented 33 | -- * Patterns 34 | , pattern TODO 35 | , pattern Unimplemented 36 | -- * IO 37 | , todoIO 38 | , unimplementedIO 39 | -- * Exceptions 40 | , TodoException(TodoException, TodoExceptionWithLocation) 41 | , UnimplementedException(UnimplementedException, UnimplementedExceptionWithLocation) 42 | ) where 43 | 44 | import Control.Exception 45 | import Data.List (intercalate) 46 | import Data.Typeable 47 | import GHC.Base (raise#, raiseIO#, TYPE, RuntimeRep) 48 | import GHC.Exception 49 | import GHC.Stack 50 | import GHC.Types (IO(IO)) 51 | import System.IO.Unsafe 52 | 53 | -- | This is the 'Exception' thrown by 'todo', 'TODO' and 'todoIO'. 54 | newtype TodoException = TodoExceptionWithLocation String 55 | deriving (Typeable, Exception) 56 | 57 | instance Show TodoException where 58 | showsPrec _ (TodoExceptionWithLocation loc) 59 | = showString todoMessage . showChar '\n' . showString loc 60 | 61 | -- | This lets us discard the location information in a TodoException 62 | pattern TodoException :: TodoException 63 | pattern TodoException <- TodoExceptionWithLocation _ where 64 | TodoException = TodoExceptionWithLocation missingLocation 65 | 66 | -- | This is the 'Exception' thrown by 'unimplemented', 'Unimplemented', and 'unimplementedIO'. 67 | newtype UnimplementedException = UnimplementedExceptionWithLocation String 68 | deriving (Typeable, Exception) 69 | 70 | instance Show UnimplementedException where 71 | showsPrec _ (UnimplementedExceptionWithLocation loc) 72 | = showString unimplementedMessage . showChar '\n' . showString loc 73 | 74 | pattern UnimplementedException :: UnimplementedException 75 | pattern UnimplementedException <- UnimplementedExceptionWithLocation _ where 76 | UnimplementedException = UnimplementedExceptionWithLocation missingLocation 77 | 78 | -- | robust retrieval of the current callstack suitable for custom exception types 79 | withCallStack :: Exception a => (String -> a) -> CallStack -> SomeException 80 | withCallStack f stk = unsafeDupablePerformIO do 81 | ccsStack <- currentCallStack 82 | let 83 | implicitParamCallStack = prettyCallStackLines stk 84 | ccsCallStack = showCCSStack ccsStack 85 | stack = intercalate "\n" $ implicitParamCallStack ++ ccsCallStack 86 | pure $ toException $ f stack 87 | 88 | {- | 'todo' indicates unfinished code. 89 | 90 | It is to be used whenever you want to indicate that you are missing a part of 91 | the implementation and want to fill that in later. 92 | 93 | The main difference to other alternatives like 'undefined' 94 | or 'error' is this also emits a warning at compile time. 95 | 96 | Similarly to 'undefined' and 'error', this will throw an error if 97 | it is evaluated at runtime which can only be caught in 'IO'. Unlike typed holes, 98 | at least without @-fdefer-typed-holes@ enabled, compilation is allowed to proceed 99 | and the program can be run. 100 | 101 | Variants such as 'TODO' and 'todoIO' allow usage in patterns and offer more control 102 | over when the exception is thrown when this code is encountered at runtime. 103 | 104 | This is intended to *never* stay in code but exists purely for signifying 105 | "work in progress" code. 106 | 107 | To make the emitted warning error instead (e.g. for the use in CI), add 108 | the @-Werror=x-todo@ flag to your @OPTIONS_GHC@. 109 | 110 | ==== __Examples__ 111 | 112 | @ 113 | superComplexFunction :: 'Maybe' a -> 'IO' 'Int' 114 | -- we already know how to implement this in the 'Nothing' case 115 | superComplexFunction 'Nothing' = 'pure' 42 116 | -- but the 'Just' case is super complicated, so we leave it as 'todo' for now 117 | superComplexFunction ('Just' a) = 'todo' 118 | @ 119 | 120 | ==== __Representation Polymorphism__ 121 | 122 | 'todo', in contrast to 'TODO', is fully representation polymorphic 123 | -} 124 | todo :: forall {r :: RuntimeRep} (a :: TYPE r). HasCallStack => a 125 | todo = raise# $ withCallStack TodoExceptionWithLocation ?callStack 126 | {-# WARNING_IN_XTODO todo "'todo' left in code" #-} 127 | 128 | {- | 'todoIO' indicates unfinished code that lives in the IO monad. 129 | 130 | It should be used similarly to how 'throwIO' should be used rather than 'throw' in IO 131 | to throw at the time the IO action is run rather than at the time it is created. 132 | 133 | -} 134 | todoIO :: HasCallStack => IO a 135 | todoIO = IO $ raiseIO# $ withCallStack TodoExceptionWithLocation ?callStack 136 | {-# WARNING_IN_XTODO todoIO "'todoIO' left in code" #-} 137 | 138 | {- | 'TODO' indicates unfinished code or an unfinished pattern match 139 | 140 | You can use this in most positions where you could pass 'todo', but it also can be used in pattern position 141 | to indicate that there are cases you haven't considered. 142 | 143 | There remain some circumstances where you can only use 'todo', however, they arise when using this in a "PolyKinded" situation. 144 | 145 | This pattern synonym is marked @COMPLETE@, implying that every match after matching on 'TODO' 146 | will /emit a redundant pattern match warning/. Adding new options to your datatype, similarly 147 | to how wildcard patterns (patterns starting with an underscore) work, will /not cause any warnings or errors/. 148 | 149 | ==== __Examples__ 150 | 151 | Since the pattern match is strict, even if the branch itself does not evaluate to bottom, matching on 152 | 'TODO' will. 153 | 154 | @ 155 | >>> x = [] 156 | >>> case x of 157 | ... (x : _) -> x 158 | ... 'TODO' -> 42 159 | *** Exception: Control.Placeholder.todo: not yet implemented 160 | @ 161 | 162 | As usual, this behaviour can be reversed by using a @~@ in front of 'TODO' in pattern position. 163 | 164 | @ 165 | >>> x = [] 166 | >>> case x of 167 | ... (x : _) -> x 168 | ... ~'TODO' -> 42 169 | 42 170 | @ 171 | 172 | In most situations, 'TODO' can be used just like 'todo', where the above is equivalent to the below 173 | 174 | @ 175 | >>> y :: 'Data.Int.Int' = 'todo' 176 | >>> x :: 'Data.Int.Int' = 'TODO' 177 | @ 178 | 179 | 180 | ==== __Representation Polymorphism__ 181 | 182 | Mind that pattern synonyms may not be representation polymorphic, hence, if you need something 183 | that can be used with some kind other than 'Data.Kind.Type', you have to use 'todo'. For example, 184 | 'TODO' cannot stand instead of a pattern match on an @'GHC.Exts.Int#' :: 'TYPE' 'GHC.Exts.IntRep'@ 185 | or as a placeholder for a @'GHC.Exts.ByteArray#' :: 'GHC.Exts.UnliftedType'@ 186 | -} 187 | pattern TODO :: HasCallStack => () => a 188 | pattern TODO <- (raise# (withCallStack TodoExceptionWithLocation ?callStack) -> _unused) where 189 | TODO = raise# $ withCallStack TodoExceptionWithLocation ?callStack 190 | {-# WARNING_IN_XTODO TODO "'TODO' left in code" #-} 191 | {-# COMPLETE TODO #-} 192 | 193 | {- | 'unimplemented' indicates that the relevant code is unimplemented. Unlike 'todo', it is expected that this _may_ remain in code 194 | long term, and so no warning is supplied. Use cases might include places where a typeclass would theoretically require a member to be 195 | implemented, but where the resulting violation is actually intended. 196 | -} 197 | 198 | unimplemented :: forall {r :: RuntimeRep} (a :: TYPE r). HasCallStack => a 199 | unimplemented = raise# $ withCallStack UnimplementedExceptionWithLocation ?callStack 200 | 201 | {- | 'unimplementedIO' indicates that the method is unimplemented, but it lives in IO, and so only throws when actually run, rather 202 | than when it is constructed. Unlike 'todoIO' it does not provide a compile-time warning, as it is expected that this _may_ remain in 203 | code long term. 204 | 205 | -} 206 | 207 | unimplementedIO :: HasCallStack => IO a 208 | unimplementedIO = IO $ raiseIO# $ withCallStack UnimplementedExceptionWithLocation ?callStack 209 | 210 | {- | 'Unimplemented' can be used in most circumstances 'unimplemented' can, but it can also be used in pattern position to indicate cases 211 | haven't been considered yet. Unlike 'TODO' it does not provide a compile-time warning, as it is expected that this _may_ remain in code long term. 212 | 213 | -} 214 | pattern Unimplemented :: HasCallStack => () => a 215 | pattern Unimplemented <- (raise# (withCallStack UnimplementedExceptionWithLocation ?callStack) -> _unused) where 216 | Unimplemented = raise# $ withCallStack UnimplementedExceptionWithLocation ?callStack 217 | {-# COMPLETE Unimplemented #-} 218 | 219 | missingLocation :: String 220 | missingLocation = "" 221 | {-# NOINLINE missingLocation #-} 222 | 223 | todoMessage :: String 224 | todoMessage = "Control.Placeholder.todo: not yet implemented" 225 | {-# NOINLINE todoMessage #-} 226 | 227 | unimplementedMessage :: String 228 | unimplementedMessage = "Control.Placeholder.unimplemented: unimplemented" 229 | {-# NOINLINE unimplementedMessage #-} 230 | 231 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | Licensed under either of 4 | * Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0) 5 | * BSD 2-Clause license (https://opensource.org/licenses/BSD-2-Clause) 6 | at your option. 7 | 8 | ## BSD 2-Clause License 9 | 10 | - Copyright 2017-2018 Edward Kmett 11 | - Copyright 2012-2014 Edward Kmett and Dan Doel 12 | 13 | All rights reserved. 14 | 15 | Redistribution and use in source and binary forms, with or without 16 | modification, are permitted provided that the following conditions 17 | are met: 18 | 19 | 1. Redistributions of source code must retain the above copyright 20 | notice, this list of conditions and the following disclaimer. 21 | 22 | 2. Redistributions in binary form must reproduce the above copyright 23 | notice, this list of conditions and the following disclaimer in the 24 | documentation and/or other materials provided with the distribution. 25 | 26 | THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR 27 | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 28 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 29 | DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR 30 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32 | OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 34 | STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 35 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36 | POSSIBILITY OF SUCH DAMAGE. 37 | 38 | ## Apache License 39 | 40 | _Version 2.0, January 2004_ 41 | _<>_ 42 | 43 | ### Terms and Conditions for use, reproduction, and distribution 44 | 45 | #### 1. Definitions 46 | 47 | “License” shall mean the terms and conditions for use, reproduction, and 48 | distribution as defined by Sections 1 through 9 of this document. 49 | 50 | “Licensor” shall mean the copyright owner or entity authorized by the copyright 51 | owner that is granting the License. 52 | 53 | “Legal Entity” shall mean the union of the acting entity and all other entities 54 | that control, are controlled by, or are under common control with that entity. 55 | For the purposes of this definition, “control” means **(i)** the power, direct or 56 | indirect, to cause the direction or management of such entity, whether by 57 | contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the 58 | outstanding shares, or **(iii)** beneficial ownership of such entity. 59 | 60 | “You” (or “Your”) shall mean an individual or Legal Entity exercising 61 | permissions granted by this License. 62 | 63 | “Source” form shall mean the preferred form for making modifications, including 64 | but not limited to software source code, documentation source, and configuration 65 | files. 66 | 67 | “Object” form shall mean any form resulting from mechanical transformation or 68 | translation of a Source form, including but not limited to compiled object code, 69 | generated documentation, and conversions to other media types. 70 | 71 | “Work” shall mean the work of authorship, whether in Source or Object form, made 72 | available under the License, as indicated by a copyright notice that is included 73 | in or attached to the work (an example is provided in the Appendix below). 74 | 75 | “Derivative Works” shall mean any work, whether in Source or Object form, that 76 | is based on (or derived from) the Work and for which the editorial revisions, 77 | annotations, elaborations, or other modifications represent, as a whole, an 78 | original work of authorship. For the purposes of this License, Derivative Works 79 | shall not include works that remain separable from, or merely link (or bind by 80 | name) to the interfaces of, the Work and Derivative Works thereof. 81 | 82 | “Contribution” shall mean any work of authorship, including the original version 83 | of the Work and any modifications or additions to that Work or Derivative Works 84 | thereof, that is intentionally submitted to Licensor for inclusion in the Work 85 | by the copyright owner or by an individual or Legal Entity authorized to submit 86 | on behalf of the copyright owner. For the purposes of this definition, 87 | “submitted” means any form of electronic, verbal, or written communication sent 88 | to the Licensor or its representatives, including but not limited to 89 | communication on electronic mailing lists, source code control systems, and 90 | issue tracking systems that are managed by, or on behalf of, the Licensor for 91 | the purpose of discussing and improving the Work, but excluding communication 92 | that is conspicuously marked or otherwise designated in writing by the copyright 93 | owner as “Not a Contribution.” 94 | 95 | “Contributor” shall mean Licensor and any individual or Legal Entity on behalf 96 | of whom a Contribution has been received by Licensor and subsequently 97 | incorporated within the Work. 98 | 99 | #### 2. Grant of Copyright License 100 | 101 | Subject to the terms and conditions of this License, each Contributor hereby 102 | grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, 103 | irrevocable copyright license to reproduce, prepare Derivative Works of, 104 | publicly display, publicly perform, sublicense, and distribute the Work and such 105 | Derivative Works in Source or Object form. 106 | 107 | #### 3. Grant of Patent License 108 | 109 | Subject to the terms and conditions of this License, each Contributor hereby 110 | grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, 111 | irrevocable (except as stated in this section) patent license to make, have 112 | made, use, offer to sell, sell, import, and otherwise transfer the Work, where 113 | such license applies only to those patent claims licensable by such Contributor 114 | that are necessarily infringed by their Contribution(s) alone or by combination 115 | of their Contribution(s) with the Work to which such Contribution(s) was 116 | submitted. If You institute patent litigation against any entity (including a 117 | cross-claim or counterclaim in a lawsuit) alleging that the Work or a 118 | Contribution incorporated within the Work constitutes direct or contributory 119 | patent infringement, then any patent licenses granted to You under this License 120 | for that Work shall terminate as of the date such litigation is filed. 121 | 122 | #### 4. Redistribution 123 | 124 | You may reproduce and distribute copies of the Work or Derivative Works thereof 125 | in any medium, with or without modifications, and in Source or Object form, 126 | provided that You meet the following conditions: 127 | 128 | * **(a)** You must give any other recipients of the Work or Derivative Works a copy of 129 | this License; and 130 | * **(b)** You must cause any modified files to carry prominent notices stating that You 131 | changed the files; and 132 | * **(c)** You must retain, in the Source form of any Derivative Works that You distribute, 133 | all copyright, patent, trademark, and attribution notices from the Source form 134 | of the Work, excluding those notices that do not pertain to any part of the 135 | Derivative Works; and 136 | * **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any 137 | Derivative Works that You distribute must include a readable copy of the 138 | attribution notices contained within such NOTICE file, excluding those notices 139 | that do not pertain to any part of the Derivative Works, in at least one of the 140 | following places: within a NOTICE text file distributed as part of the 141 | Derivative Works; within the Source form or documentation, if provided along 142 | with the Derivative Works; or, within a display generated by the Derivative 143 | Works, if and wherever such third-party notices normally appear. The contents of 144 | the NOTICE file are for informational purposes only and do not modify the 145 | License. You may add Your own attribution notices within Derivative Works that 146 | You distribute, alongside or as an addendum to the NOTICE text from the Work, 147 | provided that such additional attribution notices cannot be construed as 148 | modifying the License. 149 | 150 | You may add Your own copyright statement to Your modifications and may provide 151 | additional or different license terms and conditions for use, reproduction, or 152 | distribution of Your modifications, or for any such Derivative Works as a whole, 153 | provided Your use, reproduction, and distribution of the Work otherwise complies 154 | with the conditions stated in this License. 155 | 156 | #### 5. Submission of Contributions 157 | 158 | Unless You explicitly state otherwise, any Contribution intentionally submitted 159 | for inclusion in the Work by You to the Licensor shall be under the terms and 160 | conditions of this License, without any additional terms or conditions. 161 | Notwithstanding the above, nothing herein shall supersede or modify the terms of 162 | any separate license agreement you may have executed with Licensor regarding 163 | such Contributions. 164 | 165 | #### 6. Trademarks 166 | 167 | This License does not grant permission to use the trade names, trademarks, 168 | service marks, or product names of the Licensor, except as required for 169 | reasonable and customary use in describing the origin of the Work and 170 | reproducing the content of the NOTICE file. 171 | 172 | #### 7. Disclaimer of Warranty 173 | 174 | Unless required by applicable law or agreed to in writing, Licensor provides the 175 | Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, 176 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, 177 | including, without limitation, any warranties or conditions of TITLE, 178 | NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are 179 | solely responsible for determining the appropriateness of using or 180 | redistributing the Work and assume any risks associated with Your exercise of 181 | permissions under this License. 182 | 183 | #### 8. Limitation of Liability 184 | 185 | In no event and under no legal theory, whether in tort (including negligence), 186 | contract, or otherwise, unless required by applicable law (such as deliberate 187 | and grossly negligent acts) or agreed to in writing, shall any Contributor be 188 | liable to You for damages, including any direct, indirect, special, incidental, 189 | or consequential damages of any character arising as a result of this License or 190 | out of the use or inability to use the Work (including but not limited to 191 | damages for loss of goodwill, work stoppage, computer failure or malfunction, or 192 | any and all other commercial damages or losses), even if such Contributor has 193 | been advised of the possibility of such damages. 194 | 195 | #### 9. Accepting Warranty or Additional Liability 196 | 197 | While redistributing the Work or Derivative Works thereof, You may choose to 198 | offer, and charge a fee for, acceptance of support, warranty, indemnity, or 199 | other liability obligations and/or rights consistent with this License. However, 200 | in accepting such obligations, You may act only on Your own behalf and on Your 201 | sole responsibility, not on behalf of any other Contributor, and only if You 202 | agree to indemnify, defend, and hold each Contributor harmless for any liability 203 | incurred by, or claims asserted against, such Contributor by reason of your 204 | accepting any such warranty or additional liability. 205 | 206 | _END OF TERMS AND CONDITIONS_ 207 | 208 | ### APPENDIX: How to apply the Apache License to your work 209 | 210 | To apply the Apache License to your work, attach the following boilerplate 211 | notice, with the fields enclosed by brackets `[]` replaced with your own 212 | identifying information. (Don't include the brackets!) The text should be 213 | enclosed in the appropriate comment syntax for the file format. We also 214 | recommend that a file or class name and description of purpose be included on 215 | the same “printed page” as the copyright notice for easier identification within 216 | third-party archives. 217 | 218 | Copyright [yyyy] [name of copyright owner] 219 | 220 | Licensed under the Apache License, Version 2.0 (the "License"); 221 | you may not use this file except in compliance with the License. 222 | You may obtain a copy of the License at 223 | 224 | http://www.apache.org/licenses/LICENSE-2.0 225 | 226 | Unless required by applicable law or agreed to in writing, software 227 | distributed under the License is distributed on an "AS IS" BASIS, 228 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 229 | See the License for the specific language governing permissions and 230 | limitations under the License. 231 | 232 | --------------------------------------------------------------------------------