Lazarus

Free Pascal => Beginners => Topic started by: kveroneau on June 04, 2019, 03:50:40 am

Title: My contribution to the community for beginners
Post by: kveroneau on June 04, 2019, 03:50:40 am
Now that I have been using FreePascal for a bit, I am now starting to jot down lots of useful notes, and believe these notes could be very useful to someone who is starting out with FreePascal.  When I first started learning FreePascal, documentation was at times difficult to find for some very specific units, and I had to read the source files of those units to better understand what was going on and how to use those units.  While the Wiki is great, it can be at times difficult to locate exactly what you are looking for, and at times there are multiple pages about a similar topic, but with different solutions.  While I am very thankful that there is more than one way to do something in FreePascal, it does lead to some confusion when picking the right solution.

I now present you with what I am calling kDocs for ObjectPascal.  http://tech406.com/kdocs/

What's more, is that this website is built entirely in XML!  If you do not believe me, right-click and view source.  I choose of doing it this way, as it makes copying and pasting examples and documentation super easy, also adding new documentation is very easy as all it is, is a static website.  Anyways...

I choose not to write new Wiki pages, as firstly I was originally writing this as a personal set of documentation which I can have locally and easily reference.  However, I felt that sharing it with the community will be beneficial to all in the end, no need to hoard documentation.

With that said, it is in the very early stages, but does include some interesting topics, such as the project and module templates available in Lazarus, along with full source of what each template looks like, so you can easily review each template before choosing it in the IDE.  The IDE should have a project review button so we can preview the source code templates before committing to using it.  Other interesting topics for newcomers are basic Networking using just fcl-net and fcl-web, along with examples for a TCP client/server, and how to use the fphttpclient class in it's simplest form to get you started.  There's also a short document on Encryption and uses Blowfish as an example along with how to set-up a TStream to use it correctly.  Then there's the ever so popular documentation on Threads.  With a fully working command-line program example, as simple examples are the best way to educate.  Future examples will include how to enable a TCP server to use a thread for each incoming connection.

This is an ongoing effort I am putting together mainly for keeping personal notes, so these documents will expand as I keep thinking of new and interesting things I'd love to try out with ObjectPascal.  This is by no means meant as a tutorial, but more so for general notes on some more complicated functionality in ObjectPascal which can otherwise be difficult to grasp at first without a simple example to guide you.  Enjoy!

Oh, and the landing page has a nice introduction to me, and why I personally chose to go with ObjectPascal.  Might be useful to show others why ObjectPascal is a good choice.
Title: Re: My contribution to the community for beginners
Post by: Handoko on June 04, 2019, 05:22:52 am
Thank you for sharing your knowledge.

I've just checked the website. Great, it has networking tutorials, which is the topic I currently want to learn. I bookmarked it and hope to see more various topics  in kDocs in the future.
Title: Re: My contribution to the community for beginners
Post by: GAN on June 04, 2019, 06:06:37 am
Nice and clean site.
Thank you.
Title: Re: My contribution to the community for beginners
Post by: PascalDragon on June 04, 2019, 08:53:32 am
Now that I have been using FreePascal for a bit, I am now starting to jot down lots of useful notes, and believe these notes could be very useful to someone who is starting out with FreePascal.  When I first started learning FreePascal, documentation was at times difficult to find for some very specific units, and I had to read the source files of those units to better understand what was going on and how to use those units.  While the Wiki is great, it can be at times difficult to locate exactly what you are looking for, and at times there are multiple pages about a similar topic, but with different solutions.  While I am very thankful that there is more than one way to do something in FreePascal, it does lead to some confusion when picking the right solution.
Just for the sake of correctness: It's Free Pascal, not FreePascal. ;) (same for ObjectPascal by the way)
Title: Re: My contribution to the community for beginners
Post by: HuntingKashket on June 04, 2019, 09:56:39 am
Good job!
My advice is to add ability to contribute to it, or maybe to export its content to the freepascal wiki, which will be a useful update for.
Also, i think description for the examples is a good practice, which will be a cherry on this cake :)

P.s Lazarus needs to introduce wiki for some platform-specific differences between GUI routines
Title: Re: My contribution to the community for beginners
Post by: fred on June 04, 2019, 03:08:54 pm
Indeed very nice :)

