Docmand - Documents and Commands

Download v0.6.04
Allows creation of custom commands that will send the content of files or urls to the player.
It allows for custom message on Join (MOTD) and Teleports.
Complete with tag system that can transform tags in content to java code and thus enabling a very large portion of customization.
You decide what the plugin should do (In the frame of the functionality the plugin allows you too)
Consider it a very feature rich MCDocs replacement.
Permission and Multiworld support.
Argument support, parse arguments around to the various aspects of commands, alias' and other.

Update notice

Important before updating to v. 0.6.xx from 0.5x:

Please delete/rename your events.yml file, it will auto generate a new example file following the new code.
The old events file is NOT compatible with the new system. Recreate your events again.
I'm sorry for the inconvenience, but this update is a major change to the events system. I will try in the next update to supply a better upgrade system.
Also advised to delete the default.yml parser, it will regenerate with some new parsers, and generally avoid adding your own parsers to the default.yml parser file, instead create your parsers in seperate file(s).

Installation

Download and put in plugins folder. Reload server.
cbDocmand will auto generate default config file, and some example files.

Config

cacheTime	All files/url are loaded in to memory and stored, this cache time tells how long to store this before getting an updated text, in seconds
linesPerPage	How many lines is shown per page when creating pagination, shows up to linesPerPage + 1 before it will create pages
logLevel	(currently not in use) What level of log to show. 0 = nothing, 1 = litle information, 2 = more information, 3 = all debug information
paginationHeader	What the pagination header should render as, 3 variables can be used, %x and %y is current page and total pages respectively, and %commands will render as the 3 pagination commands defined with pageCommands
pageCommands	Defines the commands that can used to traverse the pages.

Usage

Edit and add as many Files in the files folder as you wish.
Edit and add as many Events in the events.yml file as you wish.
Edit and add as many Parsers as you wish, advised to not edit the default parser since this will be updated with new versions, but you can add new files. All .yml files in the parsers folder will be loaded, so feel free to add new parsers to support your favorite plugin, and share them in the Forum.

Messages sent to the player will be colorized using the standard minecraft colors when written with &x where x is between hex 0-f.
Messages sent to the player are automatically converted to pages, if more than 9 (or what is specified in config) lines is present.
Pages can be viewed by typing the next, previous or page command as defined in the pageCommand config.
E.g. a command /rules will be sending 16 lines to the user. The content is automatically split into two pages and a header presenting the pagination will be sent
Page 1 of 2 (/next, /prev or /page <x> to select page)
The user can then send the command /next or /page 2 to view the second page

You can reload all configs with the command:
/docmand reload - Requires the permission docmand.reload

Docmand Permissions

docmand.reload	Ability to reload all docmand configs, events, files and parsers.
docmand.all	A user with this permissions will skip permission check for all events.

Concepts

There are 3 concepts you will need to know about to use cbDocmand: Events, Parsers and Files

Events

There are 3 types of Events
Commands which triggers when a player enters the command
Joins which triggers on a join event
Teleports which triggers when a player either teleports via command or plugin or netherportals to the specified world

Events are specied by writing an element that contain one or more event descriptions (In no particular order).
You can specify several events to one trigger, e.g you can more than 1 join event, or more events to a command, based on permission and world. etc.
All events that is fullfilled will be triggered, so if an event specified no world or no permission it will be triggered alongside those that have a world or permission specied.
Event desciptions supported are: World, Permission and Actions.

World event description:
You can specify one or more worlds the event will trigger for,
they can be specified using multiple descriptions, or as an array.
E.g:
World: World
World: World_nether
OR
World: [World,World_nether]

Permission event description:
You can specify one or more permissions the event will require in order to trigger
If multiple, then all all permissions written needs to be set for the player in order to trigger
can be specified using multiple descriptions or as an array
Can be set to any permission, so you can reuse permissions used for other plugins, or create your own, etc.
E.g:
Permission: someplugin.somepermision
Permission: someotherplugin.someotherpermission
OR
Permission: [someplugin.somepermision. someotherplugin.someotherpermission]

Actions event description:
You can specify multiple actions to trigger.
Actions are key/value based, so key is Action type, and value is content for the Action
Actions are specied in a Actions event description.
Actions are triggered in the order they are specified. All actions that renders some text to displayed to the user
will be merged together, to form one piece of text, this text is then automatically cut into pages (pagination).
all remaining Command actions will triggered afterwards in the order they appear.
E.g:
Actions:
- Text: 'Some text here'
- Command: /somecommand

The 4 Action types supported are:
Url: defines a url where content will be send to the player
File: defines a file placed in the files folder of the plugin where content will be send to the player
Command: defines the command to trigger (NB: Triggers a chat, so if command is specified without / the player will chat the message to the server)
Text: content to be send to the player, the same as file/url but without the need for an external file

All Actions can contain parse scripts, which is written as %someparse%
parse scripts supports arguments such as %someparse("World",4)%

For joins and teleports the event descriptions are written as multiple events in the Joins/Teleports category
Commands events however needs to have a command assigned.
This is done by writting the command name, and under the command you specify the (1 or multiple) event descriptions

Commands support arguments (parameters)
E.g:
help
help worldedit
help tp

In this example, if a user write "help me" it will default back to help, the plugin looks for the best exact match.
But if a user writes "help tp" it will trigger ONLY the events specied for this command, and will not default back to help command

Commands also support argument parsing. So arguments specified after the oommand will be send to any parsers written in the content as $n (Where n is the argument number)
E.g, if the user writes:.
/help worldedit hello rules.txt
The plugin will trigger the help worldedit command, and parse hello as argument $1 and rules as argument $2.
E.g (for help worldedit command)
Actions:
- File: worldedit.txt
- Text: 'You wrote $1'
- Text: '%includeFile($2)%'

