Merge pull request #1 from hydrabolt/examples

Add some examples and improve older ones

examples/avatar.js

@@ -1,15 +1,30 @@
+/*
+ * A bot that shows how to mention users in messages and how to
+ * access user avatars.
+ */
+
 var Discord = require( "discord.js" );
 var myBot = new Discord.Client();
 
 myBot.login( "hello@example.com", "password1" );
 
 myBot.on( "message", function( message ) {
+	// React to all messages with the content "$avatar"
 	if ( message.content === "$avatar" ) {
-		var user = message.author; //the user who wants an avatar is the author
+		// Obtain the user who requested the avatar.
+		var user = message.author;
+
+		// Check whether the user actually has an avatar.
 		if ( user.avatar ) {
+			// Construct the avatar URL from the user ID and the avatar ID.
 			var url = "https://discordapp.com/api/users/" + user.id + "/avatars/" + user.avatar + ".jpg";
+
+			// A user can be mentioned in a message by inserting the string obtained
+			// by user.mention() into the message.
+			// Note that simply writing "@user" will NOT work.
 			bot.sendMessage( message.channel, message.author.mention() + ", here's your avatar: " + url );
 		} else {
+			// Nothing should be done if the user has not set an avatar.
 			bot.sendMessage( message.channel, message.author.mention() + ", you don't have an avatar!" );
 		}
 	}

examples/formatting.js

@@ -0,0 +1,18 @@
+/*
+ * Discord uses a subset of Markdown for formatting, so adding formatting to
+ * messages is as simple as inserting the formatting codes into the message.
+ */
+
+var Discord = require( "discord.js" );
+var myBot = new Discord.Client();
+
+myBot.login( "hello@example.com", "password1" );
+
+myBot.on( "message", function( message ) {
+	// React to all messages with the content "$formatting".
+	if ( message.content === "$formatting" ) {
+    // Show off formatting by sending a simple message with formatting codes.
+    myBot.sendMessage( message.channel, "**bold** ****semibold**** *italic* " +
+        "_**bold and italic**_ __underline__ ~~strikethrough~~" );
+	}
+} );

examples/pingpong.js

@@ -1,10 +1,26 @@
+/*
+ * A basic bot that shows how to connect to a Discord account,
+ * how to listen to messages and how to send messages.
+ *
+ * This bot responds to every "ping" message with a "pong".
+ */
+
 var Discord = require( "discord.js" );
+
+// Create the bot
 var myBot = new Discord.Client();
 
+// Login with an example email and password
 myBot.login( "hello@example.com", "password1" );
 
+// Add a listener to the "message" event, which triggers upon receiving
+// any message
 myBot.on( "message", function( message ) {
+	// message.content accesses the content of the message as a string.
+	// If it is equal to "ping", then the bot should respond with "pong".
 	if ( message.content === "ping" ) {
+		// Send a message ("pong") to the channel the message was sent in,
+		// which is accessed by message.channel.
 		this.sendMessage( message.channel, "pong" );
 	}
 } );

examples/presence.js

@@ -1,8 +1,18 @@
+/*
+ * A bot that shows how to listen to presence update events, such as a user
+ * joining or leaving.
+ */
+
 var Discord = require( "discord.js" );
 var myBot = new Discord.Client();
 
 myBot.login( "hello@example.com", "password1" );
 
+// The "presence" event is triggered when a user joins a server, leaves it or
+// goes away.
+// The status parameter can be "online", "offline" or "idle", respectively.
 myBot.on( "presence", function( user, status, server ) {
+	// Send a message on the default channel of the server, as presence updates
+	// are not restricted to one channel.
 	bot.sendMessage( server.getDefaultChannel(), user.mention() + " is " + status + "!" );
 } );

examples/query.js

@@ -0,0 +1,50 @@
+/*
+ * A bot that shows how to access and search the logs of a specific channel.
+ * Specifically, it returns the last message from a given user in the last
+ * 100 messages.
+ */
+
+var Discord = require( "discord.js" );
+var myBot = new Discord.Client();
+
+myBot.login( "hello@example.com", "password1" );
+
+myBot.on( "message", function( message ) {
+	// React to all messages starting with "$query".
+	if ( message.content.startsWith( "$query" ) ) {
+    // Obtain the channel for which logs should be accessed.
+    var channel = message.channel;
+
+    // Find all the arguments to the command.
+    var arguments = message.content.split( " " );
+
+    // Get the first argument specifically, as it contains the username
+    // to be queried for.
+    var username = arguments.slice( 1 ).join( " " );
+
+    // Exit the event handler unless the user exists.
+    if( !username ) {
+      myBot.sendMessage( channel, "That user doesn't exist!" );
+      return;
+    }
+
+    // The getChannelLogs() function takes the channel that should be accessed,
+    // the amount of messages to query and a callback as its arguments.
+    myBot.getChannelLogs( channel, 100, function( messageList ) {
+      // filter() takes three arguments, the key to be filtered for (in this
+      // case the username, so "username"), the value to look for, and whether
+      // only the first finding should be returned (true) or a list of all
+      // findings (false).
+      var message = messageList.filter( "username", username, true );
+
+      // Only continue if the message has been found
+      if( message ) {
+        myBot.sendMessage( channel, "The last message from user " + username +
+            " is: \"" + message.content + "\"." ).
+      } else {
+        myBot.sendMessage( "That user has not sent a message " +
+            "for the last 100 messages!" )
+      }
+    } );
+	}
+} );

examples/status.js

@@ -0,0 +1,24 @@
+/*
+ * A bot that doesn't interact with Discord, but instead shows how to listen
+ * to the "ready" and "disconnected" events, that are triggered when the bot
+ * starts up or shuts down, respectively.
+ */
+
+var Discord = require( "discord.js" );
+var myBot = new Discord.Client();
+
+myBot.login( "hello@example.com", "password1" );
+
+// The "ready" event is triggered after the bot successfully connected to
+// Discord and is ready to send messages.
+myBot.on( "ready", function() {
+  console.log( "Bot connected successfully." );
+} );
+
+// The "disconnected" event is triggered after the connection to Discord
+// ended.
+// It is also triggered when the connection attempt fails, for example due
+// to a wrong password.
+myBot.on( "disconnected", function() {
+  console.log( "Bot disconnected from Discord." );
+} );