You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can include _Krate_ in your project from the `mavenCentral()` repository, like so:
27
+
Krate is available from `mavenCentral()`. You can add it to your dependencies with the following line:
28
28
29
29
```groovy
30
-
implementation 'hu.autsoft:krate:1.2.0'
30
+
implementation 'hu.autsoft:krate:2.0.0'
31
31
```
32
32
33
-
# Optionals vs defaults
33
+
# Basics
34
34
35
-
Each stored property can be declared with or without a default value. Here's how the two options differ:
35
+
A Krate property is nullable by default. It will have a `null` value if no value has been set for the property yet, and its current value can be erased from `SharedPreferences` completely by setting it to `null`.
36
36
37
-
### Optional values:
37
+
```kotlin
38
+
var username:String? by stringPref()
39
+
```
40
+
41
+
### Default values
38
42
39
-
A property declared with the one-argument delegate function will have a nullable type. It will have a `null` value if no value has been set for this property yet, and its current value can be erased from `SharedPreferences` completely by setting it to `null`.
43
+
You can provide a default value for the property by chaining a `withDefault` call on the delegate function. This will give the property a non-nullable type.
40
44
41
45
```kotlin
42
-
var username:String? by stringPref("username")
46
+
var username:String by stringPref().withDefault("admin")
43
47
```
44
48
45
-
### Default values:
49
+
Reading from this property will return either the value it was last set to, or the default value if it's never been set.
50
+
51
+
> Note that there's no way to remove these values from `SharedPreferences` (although you could set it explicitly to the default value).
52
+
53
+
### Custom keys
54
+
55
+
By default, the the property will be stored under the key of the property's name in the underlying `SharedPreferences` instance.
46
56
47
-
A property declared with the two-argument delegate function takes its default value as the second argument, and it will have a non-nullable type. Reading from this property will return either the value it was last set to or the default value. Setting this property will update the value stored in `SharedPreferences`. Note that there's no way to remove these values from `SharedPreferences` (although you could set it explicitly to the default value).
57
+
You can change this behaviour by explicitly providing the key as an argument:
48
58
49
59
```kotlin
50
-
var username:String by stringPref("username", defaultValue ="admin")
60
+
var username:String? by stringPref(key ="USER_NAME")
51
61
```
52
62
63
+
> Note that if you rely on property names as keys, renaming a Krate property will become a breaking change, and the previously stored value will be lost. This can be avoided by adding an explicit key with the name of the original property.
64
+
65
+
### Validation
66
+
67
+
You can add validation rules to your Krate properties by calling `validate` on any of Krate's delegate functions:
68
+
69
+
```kotlin
70
+
var percentage:Int by intPref()
71
+
.withDefault(0)
72
+
.validate { it in0..100 }
73
+
```
74
+
75
+
If this validation fails, an `IllegalArgumentException` will be thrown.
76
+
53
77
# Custom Krate implementations
54
78
55
-
You can usually get away with extending `SimpleKrate`, as it does allow you to pass in a custom name for the `SharedPreferences` to be used to store your values in its constructor as an optional parameter. (If you pass in no `name` parameter to its constructor, it will default to using the instance returned by `PreferenceManager.getDefaultSharedPreferences(context)`.)
79
+
You can usually get away with extending `SimpleKrate`, as it does allow you to pass in a custom name for the `SharedPreferences` to be used to store your values in its constructor as an optional parameter. (If you pass in no `name` parameter to its constructor, it will default to using the instance returned by `PreferenceManager.getDefaultSharedPreferences(context)`.)
56
80
57
-
However, you can also implement the `Krate` interface directly if you want to manage the `SharedPreferences` instance yourself for whatever reason - all this interface requires is a property that holds a `SharedPreferences` instance. With that, you can use the delegate functions the same way as shown above:
81
+
However, you can also implement the `Krate` interface directly if you want to manage the `SharedPreferences` instance yourself for whatever reason - all this interface requires is a property that holds a `SharedPreferences` instance. With that, you can use the delegate functions the same way as shown above:
val myStringValue:String by stringPref("my_string_value", "")
126
+
val myStringValue:String by stringPref().withDefault("")
103
127
}
104
128
```
105
129
106
-
# Validation
107
-
108
-
You can add validation rules to your Krate properties by calling `validate` on any of Krate's delegate functions:
109
-
110
-
```kotlin
111
-
var percentage:Int by intPref(
112
-
key ="percentage",
113
-
defaultValue =0,
114
-
).validate { it in0..100 }
115
-
```
116
-
117
-
If this validation fails, an `IllegalArgumentException` will be thrown.
118
-
119
-
# Addons
130
+
# Serialization addons
120
131
121
132
Krate, by default, supports the types that `SharedPreferences` supports. These are `Boolean`, `Float`, `Int`, `Long`, `String` and `Set<String>`. You may of course want to store additional types in Krate.
122
133
@@ -132,8 +143,8 @@ The usage of the Krate integration is the same for both setups:
var savedArticles:List<Article>? by moshiPref("articles")
146
+
var user:User? by moshiPref()
147
+
var savedArticles:List<Article>? by moshiPref()
137
148
}
138
149
```
139
150
@@ -152,7 +163,7 @@ class CustomMoshiKrate(context: Context) : SimpleKrate(context) {
152
163
If you only want to use Moshi adapters that you generate via Moshi's [codegen facilities](https://github.com/square/moshi#codegen), you can use the following Krate artifact in your project to make use of these adapters:
This will give you a default `Moshi` instance created by a call to `Moshi.Builder().build()`. This instance will find and use any of the adapters generated by Moshi's codegen automatically.
@@ -162,7 +173,7 @@ This will give you a default `Moshi` instance created by a call to `Moshi.Builde
162
173
If you rely on [reflection](https://github.com/square/moshi#reflection) for your Moshi serialization, and therefore need a `KotlinJsonAdapterFactory` included in your `Moshi` instance, use the following Krate Moshi dependency:
The default `Moshi` instance from this dependency will include the aforementioned factory, and be able to serialize any Kotlin class. Note that this approach relies on the `kotlin-reflect` library, which is a large dependency.
@@ -174,15 +185,15 @@ You may choose to use Moshi's codegen for some classes in your project, and seri
174
185
The `krate-kotlinx` artifact provides a `kotlinxPref` delegate which can store any arbitrary type, as long as Kotlinx.serializazion can serialize and deserialize it. This addon, like the base library, is available from `mavenCentral()`:
175
186
176
187
```groovy
177
-
implementation 'hu.autsoft:krate-kotlinx:1.2.0'
188
+
implementation 'hu.autsoft:krate-kotlinx:2.0.0'
178
189
```
179
190
180
191
Its usage is the same as with any of the base library's delegates:
var savedArticles:List<Article>? by kotlinxPref("articles")
195
+
var user:User? by kotlinxPref()
196
+
var savedArticles:List<Article>? by kotlinxPref()
186
197
}
187
198
```
188
199
@@ -197,7 +208,7 @@ class CustomKotlinxKrate(context: Context) : SimpleKrate(context) {
197
208
}
198
209
}
199
210
200
-
var user:User? by kotlinxPref("user")
211
+
var user:User? by kotlinxPref()
201
212
}
202
213
```
203
214
@@ -206,15 +217,15 @@ class CustomKotlinxKrate(context: Context) : SimpleKrate(context) {
206
217
The `krate-gson` artifact provides a `gsonPref` delegate which can store any arbitrary type, as long as Gson can serialize and deserialize it. This addon, like the base library, is available from `mavenCentral()`:
207
218
208
219
```groovy
209
-
implementation 'hu.autsoft:krate-gson:1.2.0'
220
+
implementation 'hu.autsoft:krate-gson:2.0.0'
210
221
```
211
222
212
223
Its basic usage is the same as with any of the base library's delegates:
0 commit comments