This will get the contents of worldedit.txt, and after that it will write "You wrote hello" and then include the file "rules"

Example

Joins:
  - World: Test
    Permission: docmand.test1
    Actions:
    - Text: 'You have permission test1'
  - World: [Test, Test_nether]
    Permission: docmand.test2
    Actions:
    - Text: 'You have permission test2'
  - Actions:
    - File: motd.txt
Commands:
    someurl:
    - Actions:
      - Url: http://example.com/mc.php?name=%player_name%
    serverrules:
    - Actions:
      - Command: /rules
    news:
    - Actions:
      - File: news.txt
    motd:
    - Actions:
      - File: motd.txt
    rules:
    - Actions:
      - File: rules.txt
    test:
    - Actions:
      - Text: 'Something test'
    test hello:
    - Actions:
      - Text: 'Something other test hello'
    test say:
    - Actions:
      - Text: 'You said: $1'
    me:
    - Actions:
      - Command: '/say &d%player_name% is $1'
    stuff:
      - Text: 'Some $1 and first line from $2: %lineFromCommand("$2",1)%'
    permworldtest:
    - World: World
      Permission: docmand.permworldtest1
      Actions:
      - Text: 'You have permworldtest1 permissions'
      - Text: 'And are in world %world_name%'
    - Permission: docmand.permworldtest2
      World: [World,World_nether]
      Actions:
      - Text: 'You are in world %world_name%'
      - Text: 'And have permworldtest2 permissions'
    - Actions:
      - Text: 'You have permissions test1 or test2'
      Permission: [docmand.test1,docmand.test2]
    - World:
      - World
      - World_nether
      Actions:
      - Text: 'Hello world'
    help:
    - Permission: minecraft.tp
      Actions:
      - Text: '&b/help tp'
    - Permission: minecraft.give
      Actions:
      - Text: '&b/help give'
    - Permission: minecraft.settime
      Actions:
      - Text: '&b/help settime'
    help tp:
    - Permission: minecraft.tp
      Actions:
      - Text: 'You write /tp <player1> <player2>'     
    help give:
    - Permission: minecraft.give
      Actions:
      - Text: 'You write /give <itemid> <itemnum> it will you give you the items'
    help settime:
    - Permission: minecraft.settime
      Actions:
      - Text: 'You write /settime <xxx> where xxx is the time in ticks'

Teleports:
  - World: World
    Permission: docmand.test1
    Actions:
    - Text: 'Welcome to World'
  - World: World_nether
    Permission: docmand.test2
    Actions:
    - Text: 'Welcome to Hell!'

Parsers

Parsers are made up of a parse keyword, and some basic java code (Only basic code, and only 1 line of code is supported)
The built in fuctions are called directly, but you also have access to the Player object, and the Server object.
So to create a parser that will return the world name of the world the player is currently in, you would do something likes this:
player_world: Player.getWorld().getName()

This can then be parsed from any Text, Url source, or File source, e.g:
Welcome to %player_world%

Arguments are also supported.
lineFromCommand: readLineFromCommand($1,$2)
Notice the $1 and $2 they are argument placeholders.
They can parsed by specifying the parse command with arguments surrounded by parenthesis around them.
Latest news: %readLineFromCommand("news",1)
Will parse "news" as the first argument, and 1 as the second argument.
This command will read the lines from the command specified as /news, and return only the first line.

Arrays/Lists are supported:
Server.getPlayers[0].getName()
Server.getPlaysers.get(0).getName()
Server.getPlayers[$1].getName()

Parsers also support void methods, so you could do the following:
Add a event

Commands:
hurt:
Text: You were damaged 5 hearts %damage_player(5)%

Add a parser
damage_player: Player.damage($1)

And now you have a command that writes the message "You were damaged 5 hearts" and then triggers the damage.

Built in functions (More will come)

Java	Arguments	Description
readLineFromCommand($1,$2)	Command, line number	Includes the first x number of lines rendered from a command
readLinesFromCommand($1,$2,$3)	Command, start, end	Includes lines from start line to end line of lines rendered from a command
getOnlinePlayerNames()		Returns a comma seperate list of online players
getPlayersInPlayerWorld()		Gets the online players in the world the player is currently in
includeFile($1)	Filename	Includes a file from the files folder
includeCommand($1)	command name	includes the content from a command

Example

server_name: Server.getServerName()
player_name: Player.getName()
players_in_world: getPlayersInPlayerWorld()
online_players: getOnlinePlayerNames()
online_players_count: Server.getOnlinePlayers().length
lineFromCommand: readLineFromCommand($1,$2)
player_world: Player.getWorld().getName()
linesFromCommand: readLinesFromCommand($1,$2,$3)
include: includeFile($1)
includeCommand: includeCommand($1)

Files

Files refered to with the File command type, must reside in the cbDocmand/Files folder.

Example

Hi %player_name% and welcome to %server_name%
There are &d%online_players_count% &fplayers online
&aOnline: &c%online_players%
%include("include.txt")%

&aAll News: &b/news
&aRules: &b/rules (or /serverrules)

Future/Ideas/Current issues

More built in functions
More code support (Math, etc)
Add more supported Base classes that can be accessed in the parser (currently only Player and Server).
Clean code, and throw code in repository.
Add more default parsers.
Spout support?

No longer future, has been implemented/fixed

Permissions support
Fixed auto pagination
Group support using permission nodes
Support for nested parsers (evaluating one parser, and parsing it to another parser)
Multiple actions on events
Pagination commands

End notes

I hope you like it. Comment, ideas, bugs, parse commands(parse command files prepared to be used for other plugins) are very welcome and appreciated.
Enjoy!