Perhaps it could be a link in the wiki ( when it's working again ) ?
Title: Re: My contribution to the community for beginners
Post by: kveroneau on June 04, 2019, 04:45:22 pm
Thank you everyone for the feedback.  I will be definitely adding more as I learn more.  I am thinking of placing it into a public Git repository, as it's just a bunch of XML files, so people can either download the content for local viewing offline, and potentially contribute some content they wish to share, or even start their own static website with their own unique Pascal content.  You don't need to know HTML/CSS/JS to create your own kDocs XML files, the XML tags are easy to understand by most coders, and it automatically manages the headaches of Markdown and syntax highlighting in the browser.  :D  I'm honestly surprised by why XSLT isn't more widely used, it's definitely useful.

PasalDragon, I will go in with the handy sed command to perform the replacement.  Thank you for the suggestion.
Title: Re: My contribution to the community for beginners
Post by: kveroneau on June 06, 2019, 02:40:08 am
This is a short post to announce a newly added topic with a fully working example, a super simple introduction to fetching a JSON object from a website API, and parsing the JSON data using fpjson.  Enoy!

http://tech406.com/kdocs/json.xml
Title: Re: My contribution to the community for beginners
Post by: Picard on June 06, 2019, 03:21:42 am
Do you have any examples of how to extract data from a table an MS Access mdb file?  I imported this table from an Excel spreadsheet and I need to do a 2 dimensional search.  I have the formula for the Excel search and I wonder if this can be done in Pascal also.
Title: Re: My contribution to the community for beginners
Post by: john horst on June 06, 2019, 03:54:22 am
@kveroneau

Just as a heads up, your json is not valid. " 'cause " <-- valid. JSON should use double quotes.

Code: Javascript  [Select]
  1. {
  2.         "title": "Example JSON for OBJPAS code example.",
  3.         "languages": [{
  4.                         "name": "Turbo Pascal",
  5.                         "developer": "Borland"
  6.                 },
  7.                 {
  8.                         "name": "Free Pascal",
  9.                         "developer": "Free Pascal team"
  10.                 },
  11.                 {
  12.                         "name": "Delphi",
  13.                         "developer": "Embarcadero Technologies"
  14.                 }
  15.         ]
  16. }
Title: Re: My contribution to the community for beginners
Post by: kveroneau on June 06, 2019, 04:03:26 am
@kveroneau

Just as a heads up, your json is not valid. " 'cause " <-- valid. JSON should use double quotes.
Thanks, I also guess fpjson doesn't check for this, as it was able to download and parse it with no problem.  But, I will update it right away to use double-quotes.

A side note, a new document is now available, it's on Pointers.  While pointers are less necessary in Pascal, when compared to C, it's still nice to know of them in-case you do need to use them.  And they are needed if you want to add extra meta data to say a TTreeItem, as it's .Data property is a pointer.

http://tech406.com/kdocs/pointers.xml

This is probably one of my longest example codes so far, but it is something I wish to be-able to reference myself in the future.

I will be adding more, as there is so much more I can write about Pointers.  :D
Title: Re: My contribution to the community for beginners
Post by: valdir.marcos on June 06, 2019, 07:01:57 am
@kveroneau
Just as a heads up, your json is not valid. " 'cause " <-- valid. JSON should use double quotes.
Thanks, I also guess fpjson doesn't check for this, as it was able to download and parse it with no problem.  But, I will update it right away to use double-quotes.
Is that a bug or a missing feature?

Quote
A side note, a new document is now available, it's on Pointers.  While pointers are less necessary in Pascal, when compared to C, it's still nice to know of them in-case you do need to use them.  And they are needed if you want to add extra meta data to say a TTreeItem, as it's .Data property is a pointer.
http://tech406.com/kdocs/pointers.xml
This is probably one of my longest example codes so far, but it is something I wish to be-able to reference myself in the future.
I will be adding more, as there is so much more I can write about Pointers.  :D
Congratulations on your effort.
Title: Re: My contribution to the community for beginners
Post by: john horst on June 06, 2019, 09:00:39 am
@valdir.marcos bug if following the spec. Technically that's an apostrophe.

From the spec
"9 A string is a sequence of Unicode code points wrapped with quotation marks (U+0022). All code pointsmay be  placed  within  the  quotation  marks  except  for  the code  pointsthat  must  be  escaped:  quotation  mark (U+0022), reverse solidus (U+005C), and the control characters U+0000 to U+001F.There are two-character escape sequence representations of some characters. "

Followed by more in this PDF. http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

I believe there is a line in there about the parser must be strict. I do believe some parsers will do strict / unstrict too as a feature.

http://www.json.org/ A link to the PDF can be found at the top of the official site as well.
Title: Re: My contribution to the community for beginners
Post by: kveroneau on June 07, 2019, 03:48:37 am
I added a new section to the Networking page titled Sending and Receiving structured data.  In the newly added example code, it creates a set of Pascal records, which are then sent over a socket connection to a server which can read the structured data.  The example code provides both a working server and client program so you can play around with it yourself.  It also includes code for how to talk with the Pascal server from Python code, showing that Pascal records can indeed be transferred between programming languages.  This isn't really useful for transferring data over the public Internet, although it could be used for that, it is mainly useful for either inter-machine or inter-process communications, where other protocols might be too heavyweight, such as in embedded systems.  It also demonstrates a persistent connection, where the server and client stay connected for multiple transactions between each other.

http://tech406.com/kdocs/sockets.xml

Click on "Sending and Receiving structured data" at the top to jump right to the newly added section.

I did notice an issue when reading the Pascal record on the other side of the network pipe in Python, but I believe I know now why...  I did not specify packed record, so the record size in Pascal is 88, whereas Python calculates it out as 85.  Int+Byte+string[80] = 88 unpacked.  I will update the example code soon to reflect this, once I confirm that this is the cause of the differences.
Title: Re: My contribution to the community for beginners
Post by: lucamar on June 07, 2019, 06:45:28 am
If you're realy sending a string[80]--that is, a shortstring--remember to count the "length" byte at string[0]. That would make: LongInt (4 bytes) + byte + string (80+1) = 86 bytes if packed.

Also, if you're using Integer remember that it may be 4 or 8 bytes, depending on whether the platform is 32 or 64 bits.
Title: Re: My contribution to the community for beginners
Post by: PascalDragon on June 07, 2019, 09:10:40 am
Also, if you're using Integer remember that it may be 4 or 8 bytes, depending on whether the platform is 32 or 64 bits.
The size of Integer does not depend on the bitness. It only depends on the mode, namely it's 16 bit in modes fpc, tp and iso and 32-bit in the others.
Title: Re: My contribution to the community for beginners
Post by: giahung1997 on June 07, 2019, 09:37:34 am
Bookmarked  :)
Title: Re: My contribution to the community for beginners
Post by: kveroneau on June 08, 2019, 06:43:01 pm
I added a new document on a lesser used feature of computers these days, command parsing.  In Python I generally used both the shlex and cmd modules a lot to create interactive command-line tools which were also able to load external script files.  I was originally going to port shlex over to Object Pascal, but I managed to find an easier method by using just two pascal functions.  You can see the document and related example code here:

http://tech406.com/kdocs/parsing.xml

The second document of the day is on UNIX Signals:  http://tech406.com/kdocs/signals.xml

The first part of the document explains why you would want to trap these signals if you plan on writing a UNIX service, and explains the various use-cases for the most common signal types.

I just updated the UNIX Signals page with a fully working Pascal Unit called UnixSignals, if you wish to use the most common signals within your program, and this means any program type, except a shared library.  You can merely just check the included booleans within the Unit to see if a specific signal was sent to your program.  You should of course place this into your programs idle/event loop and check for the signals there and act upon them as needed.  This can enable either your GUI program or server process under UNIX-like systems to easily reload their configuration files from disk when the SIGHUP is sent to your process for example by just checking the HangUp boolean from the unit file.  Be sure to set the boolean back to false after handing the signal so it won't constantly trigger.  Enjoy!

Update to Pointers:  Need to work with large binary data in Pascal in a very specific way, and TMemoryStream just does not fulfill that requirement for you?  I ended up making a new class, which is similar to TMemoryStream, but does not expand or shrink, it is set to a constant allocation size defined by the class.  Why would you want to use such a class, you might be asking?  If you are writing a strict emulator or virtual machine with a very specific heap size requirement, that's why!  When writing the 6502 emulator I wrote, the CPU needs to see and have a constant 64k of memory, and the overhead of TMemoryStream constantly reallocating the pointer size just isn't ideal.  This new class simulates the flat memory model required to write emulators and virtual machines with a static amount of memory.  It has handy functions such as reading and writing both 8 and 16-bit integers from random address locations, the seek procedure is only used for the TStream compatible LoadFromStream and SaveToSteam procedures, other than that, your program is free to PEEK and POKE around at any memory location with ease.

http://tech406.com/kdocs/pointers.xml  Then click on Using flat memory in Pascal at the top.  Enjoy!

June 10th update: I added a new page on Checksums with examples on how to use the built-in crc unit to generate and store a checksum for CRC32, CRC64, and CRC128.  I still do not know how to display the u128 custom type as a GUID string, any ideas anybody?  I checked the system unit documentation where the custom type is defined to see if there are any functions or procedures to work with TGuid types, such as converting it to a GUID string, and back over to a u128, but I couldn't find anything.  If you know, please let me know and I will update the document to reflect that knowledge.  The really cool part about the custom u128 type is that it can be placed into a custom record, and easily written to disk.  The hex dump of the created file appears to have the whole 128-bit Integer intact as expected.