diff --git a/docs/docs_client.rst b/docs/docs_client.rst index 2906a4a3d..f78feca9e 100644 --- a/docs/docs_client.rst +++ b/docs/docs_client.rst @@ -7,7 +7,7 @@ This page contains documentation on the `Discord.Client` class. This should be u It might be beneficial to use CTRL+F to search for what you're looking for, or use the navigation provided by readthedocs on the left. -As of 3.10.1, Discord.Client extends EventEmitter_. In previous versions, the only available methods were `on` and `off`. +.. note:: As of 3.10.1, Discord.Client extends EventEmitter_. In previous versions, the only available methods were `on` and `off`. Attributes ---------- diff --git a/docs/docs_member.rst b/docs/docs_member.rst index c69876142..49d0b843e 100644 --- a/docs/docs_member.rst +++ b/docs/docs_member.rst @@ -3,7 +3,18 @@ Members ======= -The Member Class is used to represent a User_ but specific to a server. **Any attributes/functions available in User_ are omitted.** +The Member Class is used to represent a User_ but specific to a server. **Any attributes/functions available in the User class are omitted.** + +How do I get a Member from a User? +---------------------------------- + +Sometimes you might want a Member object, but instead you are given a User_ object. Since Members belong to servers, you can just do: + +.. code-block:: js + + server.getMember("id", user.id); + +This code will either return `false` if no member is found, or a Member if one is found. This method will work if you are given either a User OR Member object. Attributes ---------- diff --git a/docs/docs_module.rst b/docs/docs_module.rst new file mode 100644 index 000000000..88a5929b7 --- /dev/null +++ b/docs/docs_module.rst @@ -0,0 +1,98 @@ +.. include:: ./vars.rst + +Module +====== + +The Module (``require("discord.js")``) contains some helper functions/objects as well the classes use in Discord. The Classes available are omitted as they are visible under the rest of the `Documentation` section. + +Discord.Colors +-------------- + +Currently Colors are only usable in Roles_. You can't use any colour in messages, unless it's syntax highlighting from codeblocks. + +Example Usage +~~~~~~~~~~~~~ + +.. code-block:: js + + // valid color usage (examples 2-4 only from version 3.10.2): + + mybot.createRole(server, { + color : Discord.Colors.AQUA + }); + + mybot.createRole(server, { + color : "#ff0000" + }); + + mybot.createRole(server, { + color : "ff0000" + }); + + mybot.createRole(server, { + color : 0xff0000 + }); + +Preset Colors: +~~~~~~~~~~~~~~ + +.. code-block:: js + + // these values are just hex converted to base 10 + // e.g. + + // 15844367 -> #f1c40f + // dec hex + + { + DEFAULT: 0, + AQUA: 1752220, + GREEN: 3066993, + BLUE: 3447003, + PURPLE: 10181046, + GOLD: 15844367, + ORANGE: 15105570, + RED: 15158332, + GREY: 9807270, + DARKER_GREY: 8359053, + NAVY: 3426654, + DARK_AQUA: 1146986, + DARK_GREEN: 2067276, + DARK_BLUE: 2123412, + DARK_PURPLE: 7419530, + DARK_GOLD: 12745742, + DARK_ORANGE: 11027200, + DARK_RED: 10038562, + DARK_GREY: 9936031, + LIGHT_GREY: 12370112, + DARK_NAVY: 2899536 + } + +toHex(num) +~~~~~~~~~~ + +Converts a base 10 color (such as the one found in ``serverPermissions.color``) to a valid hex string (e.g. ``#ff0000``) + +- **num** - `Number` that you want to convert to hex + +.. code-block:: js + + // converts Discord.Color.DARK_NAVY to hex: + + Discord.Color.toHex( Discord.Color.DARK_NAVY ); // returns '#2C3E50' + +toDec(data) +~~~~~~~~~~~ + +Converts a hex string to a valid, base 10 Discord color. + +- **data** - `String` that you want to convert, valid formats include: ``ff0000` and ``#ff0000`. If a valid base 10 color (e.g. ``0xff0000`` is passed, this is returned, making the function well at handling ambiguous data. + +.. code-block:: js + + // if you want to create/update a role, you don't have to use + // Color.toDec, this is done for you. + + Discord.Color.toDec( "#ff0000" ); // 16711680 + Discord.Color.toDec( "ff0000" ); // 16711680 + Discord.Color.toDec( 0xff0000 ); // 16711680 \ No newline at end of file diff --git a/docs/docs_permissions.rst b/docs/docs_permissions.rst index 49eceadc3..2509ef669 100644 --- a/docs/docs_permissions.rst +++ b/docs/docs_permissions.rst @@ -18,7 +18,7 @@ name color ~~~~~ -`Number` that is the color of role, use Discord.Color to resolve (see source code under refs/colors.js) +`Number` that represents a colour in base 10. To resolve it to a hex colour, just do: ``permission.color.toString(16)`` hoist ~~~~~ diff --git a/docs/index.rst b/docs/index.rst index 195946991..15745de03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ Contents: :maxdepth: 2 :caption: Documentation + docs_module docs_resolvable docs_client docs_user diff --git a/docs/vars.rst b/docs/vars.rst index fe4493501..c1c148c37 100644 --- a/docs/vars.rst +++ b/docs/vars.rst @@ -10,6 +10,7 @@ .. _Invite Resolvable : ./docs_resolvable.html#invite-resolvable .. _Promises : https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise .. _ServerPermissions : ./docs_permissions.html#id1 +.. _Roles : ./docs_permissions.html#id1 .. _ChannelPermissions : ./docs_permissions.html#id3 .. _EvaluatedPermissions : ./docs_permissions.html#id6 .. _Member : ./docs_member.html \ No newline at end of file diff --git a/lib/Client.js b/lib/Client.js index 63340781c..5e5d21d11 100644 --- a/lib/Client.js +++ b/lib/Client.js @@ -797,15 +797,12 @@ var Client = (function (_EventEmitter) { reject(err); } else { - var moddedPerm = new ServerPermissions(res.body, server); + var perm = server.addRole(res.body); - for (var key in data) { - moddedPerm[key] = data[key]; - } + if (data.color) data.color = Color.toDec(data.color); - var perms = server.addRole(res.body); self.guildRoleCreateIgnoreList[res.body.id] = function () { - self.updateRole(server, moddedPerm).then(function (perm) { + self.updateRole(perm, data).then(function (perm) { cb(null, perm); resolve(perm); })["catch"](function (err) { diff --git a/lib/index.js b/lib/index.js index a11654b8e..7b87e7245 100644 --- a/lib/index.js +++ b/lib/index.js @@ -8,7 +8,18 @@ var Colors = require("../ref/colours.js"); var Discord = { Endpoints: Endpoints, Client: Client, - Colors: Colors + Colors: Colors, + User: require("./user.js"), + Server: require("./server.js"), + Channel: require("./channel.js"), + Message: require("./message.js"), + Invite: require("./invite.js"), + PMChannel: require("./PMChannel.js"), + ServerPermissions: require("./ServerPermissions.js"), + ChannelPermissions: require("./ChannelPermissions.js"), + EvaluatedPermissiosn: require("./EvaluatedPermissions.js"), + VoiceChannel: require("./VoiceChannel.js"), + gameMap: require("../ref/gameMap.json") }; Discord.patchStrings = function () { diff --git a/lib/internal.js b/lib/internal.js index 3acf5940b..c151fbf0c 100644 --- a/lib/internal.js +++ b/lib/internal.js @@ -1,3 +1,8 @@ +/* + this file is deprecated and should only be used as + reference. +*/ + "use strict"; var request = require("superagent"); diff --git a/package.json b/package.json index 401de1e7f..a507bcda7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "discord.js", - "version": "3.10.1", + "version": "3.10.2", "description": "A way to interface with the Discord API", "main": "./lib/index.js", "scripts": { diff --git a/ref/colours.js b/ref/colours.js index ce650dad2..bc1bb1674 100644 --- a/ref/colours.js +++ b/ref/colours.js @@ -1,5 +1,5 @@ /* - credits to izy521 for the colour list] + credits to izy521 for the colour list https://github.com/izy521/discord.io/blob/master/docs/colors.md */ module.exports = { @@ -24,4 +24,27 @@ module.exports = { DARK_GREY: 9936031, LIGHT_GREY: 12370112, DARK_NAVY: 2899536 +} + +exports.toDec = function(data){ + var hextest = /(^#[0-9A-F]{6}$)|(^#[0-9A-F]{3}$)/; + + var num; + + if(hextest.test(data)){ + // it's a hex number with a # in front + num = data.substr(1).toString(10); + }else if(hextest.test("#" + data)){ + // it's a hex number with no # in front + num = data.toString(10); + }else{ + num = data.toString(10); + } + return num; +} + +exports.toHex = function(data){ + + return "#" + data.toString(16); + } \ No newline at end of file diff --git a/src/Client.js b/src/Client.js index 3b5c11e9a..e6e57eb6a 100644 --- a/src/Client.js +++ b/src/Client.js @@ -837,16 +837,14 @@ class Client extends EventEmitter { cb(err); reject(err); } else { - - var moddedPerm = new ServerPermissions(res.body, server); - - for (var key in data) { - moddedPerm[key] = data[key]; - } - - var perms = server.addRole(res.body); + + var perm = server.addRole(res.body); + + if(data.color) + data.color = Color.toDec(data.color); + self.guildRoleCreateIgnoreList[res.body.id] = function () { - self.updateRole(server, moddedPerm) + self.updateRole(perm, data) .then((perm) => { cb(null, perm); resolve(perm); diff --git a/src/index.js b/src/index.js index 6bfd12014..2967b8f3d 100644 --- a/src/index.js +++ b/src/index.js @@ -6,7 +6,18 @@ var Colors = require("../ref/colours.js"); var Discord = { Endpoints : Endpoints, Client : Client, - Colors : Colors + Colors : Colors, + User : require("./user.js"), + Server : require("./server.js"), + Channel : require("./channel.js"), + Message : require("./message.js"), + Invite : require("./invite.js"), + PMChannel : require("./PMChannel.js"), + ServerPermissions : require("./ServerPermissions.js"), + ChannelPermissions : require("./ChannelPermissions.js"), + EvaluatedPermissiosn : require("./EvaluatedPermissions.js"), + VoiceChannel : require("./VoiceChannel.js"), + gameMap : require("../ref/gameMap.json") } Discord.patchStrings = function () { diff --git a/src/internal.js b/src/internal.js index 42d0dc689..02744cd66 100644 --- a/src/internal.js +++ b/src/internal.js @@ -1,3 +1,8 @@ +/* + this file is deprecated and should only be used as + reference. +*/ + var request = require( "superagent" ); var Endpoints = require( "./endpoints.js" );