Skip to content

Commit

Permalink
Update README, because nothing is ever simple
Browse files Browse the repository at this point in the history
In writing, assuming something is "simple", "obvious", "just do it", and similar is an irk of mine. No ill was meant when these words were originally written.
  • Loading branch information
Burgestrand committed May 10, 2023
1 parent 1f5f6be commit 64228ce
Showing 1 changed file with 15 additions and 25 deletions.
40 changes: 15 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[![Gem Version](https://badge.fury.io/rb/pundit.svg)](http://badge.fury.io/rb/pundit)

Pundit provides a set of helpers which guide you in leveraging regular Ruby
classes and object oriented design patterns to build a simple, robust and
classes and object oriented design patterns to build a straightforward, robust, and
scalable authorization system.

Links:
Expand Down Expand Up @@ -49,8 +49,8 @@ can pick up any classes in the new `app/policies/` directory.
## Policies

Pundit is focused around the notion of policy classes. We suggest that you put
these classes in `app/policies`. This is a simple example that allows updating
a post if the user is an admin, or if the post is unpublished:
these classes in `app/policies`. This is an example that allows updating a post
if the user is an admin, or if the post is unpublished:

``` ruby
class PostPolicy
Expand All @@ -67,7 +67,7 @@ class PostPolicy
end
```

As you can see, this is just a plain Ruby class. Pundit makes the following
As you can see, this is a plain Ruby class. Pundit makes the following
assumptions about this class:

- The class has the same name as some kind of model class, only suffixed
Expand Down Expand Up @@ -199,7 +199,7 @@ you can retrieve it by passing a symbol.
class DashboardPolicy
attr_reader :user

# _record in this example will just be :dashboard
# _record in this example will be :dashboard
def initialize(user, _record)
@user = user
end
Expand All @@ -211,7 +211,7 @@ end
```

Note that the headless policy still needs to accept two arguments. The
second argument will just be the symbol `:dashboard` in this case which
second argument will be the symbol `:dashboard` in this case, which
is what is passed as the record to `authorize` below.

```ruby
Expand Down Expand Up @@ -374,7 +374,7 @@ these filters without affecting how your app works in any way.**

Some people have found this feature confusing, while many others
find it extremely helpful. If you fall into the category of people who find it
confusing then you do not need to use it. Pundit will work just fine without
confusing then you do not need to use it. Pundit will work fine without
using `verify_authorized` and `verify_policy_scoped`.

### Conditional verification
Expand Down Expand Up @@ -419,20 +419,13 @@ class Post
end
```

## Just plain old Ruby
## Plain old Ruby

As you can see, Pundit doesn't do anything you couldn't have easily done
yourself. It's a very small library, it just provides a few neat helpers.
Together these give you the power of building a well structured, fully working
authorization system without using any special DSLs or funky syntax or
anything.
Pundit is a very small library on purpose, and it doesn't do anything you can't do yourself. There's no secret sauce here. It does as little as possible, and then gets out of your way.

Remember that all of the policy and scope classes are just plain Ruby classes,
which means you can use the same mechanisms you always use to DRY things up.
Encapsulate a set of permissions into a module and include them in multiple
policies. Use `alias_method` to make some permissions behave the same as
others. Inherit from a base set of permissions. Use metaprogramming if you
really have to.
With the few but powerful helpers available in Pundit, you have the power to build a well structured, fully working authorization system without using any special DSLs or funky syntax.

Remember that all of the policy and scope classes are plain Ruby classes, which means you can use the same mechanisms you always use to DRY things up. Encapsulate a set of permissions into a module and include them in multiple policies. Use `alias_method` to make some permissions behave the same as others. Inherit from a base set of permissions. Use metaprogramming if you really have to.

## Generator

Expand Down Expand Up @@ -555,8 +548,7 @@ en:
create?: 'You cannot create posts!'
```
Of course, this is just an example. Pundit is agnostic as to how you implement
your error messaging.
This is an example. Pundit is agnostic as to how you implement your error messaging.
## Manually retrieving policies and scopes
Expand All @@ -578,9 +570,7 @@ those without the bang will return nil.

## Customize Pundit user

In some cases your controller might not have access to `current_user`, or your
`current_user` is not the method that should be invoked by Pundit. Simply
define a method in your controller called `pundit_user`.
On occasion, your controller may be unable to access `current_user`, or the method that should be invoked by Pundit may not be `current_user`. To address this, you can define a method in your controller named `pundit_user`.

```ruby
def pundit_user
Expand Down Expand Up @@ -800,7 +790,7 @@ An alternative approach to Pundit policy specs is scoping them to a user context

### Scope Specs

Pundit does not provide a DSL for testing scopes. Just test it like a regular Ruby class!
Pundit does not provide a DSL for testing scopes. Test them like you would a regular Ruby class!

### Linting with RuboCop RSpec

Expand Down

0 comments on commit 64228ce

Please sign in to comment.