Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Side by Side Diff: README.md

Issue 5987679581765632: Issue 1288 - Add basic usage instructions to the README (Closed)
Patch Set: Emphasize the ineptitude of DefaultWebRequest et. al. more Created Sept. 2, 2014, 1:29 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 libadblockplus 1 libadblockplus
2 ============== 2 ==============
3 3
4 A C++ library offering the core functionality of Adblock Plus. 4 A C++ library offering the core functionality of Adblock Plus.
5 5
6 libadblockplus is still work in progress, at an early stage. 6 libadblockplus is still work in progress, at an early stage.
7 7
8 Building 8 Building
9 -------- 9 --------
10 10
(...skipping 26 matching lines...) Expand all
37 37
38 * Execute `createsolution.bat` to generate project files, this will create 38 * Execute `createsolution.bat` to generate project files, this will create
39 `build\ia32\libadblockplus.sln` (solution for the 32 bit build) and 39 `build\ia32\libadblockplus.sln` (solution for the 32 bit build) and
40 `build\x64\libadblockplus.sln` (solution for the 64 bit build). Unfortunately, 40 `build\x64\libadblockplus.sln` (solution for the 64 bit build). Unfortunately,
41 V8 doesn't support creating both from the same project files. 41 V8 doesn't support creating both from the same project files.
42 * Open `build\ia32\libadblockplus.sln` or `build\x64\libadblockplus.sln` in 42 * Open `build\ia32\libadblockplus.sln` or `build\x64\libadblockplus.sln` in
43 Visual Studio and build the solution there. Alternatively you can use the 43 Visual Studio and build the solution there. Alternatively you can use the
44 `msbuild` command line tool, e.g. run `msbuild /m build\ia32\libadblockplus.sln` 44 `msbuild` command line tool, e.g. run `msbuild /m build\ia32\libadblockplus.sln`
45 from the Visual Studio Developer Command Prompt to create a 32 bit debug build. 45 from the Visual Studio Developer Command Prompt to create a 32 bit debug build.
46 46
47 Usage
48 -----
49
50 You can use libadblockplus to build an ad blocker. Or, strictly speaking, a web
51 content filter. Just like Adblock Plus, it can detect resources that should be
52 blocked based on their URL and context information, and generate CSS selectors
53 to hide DOM elements.
54
55 The basic usage is explained below, see the
56 [API documentation](https://adblockplus.org/docs/libadblockplus) for more
57 information. See the [filter documentation](https://adblockplus.org/en/filters)
58 to learn more about Adblock Plus filters.
59
60 ### Initialising the engine
61
62 All the types and functions in libadblockplus are in the `AdblockPlus`
63 namespace. For brevity's sake, we'll assume the following `using` declaration:
64
65 using namespace AdblockPlus;
66
67 Most of the functionality of libadblockplus is available via the
68 [`FilterEngine`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_ 1_1_filter_engine.html)
69 class. Since libadblockplus uses the Adblock Plus core code under the hood, you
70 first need to create a
71 [`JsEngine`](https://adblockplus.org/docs/libadblockplus/class_adblock_plus_1_1_ js_engine.html)
72 instance and pass some information about your
73 application to it.
74
75 AppInfo appInfo;
76 appInfo.name = "awesomewebfilter";
77 appInfo.version = "0.1";
78 appInfo.locale = "en-US";
79 JsEngine jsEngine(appInfo);
80
81 `JsEngine` needs to store files, make web requests and write log messages. This
82 normally works out of the box because it is using
83 [`DefaultFileSystem`](https://adblockplus.org/docs/libadblockplus/class_adblock_ plus_1_1_default_file_system.html),
84 [`DefaultWebRequest`](https://adblockplus.org/docs/libadblockplus/class_adblock_ plus_1_1_default_web_request.html)
85 and
86 [`DefaultLogSystem`](https://adblockplus.org/docs/libadblockplus/class_adblock_p lus_1_1_default_log_system.html)
87 by default.
88
89 Depending on your application and platform, you might want to supply your own
90 implementations for these - see
91 [`FilterEngine::SetFileSystem`](https://adblockplus.org/docs/libadblockplus/clas s_adblock_plus_1_1_js_engine.html#a979e9bde78499dab9f5e3aacc5155f40),
92 [`FilterEngine::SetWebRequest`](https://adblockplus.org/docs/libadblockplus/clas s_adblock_plus_1_1_js_engine.html#a290a03b86137a56d7b2f457f03c77504)
93 and
94 [`FilterEngine::SetLogSystem`](https://adblockplus.org/docs/libadblockplus/class _adblock_plus_1_1_js_engine.html#ab60b10be1d4500bce4b17c1e9dbaf4c8)
95 respectively.
96
97 With the `JsEngine` instance created, you can create a `FilterEngine` instance:
98
99 FilterEngine filterEngine(jsEngine);
100
101 When initialised, `FilterEngine` will automatically select a suitable ad
102 blocking subscription based on `AppInfo::locale` and download the filters for
103 it.
104
105 ### Managing subscriptions
106
107 libadblockplus takes care of storing and updating subscriptions.
108
109 You can add more:
110
111 SubscriptionPtr subscription =
112 filterEngine.GetSubscription("https://example.org/filters.txt");
113 subscription->AddToList();
114
115 Retrieving an existing subscription works the same way, use
116 [`Subscription::IsListed`](https://adblockplus.org/docs/libadblockplus/class_adb lock_plus_1_1_subscription.html#a42da64bdc0cb7ee65a27a001db0307c8)
117 to check if the subscription has been added or not.
118
119 SubscriptionPtr subscription =
120 filterEngine.GetSubscription("https://example.org/filters.txt");
121 if (subscription->IsListed())
122 ....
123
124 Removing a subscription is not rocket science either:
125
126 subscription->RemoveFromList();
127
128 You can also get a list of all subscriptions that were added:
129
130 std::vector<SubscriptionPtr> subscriptions =
131 filterEngine.GetListedSubscriptions();
132
133 ### Managing custom filters
134
135 Working with custom filters is very similar to working with subscriptions:
136
137 FilterPtr filter = filterEngine.GetFilter("||example.com/ad.png");
138 filter->AddToList();
139 filter->RemoveFromList();
140
141 Note that applications should only do this to manage a user's custom filters. In
142 general, filter lists should be hosted somewhere and added as a subscription.
143
144 ### Matching blocking filters
145
146 As mentioned above, one of the two main tasks of libadblockplus is to check if
147 a URL matches any of the active blocking filters.
148
149 To demonstrate this, we'll add a custom filter:
150
151 FilterPtr filter = filterEngine.GetFilter("||example.com/ad.png");
152 filter->AddToList();
153
154 Now we'll call matches on an URL that should be blocked:
155
156 FilterPtr match =
157 filterEngine.Matches("http://example.com/ad.png", "DOCUMENT", "");
158
159 Since we've added a matching filter, `match` will point to the same filter
160 object as `filter`.
161
162 Note that we've ignored the third parameter of
163 [`FilterEngine::Matches`](https://adblockplus.org/docs/libadblockplus/class_adbl ock_plus_1_1_filter_engine.html#a184211d324bfb6e23c5e09fae2d12f91)
164 here to keep things simple. Real applications should pass the frame structure
165 in here - this is necessary because many filters and exception rules are domain
166 specific.
167
168 ### Generating CSS from element hiding filters
169
170 Aside from blocking requests, ad blockers typically also hide elements. This is
171 done via a second type of filter that is completely ignored when matching URLs:
172 [element hiding rules](https://adblockplus.org/en/filters#elemhide).
173
174 You can retrieve a list of all CSS selectors for elements that should be hidden
175 using
176 [`FilterEngine::GetElementHidingSelectors`](https://adblockplus.org/docs/libadbl ockplus/class_adblock_plus_1_1_filter_engine.html#a91c44dac13c7655230be49440f45a 168).
177
178 What libadblockplus clients typically do with this is to generate a CSS style
179 sheet that is injected into each page.
180
47 Shell 181 Shell
48 ----- 182 -----
49 183
50 The _shell_ subdirectory contains an example application using libadblockplus. 184 The _shell_ subdirectory contains an example application using libadblockplus.
51 185
52 It's a simple shell that loads subscriptions into memory and checks 186 It's a simple shell that loads subscriptions into memory and checks
53 whether a specified resource would be blocked or not. 187 whether a specified resource would be blocked or not.
54 188
55 To see the available commands, type `help`. 189 To see the available commands, type `help`.
56 190
57 ### Unix 191 ### Unix
58 192
59 The shell is automatically built by `make`, you can run it as follows: 193 The shell is automatically built by `make`, you can run it as follows:
60 194
61 build/out/abpshell 195 build/out/abpshell
62 196
63 ### Windows 197 ### Windows
64 198
65 Just run the project *abpshell*. 199 Just run the project *abpshell*.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld