[Mod] Bedrock Markup Language [markup]

Post Reply
User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

[Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Bedrock Markup Language v1.3
markup (by sorcerykid)

Note: I released Bedrock Markup Language in early 2019, but the original topic was lost during the forum reset. So I'm attempting to resurrect it.

Bedrock Markup Language is an extensible markup language and API specifically tailored for Minetest formspecs with simple-to-use tags for layout and formatting (e.g. colors, headers, borders, rows and columns), builtin word-wrapping, and support for embedded images (e.g. skins, items, etc.) It is backwards compatible with versions of Minetest 0.4.14+ and has no dependencies other than Simple Skins.

It makes a particularly nice drop-in replacement for the default sign and book editors, if you want to give your users the ability to create nicer looking messages, rather than accepting raw formspec strings which could pose security risks.

Here are a couple of screenshots showcasing what is possible using Bedrock Markup Language.

Image

Image

Repository:

https://bitbucket.org/sorcerykid/markup

Download Archive (.zip)
Download Archive (.tar.gz)

Dependencies:

Simple Skins (optional)

Source Code License:

The MIT License

Multimedia License:

Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)

Installation:
  1. Unzip the archive into the mods directory of your game.
  2. Rename the markup-master directory to "markup".
  3. Add "markup" as a dependency to any mods using the API.
Getting Started

There is support for 15 text colors (including white) via the following inline tags:
  • [q=gray][/q] - gray text
  • [q=red][/q] - red text
  • [q=green][/q] - green text
  • [q=blue][/q] - blue text
  • [q=cyan][/q] - cyan text
  • [q=magenta][/q] - magenta text
  • [q=yellow][/q] - yellow text
  • [q=black][/q] - black text
  • [q=brown][/q] - brown text
  • [q=teal][/q] - teal text
  • [q=purple][/q] - purple text
  • [q=olive][/q] - olive text
  • [q=indigo][/q] - indigo text
  • [q=maroon][/q] - maroon text
There is also support for rows and columns via the [r] and [c] tags. These two tags accept an optional numeric attribute to alter the size of the cell to be rendered.

You can set the depth of all cells on the next row using [r=#], and you can set the width of the next cell using [c=#]. In both cases, # must be an number (or 0 for the default). The unit of measurement is an approximation of the standard "em" used in typography.

Example: Here is a basic table consisting of two rows and two columns:

Code: Select all

Upper left cell[c]Upper right cell
[r]
Lower left cell[c]Lower right cell
Notice, how the initial [r] tag is missing, and the initial [c] tags are also missing. Not to worry! The lexer automatically fills in these tags behind the scenes. It is entirely optional to include them. This markup is more verbose, but produces the same results:

Code: Select all

[r=0][c=0]Upper left cell[c=0]Upper right cell
[r=0][c=0]Lower left cell[c=0]Lower right cell
  • Image
By default rows and cells are evenly spaced vertically and/or horizontally, for the most pleasing appearance. The lexer is capable of automatically resizing rows and cells to fit within the allowed dimensions of the formspec and to prevent overruns.

In addition to all the features described above, you can easily add bordered text, headline text, and even images (both skin and item textures) into your formspecs!
  • Image
The [­b] an [h] tags are row-based and accept a depth whereas the [­i] and [s] and [f] tags are column-based and accept a width:
  • [­b]<border_text>
    Insert the border text with a depth of 1.0

    [b=#]<border_text>
    Same as above, but with the specified depth

    [h]<header_text>
    Insert the header text with a depth of 1.0

    [h=#]<header_text>
    Same as above, but with the specified depth

    [­i]<item_name>
    Insert the item texture with a width of 2.0 (if the image is too large to fit on the current row, then it will be shrunk to fit).

    [i=#]<item_name>
    Same as above, but with the specified width

    [s]<skin_name>
    Insert the skin texture with a width of 2.0 (if the image is too large to fit on the current row, then it will be shrunk to fit).

    [s=#]<skin_name>
    Same as above, but with the specified width

    [f=#]<field_text>
    Insert the editable text field with the specified width
It is also possible to include dynamic text using variable interpolation:
  • $name - the name of the current player
  • $item - the wielded item of the current player (for use with the [­i] tag)
  • $skin - the selected skin of the current player (for use with the [­s] tag)
  • $date - the current world date
  • $time - the current world time
  • $cur_users - the current number of online players
  • $max_users - the maximum number of online players
A variety of special and reserved characters can be inserted by means of escape codes:
  • &amp; - ampersand
  • &gt; - greater-than
  • &lt; - less-than
  • &rb; - right bracket
  • &lb; - left bracket
  • &copy; - copyright
  • &sect; - section
  • &half; - one-half
  • &doll; - dollar
  • &deg; - degree
  • &pm; - plus-or-minus
  • &div; - division
  • &mul; - multiplication
  • &dash; - em-dash
  • &bull; - bullet
  • &lq; - opening quote
  • &rq; - closing quote
  • &lsq; - opening single-quote
  • &rsq; - closing single-quote
The Bedrock Markup Language also supports emojis! It's simple and easy to embed smilies and other symbols into your formspecs using the existing item tag. Just type one of the following emoji shortnames preceded by a colon, such as [­i]:cupid_heart or [­i]:smitten.

Image

The blank psuedo-emoji can be be useful in situations where you need to insert an empty cell for horizontal padding: :blank

Example: This is a simple Valentine's Day greeting with a large red balloon from my fireworks mod:

Code: Select all

[r=2][c=1]
[i]:heart[c=7]Here is a BIG red balloon for your extra special Valentine![i]:heart
[r][c=3][i=9]fireworks:balloon_red
Image

The following functions are available as part of the Bedrock Markup Language API:
  • markup.get_builtin_vars( player_name )
    Return a table consisting of builtin variables for use by the parser. You can add or remove builtin variables or even disable them entirely simply by editing this function.
    • player_name is the player for whom the formspec string will be generated.
    markup.parse_message( message, vars, defs )
    Parse the given message and return the rows as a table.
    • message is the message consisting of Bedrock Markup Language.
    • vars is a table of variables, with each key being the variable name and each value being the corresponding string value of the variable.
    • defs is a table of emoji, color, and/or symbol definitions, for overriding the default registrations (optional).
    markup.get_formspec_string( rows, min_horz, min_vert, max_horz, max_vert, border_color, header_color, normal_color )
    Generate a formspec string from the rows table returned by markup.parse_message( ).
    • rows is the rows table returned by the message parser
    • min_horz is the left position of the rendering area in formspec coordinates
    • min_vert is the bottom position of the rendering area in formspec coordinates
    • max_horz is the right position of the rendering area in formspec coordinates
    • max_vert is the bottom position of the rendering area in formspec coordinates
    • border_color is the hex color code to apply to border boxes (optional)
    • header_color is the hex color code to apply to header rules (optional)
    • normal_color is the hex color code to apply to normal text (optional)
Note that the parser will skip unknown tags and undefined variables and symbols, rather than stripping them from the original message.
Last edited by sorcerykid on Tue Apr 20, 2021 05:11, edited 3 times in total.

User avatar
Krock
Developer
Posts: 4649
Joined: Thu Oct 03, 2013 07:48
GitHub: SmallJoker
Location: Switzerland
Contact:

Re: [Mod] Bedrock Markup Language [markup]

by Krock » Post

I was about to ask whether this is a reverse-engineered version of the 5.2.0-dev HTML formspec element for 0.4.x releases - until I saw that it's a late presentation post (so to say).

Is the formspec GUI scalable? I'd imagine there are several users who prefer monospace fonts, which happen to be way wider than Arimo.

But as always, you've put much effort into these features. Well done!
Look, I programmed a bug for you. >> Mod Search Engine << - Mods by Krock - DuckDuckGo mod search bang: !mtmod <keyword here>

User avatar
v-rob
Developer
Posts: 970
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob
IRC: v-rob
Location: Right behind you.

Re: [Mod] Bedrock Markup Language [markup]

by v-rob » Post

Well, unlike the HTML element (which I don't think can be done perfectly in Lua), this seems to be backwards compatible, which is always a nice thing to have.
Core Developer | My Best Mods: Bridger - Slats - Stained Glass

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Krock wrote:I was about to ask whether this is a reverse-engineered version of the 5.2.0-dev HTML formspec element for 0.4.x releases - until I saw that it's a late presentation post (so to say).
Actually, the original inspiration for Bedrock Markup Language was BBCode :) I designed the syntax to be as simple as possible for players on JT2 to create fancier signs with no knowledge of formspecs. Soon afterward, I branched it off into a standalone API for in-game content publication. This was before the HTML element was introduced.

https://forum.minetest.net/viewtopic.php?p=341393#p341393
Is the formspec GUI scalable? I'd imagine there are several users who prefer monospace fonts, which happen to be way wider than Arimo.
The rows and cells scale proportionately to the width and height of the rendering area. However, since these calculations are all performed server-side I have no way to account for text overflow. Ideally, I would be able to stretch fields to compensate for larger fonts on the fly. So the best I can do is approximate.
But as always, you've put much effort into these features. Well done!
Thank you! At some point I plan to migrate to HTML. I'm definitely looking forward to bold, italic, and underline text styles. Backward compatibility should be pretty easy too, since I could simply strip the HTML tags and revert to textareas if the server version is 0.4.x.

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Version 1.3 Released

A new version of Bedrock Markup Language is ready for download. Here is a complete change log:
  • Corrected references to some missing emojis
  • Renamed and exposed emoji table in mod namespace
  • Added private string-matching helper function
  • Removed extraneous table.get_index helper function
  • Revamped parser with conditional pattern matching
  • Included support for symbols via escape codes
  • Added color and symbol tables to mod namespace
  • Allowed for overriding defaults in message parser
  • Separated various constants into head of script
  • Added option for changing normal text color
  • Consolidated parsing of item and emoji tags
  • Compensated for oddity with textarea positions
Perhaps the most noticeable change in this release is that the rendering area is now shifted right by 0.3 horizontally. Originally, I was trying to overcome a bug with textarea elements being misaligned by manually offseting the image elements to compensate. That was obviously incorrect. So the textarea elements have now been offset as they originally should have been. Of course, that means you will need to subtract 0.3 for the horizontal coordinates passed to markup.get_formspec_string() in all of your mods. Sorry about the confusion!

Code: Select all

BEFORE:
markup.get_formspec_string(rows, 1.0, 0.5, 6.0, 5.0, "#CCCCCC", "#FFFFFF") 

AFTER:
markup.get_formspec_string(rows, 0.7, 0.5, 5.7, 5.0, "#CCCCCC", "#FFFFFF") 
On a less bug-related note, I exposed the emoji registration table within the markup namespace. So now you can incorporate emojis into your own mods simply by referencing markup.registered_emojis[] with the emoji's shortname as the key.

In addition, the markup.parse message() function now accepts an optional "defs" parameter, which allows for overriding the default emoji, color, and/or symbol definitions. For example, if you wanted to limit the available emojis to a selection of four, this would work:

Code: Select all

markup.parse_message( message, vars, { emojis = {
        happy = "emoji_happy.png",
        mad = "emoji_mad.png",
        amused = "emoji_amused.png",
        cool = "emoji_cool.png",
} } )
Six more text colors have been made available, bringing the total to 15 including white:
  • [q=gray][/q] - gray text
  • [q=red][/q] - red text
  • [q=green][/q] - green text
  • [q=blue][/q] - blue text
  • [q=cyan][/q] - cyan text
  • [q=magenta][/q] - magenta text
  • [q=yellow][/q] - yellow text
  • [q=black][/q] - black text
  • [q=brown][/q] - brown text
  • [q=teal][/q] - teal text
  • [q=purple][/q] - purple text
  • [q=olive][/q] - olive text
  • [q=indigo][/q] - indigo text
  • [q=maroon][/q] - maroon text
Special and reserved characters can also be inserted into messages via escape codes:
  • & - ampersand
  • > - greater-than
  • < - less-than
  • &rb; - right bracket
  • < - left bracket
  • &copy; - copyright
  • &sect; - section
  • &half; - one-half
  • &deg; - degree
  • &pm; - plus-or-minus
  • &div; - division
  • &mul; - multiplication
  • &dash; - em-dash
  • &bull; - bullet
  • &lq; - opening quote
  • &rq; - closing quote
  • &lsq; - opening single-quote
  • &rsq; - closing single-quote
And lastly, the height and width attributes of the row and cell tags can now accept floating points. This should offer much finer-grained control of layouts, where integer-based sizing of cells may have been far too abrupt. As a bonus, for situations where you need to insert an empty cell for padding, you can use the new blank pseudo-emoji for this purpose: :blank

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Beta-testing the new markdown extension to the Bedrock Markup Language, which introduces a new cell-type [m] that supports embedding of Magic Markdown flavored text.

Image

Image

What sets this variant of Markdown apart from the more common implementations is that it's easy to create multiple levels of indentation without having to resort to bulleted lists. This is particularly nice for visualizing a hierarchy of textual information, including code blocks, subheadings, quotations, etc. all in cascading format.

Image

This, of course, will be a 5.x specific feature. But my goal is to implement a fallback renderer for legacy versions of Minetest. This way markdown content can always be viewed, regardless of the engine version.

User avatar
Extex
Member
Posts: 244
Joined: Wed Mar 14, 2018 23:14
GitHub: Extex101
In-game: Extex

Re: [Mod] Bedrock Markup Language [markup]

by Extex » Post

Could you make skins optional?
I would like to use this in a mod without needing extra unneeded mods
Creator of jelys_pizzaria and motorbike, and player of persistent kingdoms. RIP

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Yes, that's a great idea. I can certainly do that. I think I will auto-detect the skins mod. And if none are found, then a generic placeholder image will be used instead.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Bedrock Markup Language [markup]

by Wuzzy » Post

The first post looks broken.

neoh4x0r
Member
Posts: 82
Joined: Wed Aug 29, 2018 20:16
GitHub: neoh4x0r

Re: [Mod] Bedrock Markup Language [markup]

by neoh4x0r » Post

Extex wrote:
Thu Apr 02, 2020 19:58
Could you make skins optional?
I would like to use this in a mod without needing extra unneeded mods
sorcerykid wrote:
Fri Apr 03, 2020 00:51
Yes, that's a great idea. I can certainly do that. I think I will auto-detect the skins mod. And if none are found, then a generic placeholder image will be used instead.
Skins isn't actually defined as optional, also the mod name is simple_skins
depends.txt:

Code: Select all

simple_skins
default
Should be:

Code: Select all

default
simple_skins?
Even better would be to use mod.conf:

Code: Select all

name=markup
description=Bedrock Markup Language is an extensible markup language and API specifically tailored for Minetest formspecs with simple-to-use tags for layout and formatting. 
depends=default
optional_depends=simple_skins

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Thanks, I've added these suggestions to the roadmap. I'm already looking at better integration with multiple skins mods, probably via an abstraction layer. That way I can avoid hard coding specific skin implementations within the parser itself.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Bedrock Markup Language [markup]

by Wuzzy » Post

Aaand the first post is still broken.

neoh4x0r
Member
Posts: 82
Joined: Wed Aug 29, 2018 20:16
GitHub: neoh4x0r

Re: [Mod] Bedrock Markup Language [markup]

by neoh4x0r » Post

@sorcerykid
The markup mod has an undisclosed dependency on registry from https://bitbucket.org/sorcerykid/registry

Here's a patch made from (commit: 6ac436e9f487b2575377112dd7d1552775a61d7b)
https://bitbucket.org/sorcerykid/markup ... 2775a61d7b

Code: Select all

--- branches/minetest-addons/mods/minetest-mod-markup/init.lua	2020/07/13 12:07:20	1036
+++ branches/minetest-addons/mods/minetest-mod-markup/init.lua	2020/07/13 12:55:38	1042
@@ -13,6 +13,7 @@
 local UNKNOWN_ITEM_TEXTURE = "unknown_item.png"
 local UNKNOWN_EMOJI_TEXTURE = "emoji_unknown.png"
 
+local registry_path = minetest.get_modpath("registry")
 -------------------------
 
 markup.registered_emojis = {
@@ -105,7 +106,14 @@
 		name = player_name,
 		item = player:get_wielded_item( ):get_name( ),
 		skin = skins.skins[ player_name ],
-		cur_users = #registry.player_list,
+		--cur_users = #registry.player_list,
+		cur_users =  (function () 
+					if registry_path then
+						return registry.player_list 
+					else
+						return { }
+					end 
+				end)(),
 		max_users = minetest.setting_get( "max_users" ),
 	}
 end

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Bedrock Markup Language [markup]

by Wuzzy » Post

I found a bug in the README. In the README, it says that the escape for "[" is "&lt;" but it actually is "&lb;".

Also, the first post is still broken. :P

I also suggest to make the dollar sign escapable with "&dollar;" because it has a special meaning ($name, $date, etc.).

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

Thanks for all the feedback. I've addressed these issues and hope to roll out the next release soon.

Also the first post is fixed at long last, thanks to Wuzzy's persistence. I've added wiki documentation too ;)

https://github.com/sorcerykid/markup/wiki

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Bedrock Markup Language [markup]

by Wuzzy » Post

Apparently escaping doesn't work always.
If you do "$doll;date", you will get something like "Day 1 Month 2 Year 3date" instead of "$date".


PS: I still like this mod, great work on it! :)

User avatar
sorcerykid
Member
Posts: 1841
Joined: Fri Aug 26, 2016 15:36
GitHub: sorcerykid
In-game: Nemo
Location: Illinois, USA

Re: [Mod] Bedrock Markup Language [markup]

by sorcerykid » Post

I'm a little confused Wuzzy, but from what I understand you are trying to output the literal text "$date"? That should be possible with just &doll;date, as the escape code begins with an ampersand rather than a dollar sign.

I admit I'm completely baffled how the code you posted would generate a date, since there should be no interpolation at all, particularly given that $doll;date is neither a valid variable nor escape code.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Bedrock Markup Language [markup]

by Wuzzy » Post

Maybe $doll was exclusive to the JT2 server, if I remember correctly.

Post Reply

Who is online

Users browsing this forum: No registered users and 13 guests